diff --git a/docs/uk/channels/feishu.md b/docs/uk/channels/feishu.md index ec1879ee7..6f14b1cd9 100644 --- a/docs/uk/channels/feishu.md +++ b/docs/uk/channels/feishu.md @@ -2,28 +2,28 @@ read_when: - Ви хочете підключити бота Feishu/Lark - Ви налаштовуєте канал Feishu -summary: Огляд бота Feishu, функції та налаштування +summary: Огляд, функції та налаштування бота Feishu title: Feishu x-i18n: - generated_at: "2026-04-24T01:17:06Z" + generated_at: "2026-04-25T07:01:55Z" model: gpt-5.4 provider: openai - source_hash: f68a03c457fb2be7654f298fbad759705983d9e673b7b7b950609694894bdcbc + source_hash: 01e6373cc5744973e9f18016c5d5bd6a036a03eb269cba3b5fd7f4108cad2ecb source_path: channels/feishu.md workflow: 15 --- # Feishu / Lark -Feishu/Lark — це універсальна платформа для співпраці, де команди спілкуються в чаті, діляться документами, керують календарями та разом виконують роботу. +Feishu/Lark — це універсальна платформа для співпраці, де команди спілкуються в чаті, обмінюються документами, керують календарями та спільно виконують роботу. -**Статус:** готово до використання у продакшені для особистих повідомлень боту та групових чатів. WebSocket — режим за замовчуванням; режим Webhook є необов’язковим. +**Статус:** готово до використання у продакшені для особистих повідомлень боту та групових чатів. Режим WebSocket є стандартним; режим Webhook — необов’язковий. --- ## Швидкий старт -> **Потрібен OpenClaw 2026.4.24 або новіший.** Виконайте `openclaw --version`, щоб перевірити. Оновіть за допомогою `openclaw update`. +> **Потрібен OpenClaw 2026.4.24 або новіший.** Щоб перевірити, виконайте `openclaw --version`. Оновіть за допомогою `openclaw update`. @@ -46,14 +46,14 @@ Feishu/Lark — це універсальна платформа для спів ### Особисті повідомлення -Налаштуйте `dmPolicy`, щоб визначити, хто може надсилати боту особисті повідомлення: +Налаштуйте `dmPolicy`, щоб керувати тим, хто може надсилати боту особисті повідомлення: -- `"pairing"` — невідомі користувачі отримують код сполучення; схвалення через CLI -- `"allowlist"` — спілкуватися можуть лише користувачі, перелічені в `allowFrom` (за замовчуванням: лише власник бота) +- `"pairing"` — невідомі користувачі отримують код сполучення; підтвердження через CLI +- `"allowlist"` — спілкуватися можуть лише користувачі, перелічені в `allowFrom` (типово: лише власник бота) - `"open"` — дозволити всіх користувачів - `"disabled"` — вимкнути всі особисті повідомлення -**Схвалити запит на сполучення:** +**Підтвердження запиту на сполучення:** ```bash openclaw pairing list feishu @@ -62,19 +62,19 @@ openclaw pairing approve feishu ### Групові чати -**Політика груп** (`channels.feishu.groupPolicy`): +**Політика для груп** (`channels.feishu.groupPolicy`): -| Value | Поведінка | -| ------------- | ------------------------------------------- | -| `"open"` | Відповідати на всі повідомлення в групах | -| `"allowlist"` | Відповідати лише групам у `groupAllowFrom` | -| `"disabled"` | Вимкнути всі повідомлення в групах | +| Значення | Поведінка | +| ------------- | ------------------------------------------ | +| `"open"` | Відповідати на всі повідомлення в групах | +| `"allowlist"` | Відповідати лише в групах із `groupAllowFrom` | +| `"disabled"` | Вимкнути всі групові повідомлення | -За замовчуванням: `allowlist` +Типове значення: `allowlist` **Вимога згадки** (`channels.feishu.requireMention`): -- `true` — вимагати @згадку (за замовчуванням) +- `true` — вимагати @згадку (типово) - `false` — відповідати без @згадки - Перевизначення для окремої групи: `channels.feishu.groups..requireMention` @@ -94,7 +94,7 @@ openclaw pairing approve feishu } ``` -### Дозволити всі групи, але все одно вимагати @згадку +### Дозволити всі групи, але все ще вимагати @згадку ```json5 { @@ -107,14 +107,14 @@ openclaw pairing approve feishu } ``` -### Дозволити лише певні групи +### Дозволити лише конкретні групи ```json5 { channels: { feishu: { groupPolicy: "allowlist", - // ID груп мають вигляд: oc_xxx + // Ідентифікатори груп мають вигляд: oc_xxx groupAllowFrom: ["oc_xxx", "oc_yyy"], }, }, @@ -148,19 +148,19 @@ openclaw pairing approve feishu ### ID групи (`chat_id`, формат: `oc_xxx`) -Відкрийте групу у Feishu/Lark, натисніть значок меню у верхньому правому куті та перейдіть до **Settings**. ID групи (`chat_id`) указано на сторінці налаштувань. +Відкрийте групу у Feishu/Lark, натисніть значок меню у верхньому правому куті та перейдіть у **Settings**. ID групи (`chat_id`) вказано на сторінці налаштувань. -![Отримання ID групи](/images/feishu-get-group-id.png) +![Get Group ID](/images/feishu-get-group-id.png) ### ID користувача (`open_id`, формат: `ou_xxx`) -Запустіть Gateway, надішліть боту особисте повідомлення, а потім перевірте логи: +Запустіть Gateway, надішліть боту особисте повідомлення, а потім перевірте журнали: ```bash openclaw logs --follow ``` -Знайдіть `open_id` у виводі логів. Ви також можете перевірити запити на сполучення, що очікують схвалення: +Шукайте `open_id` у виводі журналу. Також можна перевірити запити на сполучення, які очікують підтвердження: ```bash openclaw pairing list feishu @@ -170,33 +170,33 @@ openclaw pairing list feishu ## Поширені команди -| Command | Опис | -| --------- | ----------------------------- | -| `/status` | Показати статус бота | -| `/reset` | Скинути поточну сесію | -| `/model` | Показати або змінити AI-модель | +| Команда | Опис | +| --------- | --------------------------------- | +| `/status` | Показати статус бота | +| `/reset` | Скинути поточну сесію | +| `/model` | Показати або перемкнути AI-модель | -> Feishu/Lark не підтримує нативні меню slash-команд, тому надсилайте їх як звичайні текстові повідомлення. +> Feishu/Lark не підтримує вбудовані меню slash-команд, тому надсилайте ці команди як звичайні текстові повідомлення. --- -## Усунення неполадок +## Усунення несправностей ### Бот не відповідає в групових чатах 1. Переконайтеся, що бота додано до групи -2. Переконайтеся, що ви @згадуєте бота (це потрібно за замовчуванням) +2. Переконайтеся, що ви згадуєте бота через @ (типово це обов’язково) 3. Перевірте, що `groupPolicy` не має значення `"disabled"` -4. Перевірте логи: `openclaw logs --follow` +4. Перевірте журнали: `openclaw logs --follow` ### Бот не отримує повідомлення -1. Переконайтеся, що бот опублікований і схвалений у Feishu Open Platform / Lark Developer -2. Переконайтеся, що підписка на події включає `im.message.receive_v1` +1. Переконайтеся, що бота опубліковано й схвалено у Feishu Open Platform / Lark Developer +2. Переконайтеся, що підписка на події містить `im.message.receive_v1` 3. Переконайтеся, що вибрано **persistent connection** (WebSocket) 4. Переконайтеся, що надано всі потрібні дозволи 5. Переконайтеся, що Gateway запущено: `openclaw gateway status` -6. Перевірте логи: `openclaw logs --follow` +6. Перевірте журнали: `openclaw logs --follow` ### App Secret скомпрометовано @@ -237,19 +237,19 @@ openclaw pairing list feishu ### Обмеження повідомлень -- `textChunkLimit` — розмір фрагмента вихідного тексту (за замовчуванням: `2000` символів) -- `mediaMaxMb` — ліміт завантаження/вивантаження медіа (за замовчуванням: `30` МБ) +- `textChunkLimit` — розмір фрагмента вихідного тексту (типово: `2000` символів) +- `mediaMaxMb` — обмеження на завантаження/вивантаження медіа (типово: `30` МБ) -### Потокове передавання +### Streaming -Feishu/Lark підтримує потокові відповіді через інтерактивні картки. Коли це ввімкнено, бот оновлює картку в реальному часі під час генерації тексту. +Feishu/Lark підтримує потокові відповіді через інтерактивні картки. Якщо цю функцію ввімкнено, бот оновлює картку в реальному часі під час генерації тексту. ```json5 { channels: { feishu: { - streaming: true, // увімкнути виведення потокових карток (за замовчуванням: true) - blockStreaming: true, // увімкнути потокове передавання на рівні блоків (за замовчуванням: true) + streaming: true, // увімкнути потоковий вивід у картках (типово: true) + blockStreaming: true, // увімкнути потокову передачу на рівні блоків (типово: true) }, }, } @@ -261,8 +261,8 @@ Feishu/Lark підтримує потокові відповіді через і Зменште кількість викликів API Feishu/Lark за допомогою двох необов’язкових прапорців: -- `typingIndicator` (за замовчуванням `true`): установіть `false`, щоб пропустити виклики реакції набору тексту -- `resolveSenderNames` (за замовчуванням `true`): установіть `false`, щоб пропустити пошук профілів відправників +- `typingIndicator` (типово `true`): установіть `false`, щоб пропустити виклики реакцій друку +- `resolveSenderNames` (типово `true`): установіть `false`, щоб пропустити пошук профілів відправників ```json5 { @@ -277,9 +277,9 @@ Feishu/Lark підтримує потокові відповіді через і ### Сесії ACP -Feishu/Lark підтримує ACP для особистих повідомлень і повідомлень у гілках груп. ACP у Feishu/Lark керується текстовими командами — нативних меню slash-команд немає, тому використовуйте повідомлення `/acp ...` безпосередньо в розмові. +Feishu/Lark підтримує ACP для особистих повідомлень і повідомлень у гілках груп. ACP у Feishu/Lark керується текстовими командами — вбудованих меню slash-команд немає, тому використовуйте повідомлення `/acp ...` безпосередньо в розмові. -#### Постійна прив’язка ACP +#### Постійне прив’язування ACP ```json5 { @@ -331,7 +331,7 @@ Feishu/Lark підтримує ACP для особистих повідомле /acp spawn codex --thread here ``` -`--thread here` працює для особистих повідомлень і повідомлень у гілках Feishu/Lark. Подальші повідомлення в прив’язаній розмові маршрутизуються безпосередньо до цієї сесії ACP. +`--thread here` працює для особистих повідомлень і повідомлень у гілках Feishu/Lark. Подальші повідомлення в прив’язаній розмові будуть маршрутизуватися безпосередньо до цієї сесії ACP. ### Маршрутизація між кількома агентами @@ -368,10 +368,10 @@ Feishu/Lark підтримує ACP для особистих повідомле Поля маршрутизації: - `match.channel`: `"feishu"` -- `match.peer.kind`: `"direct"` (особисте повідомлення) або `"group"` (груповий чат) +- `match.peer.kind`: `"direct"` (особисті повідомлення) або `"group"` (груповий чат) - `match.peer.id`: Open ID користувача (`ou_xxx`) або ID групи (`oc_xxx`) -Поради щодо пошуку дивіться в розділі [Отримання ID групи/користувача](#get-groupuser-ids). +Поради щодо пошуку див. у [Отримання ID групи/користувача](#get-groupuser-ids). --- @@ -379,33 +379,33 @@ Feishu/Lark підтримує ACP для особистих повідомле Повна конфігурація: [Конфігурація Gateway](/uk/gateway/configuration) -| Setting | Опис | За замовчуванням | -| ------------------------------------------------- | ------------------------------------------- | ---------------- | -| `channels.feishu.enabled` | Увімкнути/вимкнути канал | `true` | -| `channels.feishu.domain` | Домен API (`feishu` або `lark`) | `feishu` | -| `channels.feishu.connectionMode` | Транспорт подій (`websocket` або `webhook`) | `websocket` | -| `channels.feishu.defaultAccount` | Обліковий запис за замовчуванням для вихідної маршрутизації | `default` | -| `channels.feishu.verificationToken` | Потрібно для режиму webhook | — | -| `channels.feishu.encryptKey` | Потрібно для режиму webhook | — | -| `channels.feishu.webhookPath` | Шлях маршруту Webhook | `/feishu/events` | -| `channels.feishu.webhookHost` | Хост прив’язки Webhook | `127.0.0.1` | -| `channels.feishu.webhookPort` | Порт прив’язки Webhook | `3000` | -| `channels.feishu.accounts..appId` | App ID | — | -| `channels.feishu.accounts..appSecret` | App Secret | — | -| `channels.feishu.accounts..domain` | Перевизначення домену для окремого облікового запису | `feishu` | -| `channels.feishu.dmPolicy` | Політика особистих повідомлень | `allowlist` | -| `channels.feishu.allowFrom` | Список дозволених для особистих повідомлень (список `open_id`) | [BotOwnerId] | -| `channels.feishu.groupPolicy` | Політика груп | `allowlist` | -| `channels.feishu.groupAllowFrom` | Список дозволених груп | — | -| `channels.feishu.requireMention` | Вимагати @згадку в групах | `true` | -| `channels.feishu.groups..requireMention` | Перевизначення @згадки для окремої групи | inherited | -| `channels.feishu.groups..enabled` | Увімкнути/вимкнути окрему групу | `true` | -| `channels.feishu.textChunkLimit` | Розмір фрагмента повідомлення | `2000` | -| `channels.feishu.mediaMaxMb` | Ліміт розміру медіа | `30` | -| `channels.feishu.streaming` | Виведення потокових карток | `true` | -| `channels.feishu.blockStreaming` | Потокове передавання на рівні блоків | `true` | -| `channels.feishu.typingIndicator` | Надсилати реакції набору тексту | `true` | -| `channels.feishu.resolveSenderNames` | Визначати відображувані імена відправників | `true` | +| Параметр | Опис | Типове значення | +| ------------------------------------------------ | -------------------------------------------- | ---------------- | +| `channels.feishu.enabled` | Увімкнути/вимкнути канал | `true` | +| `channels.feishu.domain` | Домен API (`feishu` або `lark`) | `feishu` | +| `channels.feishu.connectionMode` | Транспорт подій (`websocket` або `webhook`) | `websocket` | +| `channels.feishu.defaultAccount` | Типовий обліковий запис для вихідної маршрутизації | `default` | +| `channels.feishu.verificationToken` | Потрібний для режиму Webhook | — | +| `channels.feishu.encryptKey` | Потрібний для режиму Webhook | — | +| `channels.feishu.webhookPath` | Шлях маршруту Webhook | `/feishu/events` | +| `channels.feishu.webhookHost` | Хост прив’язки Webhook | `127.0.0.1` | +| `channels.feishu.webhookPort` | Порт прив’язки Webhook | `3000` | +| `channels.feishu.accounts..appId` | App ID | — | +| `channels.feishu.accounts..appSecret` | App Secret | — | +| `channels.feishu.accounts..domain` | Перевизначення домену для облікового запису | `feishu` | +| `channels.feishu.dmPolicy` | Політика особистих повідомлень | `allowlist` | +| `channels.feishu.allowFrom` | Список дозволених для особистих повідомлень (`open_id`) | [BotOwnerId] | +| `channels.feishu.groupPolicy` | Політика для груп | `allowlist` | +| `channels.feishu.groupAllowFrom` | Список дозволених груп | — | +| `channels.feishu.requireMention` | Вимагати @згадку в групах | `true` | +| `channels.feishu.groups..requireMention` | Перевизначення @згадки для окремої групи | inherited | +| `channels.feishu.groups..enabled` | Увімкнути/вимкнути конкретну групу | `true` | +| `channels.feishu.textChunkLimit` | Розмір фрагмента повідомлення | `2000` | +| `channels.feishu.mediaMaxMb` | Обмеження розміру медіа | `30` | +| `channels.feishu.streaming` | Потоковий вивід у картках | `true` | +| `channels.feishu.blockStreaming` | Потокова передача на рівні блоків | `true` | +| `channels.feishu.typingIndicator` | Надсилати реакції друку | `true` | +| `channels.feishu.resolveSenderNames` | Визначати відображувані імена відправників | `true` | --- @@ -428,21 +428,23 @@ Feishu/Lark підтримує ACP для особистих повідомле - ✅ Файли - ✅ Аудіо - ✅ Відео/медіа -- ✅ Інтерактивні картки (включно з потоковими оновленнями) -- ⚠️ Форматований текст (форматування у стилі post; не підтримує всі можливості створення вмісту Feishu/Lark) +- ✅ Інтерактивні картки (зокрема з потоковими оновленнями) +- ⚠️ Форматований текст (форматування у стилі post; не підтримує всі можливості авторингу Feishu/Lark) ### Гілки та відповіді - ✅ Вбудовані відповіді -- ✅ Відповіді у гілках -- ✅ Відповіді з медіа залишаються прив’язаними до гілки під час відповіді на повідомлення в гілці +- ✅ Відповіді в гілках +- ✅ Відповіді з медіа зберігають прив’язку до гілки під час відповіді на повідомлення в гілці + +Для `groupSessionScope: "group_topic"` і `"group_topic_sender"` власні тематичні групи Feishu/Lark використовують подію `thread_id` (`omt_*`) як канонічний ключ сесії теми. Звичайні відповіді в групі, які OpenClaw перетворює на гілки, і далі використовують ID кореневого повідомлення відповіді (`om_*`), щоб перший хід і наступний хід залишалися в межах однієї сесії. --- ## Пов’язане - [Огляд каналів](/uk/channels) — усі підтримувані канали -- [Сполучення](/uk/channels/pairing) — автентифікація особистих повідомлень і процес сполучення -- [Групи](/uk/channels/groups) — поведінка групових чатів і обмеження через згадки +- [Сполучення](/uk/channels/pairing) — автентифікація в особистих повідомленнях і процес сполучення +- [Групи](/uk/channels/groups) — поведінка групового чату та вимога згадки - [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень -- [Безпека](/uk/gateway/security) — модель доступу та посилення захисту +- [Безпека](/uk/gateway/security) — модель доступу та зміцнення захисту diff --git a/docs/uk/cli/mcp.md b/docs/uk/cli/mcp.md index ea0faf3c7..d1e0598c8 100644 --- a/docs/uk/cli/mcp.md +++ b/docs/uk/cli/mcp.md @@ -1,37 +1,35 @@ --- read_when: - - Підключення Codex, Claude Code або іншого клієнта MCP до каналів на основі OpenClaw + - Підключення Codex, Claude Code або іншого клієнта MCP до каналів на базі OpenClaw - Запуск `openclaw mcp serve` - Керування збереженими в OpenClaw визначеннями серверів MCP -summary: Відкривайте доступ до розмов каналів OpenClaw через MCP і керуйте збереженими визначеннями серверів MCP +summary: Відкрийте доступ до розмов каналів OpenClaw через MCP і керуйте збереженими визначеннями серверів MCP title: MCP x-i18n: - generated_at: "2026-04-24T03:15:24Z" + generated_at: "2026-04-25T07:01:56Z" model: gpt-5.4 provider: openai - source_hash: b9df42ebc547f07698f84888d8cd6125340d0f0e02974a965670844589e1fbf8 + source_hash: 43505ab290d01a2c3f7dd9ff39b8a074360ba4365b628da71459c6f9a9659dc5 source_path: cli/mcp.md workflow: 15 --- -`openclaw mcp` має два завдання: +`openclaw mcp` має дві задачі: -- запускати OpenClaw як MCP-сервер за допомогою `openclaw mcp serve` -- керувати визначеннями вихідних MCP-серверів, що належать OpenClaw, за допомогою `list`, `show`, +- запускати OpenClaw як сервер MCP за допомогою `openclaw mcp serve` +- керувати визначеннями вихідних серверів MCP, якими володіє OpenClaw, за допомогою `list`, `show`, `set` і `unset` Іншими словами: -- `serve` — це OpenClaw, що діє як MCP-сервер -- `list` / `show` / `set` / `unset` — це OpenClaw, що діє як клієнтський - реєстр для інших MCP-серверів, які його середовища виконання можуть - використовувати пізніше +- `serve` — це OpenClaw, що працює як сервер MCP +- `list` / `show` / `set` / `unset` — це OpenClaw, що працює як реєстр на боці клієнта MCP + для інших серверів MCP, які його середовища виконання можуть використати пізніше -Використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має самостійно -розміщувати сесію середовища кодування та маршрутизувати це середовище -виконання через ACP. +Використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має сам розміщувати +сеанс coding harness і маршрутизувати це середовище виконання через ACP. -## OpenClaw як MCP-сервер +## OpenClaw як сервер MCP Це шлях `openclaw mcp serve`. @@ -39,19 +37,19 @@ x-i18n: Використовуйте `openclaw mcp serve`, коли: -- Codex, Claude Code або інший клієнт MCP має безпосередньо взаємодіяти - з розмовами каналів на основі OpenClaw -- у вас уже є локальний або віддалений Gateway OpenClaw із маршрутизованими сесіями -- вам потрібен один MCP-сервер, який працює через канальні бекенди OpenClaw, +- Codex, Claude Code або інший клієнт MCP має напряму взаємодіяти з + розмовами каналів на базі OpenClaw +- у вас уже є локальний або віддалений Gateway OpenClaw із маршрутизованими сеансами +- вам потрібен один сервер MCP, який працює через серверні частини каналів OpenClaw, замість запуску окремих мостів для кожного каналу -Натомість використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має сам -розміщувати середовище виконання кодування та зберігати сесію агента всередині OpenClaw. +Натомість використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має сам розміщувати +середовище виконання coding і тримати сеанс агента всередині OpenClaw. ## Як це працює -`openclaw mcp serve` запускає stdio MCP-сервер. Клієнт MCP володіє цим -процесом. Поки клієнт тримає stdio-сесію відкритою, міст підключається до +`openclaw mcp serve` запускає сервер MCP через stdio. Клієнт MCP володіє цим +процесом. Поки клієнт тримає сеанс stdio відкритим, міст підключається до локального або віддаленого Gateway OpenClaw через WebSocket і відкриває маршрутизовані розмови каналів через MCP. @@ -59,55 +57,55 @@ x-i18n: 1. клієнт MCP запускає `openclaw mcp serve` 2. міст підключається до Gateway -3. маршрутизовані сесії стають MCP-розмовами та інструментами стенограми/історії +3. маршрутизовані сеанси стають розмовами MCP та інструментами transcript/history 4. живі події ставляться в чергу в пам’яті, поки міст підключений -5. якщо ввімкнено режим каналу Claude, та сама сесія також може отримувати - специфічні для Claude push-сповіщення +5. якщо увімкнено режим каналу Claude, той самий сеанс також може отримувати + push-сповіщення, специфічні для Claude Важлива поведінка: - стан живої черги починається, коли міст підключається -- старіша історія стенограми читається через `messages_read` -- push-сповіщення Claude існують лише поки жива MCP-сесія -- коли клієнт відключається, міст завершує роботу, і жива черга зникає -- stdio MCP-сервери, запущені OpenClaw (вбудовані або налаштовані користувачем), зупиняються +- старіша історія transcript читається через `messages_read` +- push-сповіщення Claude існують лише поки активний сеанс MCP +- коли клієнт від’єднується, міст завершує роботу, і жива черга зникає +- сервери stdio MCP, запущені OpenClaw (вбудовані або налаштовані користувачем), завершуються як дерево процесів під час вимкнення, тому дочірні підпроцеси, запущені - сервером, не зберігаються після завершення батьківського stdio-клієнта -- видалення або скидання сесії звільняє MCP-клієнти цієї сесії через - спільний шлях очищення середовища виконання, тому не залишається жодних - завислих stdio-з’єднань, пов’язаних із видаленою сесією + сервером, не виживають після завершення батьківського клієнта stdio +- видалення або скидання сеансу звільняє клієнтів MCP цього сеансу через + спільний шлях очищення середовища виконання, тож не залишається завислих + stdio-з’єднань, прив’язаних до вилученого сеансу ## Вибір режиму клієнта -Використовуйте той самий міст двома різними способами: +Той самий міст можна використовувати двома різними способами: -- Загальні клієнти MCP: лише стандартні інструменти MCP. Використовуйте `conversations_list`, +- Звичайні клієнти MCP: лише стандартні інструменти MCP. Використовуйте `conversations_list`, `messages_read`, `events_poll`, `events_wait`, `messages_send` та - інструменти схвалення. + інструменти погодження. - Claude Code: стандартні інструменти MCP плюс адаптер каналу, специфічний для Claude. - Увімкніть `--claude-channel-mode on` або залиште типове значення `auto`. + Увімкніть `--claude-channel-mode on` або залиште значення за замовчуванням `auto`. Наразі `auto` поводиться так само, як `on`. Виявлення можливостей клієнта -ще не реалізовано. +ще немає. ## Що відкриває `serve` -Міст використовує наявні метадані маршруту сесії Gateway, щоб відкривати -розмови, прив’язані до каналу. Розмова з’являється, коли OpenClaw уже має -стан сесії з відомим маршрутом, таким як: +Міст використовує наявні метадані маршруту сеансу Gateway, щоб відкривати +розмови, прив’язані до каналів. Розмова з’являється, коли OpenClaw уже має стан +сеансу з відомим маршрутом, таким як: - `channel` -- метадані одержувача або призначення +- метадані отримувача або призначення - необов’язковий `accountId` - необов’язковий `threadId` -Це дає клієнтам MCP одну точку, щоб: +Це дає клієнтам MCP єдине місце, де можна: -- перелічувати нещодавні маршрутизовані розмови -- читати нещодавню історію стенограми -- очікувати нові вхідні події +- переглядати список нещодавніх маршрутизованих розмов +- читати недавню історію transcript +- чекати нові вхідні події - надсилати відповідь назад тим самим маршрутом -- бачити запити на схвалення, які надходять, поки міст підключений +- бачити запити на погодження, які надходять, поки міст підключений ## Використання @@ -118,17 +116,17 @@ openclaw mcp serve # Віддалений Gateway openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token -# Віддалений Gateway з автентифікацією паролем +# Віддалений Gateway з автентифікацією за паролем openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password -# Увімкнути докладні журнали моста +# Увімкнути докладні журнали мосту openclaw mcp serve --verbose # Вимкнути push-сповіщення, специфічні для Claude openclaw mcp serve --claude-channel-mode off ``` -## Інструменти моста +## Інструменти мосту Поточний міст відкриває такі інструменти MCP: @@ -144,8 +142,8 @@ openclaw mcp serve --claude-channel-mode off ### `conversations_list` -Перелічує нещодавні розмови, прив’язані до сесії, які вже мають метадані -маршруту в стані сесії Gateway. +Показує список нещодавніх розмов, прив’язаних до сеансів, які вже мають +метадані маршруту в стані сеансу Gateway. Корисні фільтри: @@ -161,43 +159,44 @@ openclaw mcp serve --claude-channel-mode off ### `messages_read` -Читає нещодавні повідомлення стенограми для однієї розмови, прив’язаної до сесії. +Читає недавні повідомлення transcript для однієї розмови, прив’язаної до сеансу. ### `attachments_fetch` -Витягує нетекстові блоки вмісту повідомлення з одного повідомлення стенограми. Це -подання метаданих поверх вмісту стенограми, а не окреме довговічне сховище blob-вкладень. +Витягує нетекстові блоки вмісту повідомлення з одного повідомлення transcript. Це +подання метаданих поверх вмісту transcript, а не окреме стійке сховище +вкладень blob. ### `events_poll` -Читає поставлені в чергу живі події, починаючи з числового курсора. +Читає поставлені в чергу живі події від числового курсора. ### `events_wait` -Виконує long-polling, доки не надійде наступна відповідна поставлена в чергу подія -або не спливе час очікування. +Виконує long-polling, доки не надійде наступна відповідна поставлена в чергу +подія або не спливе час очікування. -Використовуйте це, коли загальному клієнту MCP потрібна доставка, близька до -реального часу, без push-протоколу, специфічного для Claude. +Використовуйте це, коли звичайному клієнту MCP потрібна доставка, близька до +реального часу, без протоколу push, специфічного для Claude. ### `messages_send` -Надсилає текст назад тим самим маршрутом, уже записаним у сесії. +Надсилає текст назад тим самим маршрутом, уже збереженим у сеансі. Поточна поведінка: - потребує наявного маршруту розмови -- використовує канал сесії, одержувача, id облікового запису та id треду +- використовує канал сеансу, отримувача, id облікового запису та id треду - надсилає лише текст ### `permissions_list_open` -Перелічує очікувальні запити на схвалення exec/Plugin, які міст спостерігав -після підключення до Gateway. +Показує список очікуваних запитів на погодження exec/plugin, які міст спостерігав +від моменту підключення до Gateway. ### `permissions_respond` -Вирішує один очікувальний запит на схвалення exec/Plugin за допомогою: +Вирішує один очікуваний запит на погодження exec/plugin за допомогою: - `allow-once` - `allow-always` @@ -205,7 +204,7 @@ openclaw mcp serve --claude-channel-mode off ## Модель подій -Міст зберігає чергу подій у пам’яті, поки він підключений. +Міст тримає в пам’яті чергу подій, поки він підключений. Поточні типи подій: @@ -218,22 +217,22 @@ openclaw mcp serve --claude-channel-mode off Важливі обмеження: -- черга є лише живою; вона починається, коли запускається міст MCP +- черга лише жива; вона починається, коли запускається міст MCP - `events_poll` і `events_wait` самі по собі не відтворюють старішу історію Gateway -- довговічне відставання слід читати через `messages_read` +- стійкий backlog слід читати через `messages_read` ## Сповіщення каналу Claude Міст також може відкривати сповіщення каналу, специфічні для Claude. Це еквівалент OpenClaw для адаптера каналу Claude Code: стандартні інструменти MCP залишаються доступними, але живі вхідні повідомлення також можуть надходити як -специфічні для Claude MCP-сповіщення. +специфічні для Claude сповіщення MCP. Прапорці: - `--claude-channel-mode off`: лише стандартні інструменти MCP - `--claude-channel-mode on`: увімкнути сповіщення каналу Claude -- `--claude-channel-mode auto`: поточне типове значення; така сама поведінка моста, як у `on` +- `--claude-channel-mode auto`: поточне значення за замовчуванням; така сама поведінка мосту, як у `on` Коли режим каналу Claude увімкнено, сервер оголошує експериментальні можливості Claude і може надсилати: @@ -241,22 +240,22 @@ openclaw mcp serve --claude-channel-mode off - `notifications/claude/channel` - `notifications/claude/channel/permission` -Поточна поведінка моста: +Поточна поведінка мосту: -- вхідні повідомлення стенограми `user` пересилаються як +- вхідні повідомлення transcript типу `user` пересилаються як `notifications/claude/channel` -- запити на дозволи Claude, отримані через MCP, відстежуються в пам’яті -- якщо пов’язана розмова пізніше надсилає `yes abcde` або `no abcde`, міст +- запити на погодження Claude, отримані через MCP, відстежуються в пам’яті +- якщо пізніше пов’язана розмова надішле `yes abcde` або `no abcde`, міст перетворює це на `notifications/claude/channel/permission` -- ці сповіщення доступні лише в живій сесії; якщо клієнт MCP відключається, - ціль для push більше не існує +- ці сповіщення доступні лише в межах живого сеансу; якщо клієнт MCP + від’єднається, цілі для push більше не буде -Це навмисно специфічно для клієнта. Загальні клієнти MCP мають покладатися на -стандартні інструменти опитування. +Це навмисно орієнтовано на конкретного клієнта. Звичайні клієнти MCP повинні +покладатися на стандартні інструменти опитування. ## Конфігурація клієнта MCP -Приклад конфігурації stdio-клієнта: +Приклад конфігурації клієнта stdio: ```json { @@ -276,8 +275,8 @@ openclaw mcp serve --claude-channel-mode off } ``` -Для більшості загальних клієнтів MCP починайте зі стандартної поверхні -інструментів і ігноруйте режим Claude. Увімкніть режим Claude лише для +Для більшості звичайних клієнтів MCP починайте зі стандартної поверхні +інструментів та ігноруйте режим Claude. Увімкніть режим Claude лише для клієнтів, які справді розуміють методи сповіщень, специфічні для Claude. ## Параметри @@ -295,27 +294,26 @@ openclaw mcp serve --claude-channel-mode off За можливості віддавайте перевагу `--token-file` або `--password-file` замість вбудованих секретів. -## Безпека та межа довіри +## Межа безпеки й довіри Міст не вигадує маршрутизацію. Він лише відкриває розмови, які Gateway уже вміє маршрутизувати. Це означає: -- списки дозволених відправників, спарювання та довіра на рівні каналу як і раніше - належать базовій конфігурації каналу OpenClaw +- allowlist відправників, pairing і довіра на рівні каналу все ще належать + до базової конфігурації каналу OpenClaw - `messages_send` може відповідати лише через наявний збережений маршрут -- стан схвалення є лише живим/у пам’яті для поточної сесії моста -- автентифікація моста має використовувати ті самі засоби контролю токена або пароля Gateway, +- стан погодження є лише живим/в пам’яті для поточного сеансу мосту +- автентифікація мосту має використовувати ті самі елементи контролю токена або пароля Gateway, яким ви б довіряли для будь-якого іншого віддаленого клієнта Gateway Якщо розмова відсутня в `conversations_list`, типовою причиною є не -конфігурація MCP. Це відсутні або неповні метадані маршруту в базовій -сесії Gateway. +конфігурація MCP. Це відсутні або неповні метадані маршруту в базовому сеансі Gateway. ## Тестування -OpenClaw постачає детермінований Docker smoke-тест для цього моста: +OpenClaw постачається з детермінованим Docker smoke-тестом для цього мосту: ```bash pnpm test:docker:mcp-channels @@ -323,72 +321,75 @@ pnpm test:docker:mcp-channels Цей smoke-тест: -- запускає контейнер Gateway із підготовленими даними -- запускає другий контейнер, який запускає `openclaw mcp serve` -- перевіряє виявлення розмов, читання стенограм, читання метаданих вкладень, +- запускає контейнер Gateway із попередньо підготовленими даними +- запускає другий контейнер, який викликає `openclaw mcp serve` +- перевіряє виявлення розмов, читання transcript, читання метаданих вкладень, поведінку черги живих подій і маршрутизацію вихідних надсилань -- перевіряє сповіщення в стилі Claude для каналу та дозволів через реальний - stdio MCP-міст +- перевіряє сповіщення каналів і погоджень у стилі Claude через реальний + міст stdio MCP Це найшвидший спосіб довести, що міст працює, без підключення реального облікового запису Telegram, Discord або iMessage до тестового запуску. -Для ширшого контексту тестування див. [Testing](/uk/help/testing). +Для ширшого контексту тестування дивіться [Testing](/uk/help/testing). -## Усунення несправностей +## Усунення проблем -### Не повертаються розмови +### Не повертаються жодні розмови -Зазвичай це означає, що сесія Gateway ще не придатна для маршрутизації. -Підтвердьте, що базова сесія має збережені метадані маршруту каналу/провайдера, -одержувача та необов’язкового облікового запису/треду. +Зазвичай це означає, що сеанс Gateway ще не придатний для маршрутизації. +Підтвердьте, що базовий сеанс має збережені channel/provider, отримувача та +необов’язкові метадані маршруту account/thread. ### `events_poll` або `events_wait` пропускає старіші повідомлення Це очікувано. Жива черга починається, коли міст підключається. Читайте старішу -історію стенограми через `messages_read`. +історію transcript через `messages_read`. ### Сповіщення Claude не з’являються -Перевірте все з наведеного: +Перевірте все з цього списку: -- клієнт тримав stdio MCP-сесію відкритою +- клієнт тримав сеанс stdio MCP відкритим - `--claude-channel-mode` має значення `on` або `auto` - клієнт справді розуміє методи сповіщень, специфічні для Claude -- вхідне повідомлення сталося після підключення моста +- вхідне повідомлення сталося після підключення мосту -### Відсутні схвалення +### Відсутні погодження -`permissions_list_open` показує лише запити на схвалення, спостережені під час -підключення моста. Це не API довговічної історії схвалень. +`permissions_list_open` показує лише запити на погодження, спостережені, поки +міст був підключений. Це не API стійкої історії погоджень. -## OpenClaw як реєстр MCP-клієнта +## OpenClaw як реєстр клієнтів MCP Це шлях `openclaw mcp list`, `show`, `set` і `unset`. -Ці команди не відкривають OpenClaw через MCP. Вони керують визначеннями -MCP-серверів, що належать OpenClaw, у `mcp.servers` в конфігурації OpenClaw. +Ці команди не відкривають OpenClaw через MCP. Вони керують визначеннями серверів MCP, +якими володіє OpenClaw, у `mcp.servers` у конфігурації OpenClaw. Ці збережені визначення призначені для середовищ виконання, які OpenClaw -запускає або налаштовує пізніше, таких як вбудований Pi та інші адаптери -середовища виконання. OpenClaw централізовано зберігає визначення, щоб цим -середовищам виконання не доводилося тримати власні дублікати списків MCP-серверів. +запускає або налаштовує пізніше, наприклад вбудований Pi та інші адаптери +середовища виконання. OpenClaw зберігає визначення централізовано, щоб цим +середовищам не потрібно було підтримувати власні дубльовані списки серверів MCP. Важлива поведінка: - ці команди лише читають або записують конфігурацію OpenClaw -- вони не підключаються до цільового MCP-сервера +- вони не підключаються до цільового сервера MCP - вони не перевіряють, чи команда, URL або віддалений транспорт доступні прямо зараз -- адаптери середовища виконання вирішують, які форми транспорту вони фактично підтримують - під час виконання -- вбудований Pi відкриває налаштовані MCP-інструменти у звичайних профілях +- адаптери середовища виконання самі вирішують, які форми транспорту вони + фактично підтримують під час виконання +- вбудований Pi відкриває налаштовані інструменти MCP у звичайних профілях інструментів `coding` і `messaging`; `minimal` усе ще приховує їх, а `tools.deny: ["bundle-mcp"]` явно вимикає їх +- вбудовані середовища виконання MCP, прив’язані до сеансу, прибираються після + `mcp.sessionIdleTtlMs` мілісекунд простою (типово 10 хвилин; встановіть `0`, + щоб вимкнути), а одноразові вбудовані запуски очищають їх наприкінці виконання -## Збережені визначення MCP-серверів +## Збережені визначення серверів MCP -OpenClaw також зберігає в конфігурації полегшений реєстр MCP-серверів для +OpenClaw також зберігає в конфігурації легковажний реєстр серверів MCP для поверхонь, яким потрібні визначення MCP, керовані OpenClaw. Команди: @@ -400,10 +401,10 @@ OpenClaw також зберігає в конфігурації полегше Примітки: -- `list` сортує назви серверів. -- `show` без назви виводить повний налаштований об’єкт MCP-серверів. -- `set` очікує одне значення об’єкта JSON у командному рядку. -- `unset` завершується з помилкою, якщо іменований сервер не існує. +- `list` сортує імена серверів. +- `show` без імені виводить повний налаштований об’єкт сервера MCP. +- `set` очікує одне значення JSON-об’єкта в командному рядку. +- `unset` завершується помилкою, якщо сервера з вказаним іменем не існує. Приклади: @@ -433,32 +434,32 @@ openclaw mcp unset context7 } ``` -### Транспорт stdio +### Транспорт Stdio -Запускає локальний дочірній процес і взаємодіє через stdin/stdout. +Запускає локальний дочірній процес і спілкується через stdin/stdout. -| Field | Description | -| -------------------------- | --------------------------------- | +| Поле | Опис | +| -------------------------- | ----------------------------------- | | `command` | Виконуваний файл для запуску (обов’язково) | -| `args` | Масив аргументів командного рядка | -| `env` | Додаткові змінні середовища | -| `cwd` / `workingDirectory` | Робочий каталог для процесу | +| `args` | Масив аргументів командного рядка | +| `env` | Додаткові змінні середовища | +| `cwd` / `workingDirectory` | Робочий каталог для процесу | -#### Фільтр безпеки env для stdio +#### Фільтр безпеки env для Stdio -OpenClaw відхиляє ключі env запуску інтерпретатора, які можуть змінити спосіб запуску stdio MCP-сервера до першого RPC, навіть якщо вони присутні в блоці `env` сервера. Заблоковані ключі включають `NODE_OPTIONS`, `PYTHONSTARTUP`, `PYTHONPATH`, `PERL5OPT`, `RUBYOPT`, `SHELLOPTS`, `PS4` та подібні змінні керування середовищем виконання. Запуск відхиляє їх із помилкою конфігурації, щоб вони не могли впровадити неявну преамбулу, підмінити інтерпретатор або ввімкнути налагоджувач для stdio-процесу. Звичайні облікові дані, проксі та змінні середовища, специфічні для сервера (`GITHUB_TOKEN`, `HTTP_PROXY`, користувацькі `*_API_KEY` тощо), не зачіпаються. +OpenClaw відхиляє ключі env запуску інтерпретатора, які можуть змінити спосіб запуску сервера stdio MCP до першого RPC, навіть якщо вони присутні в блоці `env` сервера. Заблоковані ключі включають `NODE_OPTIONS`, `PYTHONSTARTUP`, `PYTHONPATH`, `PERL5OPT`, `RUBYOPT`, `SHELLOPTS`, `PS4` та подібні змінні керування середовищем виконання. Запуск відхиляє їх з помилкою конфігурації, щоб вони не могли впровадити неявний пролог, підмінити інтерпретатор або ввімкнути налагоджувач для процесу stdio. Звичайні змінні середовища для облікових даних, proxy та специфічні для сервера (`GITHUB_TOKEN`, `HTTP_PROXY`, власні `*_API_KEY` тощо) не зачіпаються. -Якщо вашому MCP-серверу справді потрібна одна із заблокованих змінних, задайте її в процесі хоста Gateway, а не в `env` stdio-сервера. +Якщо вашому серверу MCP справді потрібна одна із заблокованих змінних, задайте її в процесі хоста Gateway, а не в `env` сервера stdio. ### Транспорт SSE / HTTP -Підключається до віддаленого MCP-сервера через HTTP Server-Sent Events. +Підключається до віддаленого сервера MCP через HTTP Server-Sent Events. -| Field | Description | +| Поле | Опис | | --------------------- | ---------------------------------------------------------------- | | `url` | URL HTTP або HTTPS віддаленого сервера (обов’язково) | -| `headers` | Необов’язкова карта ключ-значення HTTP-заголовків (наприклад, токени автентифікації) | -| `connectionTimeoutMs` | Тайм-аут підключення для окремого сервера в мс (необов’язково) | +| `headers` | Необов’язкова карта HTTP-заголовків ключ-значення (наприклад, токени автентифікації) | +| `connectionTimeoutMs` | Тайм-аут підключення для сервера в мс (необов’язково) | Приклад: @@ -477,19 +478,19 @@ OpenClaw відхиляє ключі env запуску інтерпретато } ``` -Чутливі значення в `url` (userinfo) і `headers` маскуються в журналах і +Чутливі значення в `url` (userinfo) і `headers` маскуються в журналах та виводі стану. ### Транспорт Streamable HTTP -`streamable-http` — це додатковий варіант транспорту поряд із `sse` і `stdio`. Він використовує HTTP-streaming для двостороннього зв’язку з віддаленими MCP-серверами. +`streamable-http` — це додатковий варіант транспорту поряд із `sse` і `stdio`. Він використовує потоковий HTTP для двостороннього зв’язку з віддаленими серверами MCP. -| Field | Description | -| --------------------- | -------------------------------------------------------------------------------------- | -| `url` | URL HTTP або HTTPS віддаленого сервера (обов’язково) | +| Поле | Опис | +| --------------------- | ------------------------------------------------------------------------------------ | +| `url` | URL HTTP або HTTPS віддаленого сервера (обов’язково) | | `transport` | Встановіть `"streamable-http"`, щоб вибрати цей транспорт; якщо не вказано, OpenClaw використовує `sse` | -| `headers` | Необов’язкова карта ключ-значення HTTP-заголовків (наприклад, токени автентифікації) | -| `connectionTimeoutMs` | Тайм-аут підключення для окремого сервера в мс (необов’язково) | +| `headers` | Необов’язкова карта HTTP-заголовків ключ-значення (наприклад, токени автентифікації) | +| `connectionTimeoutMs` | Тайм-аут підключення для сервера в мс (необов’язково) | Приклад: @@ -511,23 +512,23 @@ OpenClaw відхиляє ключі env запуску інтерпретато ``` Ці команди керують лише збереженою конфігурацією. Вони не запускають міст -каналу, не відкривають живу сесію MCP-клієнта і не доводять, що цільовий +каналу, не відкривають живий сеанс клієнта MCP і не доводять, що цільовий сервер доступний. ## Поточні обмеження -Ця сторінка документує міст у тому вигляді, у якому він постачається сьогодні. +Ця сторінка документує міст у тому вигляді, в якому він постачається сьогодні. Поточні обмеження: -- виявлення розмов залежить від наявних метаданих маршруту сесії Gateway +- виявлення розмов залежить від наявних метаданих маршруту сеансу Gateway - немає загального push-протоколу, окрім адаптера, специфічного для Claude -- інструментів редагування повідомлень або реакцій поки немає +- поки немає інструментів редагування повідомлень або react - транспорт HTTP/SSE/streamable-http підключається до одного віддаленого сервера; мультиплексованого upstream поки немає -- `permissions_list_open` включає лише схвалення, спостережені, поки міст +- `permissions_list_open` включає лише погодження, спостережені, поки міст був підключений ## Пов’язане -- [Довідник CLI](/uk/cli) -- [Plugins](/uk/cli/plugins) +- [Довідка CLI](/uk/cli) +- [Плагіни](/uk/cli/plugins) diff --git a/docs/uk/cli/models.md b/docs/uk/cli/models.md index f1c93fafb..8797cac0e 100644 --- a/docs/uk/cli/models.md +++ b/docs/uk/cli/models.md @@ -1,26 +1,26 @@ --- read_when: - - Ви хочете змінити типові моделі або переглянути стан автентифікації провайдера + - Ви хочете змінити моделі за замовчуванням або переглянути статус автентифікації провайдера - Ви хочете просканувати доступні моделі/провайдерів і налагодити профілі автентифікації summary: Довідка CLI для `openclaw models` (status/list/set/scan, псевдоніми, резервні варіанти, автентифікація) title: Моделі x-i18n: - generated_at: "2026-04-24T03:15:35Z" + generated_at: "2026-04-25T07:01:56Z" model: gpt-5.4 provider: openai - source_hash: 08e04342ef240bf7a1f60c4d4e2667d17c9a97e985c1b170db8538c890dc8119 + source_hash: 2755657b334b8722da06e31fa1d69a5dced3d74e5aeadd38d625039f15911d69 source_path: cli/models.md workflow: 15 --- # `openclaw models` -Виявлення моделей, сканування та конфігурація (типова модель, резервні варіанти, профілі автентифікації). +Виявлення моделей, сканування та конфігурація (модель за замовчуванням, резервні варіанти, профілі автентифікації). Пов’язане: - Провайдери + моделі: [Моделі](/uk/providers/models) -- Концепції вибору моделі + слеш-команда `/models`: [Концепція моделей](/uk/concepts/models) +- Концепції вибору моделей + слеш-команда `/models`: [Концепція моделей](/uk/concepts/models) - Налаштування автентифікації провайдера: [Початок роботи](/uk/start/getting-started) ## Поширені команди @@ -32,42 +32,46 @@ openclaw models set openclaw models scan ``` -`openclaw models status` показує визначені типові/резервні варіанти, а також огляд автентифікації. -Коли доступні знімки використання провайдера, розділ стану OAuth/API key містить +`openclaw models status` показує визначені модель за замовчуванням/резервні варіанти, а також огляд автентифікації. +Коли доступні знімки використання провайдера, розділ статусу OAuth/API-ключів містить вікна використання провайдера та знімки квот. Поточні провайдери з вікнами використання: Anthropic, GitHub Copilot, Gemini CLI, OpenAI -Codex, MiniMax, Xiaomi і z.ai. Дані автентифікації використання надходять із хуків, -специфічних для провайдера, коли вони доступні; інакше OpenClaw повертається до зіставлення облікових даних -OAuth/API key з профілів автентифікації, середовища або конфігурації. -У виводі `--json` `auth.providers` — це огляд провайдерів з урахуванням env/config/store, -тоді як `auth.oauth` — це лише стан профілів сховища автентифікації. +Codex, MiniMax, Xiaomi і z.ai. Автентифікація використання надходить із хуків, +специфічних для провайдера, коли вони доступні; інакше OpenClaw використовує резервний варіант і підбирає OAuth/API-key +облікові дані з профілів автентифікації, змінних середовища або конфігурації. +У виводі `--json` `auth.providers` — це огляд провайдера з урахуванням env/config/store, +тоді як `auth.oauth` — це лише стан профілів у сховищі автентифікації. Додайте `--probe`, щоб виконати живі перевірки автентифікації для кожного налаштованого профілю провайдера. -Перевірки є реальними запитами (можуть споживати токени та спричиняти обмеження швидкості). -Використовуйте `--agent `, щоб перевірити стан моделі/автентифікації налаштованого агента. Якщо параметр не вказано, +Перевірки є реальними запитами (можуть витрачати токени та спричиняти обмеження швидкості). +Використовуйте `--agent `, щоб перевірити стан моделі/автентифікації налаштованого агента. Якщо цей параметр не вказано, команда використовує `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`, якщо вони задані, інакше — -налаштованого типового агента. -Рядки перевірки можуть походити з профілів автентифікації, облікових даних середовища або `models.json`. +налаштованого агента за замовчуванням. +Рядки перевірок можуть надходити з профілів автентифікації, облікових даних середовища або `models.json`. Примітки: - `models set ` приймає `provider/model` або псевдонім. -- `models list` є лише для читання: вона читає конфігурацію, профілі автентифікації, наявний стан каталогу +- `models list` є лише для читання: команда читає конфігурацію, профілі автентифікації, наявний стан каталогу та рядки каталогу, що належать провайдеру, але не перезаписує `models.json`. - `models list --all` включає вбудовані статичні рядки каталогу, що належать провайдеру, навіть - якщо ви ще не пройшли автентифікацію в цього провайдера. Такі рядки все одно показуються + якщо ви ще не автентифікувалися в цього провайдера. Такі рядки все одно показуються як недоступні, доки не буде налаштовано відповідну автентифікацію. +- `models list` зберігає власні метадані моделі та обмеження середовища виконання окремо. У табличному + виводі `Ctx` показує `contextTokens/contextWindow`, коли ефективне обмеження середовища виконання + відрізняється від власного вікна контексту; рядки JSON містять `contextTokens`, + якщо провайдер надає це обмеження. - `models list --provider ` фільтрує за ідентифікатором провайдера, наприклад `moonshot` або - `openai-codex`. Він не приймає відображувані мітки з інтерактивних засобів вибору провайдера, + `openai-codex`. Команда не приймає відображувані мітки з інтерактивних засобів вибору провайдера, такі як `Moonshot AI`. -- Посилання на моделі розбираються розділенням за **першим** `/`. Якщо ідентифікатор моделі містить `/` (у стилі OpenRouter), додайте префікс провайдера (приклад: `openrouter/moonshotai/kimi-k2`). -- Якщо ви пропускаєте провайдера, OpenClaw спочатку визначає введене значення як псевдонім, потім — - як унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише після цього - повертається до налаштованого типового провайдера з попередженням про застарілість. - Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw - повертається до першого налаштованого провайдера/моделі замість показу - застарілого типового значення від видаленого провайдера. -- `models status` може показувати `marker()` у виводі автентифікації для не секретних заповнювачів (наприклад `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) замість маскування їх як секретів. +- Посилання на моделі розбираються шляхом поділу за **першим** `/`. Якщо ідентифікатор моделі містить `/` (у стилі OpenRouter), додайте префікс провайдера (приклад: `openrouter/moonshotai/kimi-k2`). +- Якщо ви не вказали провайдера, OpenClaw спочатку визначає введення як псевдонім, потім — + як унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише потім + використовує резервний варіант — налаштованого провайдера за замовчуванням — із попередженням про застарілість. + Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw + використовує резервний варіант — перший налаштований провайдер/модель — замість показу + застарілого значення за замовчуванням для видаленого провайдера. +- `models status` може показувати `marker()` у виводі автентифікації для незасекречених заповнювачів (наприклад `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) замість маскування їх як секретів. ### `models status` @@ -84,7 +88,7 @@ OAuth/API key з профілів автентифікації, середови - `--probe-max-tokens ` - `--agent ` (ідентифікатор налаштованого агента; перевизначає `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`) -Категорії стану перевірки: +Групи статусів перевірки: - `ok` - `auth` @@ -95,15 +99,15 @@ OAuth/API key з профілів автентифікації, середови - `unknown` - `no_model` -Випадки деталей/кодів причин перевірки, на які варто очікувати: +Варіанти detail/reason-code перевірки, яких варто очікувати: - `excluded_by_auth_order`: збережений профіль існує, але явний `auth.order.` його пропустив, тому перевірка повідомляє про виключення замість спроби його використати. - `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`: - профіль присутній, але не підходить/не може бути визначений. -- `no_model`: автентифікація провайдера існує, але OpenClaw не зміг визначити - кандидата моделі для перевірки для цього провайдера. + профіль присутній, але не є придатним/не може бути визначений. +- `no_model`: автентифікація провайдера існує, але OpenClaw не зміг визначити придатний для перевірки + кандидат моделі для цього провайдера. ## Псевдоніми + резервні варіанти @@ -123,9 +127,9 @@ openclaw models auth paste-token `models auth add` — це інтерактивний помічник автентифікації. Він може запускати потік автентифікації провайдера (OAuth/API key) або провести вас через ручне вставлення токена, залежно від -вибраного провайдера. +обраного провайдера. -`models auth login` запускає потік автентифікації Plugin провайдера (OAuth/API key). Використовуйте +`models auth login` запускає потік автентифікації плагіна провайдера (OAuth/API key). Використовуйте `openclaw plugins list`, щоб побачити, які провайдери встановлено. Приклади: @@ -136,21 +140,21 @@ openclaw models auth login --provider openai-codex --set-default Примітки: -- `setup-token` і `paste-token` залишаються універсальними командами токенів для провайдерів, - які надають методи автентифікації токеном. -- `setup-token` вимагає інтерактивного TTY і запускає метод автентифікації токеном провайдера +- `setup-token` і `paste-token` залишаються універсальними командами для роботи з токенами для провайдерів, + які надають методи токен-автентифікації. +- `setup-token` вимагає інтерактивного TTY і запускає метод токен-автентифікації провайдера (типово — метод `setup-token` цього провайдера, якщо він його надає). -- `paste-token` приймає рядок токена, згенерований в іншому місці або автоматизацією. -- `paste-token` вимагає `--provider`, запитує значення токена та записує - його до типового ідентифікатора профілю `:manual`, якщо ви не передасте +- `paste-token` приймає рядок токена, згенерований деінде або засобами автоматизації. +- `paste-token` вимагає `--provider`, запитує значення токена й записує + його до ідентифікатора профілю за замовчуванням `:manual`, якщо ви не передали `--profile-id`. - `paste-token --expires-in ` зберігає абсолютний строк дії токена на основі відносної тривалості, наприклад `365d` або `12h`. -- Примітка Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож OpenClaw вважає повторне використання Claude CLI та використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. -- `setup-token` / `paste-token` для Anthropic залишаються доступними як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI та `claude -p`, коли це доступно. +- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI та використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. +- `setup-token` / `paste-token` Anthropic залишаються доступними як підтримуваний шлях роботи з токенами в OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI та `claude -p`, коли це можливо. ## Пов’язане - [Довідка CLI](/uk/cli) - [Вибір моделі](/uk/concepts/model-providers) -- [Перемикання моделей при відмові](/uk/concepts/model-failover) +- [Відмовостійке перемикання моделей](/uk/concepts/model-failover) diff --git a/docs/uk/concepts/model-providers.md b/docs/uk/concepts/model-providers.md index 516369aab..1d9871639 100644 --- a/docs/uk/concepts/model-providers.md +++ b/docs/uk/concepts/model-providers.md @@ -1,78 +1,79 @@ --- read_when: - - Вам потрібен довідник із налаштування моделей для кожного provider окремо - - Вам потрібні приклади конфігурацій або команд початкового налаштування CLI для provider-ів моделей -summary: Огляд provider-ів моделей із прикладами конфігурацій і потоками CLI -title: Provider-и моделей + - Вам потрібен довідник із налаштування моделей для кожного постачальника окремо + - Вам потрібні приклади конфігурацій або команди онбордингу CLI для постачальників моделей +summary: Огляд постачальника моделі з прикладами конфігурацій + потоками CLI +title: Постачальники моделей x-i18n: - generated_at: "2026-04-25T05:55:45Z" + generated_at: "2026-04-25T07:01:56Z" model: gpt-5.4 provider: openai - source_hash: bdab460823e3138377a7e2b183b31caa64bb2eef4c9e77ebd8db0aacc97493bb + source_hash: fe2871809711608b3e1d996084b834978b15f21dfeea1ac767dce4c1299be0aa source_path: concepts/model-providers.md workflow: 15 --- -Довідник для **provider-ів LLM/моделей** (а не каналів чату, як-от WhatsApp/Telegram). Правила вибору моделей див. у [Моделі](/uk/concepts/models). +Довідник для **постачальників LLM/моделей** (а не чат-каналів на кшталт WhatsApp/Telegram). Правила вибору моделей див. у [Models](/uk/concepts/models). ## Швидкі правила - Посилання на моделі використовують формат `provider/model` (приклад: `opencode/claude-opus-4-6`). -- `agents.defaults.models` працює як allowlist, якщо його задано. -- Helper-и CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. +- `agents.defaults.models` працює як список дозволених значень, якщо його задано. +- Допоміжні команди CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. - `models.providers.*.models[].contextWindow` — це нативні метадані моделі; `contextTokens` — це фактичне обмеження під час виконання. -- Правила fallback, cooldown probes і збереження session-override: [Перемикання моделей при збоях](/uk/concepts/model-failover). -- Маршрути родини OpenAI залежать від префікса: `openai/` використовує прямий provider API key OpenAI у PI, `openai-codex/` використовує Codex OAuth у PI, а `openai/` плюс `agents.defaults.embeddedHarness.runtime: "codex"` використовує нативний harness app-server Codex. Див. [OpenAI](/uk/providers/openai) і [Codex harness](/uk/plugins/codex-harness). Якщо поділ між provider і runtime заплутує, спершу прочитайте [Середовища виконання агентів](/uk/concepts/agent-runtimes). -- Автоувімкнення Plugin дотримується тієї самої межі: `openai-codex/` належить Plugin OpenAI, тоді як Plugin Codex вмикається через `embeddedHarness.runtime: "codex"` або застарілі посилання `codex/`. -- Середовища CLI використовують той самий поділ: вибирайте канонічні посилання на моделі, як-от `anthropic/claude-*`, `google/gemini-*` або `openai/gpt-*`, а потім задавайте `agents.defaults.embeddedHarness.runtime` як `claude-cli`, `google-gemini-cli` або `codex-cli`, якщо хочете локальний backend CLI. Застарілі посилання `claude-cli/*`, `google-gemini-cli/*` і `codex-cli/*` мігрують назад до канонічних посилань provider, а runtime записується окремо. -- GPT-5.5 зараз доступна через маршрути subscription/OAuth: `openai-codex/gpt-5.5` у PI або `openai/gpt-5.5` із harness app-server Codex. Прямий маршрут API key для `openai/gpt-5.5` підтримується, щойно OpenAI увімкне GPT-5.5 у публічному API; до того часу для конфігурацій `OPENAI_API_KEY` використовуйте моделі з доступним API, наприклад `openai/gpt-5.4`. +- Правила резервного перемикання, перевірки після cooldown і збереження перевизначень сесії див.: [Model failover](/uk/concepts/model-failover). +- Маршрути сімейства OpenAI залежать від префікса: `openai/` використовує прямого постачальника API-ключа OpenAI у PI, `openai-codex/` використовує OAuth Codex у PI, а `openai/` разом із `agents.defaults.embeddedHarness.runtime: "codex"` використовує нативний app-server harness Codex. Див. [OpenAI](/uk/providers/openai) і [Codex harness](/uk/plugins/codex-harness). Якщо розділення між постачальником і runtime викликає плутанину, спочатку прочитайте [Agent runtimes](/uk/concepts/agent-runtimes). +- Автоматичне ввімкнення Plugin дотримується тієї самої межі: `openai-codex/` належить Plugin OpenAI, тоді як Plugin Codex вмикається через `embeddedHarness.runtime: "codex"` або застарілі посилання `codex/`. +- Runtime CLI використовують те саме розділення: вибирайте канонічні посилання на моделі, як-от `anthropic/claude-*`, `google/gemini-*` або `openai/gpt-*`, а потім задавайте `agents.defaults.embeddedHarness.runtime` як `claude-cli`, `google-gemini-cli` або `codex-cli`, якщо вам потрібен локальний бекенд CLI. Застарілі посилання `claude-cli/*`, `google-gemini-cli/*` і `codex-cli/*` мігрують назад до канонічних посилань постачальників, а runtime записується окремо. +- GPT-5.5 доступна через `openai-codex/gpt-5.5` у PI, нативний app-server harness Codex і публічний API OpenAI, якщо вбудований каталог PI надає `openai/gpt-5.5` для вашої інсталяції. -## Поведінка provider-ів, що належить Plugin +## Поведінка постачальників, якою керують Plugin -Більшість provider-специфічної логіки знаходиться в provider Plugin (`registerProvider(...)`), тоді як OpenClaw зберігає загальний цикл inference. Plugin-и відповідають за onboarding, каталоги моделей, зіставлення auth env-var, нормалізацію transport/config, очищення схем інструментів, класифікацію failover, оновлення OAuth, звітування про використання, профілі thinking/reasoning тощо. +Більшість специфічної для постачальників логіки живе в Plugin постачальників (`registerProvider(...)`), тоді як OpenClaw зберігає загальний цикл inference. Plugin відповідають за онбординг, каталоги моделей, зіставлення env var для автентифікації, нормалізацію транспорту/конфігурації, очищення схем інструментів, класифікацію failover, оновлення OAuth, звітність про використання, профілі thinking/reasoning тощо. -Повний список хуків provider-SDK і прикладів bundled Plugin наведено в [Provider plugins](/uk/plugins/sdk-provider-plugins). Provider, якому потрібен повністю власний виконавець запитів, — це окрема, глибша поверхня розширення. +Повний список хуків SDK постачальників і прикладів вбудованих Plugin наведено в [Provider plugins](/uk/plugins/sdk-provider-plugins). Постачальник, якому потрібен повністю кастомний виконавець запитів, використовує окрему, глибшу поверхню розширення. -`capabilities` runtime provider-а — це спільні метадані runner-а (родина provider-а, особливості transcript/tooling, підказки щодо transport/cache). Це не те саме, що [публічна модель capability](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє Plugin (text inference, speech тощо). +`capabilities` runtime постачальника — це спільні метадані виконавця (сімейство постачальника, особливості transcript/tooling, підказки для transport/cache). Це не те саме, що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє Plugin (текстовий inference, мовлення тощо). -## Ротація API key +## Ротація API-ключів -- Підтримується загальна ротація provider-ів для вибраних provider-ів. +- Підтримується загальна ротація ключів постачальників для вибраних постачальників. - Налаштуйте кілька ключів через: - - `OPENCLAW_LIVE__KEY` (один live override, найвищий пріоритет) + - `OPENCLAW_LIVE__KEY` (одне live-перевизначення, найвищий пріоритет) - `_API_KEYS` (список через кому або крапку з комою) - `_API_KEY` (основний ключ) - `_API_KEY_*` (нумерований список, наприклад `_API_KEY_1`) -- Для provider-ів Google також використовується `GOOGLE_API_KEY` як fallback. +- Для постачальників Google `GOOGLE_API_KEY` також включається як запасний варіант. - Порядок вибору ключів зберігає пріоритет і прибирає дублікати значень. -- Запити повторюються з наступним ключем лише у відповідях rate-limit (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміти використання). -- Збої, не пов’язані з rate-limit, одразу завершуються помилкою; ротація ключів не виконується. -- Коли всі можливі ключі зазнають невдачі, повертається фінальна помилка з останньої спроби. +- Запити повторюються з наступним ключем лише у відповідь на rate-limit помилки (наприклад, `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання). +- Помилки, не пов’язані з rate-limit, одразу завершуються невдачею; ротація ключів не виконується. +- Коли всі можливі ключі завершуються невдачею, повертається остання помилка з останньої спроби. -## Вбудовані provider-и (каталог pi-ai) +## Вбудовані постачальники (каталог pi-ai) -OpenClaw постачається з каталогом pi‑ai. Для цих provider-ів **не потрібна** конфігурація `models.providers`; достатньо задати auth і вибрати модель. +OpenClaw постачається з каталогом pi‑ai. Для цих постачальників **не потрібна** +конфігурація `models.providers`; просто задайте автентифікацію й виберіть модель. ### OpenAI -- Provider: `openai` -- Auth: `OPENAI_API_KEY` -- Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (один override) -- Приклади моделей: `openai/gpt-5.4`, `openai/gpt-5.4-mini` -- Пряма підтримка GPT-5.5 через API тут буде готова в майбутньому, щойно OpenAI відкриє GPT-5.5 у API -- Перевіряйте доступність прямого API через `openclaw models list --provider openai` перед використанням `openai/gpt-5.5` без runtime app-server Codex +- Постачальник: `openai` +- Автентифікація: `OPENAI_API_KEY` +- Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення) +- Приклади моделей: `openai/gpt-5.5`, `openai/gpt-5.4`, `openai/gpt-5.4-mini` +- Підтримка прямого API для GPT-5.5 залежить від версії вбудованого каталогу PI у вашій інсталяції; перед використанням `openai/gpt-5.5` без runtime app-server Codex перевірте через `openclaw models list --provider openai` - CLI: `openclaw onboard --auth-choice openai-api-key` -- Стандартний transport — `auto` (спочатку WebSocket, fallback на SSE) -- Перевизначення для конкретної моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- Прогрівання OpenAI Responses WebSocket за замовчуванням увімкнене через `params.openaiWsWarmup` (`true`/`false`) +- Типовий transport — `auto` (спочатку WebSocket, потім SSE) +- Перевизначення для окремої моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) +- Warm-up OpenAI Responses WebSocket типово ввімкнено через `params.openaiWsWarmup` (`true`/`false`) - Пріоритетну обробку OpenAI можна ввімкнути через `agents.defaults.models["openai/"].params.serviceTier` -- `/fast` і `params.fastMode` зіставляють прямі запити Responses `openai/*` з `service_tier=priority` на `api.openai.com` -- Використовуйте `params.serviceTier`, якщо вам потрібен явний tier замість спільного перемикача `/fast` -- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не до загальних OpenAI-сумісних proxy -- Нативні маршрути OpenAI також зберігають `store` Responses, підказки prompt-cache і формування payload для сумісності reasoning OpenAI; proxy-маршрути цього не роблять -- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, тому що live-запити OpenAI API його відхиляють, а поточний каталог Codex його не надає +- `/fast` і `params.fastMode` зіставляють прямі запити Responses `openai/*` із `service_tier=priority` на `api.openai.com` +- Використовуйте `params.serviceTier`, якщо вам потрібен явний рівень замість спільного перемикача `/fast` +- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, + `User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не до загальних OpenAI-сумісних проксі +- Нативні маршрути OpenAI також зберігають `store` Responses, підказки кешу prompt і формування payload для сумісності reasoning OpenAI; проксі-маршрути — ні +- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, оскільки live-запити до API OpenAI його відхиляють, а поточний каталог Codex його не показує ```json5 { @@ -82,14 +83,14 @@ OpenClaw постачається з каталогом pi‑ai. Для цих p ### Anthropic -- Provider: `anthropic` -- Auth: `ANTHROPIC_API_KEY` -- Необов’язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (один override) +- Постачальник: `anthropic` +- Автентифікація: `ANTHROPIC_API_KEY` +- Необов’язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (одне перевизначення) - Приклад моделі: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, зокрема трафік з автентифікацією API key і OAuth, надісланий до `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) -- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw розглядає повторне використання Claude CLI і `claude -p` як санкціонований варіант для цієї інтеграції, якщо Anthropic не опублікує нову політику. -- Setup-token Anthropic залишається доступним як підтримуваний шлях токена OpenClaw, але тепер OpenClaw віддає перевагу повторному використанню Claude CLI і `claude -p`, коли це можливо. +- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком, автентифікованим через API-ключ і OAuth, який надсилається на `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) +- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволено, тож OpenClaw вважає повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, доки Anthropic не опублікує нову політику. +- Setup-token Anthropic залишається доступним як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли це можливо. ```json5 { @@ -99,22 +100,24 @@ OpenClaw постачається з каталогом pi‑ai. Для цих p ### OpenAI Codex OAuth -- Provider: `openai-codex` -- Auth: OAuth (ChatGPT) +- Постачальник: `openai-codex` +- Автентифікація: OAuth (ChatGPT) - Посилання на модель PI: `openai-codex/gpt-5.5` -- Посилання для нативного harness app-server Codex: `openai/gpt-5.5` із `agents.defaults.embeddedHarness.runtime: "codex"` -- Документація для нативного harness app-server Codex: [Codex harness](/uk/plugins/codex-harness) +- Посилання нативного app-server harness Codex: `openai/gpt-5.5` з `agents.defaults.embeddedHarness.runtime: "codex"` +- Документація нативного app-server harness Codex: [Codex harness](/uk/plugins/codex-harness) - Застарілі посилання на моделі: `codex/gpt-*` -- Межа Plugin: `openai-codex/*` завантажує Plugin OpenAI; нативний Plugin app-server Codex вибирається лише через runtime Codex harness або застарілі посилання `codex/*`. +- Межа Plugin: `openai-codex/*` завантажує Plugin OpenAI; нативний Plugin app-server Codex вибирається лише runtime Codex harness або застарілими посиланнями `codex/*`. - CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex` -- Стандартний transport — `auto` (спочатку WebSocket, fallback на SSE) -- Перевизначення для конкретної моделі PI через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) +- Типовий transport — `auto` (спочатку WebSocket, потім SSE) +- Перевизначення для окремої моделі PI через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) - `params.serviceTier` також передається в нативних запитах Codex Responses (`chatgpt.com/backend-api`) -- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) додаються лише до нативного трафіку Codex на `chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних proxy -- Використовує той самий спільний перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` -- `openai-codex/gpt-5.5` зберігає нативні `contextWindow = 1000000` і стандартні runtime `contextTokens = 272000`; перевизначайте обмеження runtime через `models.providers.openai-codex.models[].contextTokens` -- Примітка щодо політики: OpenAI Codex OAuth офіційно підтримується для зовнішніх інструментів/workflow, таких як OpenClaw. -- Поточний доступ до GPT-5.5 використовує цей маршрут OAuth/subscription, доки OpenAI не ввімкне GPT-5.5 у публічному API. +- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, + `User-Agent`) додаються лише до нативного трафіку Codex на + `chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних проксі +- Використовує той самий перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` +- `openai-codex/gpt-5.5` використовує нативні значення каталогу Codex `contextWindow = 400000` і типове runtime `contextTokens = 272000`; перевизначте runtime-ліміт через `models.providers.openai-codex.models[].contextTokens` +- Примітка щодо політики: OpenAI Codex OAuth явно підтримується для зовнішніх інструментів/процесів на кшталт OpenClaw. +- Використовуйте `openai-codex/gpt-5.5`, якщо вам потрібен маршрут Codex OAuth/підписки; використовуйте `openai/gpt-5.5`, якщо ваше налаштування API-ключа і локальний каталог показують маршрут публічного API. ```json5 { @@ -134,17 +137,17 @@ OpenClaw постачається з каталогом pi‑ai. Для цих p } ``` -### Інші розміщені варіанти в стилі subscription +### Інші хостовані варіанти в стилі підписки -- [Qwen Cloud](/uk/providers/qwen): поверхня provider-а Qwen Cloud плюс зіставлення endpoint-ів Alibaba DashScope і Coding Plan -- [MiniMax](/uk/providers/minimax): доступ до MiniMax Coding Plan через OAuth або API key -- [GLM models](/uk/providers/glm): endpoint-и Z.AI Coding Plan або загального API +- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud, а також зіставлення кінцевих точок Alibaba DashScope і Coding Plan +- [MiniMax](/uk/providers/minimax): OAuth MiniMax Coding Plan або доступ за API-ключем +- [GLM models](/uk/providers/glm): кінцеві точки Z.AI Coding Plan або загального API ### OpenCode -- Auth: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`) -- Provider runtime Zen: `opencode` -- Provider runtime Go: `opencode-go` +- Автентифікація: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`) +- Постачальник runtime Zen: `opencode` +- Постачальник runtime Go: `opencode-go` - Приклади моделей: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.6` - CLI: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go` @@ -154,68 +157,70 @@ OpenClaw постачається з каталогом pi‑ai. Для цих p } ``` -### Google Gemini (API key) +### Google Gemini (API-ключ) -- Provider: `google` -- Auth: `GEMINI_API_KEY` -- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (один override) +- Постачальник: `google` +- Автентифікація: `GEMINI_API_KEY` +- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, запасний варіант `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення) - Приклади моделей: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - Сумісність: застаріла конфігурація OpenClaw з `google/gemini-3.1-flash-preview` нормалізується до `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` -- Thinking: `/think adaptive` використовує динамічне thinking Google. Gemini 3/3.1 не мають фіксованого `thinkingLevel`; Gemini 2.5 надсилає `thinkingBudget: -1`. -- Прямі запуски Gemini також приймають `agents.defaults.models["google/"].params.cachedContent` (або застаріле `cached_content`) для передавання нативного дескриптора provider-а `cachedContents/...`; cache hit-и Gemini відображаються як OpenClaw `cacheRead` +- Thinking: `/think adaptive` використовує динамічний thinking Google. Gemini 3/3.1 не надсилають фіксований + `thinkingLevel`; Gemini 2.5 надсилає `thinkingBudget: -1`. +- Прямі запуски Gemini також приймають `agents.defaults.models["google/"].params.cachedContent` + (або застарілий `cached_content`) для передавання нативного дескриптора постачальника + `cachedContents/...`; збіги кешу Gemini відображаються як OpenClaw `cacheRead` ### Google Vertex і Gemini CLI -- Provider-и: `google-vertex`, `google-gemini-cli` -- Auth: Vertex використовує gcloud ADC; Gemini CLI використовує власний потік OAuth -- Застереження: Gemini CLI OAuth в OpenClaw — неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Перегляньте умови Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. -- Gemini CLI OAuth постачається як частина bundled Plugin `google`. +- Постачальники: `google-vertex`, `google-gemini-cli` +- Автентифікація: Vertex використовує gcloud ADC; Gemini CLI використовує власний OAuth-потік +- Застереження: OAuth Gemini CLI в OpenClaw — це неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікових записів Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. +- OAuth Gemini CLI постачається як частина вбудованого Plugin `google`. - Спочатку встановіть Gemini CLI: - `brew install gemini-cli` - або `npm install -g @google/gemini-cli` - - Увімкніть: `openclaw plugins enable google` - - Увійдіть: `openclaw models auth login --provider google-gemini-cli --set-default` - - Стандартна модель: `google-gemini-cli/gemini-3-flash-preview` - - Примітка: вам **не потрібно** вставляти client id або secret у `openclaw.json`. Потік входу CLI зберігає токени в auth profiles на host Gateway. - - Якщо після входу запити не працюють, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на host Gateway. - - JSON-відповіді Gemini CLI розбираються з `response`; дані про використання беруться з fallback на `stats`, де `stats.cached` нормалізується до OpenClaw `cacheRead`. + - Увімкнення: `openclaw plugins enable google` + - Вхід: `openclaw models auth login --provider google-gemini-cli --set-default` + - Типова модель: `google-gemini-cli/gemini-3-flash-preview` + - Примітка: вам **не потрібно** вставляти client id або secret у `openclaw.json`. Потік входу CLI зберігає токени в профілях автентифікації на хості Gateway. + - Якщо після входу запити завершуються помилкою, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості Gateway. + - JSON-відповіді Gemini CLI розбираються з `response`; використання за замовчуванням береться з `stats`, а `stats.cached` нормалізується до OpenClaw `cacheRead`. ### Z.AI (GLM) -- Provider: `zai` -- Auth: `ZAI_API_KEY` +- Постачальник: `zai` +- Автентифікація: `ZAI_API_KEY` - Приклад моделі: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - - Аліаси: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*` - - `zai-api-key` автоматично визначає відповідний endpoint Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово вибирають конкретну поверхню + - Псевдоніми: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*` + - `zai-api-key` автоматично визначає відповідну кінцеву точку Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово вибирають конкретну поверхню ### Vercel AI Gateway -- Provider: `vercel-ai-gateway` -- Auth: `AI_GATEWAY_API_KEY` +- Постачальник: `vercel-ai-gateway` +- Автентифікація: `AI_GATEWAY_API_KEY` - Приклади моделей: `vercel-ai-gateway/anthropic/claude-opus-4.6`, `vercel-ai-gateway/moonshotai/kimi-k2.6` - CLI: `openclaw onboard --auth-choice ai-gateway-api-key` ### Kilo Gateway -- Provider: `kilocode` -- Auth: `KILOCODE_API_KEY` +- Постачальник: `kilocode` +- Автентифікація: `KILOCODE_API_KEY` - Приклад моделі: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` -- Base URL: `https://api.kilo.ai/api/gateway/` -- Статичний fallback-каталог постачається з `kilocode/kilo/auto`; live - виявлення через `https://api.kilo.ai/api/gateway/models` може додатково - розширити каталог runtime. -- Точна маршрутизація upstream за `kilocode/kilo/auto` належить Kilo Gateway, +- Базовий URL: `https://api.kilo.ai/api/gateway/` +- Статичний запасний каталог постачається з `kilocode/kilo/auto`; live-виявлення через + `https://api.kilo.ai/api/gateway/models` може додатково розширити runtime-каталог. +- Точна маршрутизація вгору за потоком для `kilocode/kilo/auto` належить Kilo Gateway, а не жорстко закодована в OpenClaw. -Деталі налаштування див. у [/providers/kilocode](/uk/providers/kilocode). +Докладні відомості про налаштування див. у [/providers/kilocode](/uk/providers/kilocode). -### Інші bundled provider Plugin +### Інші вбудовані Plugin постачальників -| Provider | Id | Auth env | Приклад моделі | +| Постачальник | Id | Auth env | Приклад моделі | | ----------------------- | -------------------------------- | ------------------------------------------------------------ | ---------------------------------------------- | | BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | | Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | @@ -241,30 +246,31 @@ OpenClaw постачається з каталогом pi‑ai. Для цих p | xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | | Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | -Особливості, які варто знати: +Варто знати такі особливості: -- **OpenRouter** застосовує свої заголовки атрибуції застосунку й маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Посилання DeepSeek, Moonshot і ZAI придатні для cache-TTL у prompt caching під керуванням OpenRouter, але не отримують маркери кешу Anthropic. Як proxy-стиль OpenAI-сумісного шляху, він пропускає формування, доступне лише для нативного OpenAI (`serviceTier`, `store` у Responses, підказки prompt-cache, сумісність reasoning OpenAI). Посилання на базі Gemini зберігають лише санітизацію thought-signature для proxy-Gemini. -- **Kilo Gateway** для посилань на базі Gemini дотримується того самого шляху санітизації proxy-Gemini; `kilocode/kilo/auto` та інші посилання, що не підтримують proxy reasoning, пропускають ін’єкцію proxy reasoning. -- **MiniMax** onboarding через API key записує явні текстові визначення chat-моделей M2.7; розуміння зображень залишається в media provider `MiniMax-VL-01`, що належить Plugin. -- **xAI** використовує шлях xAI Responses. `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast`. `tool_stream` увімкнено за замовчуванням; вимкніть через `agents.defaults.models["xai/"].params.tool_stream=false`. -- **Cerebras** моделі GLM використовують `zai-glm-4.7` / `zai-glm-4.6`; OpenAI-сумісний Base URL — `https://api.cerebras.ai/v1`. +- **OpenRouter** застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Посилання DeepSeek, Moonshot і ZAI підтримують TTL кешу для керованого OpenRouter кешування prompt, але не отримують маркери кешу Anthropic. Як проксі-шлях у стилі OpenAI-compatible, він пропускає формування, притаманне лише нативному OpenAI (`serviceTier`, `store` Responses, підказки кешу prompt, сумісність reasoning OpenAI). Посилання на базі Gemini зберігають лише санітизацію сигнатури думок proxy-Gemini. +- **Kilo Gateway** для посилань на базі Gemini дотримується того самого шляху санітизації proxy-Gemini; `kilocode/kilo/auto` та інші посилання, де reasoning через proxy не підтримується, пропускають ін’єкцію reasoning через proxy. +- **MiniMax** онбординг через API-ключ записує явні текстові визначення моделей чату M2.7; розпізнавання зображень залишається на медіа-постачальнику `MiniMax-VL-01`, яким керує Plugin. +- **xAI** використовує шлях xAI Responses. `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast`. `tool_stream` типово ввімкнено; вимкніть через `agents.defaults.models["xai/"].params.tool_stream=false`. +- **Cerebras** моделі GLM використовують `zai-glm-4.7` / `zai-glm-4.6`; базовий URL у форматі OpenAI-compatible: `https://api.cerebras.ai/v1`. -## Provider-и через `models.providers` (custom/Base URL) +## Постачальники через `models.providers` (custom/base URL) -Використовуйте `models.providers` (або `models.json`), щоб додавати **custom** provider-и або OpenAI/Anthropic‑сумісні proxy. +Використовуйте `models.providers` (або `models.json`) для додавання **власних** постачальників або +OpenAI/Anthropic‑compatible проксі. -Багато з bundled provider Plugin нижче вже публікують стандартний каталог. +Багато вбудованих нижче Plugin постачальників уже публікують типовий каталог. Використовуйте явні записи `models.providers.` лише тоді, коли хочете перевизначити -стандартний base URL, headers або список моделей. +типовий base URL, заголовки або список моделей. ### Moonshot AI (Kimi) -Moonshot постачається як bundled provider Plugin. Використовуйте вбудований provider -за замовчуванням і додавайте явний запис `models.providers.moonshot` лише тоді, коли +Moonshot постачається як вбудований Plugin постачальника. Типово використовуйте +вбудованого постачальника, а явний запис `models.providers.moonshot` додавайте лише тоді, коли потрібно перевизначити base URL або метадані моделі: -- Provider: `moonshot` -- Auth: `MOONSHOT_API_KEY` +- Постачальник: `moonshot` +- Автентифікація: `MOONSHOT_API_KEY` - Приклад моделі: `moonshot/kimi-k2.6` - CLI: `openclaw onboard --auth-choice moonshot-api-key` або `openclaw onboard --auth-choice moonshot-api-key-cn` @@ -301,10 +307,10 @@ Id моделей Kimi K2: ### Kimi Coding -Kimi Coding використовує Anthropic-сумісний endpoint Moonshot AI: +Kimi Coding використовує Anthropic-compatible кінцеву точку Moonshot AI: -- Provider: `kimi` -- Auth: `KIMI_API_KEY` +- Постачальник: `kimi` +- Автентифікація: `KIMI_API_KEY` - Приклад моделі: `kimi/kimi-code` ```json5 @@ -316,14 +322,14 @@ Kimi Coding використовує Anthropic-сумісний endpoint Moonsho } ``` -Застарілий `kimi/k2p5` і далі приймається як сумісний id моделі. +Застарілий `kimi/k2p5` і далі приймається як id моделі для сумісності. ### Volcano Engine (Doubao) Volcano Engine (火山引擎) надає доступ до Doubao та інших моделей у Китаї. -- Provider: `volcengine` (для кодування: `volcengine-plan`) -- Auth: `VOLCANO_ENGINE_API_KEY` +- Постачальник: `volcengine` (coding: `volcengine-plan`) +- Автентифікація: `VOLCANO_ENGINE_API_KEY` - Приклад моделі: `volcengine-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice volcengine-api-key` @@ -335,9 +341,13 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши } ``` -Початкове налаштування за замовчуванням використовує поверхню кодування, але загальний каталог `volcengine/*` реєструється одночасно. +Онбординг типово використовує coding-поверхню, але загальний каталог `volcengine/*` +реєструється одночасно. -У вибирачах моделей onboarding/configure для варіанта auth Volcengine пріоритет надається рядкам `volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажені, OpenClaw повертається до нефільтрованого каталогу замість показу порожнього вибирача в межах provider-а. +У засобах вибору моделей onboarding/configure для варіанта автентифікації Volcengine пріоритет надається і рядкам +`volcengine/*`, і `volcengine-plan/*`. Якщо ці моделі ще не завантажені, +OpenClaw повертається до нефільтрованого каталогу, замість того щоб показувати порожній +picker з областю постачальника. Доступні моделі: @@ -347,7 +357,7 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши - `volcengine/glm-4-7-251222` (GLM 4.7) - `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K) -Моделі кодування (`volcengine-plan`): +Coding-моделі (`volcengine-plan`): - `volcengine-plan/ark-code-latest` - `volcengine-plan/doubao-seed-code` @@ -355,12 +365,12 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши - `volcengine-plan/kimi-k2-thinking` - `volcengine-plan/glm-4.7` -### BytePlus (міжнародний) +### BytePlus (International) -BytePlus ARK надає доступ до тих самих моделей, що й Volcano Engine, для міжнародних користувачів. +BytePlus ARK надає міжнародним користувачам доступ до тих самих моделей, що й Volcano Engine. -- Provider: `byteplus` (для кодування: `byteplus-plan`) -- Auth: `BYTEPLUS_API_KEY` +- Постачальник: `byteplus` (coding: `byteplus-plan`) +- Автентифікація: `BYTEPLUS_API_KEY` - Приклад моделі: `byteplus-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice byteplus-api-key` @@ -372,9 +382,13 @@ BytePlus ARK надає доступ до тих самих моделей, що } ``` -Початкове налаштування за замовчуванням використовує поверхню кодування, але загальний каталог `byteplus/*` реєструється одночасно. +Онбординг типово використовує coding-поверхню, але загальний каталог `byteplus/*` +реєструється одночасно. -У вибирачах моделей onboarding/configure для варіанта auth BytePlus пріоритет надається рядкам `byteplus/*` і `byteplus-plan/*`. Якщо ці моделі ще не завантажені, OpenClaw повертається до нефільтрованого каталогу замість показу порожнього вибирача в межах provider-а. +У засобах вибору моделей onboarding/configure для варіанта автентифікації BytePlus пріоритет надається і рядкам +`byteplus/*`, і `byteplus-plan/*`. Якщо ці моделі ще не завантажені, +OpenClaw повертається до нефільтрованого каталогу, замість того щоб показувати порожній +picker з областю постачальника. Доступні моделі: @@ -382,7 +396,7 @@ BytePlus ARK надає доступ до тих самих моделей, що - `byteplus/kimi-k2-5-260127` (Kimi K2.5) - `byteplus/glm-4-7-251222` (GLM 4.7) -Моделі кодування (`byteplus-plan`): +Coding-моделі (`byteplus-plan`): - `byteplus-plan/ark-code-latest` - `byteplus-plan/doubao-seed-code` @@ -392,10 +406,10 @@ BytePlus ARK надає доступ до тих самих моделей, що ### Synthetic -Synthetic надає Anthropic-сумісні моделі через provider `synthetic`: +Synthetic надає Anthropic-compatible моделі через постачальника `synthetic`: -- Provider: `synthetic` -- Auth: `SYNTHETIC_API_KEY` +- Постачальник: `synthetic` +- Автентифікація: `SYNTHETIC_API_KEY` - Приклад моделі: `synthetic/hf:MiniMaxAI/MiniMax-M2.5` - CLI: `openclaw onboard --auth-choice synthetic-api-key` @@ -420,35 +434,37 @@ Synthetic надає Anthropic-сумісні моделі через provider ` ### MiniMax -MiniMax налаштовується через `models.providers`, оскільки використовує custom endpoint-и: +MiniMax налаштовується через `models.providers`, оскільки використовує власні кінцеві точки: - MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` - MiniMax API key (Global): `--auth-choice minimax-global-api` - MiniMax API key (CN): `--auth-choice minimax-cn-api` -- Auth: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або +- Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` -Деталі налаштування, варіанти моделей і фрагменти конфігурації див. у [/providers/minimax](/uk/providers/minimax). +Докладні відомості про налаштування, варіанти моделей і фрагменти конфігурації див. у [/providers/minimax](/uk/providers/minimax). -На Anthropic-сумісному streaming-шляху MiniMax OpenClaw за замовчуванням вимикає thinking, якщо ви явно його не задасте, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. +На Anthropic-compatible шляху потокової передачі MiniMax OpenClaw типово вимикає thinking, +якщо ви не задали його явно, а `/fast on` переписує +`MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. -Поділ capability, що належить Plugin: +Розділення можливостей, яким керує Plugin: -- Стандартні text/chat залишаються на `minimax/MiniMax-M2.7` +- Типові значення text/chat залишаються на `minimax/MiniMax-M2.7` - Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01` -- Розуміння зображень — це `MiniMax-VL-01`, що належить Plugin, для обох шляхів auth MiniMax -- Вебпошук залишається на id provider-а `minimax` +- Розпізнавання зображень — це `MiniMax-VL-01`, яким на обох шляхах автентифікації MiniMax керує Plugin +- Вебпошук залишається на id постачальника `minimax` ### LM Studio -LM Studio постачається як bundled provider Plugin, який використовує нативний API: +LM Studio постачається як вбудований Plugin постачальника, який використовує нативний API: -- Provider: `lmstudio` -- Auth: `LM_API_TOKEN` -- Стандартний base URL для inference: `http://localhost:1234/v1` +- Постачальник: `lmstudio` +- Автентифікація: `LM_API_TOKEN` +- Типовий базовий URL inference: `http://localhost:1234/v1` -Потім задайте модель (замініть на один з id, які повертає `http://localhost:1234/api/v1/models`): +Потім задайте модель (замініть на один з id, повернених `http://localhost:1234/api/v1/models`): ```json5 { @@ -458,20 +474,21 @@ LM Studio постачається як bundled provider Plugin, який вик } ``` -OpenClaw використовує нативні `LM Studio` `/api/v1/models` і `/api/v1/models/load` для виявлення й auto-load, а `/v1/chat/completions` — для inference за замовчуванням. -Деталі налаштування й усунення несправностей див. у [/providers/lmstudio](/uk/providers/lmstudio). +OpenClaw використовує нативні `LM Studio` `/api/v1/models` і `/api/v1/models/load` +для виявлення та авто-завантаження, а `/v1/chat/completions` — для inference за замовчуванням. +Відомості про налаштування й усунення несправностей див. у [/providers/lmstudio](/uk/providers/lmstudio). ### Ollama -Ollama постачається як bundled provider Plugin і використовує нативний API Ollama: +Ollama постачається як вбудований Plugin постачальника й використовує нативний API Ollama: -- Provider: `ollama` -- Auth: не потрібна (локальний сервер) +- Постачальник: `ollama` +- Автентифікація: не потрібна (локальний сервер) - Приклад моделі: `ollama/llama3.3` - Встановлення: [https://ollama.com/download](https://ollama.com/download) ```bash -# Встановіть Ollama, потім завантажте модель: +# Install Ollama, then pull a model: ollama pull llama3.3 ``` @@ -483,27 +500,26 @@ ollama pull llama3.3 } ``` -Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте це через -`OLLAMA_API_KEY`, а bundled provider Plugin додає Ollama безпосередньо до -`openclaw onboard` і вибирача моделей. Див. [/providers/ollama](/uk/providers/ollama) -для onboarding, cloud/local mode і custom-конфігурації. +Ollama локально виявляється за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте його через +`OLLAMA_API_KEY`, а вбудований Plugin постачальника додає Ollama безпосередньо до +`openclaw onboard` і picker моделей. Відомості про онбординг, хмарний/локальний режим і власну конфігурацію див. у [/providers/ollama](/uk/providers/ollama). ### vLLM -vLLM постачається як bundled provider Plugin для локальних/self-hosted OpenAI-сумісних +vLLM постачається як вбудований Plugin постачальника для локальних/self-hosted OpenAI-compatible серверів: -- Provider: `vllm` -- Auth: необов’язкова (залежить від вашого сервера) -- Стандартний base URL: `http://127.0.0.1:8000/v1` +- Постачальник: `vllm` +- Автентифікація: необов’язкова (залежить від вашого сервера) +- Типовий базовий URL: `http://127.0.0.1:8000/v1` -Щоб увімкнути auto-discovery локально (підійде будь-яке значення, якщо ваш сервер не вимагає auth): +Щоб увімкнути авто-виявлення локально (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації): ```bash export VLLM_API_KEY="vllm-local" ``` -Потім задайте модель (замініть на один з id, які повертає `/v1/models`): +Потім задайте модель (замініть на один з id, повернених `/v1/models`): ```json5 { @@ -513,25 +529,25 @@ export VLLM_API_KEY="vllm-local" } ``` -Деталі див. у [/providers/vllm](/uk/providers/vllm). +Відомості див. у [/providers/vllm](/uk/providers/vllm). ### SGLang -SGLang постачається як bundled provider Plugin для швидких self-hosted -OpenAI-сумісних серверів: +SGLang постачається як вбудований Plugin постачальника для швидких self-hosted +OpenAI-compatible серверів: -- Provider: `sglang` -- Auth: необов’язкова (залежить від вашого сервера) -- Стандартний base URL: `http://127.0.0.1:30000/v1` +- Постачальник: `sglang` +- Автентифікація: необов’язкова (залежить від вашого сервера) +- Типовий базовий URL: `http://127.0.0.1:30000/v1` -Щоб увімкнути auto-discovery локально (підійде будь-яке значення, якщо ваш сервер не -вимагає auth): +Щоб увімкнути авто-виявлення локально (підійде будь-яке значення, якщо ваш сервер не +вимагає автентифікації): ```bash export SGLANG_API_KEY="sglang-local" ``` -Потім задайте модель (замініть на один з id, які повертає `/v1/models`): +Потім задайте модель (замініть на один з id, повернених `/v1/models`): ```json5 { @@ -541,11 +557,11 @@ export SGLANG_API_KEY="sglang-local" } ``` -Деталі див. у [/providers/sglang](/uk/providers/sglang). +Відомості див. у [/providers/sglang](/uk/providers/sglang). -### Локальні proxy (LM Studio, vLLM, LiteLLM тощо) +### Локальні проксі (LM Studio, vLLM, LiteLLM тощо) -Приклад (OpenAI‑сумісний): +Приклад (OpenAI‑compatible): ```json5 { @@ -580,21 +596,24 @@ export SGLANG_API_KEY="sglang-local" Примітки: -- Для custom provider-ів `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` необов’язкові. - Якщо їх не вказано, OpenClaw використовує такі значення за замовчуванням: +- Для custom постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` не є обов’язковими. + Якщо їх пропущено, OpenClaw типово використовує: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- Рекомендовано: задавайте явні значення, що відповідають обмеженням вашого proxy/моделі. -- Для `api: "openai-completions"` на не нативних endpoint-ах (будь-який непорожній `baseUrl`, чий host не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникати помилок provider 400 для непідтримуваних ролей `developer`. -- Маршрути OpenAI-сумісного proxy-стилю також пропускають формування запитів, доступне лише для нативного OpenAI: без `service_tier`, без `store` у Responses, без `store` у Completions, без підказок prompt-cache, без формування payload для сумісності reasoning OpenAI і без прихованих заголовків атрибуції OpenClaw. -- Для OpenAI-сумісних Completions proxy, яким потрібні vendor-специфічні поля, +- Рекомендовано: задавайте явні значення, що відповідають обмеженням вашого проксі/моделі. +- Для `api: "openai-completions"` на ненативних кінцевих точках (будь-який непорожній `baseUrl`, чий хост не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникнути помилок постачальника 400 для ролей `developer`, які не підтримуються. +- Маршрути OpenAI-compatible у стилі проксі також пропускають формування запитів, притаманне лише нативному OpenAI: + без `service_tier`, без `store` Responses, без `store` Completions, без + підказок кешу prompt, без формування payload для сумісності reasoning OpenAI і без прихованих + заголовків атрибуції OpenClaw. +- Для проксі Completions у форматі OpenAI-compatible, яким потрібні поля, специфічні для постачальника, задайте `agents.defaults.models["provider/model"].params.extra_body` (або `extraBody`), щоб об’єднати додатковий JSON у вихідне тіло запиту. -- Якщо `baseUrl` порожній або не вказаний, OpenClaw зберігає стандартну поведінку OpenAI (яка вказує на `api.openai.com`). -- Для безпеки явне `compat.supportsDeveloperRole: true` однаково перевизначається на не нативних endpoint-ах `openai-completions`. +- Якщо `baseUrl` порожній/не заданий, OpenClaw зберігає типову поведінку OpenAI (яка вказує на `api.openai.com`). +- Для безпеки явний `compat.supportsDeveloperRole: true` усе одно перевизначається на ненативних кінцевих точках `openai-completions`. ## Приклади CLI @@ -604,11 +623,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -Див. також: [Конфігурація](/uk/gateway/configuration) для повних прикладів конфігурації. +Див. також: [Configuration](/uk/gateway/configuration) для повних прикладів конфігурації. -## Пов’язане +## Пов’язані матеріали -- [Моделі](/uk/concepts/models) — конфігурація моделей і псевдоніми -- [Model failover](/uk/concepts/model-failover) — ланцюжки fallback і поведінка повторних спроб -- [Довідник із конфігурації](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей -- [Provider-и](/uk/providers) — окремі інструкції з налаштування для кожного provider-а +- [Models](/uk/concepts/models) — конфігурація моделей і псевдоніми +- [Model failover](/uk/concepts/model-failover) — ланцюжки резервного перемикання й поведінка повторних спроб +- [Configuration reference](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделі +- [Providers](/uk/providers) — посібники з налаштування для кожного постачальника diff --git a/docs/uk/gateway/cli-backends.md b/docs/uk/gateway/cli-backends.md index 8f92414d1..f6e3d82b4 100644 --- a/docs/uk/gateway/cli-backends.md +++ b/docs/uk/gateway/cli-backends.md @@ -1,45 +1,45 @@ --- read_when: - - Вам потрібен надійний резервний варіант, коли API-провайдери зазнають збою - - Ви використовуєте Codex CLI або інші локальні AI CLI й хочете використовувати їх повторно - - Ви хочете зрозуміти міст MCP local loopback для доступу CLI-бекенда до інструментів -summary: 'Бекенди CLI: резервний локальний AI CLI з необов’язковим мостом інструментів MCP' + - Вам потрібен надійний резервний варіант, коли API-провайдери не працюють + - Ви використовуєте Codex CLI або інші локальні AI CLI і хочете повторно використовувати їх + - Ви хочете зрозуміти міст local loopback MCP для доступу до інструментів бекенду CLI +summary: 'Бекенди CLI: локальний резервний AI CLI з необов’язковим мостом інструментів MCP' title: Бекенди CLI x-i18n: - generated_at: "2026-04-24T18:10:13Z" + generated_at: "2026-04-25T07:01:57Z" model: gpt-5.4 provider: openai - source_hash: 81d5f41ebaf16d4171379cf446b4c70b167519cd1f647c0701cccda19f0b3419 + source_hash: 09e184bb99a6c354738c3d770460bc2f282a31c41d2cbce4c1e021ae828ba27c source_path: gateway/cli-backends.md workflow: 15 --- -OpenClaw може запускати **локальні AI CLI** як **текстовий резервний варіант**, коли API-провайдери недоступні, -обмежені за rate limit або тимчасово працюють некоректно. Це навмисно консервативний підхід: +OpenClaw може запускати **локальні AI CLI** як **резервний варіант лише для тексту**, коли API-провайдери недоступні, +обмежені за частотою запитів або тимчасово працюють некоректно. Це навмисно консервативний підхід: -- **Інструменти OpenClaw не інжектуються безпосередньо**, але бекенди з `bundleMcp: true` - можуть отримувати інструменти gateway через міст MCP local loopback. -- **Потокове передавання JSONL** для CLI, які це підтримують. +- **Інструменти OpenClaw не впроваджуються безпосередньо**, але бекенди з `bundleMcp: true` + можуть отримувати інструменти gateway через міст loopback MCP. +- **Потокова передача JSONL** для CLI, які її підтримують. - **Сесії підтримуються** (тому наступні ходи залишаються узгодженими). - **Зображення можна передавати далі**, якщо CLI приймає шляхи до зображень. Це задумано як **страхувальна сітка**, а не як основний шлях. Використовуйте це, коли -вам потрібні текстові відповіді в стилі «завжди працює» без залежності від зовнішніх API. +вам потрібні текстові відповіді в режимі «працює завжди» без залежності від зовнішніх API. Якщо вам потрібне повноцінне середовище harness із керуванням сесіями ACP, фоновими завданнями, -прив’язкою до thread/conversation і постійними зовнішніми сесіями кодування, використовуйте -[ACP Agents](/uk/tools/acp-agents). CLI-бекенди — це не ACP. +прив’язкою до потоку/розмови та постійними зовнішніми сесіями кодування, використовуйте +[ACP Agents](/uk/tools/acp-agents). Бекенди CLI — це не ACP. ## Швидкий старт для початківців -Ви можете використовувати Codex CLI **без жодної конфігурації** (вбудований Plugin OpenAI +Ви можете використовувати Codex CLI **без жодної конфігурації** (вбудований плагін OpenAI реєструє бекенд за замовчуванням): ```bash openclaw agent --message "hi" --model codex-cli/gpt-5.5 ``` -Якщо ваш gateway працює під launchd/systemd і PATH мінімальний, додайте лише +Якщо ваш gateway працює через launchd/systemd і `PATH` мінімальний, додайте лише шлях до команди: ```json5 @@ -56,16 +56,16 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5 } ``` -Ось і все. Жодних ключів, жодної додаткової конфігурації автентифікації не потрібно, окрім самої CLI. +Ось і все. Жодних ключів, жодної додаткової конфігурації автентифікації, окрім самої CLI. -Якщо ви використовуєте вбудований CLI-бекенд як **основний провайдер повідомлень** на -хості gateway, OpenClaw тепер автоматично завантажує відповідний вбудований Plugin, коли ваша конфігурація -явно посилається на цей бекенд у model ref або в +Якщо ви використовуєте вбудований бекенд CLI як **основного провайдера повідомлень** на +хості gateway, OpenClaw тепер автоматично завантажує відповідний вбудований плагін, коли ваша конфігурація +явно посилається на цей бекенд у посиланні на модель або в `agents.defaults.cliBackends`. ## Використання як резервного варіанту -Додайте CLI-бекенд до списку резервних, щоб він запускався лише тоді, коли основні моделі недоступні: +Додайте бекенд CLI до списку резервних варіантів, щоб він запускався лише тоді, коли основні моделі не працюють: ```json5 { @@ -86,20 +86,20 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5 Примітки: -- Якщо ви використовуєте `agents.defaults.models` (allowlist), ви також маєте включити туди моделі CLI-бекенда. -- Якщо основний провайдер недоступний (автентифікація, rate limits, тайм-аути), OpenClaw - спробує CLI-бекенд наступним. +- Якщо ви використовуєте `agents.defaults.models` (список дозволених), ви також маєте включити туди моделі вашого бекенду CLI. +- Якщо основний провайдер не працює (автентифікація, ліміти частоти, тайм-аути), OpenClaw + спробує далі бекенд CLI. ## Огляд конфігурації -Усі CLI-бекенди розміщуються в: +Усі бекенди CLI знаходяться тут: ``` agents.defaults.cliBackends ``` -Кожен запис має ключ у вигляді **provider id** (наприклад, `codex-cli`, `my-cli`). -Provider id стає лівою частиною вашого model ref: +Кожен запис має ключ **ідентифікатора провайдера** (наприклад, `codex-cli`, `my-cli`). +Ідентифікатор провайдера стає лівою частиною посилання на модель: ``` / @@ -145,41 +145,41 @@ Provider id стає лівою частиною вашого model ref: ## Як це працює -1. **Вибирає бекенд** на основі префікса provider (`codex-cli/...`). -2. **Будує system prompt** з використанням того самого prompt OpenClaw і контексту workspace. -3. **Запускає CLI** з id сесії (якщо підтримується), щоб історія залишалася узгодженою. - Вбудований бекенд `claude-cli` підтримує процес Claude stdio живим для кожної - сесії OpenClaw і надсилає наступні ходи через stdin stream-json. +1. **Вибирає бекенд** на основі префікса провайдера (`codex-cli/...`). +2. **Формує системний prompt** з використанням того самого prompt OpenClaw і контексту робочого простору. +3. **Виконує CLI** з ідентифікатором сесії (якщо підтримується), щоб історія залишалася узгодженою. + Вбудований бекенд `claude-cli` підтримує процес Claude stdio активним для кожної + сесії OpenClaw і надсилає наступні ходи через stream-json stdin. 4. **Розбирає вивід** (JSON або звичайний текст) і повертає фінальний текст. -5. **Зберігає id сесій** для кожного бекенда, щоб наступні ходи повторно використовували ту саму CLI-сесію. +5. **Зберігає ідентифікатори сесій** для кожного бекенду, щоб наступні ходи повторно використовували ту саму сесію CLI. -Вбудований бекенд Anthropic `claude-cli` знову підтримується. Співробітники Anthropic -повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає -використання `claude -p` санкціонованим для цієї інтеграції, якщо Anthropic не опублікує +Вбудований Anthropic-бекенд `claude-cli` знову підтримується. Співробітники Anthropic +повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw розглядає +використання `claude -p` як санкціоноване для цієї інтеграції, якщо Anthropic не опублікує нову політику. -Вбудований бекенд OpenAI `codex-cli` передає system prompt OpenClaw через -override конфігурації `model_instructions_file` у Codex (`-c -model_instructions_file="..."`). Codex не надає прапорець у стилі Claude -`--append-system-prompt`, тому OpenClaw записує зібраний prompt у тимчасовий -файл для кожної нової сесії Codex CLI. +Вбудований OpenAI-бекенд `codex-cli` передає системний prompt OpenClaw через +перевизначення конфігурації Codex `model_instructions_file` (`-c +model_instructions_file="..."`). Codex не надає прапора у стилі Claude +`--append-system-prompt`, тому OpenClaw записує зібраний prompt у +тимчасовий файл для кожної нової сесії Codex CLI. -Вбудований бекенд Anthropic `claude-cli` отримує знімок Skills OpenClaw -двома способами: компактний каталог Skills OpenClaw у доданому system prompt і -тимчасовий Plugin Claude Code, переданий через `--plugin-dir`. Plugin містить -лише дозволені Skills для цього агента/сесії, тому власний resolver Skills у Claude Code -бачить той самий відфільтрований набір, який OpenClaw інакше рекламував би в prompt. -Перевизначення env/API key для Skills і далі застосовуються OpenClaw до середовища дочірнього процесу під час виконання. +Вбудований Anthropic-бекенд `claude-cli` отримує знімок Skills OpenClaw +двома способами: компактний каталог Skills OpenClaw у доданому системному prompt і +тимчасовий плагін Claude Code, переданий через `--plugin-dir`. Плагін містить +лише ті Skills, які підходять для цього агента/сесії, тому вбудований механізм розв’язання Skills Claude Code +бачить той самий відфільтрований набір, який OpenClaw інакше рекламував би у prompt. +Перевизначення середовища/API-ключів для Skills усе ще застосовуються OpenClaw до середовища дочірнього процесу для цього запуску. Claude CLI також має власний неінтерактивний режим дозволів. OpenClaw зіставляє його -з наявною policy виконання замість додавання специфічної для Claude конфігурації: коли -ефективно запитана policy виконання — YOLO (`tools.exec.security: "full"` і +з наявною політикою exec замість додавання окремої конфігурації для Claude: коли +ефективно запитана політика exec — YOLO (`tools.exec.security: "full"` і `tools.exec.ask: "off"`), OpenClaw додає `--permission-mode bypassPermissions`. Налаштування `agents.list[].tools.exec` для окремого агента мають пріоритет над глобальним `tools.exec` для -цього агента. Щоб примусово встановити інший режим Claude, задайте явні сирі аргументи бекенда, -наприклад `--permission-mode default` або `--permission-mode acceptEdits`, у +цього агента. Щоб примусово використати інший режим Claude, задайте явні сирі аргументи бекенду, +такі як `--permission-mode default` або `--permission-mode acceptEdits`, у `agents.defaults.cliBackends.claude-cli.args` і відповідних `resumeArgs`. Перш ніж OpenClaw зможе використовувати вбудований бекенд `claude-cli`, сам Claude Code @@ -192,40 +192,42 @@ openclaw models auth login --provider anthropic --method cli --set-default ``` Використовуйте `agents.defaults.cliBackends.claude-cli.command` лише тоді, коли бінарний файл `claude` -ще не доступний у `PATH`. +вже недоступний у `PATH`. ## Сесії - Якщо CLI підтримує сесії, задайте `sessionArg` (наприклад, `--session-id`) або - `sessionArgs` (placeholder `{sessionId}`), коли ID потрібно вставити - в кілька прапорців. -- Якщо CLI використовує **підкоманду resume** з іншими прапорцями, задайте + `sessionArgs` (плейсхолдер `{sessionId}`), коли ID потрібно вставити + в кілька прапорів. +- Якщо CLI використовує **підкоманду resume** з іншими прапорами, задайте `resumeArgs` (замінює `args` під час відновлення) і за потреби `resumeOutput` (для відновлень не у форматі JSON). - `sessionMode`: - - `always`: завжди надсилати id сесії (новий UUID, якщо нічого не збережено). - - `existing`: надсилати id сесії лише якщо його було збережено раніше. - - `none`: ніколи не надсилати id сесії. + - `always`: завжди надсилати ідентифікатор сесії (новий UUID, якщо нічого не збережено). + - `existing`: надсилати ідентифікатор сесії лише тоді, коли його було збережено раніше. + - `none`: ніколи не надсилати ідентифікатор сесії. - `claude-cli` за замовчуванням використовує `liveSession: "claude-stdio"`, `output: "jsonl"` - і `input: "stdin"`, щоб наступні ходи повторно використовували живий процес Claude, поки - він активний. Теплий stdio тепер є варіантом за замовчуванням, зокрема для користувацьких конфігурацій, - у яких не вказані поля транспорту. Якщо Gateway перезапускається або неактивний процес завершується, - OpenClaw відновлюється із збереженого id сесії Claude. Збережені id сесій - перевіряються на наявність доступного для читання transcript проєкту перед + і `input: "stdin"`, щоб наступні ходи повторно використовували активний процес Claude, + поки він активний. Теплий stdio тепер є типовим режимом, зокрема для користувацьких конфігурацій, + у яких поля транспорту не задані. Якщо Gateway перезапускається або неактивний процес + завершується, OpenClaw відновлюється зі збереженого ідентифікатора сесії Claude. Збережені ідентифікатори сесій + перевіряються на наявність доступного для читання наявного транскрипту проєкту перед відновленням, тому фантомні прив’язки очищаються з `reason=transcript-missing`, - а не тихо запускають нову сесію Claude CLI під `--resume`. -- Збережені CLI-сесії — це безперервність, якою володіє provider. Неявне щоденне - скидання сесії не розриває їх; це роблять `/reset` і явні policy `session.reset`. + а не тихо запускають нову сесію Claude CLI через `--resume`. +- Збережені сесії CLI — це безперервність, що належить провайдеру. Неявне щоденне + скидання їх не обриває; `/reset` і явні політики `session.reset` — обривають. Примітки щодо серіалізації: -- `serialize: true` зберігає впорядкованість запусків в одній lane. -- Більшість CLI серіалізуються в одній lane provider. -- OpenClaw скидає повторне використання збереженої CLI-сесії, коли змінюється вибрана ідентичність автентифікації, - зокрема змінений id auth profile, статичний API key, статичний токен або ідентичність OAuth-облікового запису, якщо CLI її розкриває. Ротація токенів доступу й оновлення OAuth не - розриває збережену CLI-сесію. Якщо CLI не розкриває стабільний id OAuth-облікового запису, OpenClaw дозволяє цій CLI самостійно застосовувати дозволи на resume. +- `serialize: true` зберігає впорядкованість запусків у тій самій lane. +- Більшість CLI серіалізують на одній lane провайдера. +- OpenClaw відмовляється від повторного використання збереженої сесії CLI, коли змінюється вибрана автентифікаційна ідентичність, + зокрема якщо змінюється ID профілю автентифікації, статичний API-ключ, статичний токен + або ідентичність OAuth-акаунта, якщо CLI її надає. Ротація OAuth access і refresh токенів + не обриває збережену сесію CLI. Якщо CLI не надає стабільний ID OAuth-акаунта, + OpenClaw дозволяє цій CLI самій забезпечувати дозволи на відновлення. -## Зображення (передавання далі) +## Зображення (передача наскрізь) Якщо ваша CLI приймає шляхи до зображень, задайте `imageArg`: @@ -234,28 +236,29 @@ imageArg: "--image", imageMode: "repeat" ``` -OpenClaw записуватиме base64-зображення у тимчасові файли. Якщо задано `imageArg`, ці -шляхи передаються як аргументи CLI. Якщо `imageArg` відсутній, OpenClaw додає -шляхи до файлів у prompt (ін’єкція шляхів), чого достатньо для CLI, які автоматично +OpenClaw записуватиме base64-зображення в тимчасові файли. Якщо задано `imageArg`, ці +шляхи передаються як аргументи CLI. Якщо `imageArg` не задано, OpenClaw додає +шляхи до файлів у prompt (ін’єкція шляху), чого достатньо для CLI, які автоматично завантажують локальні файли зі звичайних шляхів. ## Входи / виходи -- `output: "json"` (за замовчуванням) намагається розібрати JSON і витягти текст + id сесії. -- Для JSON-виводу Gemini CLI OpenClaw читає текст відповіді з `response`, а - використання — з `stats`, коли `usage` відсутній або порожній. -- `output: "jsonl"` розбирає потоки JSONL (наприклад, Codex CLI `--json`) і витягує фінальне повідомлення агента плюс ідентифікатори сесії, якщо вони присутні. +- `output: "json"` (типово) намагається розібрати JSON і витягти текст + ідентифікатор сесії. +- Для JSON-виводу Gemini CLI OpenClaw зчитує текст відповіді з `response`, а + використання — зі `stats`, коли `usage` відсутній або порожній. +- `output: "jsonl"` розбирає потоки JSONL (наприклад Codex CLI `--json`) і витягує фінальне повідомлення агента разом з ідентифікаторами сесії, + якщо вони присутні. - `output: "text"` розглядає stdout як фінальну відповідь. Режими введення: -- `input: "arg"` (за замовчуванням) передає prompt як останній аргумент CLI. +- `input: "arg"` (типово) передає prompt як останній аргумент CLI. - `input: "stdin"` надсилає prompt через stdin. - Якщо prompt дуже довгий і задано `maxPromptArgChars`, використовується stdin. -## Значення за замовчуванням (керуються Plugin) +## Значення за замовчуванням (належать плагіну) -Вбудований Plugin OpenAI також реєструє значення за замовчуванням для `codex-cli`: +Вбудований плагін OpenAI також реєструє значення за замовчуванням для `codex-cli`: - `command: "codex"` - `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]` @@ -266,7 +269,7 @@ OpenClaw записуватиме base64-зображення у тимчасо - `imageArg: "--image"` - `sessionMode: "existing"` -Вбудований Plugin Google також реєструє значення за замовчуванням для `google-gemini-cli`: +Вбудований плагін Google також реєструє значення за замовчуванням для `google-gemini-cli`: - `command: "gemini"` - `args: ["--output-format", "json", "--prompt", "{prompt}"]` @@ -281,28 +284,28 @@ OpenClaw записуватиме base64-зображення у тимчасо `gemini` у `PATH` (`brew install gemini-cli` або `npm install -g @google/gemini-cli`). -Примітки щодо JSON Gemini CLI: +Примітки щодо Gemini CLI JSON: -- Текст відповіді читається з поля JSON `response`. -- Використання бере резервне значення з `stats`, коли `usage` відсутній або порожній. -- `stats.cached` нормалізується в `cacheRead` OpenClaw. -- Якщо `stats.input` відсутній, OpenClaw виводить кількість вхідних токенів із +- Текст відповіді зчитується з поля JSON `response`. +- Використання береться зі `stats`, якщо `usage` відсутній або порожній. +- `stats.cached` нормалізується до OpenClaw `cacheRead`. +- Якщо `stats.input` відсутній, OpenClaw виводить вхідні токени з `stats.input_tokens - stats.cached`. -Перевизначайте лише за потреби (типовий випадок: абсолютний шлях `command`). +Перевизначайте лише за потреби (поширений випадок: абсолютний шлях `command`). -## Значення за замовчуванням, керовані Plugin +## Значення за замовчуванням, що належать плагіну -Значення за замовчуванням для CLI-бекендів тепер є частиною поверхні Plugin: +Значення за замовчуванням для бекендів CLI тепер є частиною поверхні плагіна: -- Plugins реєструють їх через `api.registerCliBackend(...)`. -- `id` бекенда стає префіксом provider у model refs. -- Конфігурація користувача в `agents.defaults.cliBackends.` усе ще перевизначає значення Plugin за замовчуванням. -- Очищення конфігурації, специфічне для бекенда, залишається під контролем Plugin через необов’язковий - hook `normalizeConfig`. +- Плагіни реєструють їх через `api.registerCliBackend(...)`. +- `id` бекенду стає префіксом провайдера в посиланнях на моделі. +- Користувацька конфігурація в `agents.defaults.cliBackends.` як і раніше перевизначає значення плагіна за замовчуванням. +- Очищення конфігурації, специфічне для бекенду, залишається у власності плагіна через необов’язковий + хук `normalizeConfig`. -Plugins, яким потрібні невеликі шими сумісності для prompt/повідомлень, можуть оголошувати -двонапрямні текстові перетворення без заміни provider або CLI-бекенда: +Плагіни, яким потрібні невеликі шими сумісності prompt/повідомлень, можуть оголосити +двонапрямні текстові перетворення без заміни провайдера або бекенду CLI: ```typescript api.registerTextTransforms({ @@ -319,59 +322,65 @@ api.registerTextTransforms({ }); ``` -`input` переписує system prompt і prompt користувача, передані до CLI. `output` +`input` переписує системний prompt і користувацький prompt, передані до CLI. `output` переписує потокові дельти помічника й розібраний фінальний текст до того, як OpenClaw обробить -власні control markers і доставку каналом. +власні керувальні маркери та доставку в channel. -Для CLI, які виводять JSONL, сумісний зі stream-json Claude Code, задайте -`jsonlDialect: "claude-stream-json"` у конфігурації цього бекенда. +Для CLI, які видають JSONL, сумісний із Claude Code stream-json, задайте +`jsonlDialect: "claude-stream-json"` у конфігурації цього бекенду. -## Оверлеї MCP для bundle +## Bundle MCP overlays -CLI-бекенди **не** отримують виклики інструментів OpenClaw безпосередньо, але бекенд може -ввімкнути генерацію оверлею конфігурації MCP за допомогою `bundleMcp: true`. +Бекенди CLI **не** отримують виклики інструментів OpenClaw безпосередньо, але бекенд може +увімкнути згенерований оверлей конфігурації MCP через `bundleMcp: true`. Поточна вбудована поведінка: -- `claude-cli`: згенерований суворий файл конфігурації MCP -- `codex-cli`: inline override конфігурації для `mcp_servers`; згенерований - loopback-сервер OpenClaw позначається режимом схвалення інструментів для окремого сервера в Codex, - щоб виклики MCP не зависали через локальні запити на схвалення +- `claude-cli`: згенерований строгий файл конфігурації MCP +- `codex-cli`: вбудовані перевизначення конфігурації для `mcp_servers`; згенерований + loopback-сервер OpenClaw позначається режимом погодження інструментів на рівні сервера Codex, + щоб виклики MCP не зависали на локальних запитах підтвердження - `google-gemini-cli`: згенерований файл системних налаштувань Gemini Коли bundle MCP увімкнено, OpenClaw: - запускає loopback HTTP MCP-сервер, який надає інструменти gateway процесу CLI -- автентифікує міст за допомогою токена для кожної сесії (`OPENCLAW_MCP_TOKEN`) -- обмежує доступ до інструментів поточною сесією, обліковим записом і контекстом каналу -- завантажує увімкнені сервери bundle-MCP для поточного workspace -- об’єднує їх із будь-якою наявною формою конфігурації/налаштувань MCP бекенда -- переписує конфігурацію запуску, використовуючи режим інтеграції, що належить бекенду, із відповідного extension +- автентифікує міст токеном на рівні сесії (`OPENCLAW_MCP_TOKEN`) +- обмежує доступ до інструментів поточною сесією, акаунтом і контекстом channel +- завантажує увімкнені bundle-MCP сервери для поточного робочого простору +- об’єднує їх із будь-якою наявною формою конфігурації/налаштувань MCP бекенду +- переписує конфігурацію запуску з використанням режиму інтеграції, що належить бекенду з відповідного extension -Якщо жоден MCP-сервер не увімкнено, OpenClaw все одно інжектує сувору конфігурацію, коли -бекенд використовує bundle MCP, щоб фонові запуски залишалися ізольованими. +Якщо жоден MCP-сервер не увімкнено, OpenClaw все одно впроваджує строгу конфігурацію, коли +бекенд увімкнув bundle MCP, щоб фонові запуски залишалися ізольованими. + +Вбудовані MCP-рантайми з областю дії сесії кешуються для повторного використання в межах сесії, а потім +очищаються після `mcp.sessionIdleTtlMs` мілісекунд простою (типово 10 +хвилин; встановіть `0`, щоб вимкнути). Одноразові вбудовані запуски, як-от перевірки auth, +генерація slug і очищення запитів recall Active Memory, виконують очищення наприкінці запуску, щоб дочірні +stdio-процеси й потоки Streamable HTTP/SSE не жили довше за сам запуск. ## Обмеження -- **Без прямих викликів інструментів OpenClaw.** OpenClaw не інжектує виклики інструментів у - протокол CLI-бекенда. Бекенди бачать інструменти gateway лише тоді, коли використовують +- **Без прямих викликів інструментів OpenClaw.** OpenClaw не впроваджує виклики інструментів у + протокол бекенду CLI. Бекенди бачать інструменти gateway лише тоді, коли вони увімкнули `bundleMcp: true`. -- **Streaming залежить від бекенда.** Деякі бекенди передають JSONL потоком; інші буферизують +- **Потокова передача залежить від бекенду.** Деякі бекенди передають JSONL потоком; інші буферизують до завершення. - **Структуровані виходи** залежать від JSON-формату CLI. - **Сесії Codex CLI** відновлюються через текстовий вивід (без JSONL), що менш - структуровано, ніж початковий запуск `--json`. Сесії OpenClaw і далі працюють + структуровано, ніж початковий запуск `--json`. Сесії OpenClaw при цьому все одно працюють нормально. -## Усунення несправностей +## Усунення проблем - **CLI не знайдено**: задайте `command` як повний шлях. - **Неправильна назва моделі**: використовуйте `modelAliases`, щоб зіставити `provider/model` → модель CLI. -- **Немає безперервності сесії**: переконайтеся, що задано `sessionArg` і що `sessionMode` не є +- **Немає безперервності сесії**: переконайтеся, що задано `sessionArg`, а `sessionMode` не дорівнює `none` (Codex CLI наразі не може відновлюватися з JSON-виводом). -- **Зображення ігноруються**: задайте `imageArg` (і переконайтеся, що CLI підтримує шляхи до файлів). +- **Зображення ігноруються**: задайте `imageArg` (і перевірте, що CLI підтримує шляхи до файлів). -## Пов’язане +## Пов’язані матеріали -- [Gateway runbook](/uk/gateway) -- [Local models](/uk/gateway/local-models) +- [Runbook Gateway](/uk/gateway) +- [Локальні моделі](/uk/gateway/local-models) diff --git a/docs/uk/gateway/config-tools.md b/docs/uk/gateway/config-tools.md index 8eb6df9e0..dd2633805 100644 --- a/docs/uk/gateway/config-tools.md +++ b/docs/uk/gateway/config-tools.md @@ -1,20 +1,20 @@ --- read_when: - - Налаштування політики, списків дозволеного або експериментальних можливостей для `tools.*` - - Реєстрація користувацьких провайдерів або перевизначення базових URL-адрес + - Налаштування політики, списків дозволених елементів або експериментальних функцій `tools.*` + - Реєстрація власних провайдерів або перевизначення base URL - Налаштування самостійно розміщених кінцевих точок, сумісних з OpenAI -summary: Конфігурація інструментів (політика, експериментальні перемикачі, інструменти на основі провайдерів) і налаштування користувацького провайдера/base-URL -title: Конфігурація — інструменти та користувацькі провайдери +summary: Конфігурація інструментів (політика, експериментальні перемикачі, інструменти з підтримкою провайдера) і налаштування власного провайдера/base-URL +title: Конфігурація — інструменти та власні провайдери x-i18n: - generated_at: "2026-04-25T00:30:50Z" + generated_at: "2026-04-25T07:01:57Z" model: gpt-5.4 provider: openai - source_hash: a3a9ab07a5536196f3ba6c64111eb97206c3b4ff12e497564fe09684193e5c8a + source_hash: d63b080550a6c95d714d3bb42c2b079368040aa09378d88c2e498ccd5ec113c1 source_path: gateway/config-tools.md workflow: 15 --- -Ключі конфігурації `tools.*` і налаштування користувацького провайдера / base-URL. Для агентів, +Ключі конфігурації `tools.*` і налаштування власного провайдера / base URL. Для агентів, каналів та інших ключів конфігурації верхнього рівня див. [Довідник із конфігурації](/uk/gateway/configuration-reference). @@ -22,7 +22,7 @@ x-i18n: ### Профілі інструментів -`tools.profile` задає базовий список дозволеного перед `tools.allow`/`tools.deny`: +`tools.profile` задає базовий список дозволених елементів перед `tools.allow`/`tools.deny`: Локальне онбординг-налаштування за замовчуванням встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явно вказані профілі зберігаються). @@ -35,24 +35,24 @@ x-i18n: ### Групи інструментів -| Група | Інструменти | -| ------------------ | --------------------------------------------------------------------------------------------------------------------- | -| `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 вимкнено. +Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Без урахування регістру, підтримує шаблони `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено. ```json5 { @@ -78,7 +78,7 @@ x-i18n: ### `tools.elevated` -Керує розширеним доступом `exec` поза пісочницею: +Керує розширеним доступом `exec` поза sandbox: ```json5 { @@ -96,7 +96,7 @@ x-i18n: - Перевизначення на рівні агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. - `/elevated on|off|ask|full` зберігає стан для кожної сесії; вбудовані директиви застосовуються до одного повідомлення. -- Розширений `exec` обходить пісочницю та використовує налаштований шлях виходу (`gateway` за замовчуванням або `node`, коли ціль `exec` — `node`). +- Розширений `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` за замовчуванням або `node`, якщо ціль `exec` — `node`). ### `tools.exec` @@ -120,8 +120,8 @@ x-i18n: ### `tools.loopDetection` -Перевірки безпеки на цикли інструментів **вимкнені за замовчуванням**. Установіть `enabled: true`, щоб увімкнути виявлення. -Параметри можна задати глобально в `tools.loopDetection` і перевизначити для окремого агента в `agents.list[].tools.loopDetection`. +Перевірки безпеки циклів інструментів **вимкнені за замовчуванням**. Установіть `enabled: true`, щоб увімкнути виявлення. +Параметри можна визначити глобально в `tools.loopDetection` і перевизначити для окремого агента в `agents.list[].tools.loopDetection`. ```json5 { @@ -166,7 +166,7 @@ x-i18n: }, fetch: { enabled: true, - provider: "firecrawl", // необов’язково; пропустіть для автовизначення + provider: "firecrawl", // необов’язково; не вказуйте для автовизначення maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, @@ -191,7 +191,7 @@ x-i18n: media: { concurrency: 2, asyncCompletion: { - directSend: false, // опціонально: надсилати завершені асинхронні музичні/відео результати безпосередньо в канал + directSend: false, // опціонально: надсилати завершену асинхронну музику/відео безпосередньо в канал }, audio: { enabled: true, @@ -217,7 +217,7 @@ x-i18n: -**Запис провайдера** (`type: "provider"` або пропущено): +**Запис провайдера** (`type: "provider"` або не вказано): - `provider`: ідентифікатор API-провайдера (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) - `model`: перевизначення ідентифікатора моделі @@ -226,21 +226,21 @@ x-i18n: **CLI-запис** (`type: "cli"`): - `command`: виконуваний файл для запуску -- `args`: шаблонізовані аргументи (підтримує `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) +- `args`: параметризовані аргументи (підтримуються `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) -**Спільні поля:** +**Загальні поля:** - `capabilities`: необов’язковий список (`image`, `audio`, `video`). Значення за замовчуванням: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису. -- У разі помилки використовується наступний запис. +- У разі помилки виконується перехід до наступного запису. -Автентифікація провайдера виконується у стандартному порядку: `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` + (застарілий шлях пробудження сесії запитувача/доставки через модель). @@ -259,9 +259,9 @@ x-i18n: ### `tools.sessions` -Керує тим, які сесії можуть бути ціллю для інструментів сесій (`sessions_list`, `sessions_history`, `sessions_send`). +Керує тим, на які сесії можуть бути націлені інструменти сесій (`sessions_list`, `sessions_history`, `sessions_send`). -За замовчуванням: `tree` (поточна сесія + сесії, породжені нею, наприклад субагенти). +Значення за замовчуванням: `tree` (поточна сесія + сесії, породжені нею, наприклад субагенти). ```json5 { @@ -279,8 +279,8 @@ x-i18n: - `self`: лише ключ поточної сесії. - `tree`: поточна сесія + сесії, породжені поточною сесією (субагенти). - `agent`: будь-яка сесія, що належить поточному ідентифікатору агента (може включати інших користувачів, якщо ви запускаєте сесії для кожного відправника під тим самим ідентифікатором агента). -- `all`: будь-яка сесія. Націлювання між агентами все одно вимагає `tools.agentToAgent`. -- Обмеження пісочниці: коли поточна сесія працює в пісочниці і `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"`. ### `tools.sessions_spawn` @@ -291,10 +291,10 @@ x-i18n: tools: { sessions_spawn: { attachments: { - enabled: false, // опціонально: установіть true, щоб дозволити вбудовані файлові вкладення - maxTotalBytes: 5242880, // загалом 5 МБ для всіх файлів + enabled: false, // опціонально: встановіть true, щоб дозволити вбудовані файлові вкладення + maxTotalBytes: 5242880, // 5 MB сумарно для всіх файлів maxFiles: 50, - maxFileBytes: 1048576, // 1 МБ на файл + maxFileBytes: 1048576, // 1 MB на файл retainOnSessionKeep: false, // зберігати вкладення, коли cleanup="keep" }, }, @@ -306,16 +306,16 @@ x-i18n: - Вкладення підтримуються лише для `runtime: "subagent"`. Середовище ACP їх відхиляє. - Файли матеріалізуються в робочому просторі дочірньої сесії в `.openclaw/attachments//` разом із `.manifest.json`. -- Вміст вкладень автоматично редагується під час збереження транскрипту. -- Входи base64 перевіряються суворою перевіркою алфавіту/доповнення та захистом розміру до декодування. +- Вміст вкладень автоматично редагується в збереженні транскриптів. +- Входи Base64 перевіряються суворою перевіркою алфавіту/доповнення та захистом розміру до декодування. - Права доступу до файлів: `0700` для каталогів і `0600` для файлів. -- Очищення виконується згідно з політикою `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. +- Очищення виконується відповідно до політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. ### `tools.experimental` -Прапорці експериментальних вбудованих інструментів. За замовчуванням вимкнено, якщо не застосовується правило автоувімкнення strict-agentic GPT-5. +Експериментальні прапорці вбудованих інструментів. За замовчуванням вимкнено, якщо не застосовується правило автоувімкнення strict-agentic GPT-5. ```json5 { @@ -330,8 +330,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` @@ -352,15 +352,15 @@ x-i18n: ``` - `model`: модель за замовчуванням для породжених субагентів. Якщо не вказано, субагенти успадковують модель викликача. -- `allowAgents`: список дозволених ідентифікаторів цільових агентів за замовчуванням для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; за замовчуванням: лише той самий агент). -- `runTimeoutSeconds`: тайм-аут за замовчуванням (у секундах) для `sessions_spawn`, коли виклик інструмента не містить `runTimeoutSeconds`. `0` означає відсутність тайм-ауту. -- Політика інструментів для кожного субагента: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- `allowAgents`: список дозволених цільових ідентифікаторів агентів за замовчуванням для `sessions_spawn`, якщо агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; за замовчуванням: лише той самий агент). +- `runTimeoutSeconds`: тайм-аут за замовчуванням (у секундах) для `sessions_spawn`, коли виклик інструмента не містить `runTimeoutSeconds`. `0` означає без тайм-ауту. +- Політика інструментів для субагентів: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Користувацькі провайдери та base URL +## Власні провайдери та base URL -OpenClaw використовує вбудований каталог моделей. Додавайте користувацьких провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. +OpenClaw використовує вбудований каталог моделей. Додавайте власних провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -389,49 +389,49 @@ OpenClaw використовує вбудований каталог модел } ``` -- Використовуйте `authHeader: true` + `headers` для нестандартних потреб автентифікації. +- Використовуйте `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` зберігає явне обмеження середовища виконання, якщо воно задане; використовуйте це, щоб обмежити ефективний контекст без зміни власних метаданих моделі. + - Значення `apiKey` для провайдера, яким керує SecretRef, оновлюються з вихідних маркерів (`ENV_VAR_NAME` для посилань на змінні середовища, `secretref-managed` для посилань на файл/exec) замість збереження розкритих секретів. + - Значення заголовків провайдера, якими керує SecretRef, оновлюються з вихідних маркерів (`secretref-env:ENV_VAR_NAME` для посилань на змінні середовища, `secretref-managed` для посилань на файл/exec). + - Порожні або відсутні агентські `apiKey`/`baseUrl` беруться з `models.providers` у конфігурації. + - Для однакових моделей `contextWindow`/`maxTokens` використовують більше значення між явною конфігурацією та неявними значеннями каталогу. + - Для однакових моделей `contextTokens` зберігає явне обмеження середовища виконання, якщо воно задане; використовуйте це, щоб обмежити ефективний контекст без зміни рідних метаданих моделі. - Використовуйте `models.mode: "replace"`, якщо хочете, щоб конфігурація повністю переписала `models.json`. - - Збереження маркерів є авторитетним щодо джерела: маркери записуються з активного знімка вихідної конфігурації (до розкриття), а не з розкритих значень секретів середовища виконання. + - Збереження маркерів визначається джерелом: маркери записуються з активного знімка конфігурації джерела (до розкриття), а не з розкритих секретних значень середовища виконання. ### Докладно про поля провайдера -- `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.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.*.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.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` додавати `options.num_ctx` у запити (за замовчуванням: `true`). -- `models.providers.*.authHeader`: примусово передавати облікові дані в заголовку `Authorization`, коли це потрібно. -- `models.providers.*.baseUrl`: базова URL-адреса висхідного API. -- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації через проксі/орендаря. -- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів до провайдера моделі. - - `request.headers`: додаткові заголовки (об’єднуються зі значеннями провайдера за замовчуванням). Значення підтримують SecretRef. +- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вставляє `options.num_ctx` у запити (за замовчуванням: `true`). +- `models.providers.*.authHeader`: примусово передає облікові дані в заголовку `Authorization`, коли це потрібно. +- `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.allowPrivateNetwork`: якщо `true`, дозволяє HTTPS до `baseUrl`, коли DNS резолвиться в приватні, CGNAT або подібні діапазони, через захист HTTP fetch провайдера (явне рішення оператора для довірених самостійно розміщених OpenAI-сумісних кінцевих точок). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-захист fetch. За замовчуванням `false`. - `models.providers.*.models`: явні записи каталогу моделей провайдера. -- `models.providers.*.models.*.contextWindow`: метадані власного вікна контексту моделі. -- `models.providers.*.models.*.contextTokens`: необов’язкове обмеження контексту середовища виконання. Використовуйте це, коли хочете менший ефективний бюджет контексту, ніж власний `contextWindow` моделі. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім не-власним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це значення в `false` під час виконання. Порожній/відсутній `baseUrl` зберігає стандартну поведінку OpenAI. -- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-сумісних chat-кінцевих точок, що приймають лише рядки. Коли `true`, OpenClaw сплющує масиви `messages[].content`, які містять лише текст, у звичайні рядки перед надсиланням запиту. -- `plugins.entries.amazon-bedrock.config.discovery`: корінь налаштувань авто-виявлення Bedrock. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне виявлення. +- `models.providers.*.models.*.contextWindow`: метадані рідного вікна контексту моделі. +- `models.providers.*.models.*.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. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнення/вимкнення неявного виявлення. - `plugins.entries.amazon-bedrock.config.discovery.region`: регіон AWS для виявлення. - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр ідентифікатора провайдера для цільового виявлення. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: інтервал опитування для оновлення виявлення. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервне вікно контексту для виявлених моделей. -- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервна максимальна кількість токенів виводу для виявлених моделей. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервне максимальне число вихідних токенів для виявлених моделей. ### Приклади провайдерів @@ -486,7 +486,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або посилання `opencode-go/...` для каталогу Go. Скорочений варіант: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`. +Установіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або `opencode-go/...` для каталогу Go. Скорочений варіант: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`. @@ -507,7 +507,7 @@ OpenClaw використовує вбудований каталог модел - Загальна кінцева точка: `https://api.z.ai/api/paas/v4` - Кінцева точка для кодування (за замовчуванням): `https://api.z.ai/api/coding/paas/v4` -- Для загальної кінцевої точки визначте користувацького провайдера з перевизначенням base URL. +- Для загальної кінцевої точки визначте власного провайдера з перевизначенням base URL. @@ -546,9 +546,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 оголошують сумісність потокового використання на спільному +Рідні кінцеві точки Moonshot оголошують сумісність використання потокової передачі на спільному транспорті `openai-completions`, і OpenClaw визначає це за можливостями кінцевої точки, а не лише за ідентифікатором вбудованого провайдера. @@ -607,7 +607,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Base URL має не містити `/v1` (клієнт Anthropic додає його сам). Скорочений варіант: `openclaw onboard --auth-choice synthetic-api-key`. +Base URL має не містити `/v1` (клієнт Anthropic додає його). Скорочений варіант: `openclaw onboard --auth-choice synthetic-api-key`. @@ -652,15 +652,15 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й `openclaw onboard --auth-choice minimax-cn-api`. Каталог моделей за замовчуванням містить лише M2.7. На Anthropic-сумісному шляху потокової передачі OpenClaw вимикає thinking -за замовчуванням, якщо ви явно не задасте `thinking` самостійно. `/fast on` або +для MiniMax за замовчуванням, якщо ви явно не задасте `thinking` самостійно. `/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. - + -Див. [Локальні моделі](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на достатньо потужному обладнанні; залишайте розміщені моделі об’єднаними для резервного використання. +Див. [Локальні моделі](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на достатньо потужному обладнанні; залишайте об’єднаними розміщені моделі як резервний варіант. diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index 78a9d533f..60bb687d0 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -1,61 +1,99 @@ --- read_when: - - Вам потрібні точні семантики полів конфігурації або значення за замовчуванням - - Ви перевіряєте блоки конфігурації каналів, моделей, Gateway або інструментів -summary: Довідка з конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем -title: Довідка з конфігурації + - Вам потрібні точні семантики або значення за замовчуванням конфігурації на рівні полів + - Ви перевіряєте блоки конфігурації каналу, моделі, Gateway або інструмента +summary: Довідник конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем +title: Довідник конфігурації x-i18n: - generated_at: "2026-04-25T05:55:51Z" + generated_at: "2026-04-25T07:01:56Z" model: gpt-5.4 provider: openai - source_hash: 6fc32c7387a8ece01020342186b52202d954a44c6db3fa827a5ed4302e995af7 + source_hash: a0f69861c754e0f6d3e41ac357fa56612b90da69249c6f24ec9f6ade21acc1d3 source_path: gateway/configuration-reference.md workflow: 15 --- -Основна довідка з конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration). +Основний довідник конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Конфігурація](/uk/gateway/configuration). -Охоплює основні поверхні конфігурації OpenClaw і містить посилання назовні, коли підсистема має власну глибшу довідку. Каталоги команд, що належать каналам і Plugin, а також глибокі параметри пам’яті/QMD розміщено на окремих сторінках, а не тут. +Охоплює основні поверхні конфігурації OpenClaw і надає посилання назовні, коли підсистема має власний глибший довідник. Каталоги команд, що належать каналам і Plugin, а також детальні параметри пам’яті/QMD розміщені на окремих сторінках, а не тут. Джерело істини в коді: -- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, із вбудованими метаданими Plugin/каналів, об’єднаними за наявності -- `config.schema.lookup` повертає один вузол схеми для певного шляху для інструментів детального перегляду -- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють baseline hash документації конфігурації щодо поточної поверхні схеми +- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, із об’єднаними метаданими bundled/plugin/channel, коли вони доступні +- `config.schema.lookup` повертає один вузол схеми для вказаного шляху для інструментів детального перегляду +- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш документації конфігурації відносно поточної поверхні схеми -Окремі глибокі довідники: +Окремі поглиблені довідники: -- [Memory configuration reference](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming` -- [Slash commands](/uk/tools/slash-commands) для поточного каталогу вбудованих + bundled команд -- сторінки каналів/Plugin-власників для поверхонь команд, специфічних для каналу +- [Довідник конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming` +- [Slash-команди](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд +- сторінки відповідного каналу/Plugin для поверхонь команд, специфічних для каналу -Формат конфігурації — **JSON5** (дозволено коментарі та завершаючі коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не задано. +Формат конфігурації — **JSON5** (дозволені коментарі та кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено. --- ## Канали -Ключі конфігурації для окремих каналів перенесено на окрему сторінку — див. -[Configuration — channels](/uk/gateway/config-channels) для `channels.*`, -включно зі Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та іншими -bundled каналами (автентифікація, контроль доступу, кілька облікових записів, обмеження за згадками). +Ключі конфігурації для кожного каналу перенесено на окрему сторінку — див. +[Конфігурація — канали](/uk/gateway/config-channels) для `channels.*`, +зокрема Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та інших +bundled каналів (автентифікація, контроль доступу, кілька облікових записів, керування згадками). -## Типові значення агента, мультиагентність, сесії та повідомлення +## Значення агента за замовчуванням, multi-agent, сесії та повідомлення Перенесено на окрему сторінку — див. -[Configuration — agents](/uk/gateway/config-agents) для: +[Конфігурація — агенти](/uk/gateway/config-agents) для: -- `agents.defaults.*` (робочий простір, модель, thinking, heartbeat, пам’ять, медіа, Skills, sandbox) -- `multiAgent.*` (маршрутизація та прив’язки мультиагентності) -- `session.*` (життєвий цикл сесії, compaction, prунінг) +- `agents.defaults.*` (робочий простір, модель, thinking, Heartbeat, пам’ять, медіа, Skills, sandbox) +- `multiAgent.*` (маршрутизація та прив’язки multi-agent) +- `session.*` (життєвий цикл сесії, Compaction, очищення) - `messages.*` (доставка повідомлень, TTS, рендеринг markdown) - `talk.*` (режим Talk) - - `talk.silenceTimeoutMs`: якщо не задано, Talk зберігає типове для платформи вікно паузи перед надсиланням транскрипту (`700 ms на macOS та Android, 900 ms на iOS`) + - `talk.silenceTimeoutMs`: якщо не задано, Talk зберігає стандартне для платформи вікно паузи перед надсиланням транскрипту (`700 ms на macOS та Android, 900 ms на iOS`) -## Інструменти та власні провайдери +## Інструменти та користувацькі провайдери -Політика інструментів, експериментальні перемикачі, конфігурація інструментів із підтримкою провайдерів і налаштування власних провайдерів / base-URL перенесені на окрему сторінку — див. -[Configuration — tools and custom providers](/uk/gateway/config-tools). +Політика інструментів, експериментальні перемикачі, конфігурація інструментів на базі провайдерів і налаштування користувацьких провайдерів / базових URL перенесено на окрему сторінку — див. +[Конфігурація — інструменти та користувацькі провайдери](/uk/gateway/config-tools). + +## MCP + +Визначення MCP-серверів, якими керує OpenClaw, знаходяться в `mcp.servers` і +використовуються вбудованим Pi та іншими адаптерами часу виконання. Команди `openclaw mcp list`, +`show`, `set` і `unset` керують цим блоком без підключення до +цільового сервера під час редагування конфігурації. + +```json5 +{ + mcp: { + // Необов’язково. За замовчуванням: 600000 ms (10 хвилин). Установіть 0, щоб вимкнути видалення при простої. + sessionIdleTtlMs: 600000, + servers: { + docs: { + command: "npx", + args: ["-y", "@modelcontextprotocol/server-fetch"], + }, + remote: { + url: "https://example.com/mcp", + transport: "streamable-http", // streamable-http | sse + headers: { + Authorization: "Bearer ${MCP_REMOTE_TOKEN}", + }, + }, + }, + }, +} +``` + +- `mcp.servers`: іменовані визначення stdio або віддалених MCP-серверів для середовищ виконання, які + надають налаштовані інструменти MCP. +- `mcp.sessionIdleTtlMs`: TTL простою для bundled MCP runtime з областю дії сесії. + Одноразові вбудовані запуски запитують очищення наприкінці запуску; цей TTL є запасним механізмом для + довготривалих сесій і майбутніх викликів. + +Див. [MCP](/uk/cli/mcp#openclaw-as-an-mcp-client-registry) і +[CLI backends](/uk/gateway/cli-backends#bundle-mcp-overlays) для поведінки під час виконання. ## Skills @@ -82,14 +120,14 @@ bundled каналами (автентифікація, контроль дос } ``` -- `allowBundled`: необов’язковий allowlist лише для bundled Skills (керовані/робочі Skills не зачіпаються). -- `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет). -- `install.preferBrew`: якщо true, віддавати перевагу інсталяторам Homebrew, коли `brew` - доступний, перед переходом до інших типів інсталяторів. -- `install.nodeManager`: пріоритет менеджера Node для специфікацій `metadata.openclaw.install` +- `allowBundled`: необов’язковий список дозволу лише для bundled skills (керовані/workspace skills не зачіпаються). +- `load.extraDirs`: додаткові спільні корені skills (найнижчий пріоритет). +- `install.preferBrew`: якщо `true`, надавати перевагу інсталяторам Homebrew, коли `brew` + доступний, перш ніж переходити до інших типів інсталяторів. +- `install.nodeManager`: бажаний менеджер вузлів для специфікацій `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` вимикає Skill, навіть якщо він bundled/installed. -- `entries..apiKey`: спрощене поле для Skills, які оголошують основну env-змінну (рядок відкритого тексту або об’єкт SecretRef). +- `entries..enabled: false` вимикає skill, навіть якщо він bundled/інстальований. +- `entries..apiKey`: зручне поле для skills, які оголошують основну змінну середовища (простий текстовий рядок або об’єкт SecretRef). --- @@ -117,43 +155,43 @@ bundled каналами (автентифікація, контроль дос } ``` -- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions` і `plugins.load.paths`. -- Виявлення приймає нативні Plugin OpenClaw, а також сумісні bundles Codex і Claude, включно з bundles Claude зі стандартним макетом без manifest. -- **Зміни конфігурації потребують перезапуску gateway.** -- `allow`: необов’язковий allowlist (завантажуються лише перелічені Plugin). `deny` має пріоритет. -- `plugins.entries..apiKey`: спрощене поле API-ключа на рівні Plugin (коли підтримується Plugin). -- `plugins.entries..env`: мапа env-змінних у межах Plugin. -- `plugins.entries..hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` і ігнорує поля, що змінюють prompt, із застарілого `before_agent_start`, зберігаючи застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hooks Plugin і підтримуваних директорій hooks, наданих bundle. -- `plugins.entries..hooks.allowConversationAccess`: коли `true`, довірені неbundled Plugin можуть читати сирий вміст розмови з типізованих hooks, таких як `llm_input`, `llm_output` і `agent_end`. -- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремого запуску фонових subagent. -- `plugins.entries..subagent.allowedModels`: необов’язковий allowlist канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"`, лише якщо свідомо хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (валідується схемою нативного Plugin OpenClaw, якщо доступна). -- Налаштування облікового запису/runtime для Plugin-каналів розміщуються в `channels.` і мають описуватися метаданими `channelConfigs` у manifest Plugin-власника, а не центральним реєстром параметрів OpenClaw. -- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера Firecrawl web-fetch. - - `apiKey`: API-ключ Firecrawl (приймає SecretRef). Використовує резервне значення з `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілого `tools.web.fetch.firecrawl.apiKey` або env-змінної `FIRECRAWL_API_KEY`. - - `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`). - - `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`). - - `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні). - - `timeoutSeconds`: тайм-аут scrape-запиту в секундах (типово: `60`). +- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. +- Виявлення підтримує нативні Plugins OpenClaw, а також сумісні пакети Codex і Claude, включно з пакетами Claude стандартного макета без маніфесту. +- **Зміни конфігурації потребують перезапуску Gateway.** +- `allow`: необов’язковий список дозволу (завантажуються лише перелічені Plugins). `deny` має пріоритет. +- `plugins.entries..apiKey`: зручне поле API-ключа на рівні Plugin (коли підтримується Plugin). +- `plugins.entries..env`: карта змінних середовища в межах Plugin. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` та ігнорує поля зміни prompt із застарілого `before_agent_start`, зберігаючи при цьому застарілі `modelOverride` і `providerOverride`. Застосовується до нативних хуків Plugin і підтримуваних каталогів хуків, наданих пакетами. +- `plugins.entries..hooks.allowConversationAccess`: коли `true`, довірені небандловані Plugins можуть читати сирий вміст розмови з типізованих хуків, таких як `llm_input`, `llm_output` і `agent_end`. +- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для кожного запуску фонових підзапусків subagent. +- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволу канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли ви свідомо хочете дозволити будь-яку модель. +- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (перевіряється схемою нативного Plugin OpenClaw, якщо доступна). +- Налаштування облікових записів/runtime для плагінів каналів містяться в `channels.` і мають описуватися метаданими `channelConfigs` у маніфесті відповідного Plugin, а не центральним реєстром опцій OpenClaw. +- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl. + - `apiKey`: API-ключ Firecrawl (підтримує SecretRef). Використовує як резервне джерело `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілий `tools.web.fetch.firecrawl.apiKey` або змінну середовища `FIRECRAWL_API_KEY`. + - `baseUrl`: базовий URL API Firecrawl (за замовчуванням: `https://api.firecrawl.dev`). + - `onlyMainContent`: витягувати лише основний вміст сторінок (за замовчуванням: `true`). + - `maxAgeMs`: максимальний вік кешу в мілісекундах (за замовчуванням: `172800000` / 2 дні). + - `timeoutSeconds`: тайм-аут запиту на скрапінг у секундах (за замовчуванням: `60`). - `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok). - `enabled`: увімкнути провайдер X Search. - - `model`: модель Grok, яку використовувати для пошуку (наприклад, `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming. Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів. - - `enabled`: головний перемикач dreaming (типово `false`). - - `frequency`: Cron-каденція для кожного повного циклу dreaming (типово `"0 3 * * *"`). + - `model`: модель Grok для використання в пошуку (наприклад, `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: налаштування dreaming пам’яті. Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів. + - `enabled`: головний перемикач dreaming (за замовчуванням `false`). + - `frequency`: частота Cron для кожного повного циклу dreaming (за замовчуванням `"0 3 * * *"`). - політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації). -- Повна конфігурація пам’яті міститься в [Memory configuration reference](/uk/reference/memory-config): +- Повна конфігурація пам’яті міститься в [Довіднику конфігурації пам’яті](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені Plugin-бандли Claude також можуть додавати вбудовані типові значення Pi з `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі конфігурації OpenClaw. -- `plugins.slots.memory`: вибрати id активного Plugin пам’яті або `"none"`, щоб вимкнути Plugin пам’яті. -- `plugins.slots.contextEngine`: вибрати id активного Plugin engine контексту; типово `"legacy"`, якщо ви не встановили й не вибрали інший engine. -- `plugins.installs`: керовані CLI метадані встановлення, які використовує `openclaw plugins update`. - - Містить `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Сприймайте `plugins.installs.*` як керований стан; віддавайте перевагу командам CLI замість ручного редагування. +- Увімкнені Plugins Claude bundle також можуть надавати вбудовані значення Pi за замовчуванням із `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі конфігурації OpenClaw. +- `plugins.slots.memory`: вибір id активного плагіна пам’яті або `"none"` для вимкнення плагінів пам’яті. +- `plugins.slots.contextEngine`: вибір id активного плагіна рушія контексту; за замовчуванням `"legacy"`, якщо ви не встановите й не виберете інший рушій. +- `plugins.installs`: метадані інсталяції, керовані CLI, які використовуються `openclaw plugins update`. + - Містять `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. + - Розглядайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI над ручними редагуваннями. Див. [Plugins](/uk/tools/plugin). @@ -168,8 +206,8 @@ bundled каналами (автентифікація, контроль дос evaluateEnabled: true, defaultProfile: "user", ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access - // allowPrivateNetwork: true, // legacy alias + // dangerouslyAllowPrivateNetwork: true, // вмикайте лише для довіреного доступу до приватної мережі + // allowPrivateNetwork: true, // застарілий псевдонім // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, @@ -209,31 +247,31 @@ bundled каналами (автентифікація, контроль дос - `tabCleanup` звільняє відстежувані вкладки основного агента після простою або коли сесія перевищує свій ліміт. Установіть `idleMinutes: 0` або `maxTabsPerSession: 0`, щоб вимкнути ці окремі режими очищення. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація браузера за замовчуванням лишається суворою. -- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, лише якщо ви свідомо довіряєте навігації браузера в приватній мережі. -- У суворому режимі віддалені кінцеві точки профілів CDP (`profiles.*.cdpUrl`) підпадають під ті самі обмеження приватної мережі під час перевірок доступності/виявлення. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація браузера за замовчуванням залишається суворо обмеженою. +- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації браузера в приватній мережі. +- У суворому режимі кінцеві точки віддалених профілів CDP (`profiles.*.cdpUrl`) підлягають такому самому блокуванню приватної мережі під час перевірок доступності/виявлення. - `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім. - У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. -- Віддалені профілі є лише attach-only (start/stop/reset недоступні). +- Віддалені профілі працюють лише в режимі attach-only (запуск/зупинка/скидання вимкнені). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. - Використовуйте HTTP(S), якщо хочете, щоб OpenClaw виявив `/json/version`; використовуйте WS(S), - коли ваш провайдер надає прямий URL WebSocket DevTools. -- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися - на вибраному хості або через підключений browser Node. -- Профілі `existing-session` можуть встановлювати `userDataDir`, щоб націлитися на конкретний - профіль браузера на базі Chromium, такий як Brave або Edge. -- Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії на основі snapshot/ref замість націлювання на CSS-selector, hooks завантаження одного файлу, - відсутність перевизначення тайм-ауту діалогів, відсутність `wait --load networkidle`, а також - `responsebody`, експорту PDF, перехоплення завантажень чи пакетних дій. + Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S), + коли ваш провайдер надає вам прямий URL WebSocket DevTools. +- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися на + вибраному хості або через підключений browser node. +- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний + профіль браузера на базі Chromium, наприклад Brave або Edge. +- Профілі `existing-session` зберігають поточні обмеження маршрутизації Chrome MCP: + дії на основі snapshot/ref замість націлювання за CSS-селекторами, хуки завантаження + одного файла, без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без + `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. - Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно задавайте `cdpUrl` лише для віддаленого CDP. -- Локальні керовані профілі можуть встановлювати `executablePath`, щоб перевизначити глобальний +- Локальні керовані профілі можуть задавати `executablePath`, щоб перевизначити глобальний `browser.executablePath` для цього профілю. Використовуйте це, щоб запускати один профіль у Chrome, а інший — у Brave. -- Порядок автодетекції: браузер за замовчуванням, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- `browser.executablePath` приймає `~` для домашньої директорії вашої ОС. -- Сервіс керування: лише loopback (порт похідний від `gateway.port`, типово `18791`). +- Порядок автовиявлення: браузер за замовчуванням, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- `browser.executablePath` приймає `~` для домашнього каталогу вашої ОС. +- Служба керування: лише local loopback (порт визначається з `gateway.port`, за замовчуванням `18791`). - `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад, `--disable-gpu`, розмір вікна або прапорці налагодження). @@ -253,8 +291,8 @@ bundled каналами (автентифікація, контроль дос } ``` -- `seamColor`: колір акценту для chrome інтерфейсу нативного застосунку (відтінок бульбашки Talk Mode тощо). -- `assistant`: перевизначення ідентичності в Control UI. Використовує резервне значення з ідентичності активного агента. +- `seamColor`: акцентний колір для chrome інтерфейсу нативного застосунку (відтінок бульбашки режиму Talk тощо). +- `assistant`: перевизначення ідентичності для Control UI. Якщо не задано, використовується ідентичність активного агента. --- @@ -329,71 +367,70 @@ bundled каналами (автентифікація, контроль дос } ``` - + -- `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`. +- `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо не вказано `local`. - `port`: єдиний мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. -- `bind`: `auto`, `loopback` (типово), `lan` (`0.0.0.0`), `tailnet` (лише Tailscale IP) або `custom`. -- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми host (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Примітка щодо Docker**: типове значення bind `loopback` слухає `127.0.0.1` всередині контейнера. За мережі Docker bridge (`-p 18789:18789`) трафік надходить через `eth0`, тому gateway недосяжний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. -- **Auth**: обов’язкова за замовчуванням. Прив’язки не до loopback вимагають auth gateway. На практиці це означає спільний token/password або reverse proxy з контролем ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер onboarding типово генерує token. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно встановіть `gateway.auth.mode` у `token` або `password`. Під час запуску та в потоках встановлення/відновлення сервісу виникає помилка, якщо налаштовано обидва, а mode не задано. -- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних налаштувань local loopback; цей варіант навмисно не пропонується в підказках onboarding. -- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з контролем ідентичності та довіряти заголовкам ідентичності від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy на тому самому хості через loopback не задовольняють auth trusted-proxy. -- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти auth Control UI/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цю auth через заголовки Tailscale; для них застосовується звичайний режим HTTP auth gateway. Цей безтокенний потік припускає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: необов’язковий лімітатор невдалих auth-спроб. Застосовується окремо для кожного IP клієнта та для кожного scope auth (спільний секрет і token пристрою відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`. - - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні помилкові спроби від того самого клієнта можуть спровокувати лімітатор на другому запиті замість того, щоб обидві просто завершилися звичайною невідповідністю. - - `gateway.auth.rateLimit.exemptLoopback` типово дорівнює `true`; встановіть `false`, якщо свідомо хочете також обмежувати трафік localhost (для тестових налаштувань або строгих proxy-розгортань). -- Спроби WS auth із browser-origin завжди обмежуються з вимкненим винятком loopback (додатковий захист від brute force localhost через браузер). -- На loopback ці блокування для browser-origin ізольовані за нормалізованим значенням `Origin`, - тому повторні збої з одного origin localhost не блокують автоматично інший origin. -- `tailscale.mode`: `serve` (лише tailnet, bind до loopback) або `funnel` (публічний, потребує auth). -- `controlUi.allowedOrigins`: явний allowlist browser-origin для підключень WebSocket до Gateway. Обов’язковий, коли очікуються клієнти браузера з не-loopback origin. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, що вмикає fallback origin за заголовком Host для розгортань, які навмисно покладаються на політику origin за заголовком Host. -- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійний client-side override - у середовищі процесу, який дозволяє незашифрований `ws://` до довірених IP - приватної мережі; за замовчуванням незашифрований трафік як і раніше дозволено лише для loopback. Еквівалента в `openclaw.json` немає, а конфігурація приватної мережі браузера, така як - `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на клієнти - WebSocket Gateway. -- `gateway.remote.token` / `.password`: поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway. -- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL зовнішнього relay APNs, який використовується офіційними/TestFlight збірками iOS після публікації relay-backed реєстрацій у gateway. Цей URL має збігатися з URL relay, зібраним у збірку iOS. -- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. Типово `10000`. -- Реєстрації з relay-backed прив’язуються до конкретної ідентичності gateway. Сполучений застосунок iOS викликає `gateway.identity.get`, включає цю ідентичність до реєстрації relay і пересилає до gateway send grant на рівні реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові env-перевизначення для наведеної вище конфігурації relay. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: лише для розробки — аварійний дозвіл на loopback HTTP relay URL. У production URL relay мають залишатися на HTTPS. -- `gateway.channelHealthCheckMinutes`: інтервал моніторингу здоров’я каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типово: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`. -- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor на канал/обліковий запис за ковзну годину. Типово: `10`. -- `channels..healthMonitor.enabled`: відмова від перезапусків health-monitor на рівні каналу зі збереженням увімкненого глобального монітора. -- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для каналів із кількома обліковими записами. Якщо задано, має пріоритет над перевизначенням на рівні каналу. -- Локальні шляхи викликів gateway можуть використовувати `gateway.remote.*` як fallback лише тоді, коли `gateway.auth.*` не задано. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і їх не вдається розв’язати, розв’язання завершується fail-closed (без маскування через fallback на remote). -- `trustedProxies`: IP reverse proxy, які завершують TLS або вставляють заголовки forwarded-client. Додавайте лише ті proxy, які ви контролюєте. Записи loopback усе ще валідні для налаштувань proxy/local-detection на тому самому хості (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. Типово `false` для fail-closed поведінки. -- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий allowlist CIDR/IP для автоматичного підтвердження першого сполучення пристрою вузла без запитаних scope. Якщо не задано, вимкнено. Це не підтверджує автоматично сполучення operator/browser/Control UI/WebChat і не підтверджує автоматично оновлення role, scope, metadata чи public-key. -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування allow/deny для оголошених команд вузлів після сполучення та перевірки allowlist. -- `gateway.tools.deny`: додаткові імена інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий deny list). -- `gateway.tools.allow`: прибрати імена інструментів із типового HTTP deny list. +- `bind`: `auto`, `loopback` (за замовчуванням), `lan` (`0.0.0.0`), `tailnet` (лише IP Tailscale) або `custom`. +- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хостів (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Примітка щодо Docker**: стандартне значення bind `loopback` слухає `127.0.0.1` усередині контейнера. За мережевої конфігурації Docker bridge (`-p 18789:18789`) трафік надходить через `eth0`, тому gateway недоступний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. +- **Auth**: за замовчуванням обов’язкова. Прив’язки не до loopback вимагають auth gateway. На практиці це означає спільний token/password або reverse proxy з урахуванням ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер початкового налаштування за замовчуванням генерує token. +- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно встановіть `gateway.auth.mode` у `token` або `password`. Запуск і потоки встановлення/відновлення сервісу завершуються помилкою, якщо налаштовано обидва, а режим не задано. +- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних налаштувань local loopback; цей варіант навмисно не пропонується в запитах початкового налаштування. +- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з урахуванням ідентичності та довіряти заголовкам ідентичності від `gateway.trustedProxies` (див. [Auth через Trusted Proxy](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy loopback на тому ж хості не задовольняють auth trusted-proxy. +- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цю auth через заголовки Tailscale; вони натомість дотримуються звичайного режиму HTTP auth gateway. Цей безтокеновий потік передбачає, що хост gateway є довіреним. За замовчуванням `true`, коли `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб auth. Застосовується окремо до IP клієнта і до області auth (спільний секрет і токен пристрою відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`. + - В асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом збою. Тому одночасні хибні спроби від того самого клієнта можуть активувати ліміт уже на другому запиті, замість того щоб обидві пройшли як звичайні невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` за замовчуванням має значення `true`; установіть `false`, якщо ви навмисно хочете також застосовувати rate limit до localhost-трафіку (для тестових середовищ або суворих proxy-розгортань). +- Спроби WS auth з походження browser завжди обмежуються без винятку для loopback (додатковий захист від brute force localhost через browser). +- У loopback ці блокування для походження browser ізольовані за нормалізованим значенням `Origin`, + тож повторні збої з одного localhost-origin не блокують автоматично + інше origin. +- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічний доступ, потребує auth). +- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язково, якщо очікуються browser-клієнти з origin не-loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервне визначення origin через заголовок Host для розгортань, що навмисно покладаються на політику origin за заголовком Host. +- `remote.transport`: `ssh` (за замовчуванням) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійний client-side override через змінну середовища процесу, + що дозволяє відкритий `ws://` до довірених IP приватної мережі; за замовчуванням відкритий текст лишається дозволеним лише для loopback. Еквівалента в `openclaw.json` немає, а конфігурація приватної мережі browser, така як + `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на WebSocket-клієнти Gateway. +- `gateway.remote.token` / `.password`: поля облікових даних віддаленого клієнта. Самі по собі вони не налаштовують auth gateway. +- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL зовнішнього relay APNs, який використовують офіційні/TestFlight збірки iOS після публікації в gateway реєстрацій на основі relay. Цей URL має збігатися з URL relay, скомпільованим у збірку iOS. +- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. За замовчуванням `10000`. +- Реєстрації на основі relay делегуються конкретній ідентичності gateway. Зв’язаний застосунок iOS отримує `gateway.identity.get`, включає цю ідентичність у реєстрацію relay і пересилає в gateway право надсилання в межах реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові env override для конфігурації relay вище. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний виняток лише для розробки для loopback HTTP URL relay. У production URL relay мають залишатися на HTTPS. +- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналів у хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски монітором стану. За замовчуванням: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого socket у хвилинах. Зберігайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. За замовчуванням: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітором стану на канал/обліковий запис за ковзну годину. За замовчуванням: `10`. +- `channels..healthMonitor.enabled`: відмова від перезапусків монітором стану для окремого каналу, зберігаючи глобальний монітор увімкненим. +- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для каналів з кількома обліковими записами. Якщо задано, має пріоритет над перевизначенням на рівні каналу. +- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання завершується за принципом fail closed (без маскування резервним віддаленим варіантом). +- `trustedProxies`: IP reverse proxy, які завершують TLS або додають заголовки forwarded-client. Додавайте лише proxy, які ви контролюєте. Записи loopback усе ще коректні для налаштувань proxy/локального виявлення на тому самому хості (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. За замовчуванням `false` для поведінки fail closed. +- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий список дозволу CIDR/IP для автоматичного схвалення першого pairing пристроїв node без запитаних областей доступу. Якщо не задано, вимкнено. Це не схвалює автоматично pairing operator/browser/Control UI/WebChat, а також не схвалює автоматично оновлення ролей, областей доступу, метаданих або публічних ключів. +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування дозволу/заборони для оголошених команд node після pairing та оцінки списку дозволу. +- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює стандартний список заборон). +- `gateway.tools.allow`: прибрати назви інструментів зі стандартного HTTP-списку заборон. -### OpenAI-сумісні кінцеві точки +### Кінцеві точки, сумісні з OpenAI - Chat Completions: вимкнено за замовчуванням. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Посилення захисту URL-входів Responses: +- Посилене захист URL-входів Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Порожні allowlist трактуються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` - і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. -- Необов’язковий заголовок посилення захисту відповіді: - - `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для HTTPS origin, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + Порожні списки дозволу трактуються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` + та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. +- Необов’язковий заголовок посиленого захисту відповіді: + - `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для HTTPS-origin, які ви контролюєте; див. [Auth через Trusted Proxy](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Ізоляція кількох екземплярів -Запускайте кілька gateway на одному хості з унікальними портами й каталогами стану: +Запускайте кілька gateway на одному хості з унікальними портами та каталогами стану: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -403,7 +440,7 @@ openclaw gateway --port 19001 Зручні прапорці: `--dev` (використовує `~/.openclaw-dev` + порт `19001`), `--profile ` (використовує `~/.openclaw-`). -Див. [Multiple Gateways](/uk/gateway/multiple-gateways). +Див. [Кілька Gateway](/uk/gateway/multiple-gateways). ### `gateway.tls` @@ -421,11 +458,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: вмикає завершення TLS на listener gateway (HTTPS/WSS) (типово: `false`). -- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для local/dev. -- `certPath`: шлях у файловій системі до файлу сертифіката TLS. -- `keyPath`: шлях у файловій системі до приватного ключа TLS; обмежте права доступу. -- `caPath`: необов’язковий шлях до пакета CA для верифікації клієнта або власних ланцюгів довіри. +- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (за замовчуванням: `false`). +- `autoGenerate`: автоматично генерує локальну самопідписану пару сертифікат/ключ, якщо явні файли не налаштовано; лише для local/dev. +- `certPath`: шлях у файловій системі до файла TLS-сертифіката. +- `keyPath`: шлях у файловій системі до файла приватного ключа TLS; обмежуйте доступ правами. +- `caPath`: необов’язковий шлях до bundle CA для перевірки клієнта або користувацьких ланцюжків довіри. ### `gateway.reload` @@ -441,13 +478,13 @@ openclaw gateway --port 19001 } ``` -- `mode`: керує тим, як зміни конфігурації застосовуються під час runtime. - - `"off"`: ігнорувати live-зміни; для змін потрібен явний перезапуск. +- `mode`: керує тим, як редагування конфігурації застосовуються під час виконання. + - `"off"`: ігнорувати живі зміни; зміни потребують явного перезапуску. - `"restart"`: завжди перезапускати процес gateway після зміни конфігурації. - - `"hot"`: застосовувати зміни в процесі без перезапуску. - - `"hybrid"` (типово): спочатку спробувати hot reload; за потреби перейти до перезапуску. + - `"hot"`: застосовувати зміни в межах процесу без перезапуску. + - `"hybrid"` (за замовчуванням): спочатку пробувати hot reload; за потреби переходити до перезапуску. - `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число). -- `deferralTimeoutMs`: максимальний час у мс очікування завершення операцій у процесі перед примусовим перезапуском (типово: `300000` = 5 хвилин). +- `deferralTimeoutMs`: максимальний час у мс очікування завершення поточних операцій перед примусовим перезапуском (за замовчуванням: `300000` = 5 хвилин). --- @@ -485,46 +522,46 @@ openclaw gateway --port 19001 ``` Auth: `Authorization: Bearer ` або `x-openclaw-token: `. -Токени hook у query string відхиляються. +Hook-токени в query string відхиляються. Примітки щодо валідації та безпеки: - `hooks.enabled=true` вимагає непорожній `hooks.token`. -- `hooks.token` має бути **відмінним** від `gateway.auth.token`; повторне використання token Gateway відхиляється. +- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання токена Gateway відхиляється. - `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`. - Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). -- Якщо mapping або preset використовує шаблонний `sessionKey`, установіть `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не потребують цього opt-in. +- Якщо mapping або preset використовує шаблонний `sessionKey`, установіть `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не потребують цього явного ввімкнення. **Кінцеві точки:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - `sessionKey` із payload запиту приймається лише коли `hooks.allowRequestSessionKey=true` (типово: `false`). + - `sessionKey` з тіла запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (за замовчуванням: `false`). - `POST /hooks/` → розв’язується через `hooks.mappings` - - Значення `sessionKey` у mapping, згенеровані шаблоном, розглядаються як зовнішньо передані й також потребують `hooks.allowRequestSessionKey=true`. + - Значення `sessionKey` у mapping, згенеровані шаблоном, вважаються зовнішньо наданими й також потребують `hooks.allowRequestSessionKey=true`. - + -- `match.path` відповідає підшляху після `/hooks` (наприклад `/hooks/gmail` → `gmail`). +- `match.path` відповідає підшляху після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). - `match.source` відповідає полю payload для загальних шляхів. -- Шаблони на кшталт `{{messages[0].subject}}` читають значення з payload. +- Шаблони на кшталт `{{messages[0].subject}}` читають дані з payload. - `transform` може вказувати на модуль JS/TS, який повертає дію hook. - - `transform.module` має бути відносним шляхом і лишатися в межах `hooks.transformsDir` (абсолютні шляхи й traversal відхиляються). -- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до типового значення. -- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або не задано = дозволити всі, `[]` = заборонити всі). -- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків агента через hook без явного `sessionKey`. -- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і ключам сесій mapping, керованим шаблонами, задавати `sessionKey` (типово: `false`). -- `allowedSessionKeyPrefixes`: необов’язковий allowlist префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Стає обов’язковим, коли будь-який mapping або preset використовує шаблонний `sessionKey`. -- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово `last`. -- `model` перевизначає LLM для цього запуску hook (має бути дозволена, якщо задано каталог моделей). + - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються). +- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до значення за замовчуванням. +- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або без значення = дозволити всі, `[]` = заборонити всі). +- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook agent без явного `sessionKey`. +- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і ключам сесії в mapping, керованим шаблонами, задавати `sessionKey` (за замовчуванням: `false`). +- `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Він стає обов’язковим, коли будь-який mapping або preset використовує шаблонний `sessionKey`. +- `deliver: true` надсилає фінальну відповідь у канал; `channel` за замовчуванням — `last`. +- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо задано каталог моделей). -### Інтеграція Gmail +### Інтеграція з Gmail - Вбудований preset Gmail використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`. - Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes`, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. -- Якщо вам потрібно `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість шаблонного типового значення. +- Якщо вам потрібен `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість шаблонного значення за замовчуванням. ```json5 { @@ -564,18 +601,18 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Обслуговує HTML/CSS/JS, які агент може редагувати, і A2UI через HTTP на порту Gateway: +- Обслуговує редаговані агентом HTML/CSS/JS і A2UI через HTTP на порту Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Лише локально: зберігайте `gateway.bind: "loopback"` (типово). -- Прив’язки не до loopback: маршрути canvas вимагають auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway. -- Node WebView зазвичай не надсилають заголовки auth; після сполучення й підключення вузла Gateway рекламує URL можливостей із scope вузла для доступу до canvas/A2UI. -- URL можливостей прив’язані до активної WS-сесії вузла та швидко спливають. Fallback на основі IP не використовується. -- Впроваджує клієнт live-reload у HTML, що обслуговується. -- Автоматично створює стартовий `index.html`, якщо каталог порожній. -- Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`. +- Лише локально: використовуйте `gateway.bind: "loopback"` (за замовчуванням). +- Bind не до loopback: маршрути canvas потребують auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway. +- Node WebView зазвичай не надсилають заголовки auth; після pairing і підключення node Gateway рекламує URL можливостей з областю дії node для доступу до canvas/A2UI. +- URL можливостей прив’язані до активної WS-сесії node і швидко спливають. Резервний варіант на основі IP не використовується. +- Впроваджує клієнт live reload у HTML, що обслуговується. +- Автоматично створює початковий `index.html`, якщо каталог порожній. +- Також обслуговує A2UI на `/__openclaw__/a2ui/`. - Зміни потребують перезапуску gateway. -- Вимкніть live reload для великих каталогів або помилок `EMFILE`. +- Вимкніть live reload для великих каталогів або в разі помилок `EMFILE`. --- @@ -593,11 +630,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `minimal` (типово): не включає `cliPath` + `sshPort` до TXT-записів. +- `minimal` (за замовчуванням): не включає `cliPath` + `sshPort` із TXT-записів. - `full`: включає `cliPath` + `sshPort`. -- Ім’я хоста типово `openclaw`. Перевизначте через `OPENCLAW_MDNS_HOSTNAME`. +- Ім’я хоста за замовчуванням — `openclaw`. Перевизначте через `OPENCLAW_MDNS_HOSTNAME`. -### Wide-area (DNS-SD) +### Глобальне виявлення (DNS-SD) ```json5 { @@ -607,7 +644,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + Tailscale split DNS. +Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднайте це із DNS-сервером (рекомендовано CoreDNS) + Tailscale split DNS. Налаштування: `openclaw dns setup --apply`. @@ -615,7 +652,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Середовище -### `env` (вбудовані env-змінні) +### `env` (вбудовані змінні середовища) ```json5 { @@ -632,14 +669,14 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Вбудовані env-змінні застосовуються лише якщо в середовищі процесу відсутній цей ключ. +- Вбудовані змінні середовища застосовуються лише тоді, коли у змінних середовища процесу немає цього ключа. - Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). - `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. -- Повний пріоритет див. у [Environment](/uk/help/environment). +- Див. [Середовище](/uk/help/environment) для повного порядку пріоритетів. -### Підстановка env-змінних +### Підстановка змінних середовища -Посилайтеся на env-змінні в будь-якому рядку конфігурації через `${VAR_NAME}`: +Посилайтеся на змінні середовища в будь-якому рядку конфігурації за допомогою `${VAR_NAME}`: ```json5 { @@ -649,7 +686,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. +- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації. - Екрануйте через `$${VAR}` для буквального `${VAR}`. - Працює з `$include`. @@ -658,7 +695,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Секрети -Посилання на секрети є адитивними: значення відкритим текстом також працюють. +Посилання на секрети є адитивними: значення у відкритому тексті теж продовжують працювати. ### `SecretRef` @@ -671,16 +708,16 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. Валідація: - шаблон `provider`: `^[a-z][a-z0-9_-]{0,63}$` -- шаблон id для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` id: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`) -- шаблон id для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- id для `source: "exec"` не мають містити сегменти шляху `.` або `..`, розділені слешами (наприклад `a/../b` відхиляється) +- шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- `id` для `source: "file"`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`) +- шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- `id` для `source: "exec"` не повинні містити сегменти шляху `.` або `..`, розділені слешами (наприклад, `a/../b` відхиляється) ### Підтримувана поверхня облікових даних -- Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface) +- Канонічна матриця: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface) - `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`. -- Посилання в `auth-profiles.json` включено до runtime-розв’язання та покриття аудиту. +- Посилання в `auth-profiles.json` включаються в runtime-розв’язання та покриття аудиту. ### Конфігурація провайдерів секретів @@ -713,13 +750,13 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. Примітки: - Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue значення `id` має бути `"value"`). -- Шляхи провайдера file та exec завершуються fail-closed, якщо перевірка Windows ACL недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. -- Провайдер `exec` вимагає абсолютний шлях `command` і використовує payload-и протоколу через stdin/stdout. -- За замовчуванням шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання, водночас перевіряючи шлях до розв’язаного цільового файлу. -- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до шляху розв’язаного цільового файлу. -- Дочірнє середовище `exec` за замовчуванням мінімальне; явно передайте потрібні змінні через `passEnv`. -- Посилання на секрети розв’язуються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. -- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на ввімкнених поверхнях призводять до помилки запуску/reload, а неактивні поверхні пропускаються з діагностикою. +- Шляхи провайдерів file і exec працюють за принципом fail closed, коли перевірка ACL Windows недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. +- Провайдер `exec` вимагає абсолютний шлях `command` і використовує payload протоколу через stdin/stdout. +- За замовчуванням шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи symlink із перевіркою розв’язаного цільового шляху. +- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до розв’язаного цільового шляху. +- Середовище дочірнього процесу `exec` за замовчуванням мінімальне; передавайте потрібні змінні явно через `passEnv`. +- Посилання на секрети розв’язуються під час активації в snapshot у пам’яті, після чого шляхи запитів читають лише цей snapshot. +- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на увімкнених поверхнях спричиняють збій запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. --- @@ -741,13 +778,13 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Профілі для кожного агента зберігаються в `/auth-profiles.json`. +- Профілі для окремих агентів зберігаються в `/auth-profiles.json`. - `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. -- Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілів auth на основі SecretRef. -- Статичні runtime-облікові дані надходять із розв’язаних знімків у пам’яті; застарілі статичні записи `auth.json` очищаються, коли їх виявлено. -- Застарілий імпорт OAuth із `~/.openclaw/credentials/oauth.json`. +- Профілі в режимі OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілів auth на основі SecretRef. +- Статичні runtime-облікові дані надходять із розв’язаних snapshot у пам’яті; застарілі статичні записи `auth.json` очищуються після виявлення. +- Застарілий імпорт OAuth відбувається з `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). -- Поведінка runtime секретів і інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). +- Поведінка runtime для секретів і інструменти `audit/configure/apply`: [Керування секретами](/uk/gateway/secrets). ### `auth.cooldowns` @@ -769,20 +806,15 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `billingBackoffHours`: базова затримка в годинах, коли профіль завершується помилкою через справжні помилки білінгу/недостатнього кредиту (типово: `5`). Явний текст про білінг - усе ще може потрапляти сюди навіть для відповідей `401`/`403`, але - провайдер-специфічні текстові зіставлення лишаються обмеженими тим провайдером, - якому вони належать (наприклад, OpenRouter - `Key limit exceeded`). Повторювані повідомлення HTTP `402` про usage-window або - ліміти витрат organization/workspace натомість лишаються в гілці `rate_limit`. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин затримки білінгу для кожного провайдера. -- `billingMaxHours`: межа в годинах для експоненційного зростання затримки білінгу (типово: `24`). -- `authPermanentBackoffMinutes`: базова затримка в хвилинах для high-confidence збоїв `auth_permanent` (типово: `10`). -- `authPermanentMaxMinutes`: межа в хвилинах для зростання затримки `auth_permanent` (типово: `60`). -- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників затримок (типово: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок перевантаження перед переходом до fallback моделі (типово: `1`). Сюди потрапляють форми зайнятості провайдера, як-от `ModelNotReadyException`. -- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок rate-limit перед переходом до fallback моделі (типово: `1`). Цей bucket rate-limit включає характерний для провайдерів текст, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `billingBackoffHours`: базовий backoff у годинах, коли профіль зазнає збою через справжні помилки billing/недостатнього кредиту (за замовчуванням: `5`). Явний текст billing усе ще може потрапити сюди навіть для відповідей `401`/`403`, але зіставлювачі тексту, специфічні для провайдера, залишаються обмеженими провайдером, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Повторно придатні помилки використання `402` у вікні usage-window або повідомлення про ліміт витрат organization/workspace натомість залишаються в шляху `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff billing для кожного провайдера. +- `billingMaxHours`: межа в годинах для експоненційного зростання backoff billing (за замовчуванням: `24`). +- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для збоїв `auth_permanent` з високою впевненістю (за замовчуванням: `10`). +- `authPermanentMaxMinutes`: межа в хвилинах для зростання backoff `auth_permanent` (за замовчуванням: `60`). +- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників backoff (за замовчуванням: `24`). +- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілю в межах одного провайдера для помилок перевантаження перед перемиканням на резервну модель (за замовчуванням: `1`). Сюди потрапляють форми «провайдер зайнятий», як-от `ModelNotReadyException`. +- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (за замовчуванням: `0`). +- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілю в межах одного провайдера для помилок rate limit перед перемиканням на резервну модель (за замовчуванням: `1`). Цей кошик rate limit включає текст у формі провайдера, наприклад `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- @@ -801,10 +833,10 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. -- Установіть `logging.file` для сталого шляху. -- `consoleLevel` підвищується до `debug`, коли використано `--verbose`. -- `maxFileBytes`: максимальний розмір файлу журналу в байтах, після якого записи пригнічуються (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. +- Файл журналу за замовчуванням: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. +- Установіть `logging.file` для стабільного шляху. +- `consoleLevel` підвищується до `debug`, коли використовується `--verbose`. +- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого записи пригнічуються (додатне ціле число; за замовчуванням: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. --- @@ -849,21 +881,22 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `enabled`: головний перемикач для виводу інструментування (типово: `true`). -- `flags`: масив рядків-прапорців, які вмикають цільовий вивід журналу (підтримуються wildcard, як-от `"telegram.*"` або `"*"`). -- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислі сесії, поки сесія лишається в стані обробки. -- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). -- `otel.endpoint`: URL collector для експорту OTel. -- `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`. -- `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються з запитами експорту OTel. -- `otel.serviceName`: ім’я сервісу для атрибутів resource. -- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнення експорту trace, metrics або logs. +- `enabled`: головний перемикач для виводу інструментування (за замовчуванням: `true`). +- `flags`: масив рядків-прапорців, які вмикають цільовий вивід журналу (підтримує шаблони з символами узагальнення, як-от `"telegram.*"` або `"*"`). +- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислу сесію, поки сесія залишається у стані обробки. +- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (за замовчуванням: `false`). +- `otel.endpoint`: URL колектора для експорту OTel. +- `otel.protocol`: `"http/protobuf"` (за замовчуванням) або `"grpc"`. +- `otel.headers`: додаткові метадані-заголовки HTTP/gRPC, що надсилаються із запитами експорту OTel. +- `otel.serviceName`: назва сервісу для атрибутів ресурсу. +- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або logs. - `otel.sampleRate`: частота семплювання trace `0`–`1`. -- `otel.flushIntervalMs`: періодичний інтервал flush телеметрії в мс. -- `otel.captureContent`: opt-in захоплення сирого вмісту для атрибутів span OTEL. Типово вимкнено. Булеве значення `true` захоплює вміст повідомлень/інструментів, крім system; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. -- `cacheTrace.enabled`: журналювати знімки cache trace для embedded-запусків (типово: `false`). -- `cacheTrace.filePath`: шлях виводу для JSONL cache trace (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається до виводу cache trace (усі типово: `true`). +- `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс. +- `otel.captureContent`: явне ввімкнення захоплення сирого вмісту для атрибутів span OTEL. За замовчуванням вимкнено. Булеве значення `true` захоплює вміст повідомлень/інструментів, що не є системними; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. +- `OPENCLAW_OTEL_PRELOADED=1`: перемикач середовища для хостів, які вже зареєстрували глобальний SDK OpenTelemetry. Тоді OpenClaw пропускає запуск/завершення SDK, що належить Plugin, але зберігає активними діагностичні прослуховувачі. +- `cacheTrace.enabled`: журналювати snapshot cache trace для вбудованих запусків (за замовчуванням: `false`). +- `cacheTrace.filePath`: вихідний шлях для JSONL cache trace (за замовчуванням: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід cache trace (усі за замовчуванням: `true`). --- @@ -886,11 +919,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - `channel`: канал релізів для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`. -- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`). -- `auto.enabled`: увімкнути фонове автооновлення для пакетних встановлень (типово: `false`). -- `auto.stableDelayHours`: мінімальна затримка в годинах перед автозастосуванням stable-каналу (типово: `6`; максимум: `168`). -- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (типово: `12`; максимум: `168`). -- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу в годинах (типово: `1`; максимум: `24`). +- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (за замовчуванням: `true`). +- `auto.enabled`: увімкнути фонове автооновлення для пакетних встановлень (за замовчуванням: `false`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед автозастосуванням stable-каналу (за замовчуванням: `6`; максимум: `168`). +- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (за замовчуванням: `12`; максимум: `168`). +- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу, у годинах (за замовчуванням: `1`; максимум: `24`). --- @@ -923,22 +956,22 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `enabled`: глобальний feature gate для ACP (типово: `false`). -- `dispatch.enabled`: незалежний gate для dispatch ходів сесії ACP (типово: `true`). Установіть `false`, щоб команди ACP лишалися доступними, але виконання блокувалося. -- `backend`: id типового runtime backend ACP (має відповідати зареєстрованому runtime plugin ACP). -- `defaultAgent`: fallback id цільового агента ACP, коли спавни не вказують явну ціль. -- `allowedAgents`: allowlist id агентів, дозволених для runtime-сесій ACP; порожнє значення означає відсутність додаткових обмежень. +- `enabled`: глобальний feature gate ACP (за замовчуванням: `false`). +- `dispatch.enabled`: незалежний gate для диспетчеризації ходів сесії ACP (за замовчуванням: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання. +- `backend`: id runtime backend ACP за замовчуванням (має відповідати зареєстрованому ACP runtime Plugin). +- `defaultAgent`: резервний id цільового агента ACP, коли spawn не вказує явну ціль. +- `allowedAgents`: список дозволу id агентів, дозволених для runtime-сесій ACP; порожній список означає відсутність додаткових обмежень. - `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP. -- `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту. -- `stream.maxChunkChars`: максимальний розмір chunk перед розбиттям проєкції потокового блока. -- `stream.repeatSuppression`: пригнічувати повторювані рядки status/tool на хід (типово: `true`). -- `stream.deliveryMode`: `"live"` передає потік інкрементально; `"final_only"` буферизує до термінальних подій ходу. -- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій tool (типово: `"paragraph"`). -- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, проєктованих за один хід ACP. -- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків status/update ACP. -- `stream.tagVisibility`: запис назв тегів у логічні перевизначення видимості для потокових подій. -- `runtime.ttlMinutes`: idle TTL у хвилинах для воркерів сесій ACP до моменту можливого очищення. -- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час bootstrap середовища runtime ACP. +- `stream.coalesceIdleMs`: вікно скидання простою в мс для потокового тексту. +- `stream.maxChunkChars`: максимальний розмір чанка перед розбиттям проєкції потокового блоку. +- `stream.repeatSuppression`: пригнічувати повторювані рядки стану/інструментів у межах одного ходу (за замовчуванням: `true`). +- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до кінцевих подій ходу. +- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (за замовчуванням: `"paragraph"`). +- `stream.maxOutputChars`: максимальна кількість символів виводу помічника, що проєктується за один хід ACP. +- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків стану/оновлення ACP. +- `stream.tagVisibility`: запис назв тегів із булевими перевизначеннями видимості для потокових подій. +- `runtime.ttlMinutes`: TTL простою в хвилинах для worker сесій ACP до моменту, коли їх можна очищати. +- `runtime.installCommand`: необов’язкова команда встановлення, яку слід виконати під час bootstrap середовища runtime ACP. --- @@ -954,17 +987,17 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `cli.banner.taglineMode` керує стилем tagline банера: - - `"random"` (типово): змінні кумедні/сезонні tagline. - - `"default"`: фіксований нейтральний tagline (`Усі ваші чати, один OpenClaw.`). - - `"off"`: без тексту tagline (назва/версія банера все одно показуються). -- Щоб приховати весь банер (а не лише tagline), установіть env `OPENCLAW_HIDE_BANNER=1`. +- `cli.banner.taglineMode` керує стилем слогана банера: + - `"random"` (за замовчуванням): ротаційні кумедні/сезонні слогани. + - `"default"`: фіксований нейтральний слоган (`Усі ваші чати, один OpenClaw.`). + - `"off"`: без тексту слогана (назва/версія банера все одно показуються). +- Щоб приховати весь банер (а не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Метадані, які записуються потоками покрокового налаштування CLI (`onboard`, `configure`, `doctor`): +Метадані, які записуються керованими CLI потоками налаштування (`onboard`, `configure`, `doctor`): ```json5 { @@ -982,13 +1015,13 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Ідентичність -Див. поля ідентичності `agents.list` у розділі [Agent defaults](/uk/gateway/config-agents#agent-defaults). +Див. поля ідентичності `agents.list` у розділі [Значення агента за замовчуванням](/uk/gateway/config-agents#agent-defaults). --- -## Bridge (застарілий, видалено) +## Bridge (застарілий, вилучений) -Поточні збірки більше не містять TCP bridge. Вузли підключаються через WebSocket Gateway. Ключі `bridge.*` більше не входять до схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP bridge. Node підключаються через WebSocket Gateway. Ключі `bridge.*` більше не входять до схеми конфігурації (валідація завершується помилкою, доки їх не буде вилучено; `openclaw doctor --fix` може прибрати невідомі ключі). @@ -1028,11 +1061,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `sessionRetention`: як довго зберігати завершені ізольовані сесії запуску cron перед pruning із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. Типово: `24h`; установіть `false`, щоб вимкнути. -- `runLog.maxBytes`: максимальний розмір файлу журналу одного запуску (`cron/runs/.jsonl`) перед pruning. Типово: `2_000_000` байтів. -- `runLog.keepLines`: найновіші рядки, що зберігаються, коли запускається pruning журналу запуску. Типово: `2000`. -- `webhookToken`: bearer token, що використовується для POST-доставки webhook cron (`delivery.mode = "webhook"`); якщо не задано, заголовок auth не надсилається. -- `webhook`: застарілий legacy fallback URL webhook (http/https), який використовується лише для збережених завдань, що все ще мають `notify: true`. +- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. За замовчуванням: `24h`; установіть `false`, щоб вимкнути. +- `runLog.maxBytes`: максимальний розмір файла журналу на один запуск (`cron/runs/.jsonl`) перед очищенням. За замовчуванням: `2_000_000` байтів. +- `runLog.keepLines`: кількість найновіших рядків, що зберігаються після спрацьовування очищення журналу запусків. За замовчуванням: `2000`. +- `webhookToken`: bearer token, який використовується для POST-доставки Webhook cron (`delivery.mode = "webhook"`); якщо не задано, заголовок auth не надсилається. +- `webhook`: застарілий резервний URL Webhook (http/https), який використовується лише для збережених завдань, у яких і далі встановлено `notify: true`. ### `cron.retry` @@ -1048,11 +1081,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (типово: `3`; діапазон: `0`–`10`). -- `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 елементів). -- `retryOn`: типи помилок, які спричиняють повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Не вказуйте, щоб повторювати всі тимчасові типи. +- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань за тимчасових помилок (за замовчуванням: `3`; діапазон: `0`–`10`). +- `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (за замовчуванням: `[30000, 60000, 300000]`; 1–10 записів). +- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Не вказуйте, щоб повторювати всі тимчасові типи. -Застосовується лише до одноразових cron-завдань. Для повторюваних завдань використовується окрема обробка помилок. +Застосовується лише до одноразових cron-завдань. Повторювані завдання використовують окрему обробку збоїв. ### `cron.failureAlert` @@ -1070,11 +1103,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `enabled`: увімкнути сповіщення про збої для cron-завдань (типово: `false`). -- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мінімум: `1`). +- `enabled`: увімкнути сповіщення про збої для cron-завдань (за замовчуванням: `false`). +- `after`: кількість послідовних збоїв до спрацьовування сповіщення (додатне ціле число, мінімум: `1`). - `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). -- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST на налаштований webhook. -- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки сповіщень. +- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` надсилає POST на налаштований Webhook. +- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки сповіщення. ### `cron.failureDestination` @@ -1091,51 +1124,51 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Типове призначення для сповіщень про збої cron для всіх завдань. -- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних цілі. +- Цільове місце за замовчуванням для сповіщень про збої cron для всіх завдань. +- `mode`: `"announce"` або `"webhook"`; за замовчуванням `"announce"`, коли є достатньо цільових даних. - `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки. -- `to`: явна ціль announce або URL webhook. Обов’язкове для режиму webhook. +- `to`: явна ціль announce або URL Webhook. Обов’язково для режиму webhook. - `accountId`: необов’язкове перевизначення облікового запису для доставки. -- `delivery.failureDestination` на рівні завдання перевизначає це глобальне типове значення. -- Коли не задано ні глобальне, ні рівень завдання failure destination, завдання, які вже доставляють через `announce`, у разі збою використовують як fallback цю основну announce-ціль. +- `delivery.failureDestination` для окремого завдання перевизначає це глобальне значення за замовчуванням. +- Якщо не задано ні глобальне, ні для окремого завдання місце призначення збоїв, завдання, які вже доставляють через `announce`, у разі збою використовують цей основний цільовий announce як резервний варіант. - `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`. -Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [background tasks](/uk/automation/tasks). +Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [фонові завдання](/uk/automation/tasks). --- -## Змінні шаблону моделі медіа +## Змінні шаблонів моделі медіа -Заповнювачі шаблону, що розгортаються в `tools.media.models[].args`: +Заповнювачі шаблонів, які розгортаються в `tools.media.models[].args`: -| Змінна | Опис | -| ----------------- | ------------------------------------------------- | -| `{{Body}}` | Повний текст вхідного повідомлення | -| `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) | -| `{{BodyStripped}}`| Текст без групових згадок | -| `{{From}}` | Ідентифікатор відправника | -| `{{To}}` | Ідентифікатор призначення | -| `{{MessageSid}}` | id повідомлення каналу | -| `{{SessionId}}` | UUID поточної сесії | -| `{{IsNewSession}}`| `"true"`, коли створено нову сесію | -| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | -| `{{MediaPath}}` | Локальний шлях до медіа | -| `{{MediaType}}` | Тип медіа (image/audio/document/…) | -| `{{Transcript}}` | Транскрипт аудіо | -| `{{Prompt}}` | Розв’язаний prompt медіа для записів CLI | -| `{{MaxChars}}` | Розв’язана максимальна кількість символів виводу для записів CLI | -| `{{ChatType}}` | `"direct"` або `"group"` | -| `{{GroupSubject}}`| Тема групи (best effort) | -| `{{GroupMembers}}`| Попередній список учасників групи (best effort) | -| `{{SenderName}}` | Відображуване ім’я відправника (best effort) | -| `{{SenderE164}}` | Номер телефону відправника (best effort) | -| `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | +| Змінна | Опис | +| ------------------ | ------------------------------------------------- | +| `{{Body}}` | Повний текст вхідного повідомлення | +| `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) | +| `{{BodyStripped}}` | Текст без згадок у групі | +| `{{From}}` | Ідентифікатор відправника | +| `{{To}}` | Ідентифікатор призначення | +| `{{MessageSid}}` | ID повідомлення каналу | +| `{{SessionId}}` | UUID поточної сесії | +| `{{IsNewSession}}` | `"true"`, якщо створено нову сесію | +| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | +| `{{MediaPath}}` | Локальний шлях до медіа | +| `{{MediaType}}` | Тип медіа (image/audio/document/…) | +| `{{Transcript}}` | Аудіотранскрипт | +| `{{Prompt}}` | Розв’язаний медіа-prompt для записів CLI | +| `{{MaxChars}}` | Розв’язана максимальна кількість символів виводу для записів CLI | +| `{{ChatType}}` | `"direct"` або `"group"` | +| `{{GroupSubject}}` | Назва групи (за можливості) | +| `{{GroupMembers}}` | Попередній перегляд учасників групи (за можливості) | +| `{{SenderName}}` | Відображуване ім’я відправника (за можливості) | +| `{{SenderE164}}` | Номер телефону відправника (за можливості) | +| `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | --- ## Включення конфігурації (`$include`) -Розбийте конфігурацію на кілька файлів: +Розділіть конфігурацію на кілька файлів: ```json5 // ~/.openclaw/openclaw.json @@ -1151,19 +1184,19 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. **Поведінка злиття:** - Один файл: замінює об’єкт-контейнер. -- Масив файлів: deep-merge у заданому порядку (пізніші перевизначають попередні). -- Сусідні ключі: зливаються після includes (перевизначають включені значення). -- Вкладені includes: до 10 рівнів углиб. -- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли після розв’язання вони все одно лишаються в межах цієї границі. -- Записи, керовані OpenClaw, які змінюють лише один розділ верхнього рівня, підкріплений include одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін. -- Root includes, масиви include і includes із сусідніми перевизначеннями є read-only для записів, керованих OpenClaw; такі записи завершуються fail-closed замість сплощення конфігурації. -- Помилки: чіткі повідомлення для відсутніх файлів, помилок парсингу та циклічних includes. +- Масив файлів: глибоко зливається за порядком (пізніші перевизначають попередні). +- Сусідні ключі: зливаються після включень (перевизначають включені значення). +- Вкладені включення: до 10 рівнів глибини. +- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/форми з `../` дозволені лише тоді, коли вони все одно розв’язуються в межах цієї межі. +- Записи OpenClaw, які змінюють лише один розділ верхнього рівня, підкріплений включенням одного файла, записуються безпосередньо до цього включеного файла. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін. +- Кореневі включення, масиви включень і включення із сусідніми перевизначеннями доступні лише для читання для записів, що виконуються OpenClaw; такі записи завершуються за принципом fail closed замість сплощення конфігурації. +- Помилки: чіткі повідомлення для відсутніх файлів, помилок розбору та циклічних включень. --- -_Пов’язане: [Configuration](/uk/gateway/configuration) · [Configuration Examples](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ +_Пов’язано: [Конфігурація](/uk/gateway/configuration) · [Приклади конфігурації](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ ## Пов’язане -- [Configuration](/uk/gateway/configuration) -- [Configuration examples](/uk/gateway/configuration-examples) +- [Конфігурація](/uk/gateway/configuration) +- [Приклади конфігурації](/uk/gateway/configuration-examples) diff --git a/docs/uk/logging.md b/docs/uk/logging.md index 274042637..02d61c9ec 100644 --- a/docs/uk/logging.md +++ b/docs/uk/logging.md @@ -3,13 +3,13 @@ read_when: - Вам потрібен дружній до початківців огляд журналювання - Ви хочете налаштувати рівні журналювання або формати - Ви усуваєте несправності й хочете швидко знайти журнали -summary: 'Огляд журналювання: журнали у файлах, вивід у консолі, відстеження в CLI та інтерфейс керування' +summary: 'Огляд журналювання: журнали файлів, вивід у консоль, відстеження в CLI та інтерфейс керування' title: Огляд журналювання x-i18n: - generated_at: "2026-04-24T23:44:42Z" + generated_at: "2026-04-25T07:01:56Z" model: gpt-5.4 provider: openai - source_hash: 8e179c883d98caa7fd8d3ece8962d0b628562d35568ebf452c34bededba22e2c + source_hash: 7f9593b117ef2ba76dbe91d5b38e3f463b358631961c9d44beed3aee6152f9a2 source_path: logging.md workflow: 15 --- @@ -18,20 +18,20 @@ x-i18n: OpenClaw має дві основні поверхні журналювання: -- **Журнали у файлах** (рядки JSON), які записує Gateway. -- **Вивід у консолі**, що показується в терміналах і в інтерфейсі налагодження Gateway. +- **Журнали файлів** (рядки JSON), які записує Gateway. +- **Вивід у консоль**, що показується в терміналах і в інтерфейсі Gateway Debug UI. -Вкладка **Logs** в інтерфейсі керування відстежує журнал файлу gateway. На цій сторінці пояснюється, де зберігаються журнали, як їх читати та як налаштовувати рівні й формати журналювання. +Вкладка **Logs** в інтерфейсі керування відстежує файл журналу gateway. На цій сторінці пояснюється, де зберігаються журнали, як їх читати та як налаштовувати рівні й формати журналювання. ## Де зберігаються журнали -За замовчуванням Gateway записує ротаційний файл журналу за шляхом: +За замовчуванням Gateway записує ротаційний файл журналу в: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` Дата використовує локальний часовий пояс хоста gateway. -Ви можете змінити це в `~/.openclaw/openclaw.json`: +Ви можете перевизначити це в `~/.openclaw/openclaw.json`: ```json { @@ -55,26 +55,26 @@ openclaw logs --follow - `--local-time`: відображати часові мітки у вашому локальному часовому поясі - `--url ` / `--token ` / `--timeout `: стандартні прапорці Gateway RPC -- `--expect-final`: прапорець очікування фінальної відповіді для RPC на основі агентів (тут приймається через спільний клієнтський шар) +- `--expect-final`: прапорець очікування фінальної відповіді для RPC на основі агентів (приймається тут через спільний клієнтський шар) Режими виводу: -- **Сеанси TTY**: гарні, кольорові, структуровані рядки журналу. -- **Сеанси без TTY**: звичайний текст. -- `--json`: JSON з розділенням по рядках (одна подія журналу на рядок). -- `--plain`: примусово використовувати звичайний текст у сеансах TTY. -- `--no-color`: вимкнути кольори ANSI. +- **TTY-сеанси**: гарні, кольорові, структуровані рядки журналу. +- **Не-TTY-сеанси**: звичайний текст. +- `--json`: JSON із розділенням по рядках (одна подія журналу на рядок). +- `--plain`: примусово використовувати звичайний текст у TTY-сеансах. +- `--no-color`: вимкнути ANSI-кольори. -Коли ви передаєте явний `--url`, CLI не застосовує автоматично облікові дані з конфігурації або середовища; вкажіть `--token` самостійно, якщо цільовий Gateway вимагає автентифікації. +Коли ви передаєте явний `--url`, CLI не застосовує автоматично облікові дані з конфігурації або середовища; самостійно додайте `--token`, якщо цільовий Gateway вимагає автентифікацію. У режимі JSON CLI виводить об’єкти з тегом `type`: - `meta`: метадані потоку (файл, курсор, розмір) - `log`: розібраний запис журналу -- `notice`: підказки щодо обрізання / ротації +- `notice`: підказки про обрізання / ротацію - `raw`: нерозібраний рядок журналу -Якщо Gateway на local loopback просить виконати pairing, `openclaw logs` автоматично переходить до налаштованого локального файла журналу. Явні цілі `--url` не використовують цей резервний варіант. +Якщо локальний loopback Gateway запитує pair-налаштування, `openclaw logs` автоматично перемикається на налаштований локальний файл журналу. Явні цілі `--url` не використовують цей резервний режим. Якщо Gateway недоступний, CLI виводить коротку підказку виконати: @@ -97,27 +97,27 @@ openclaw channels logs --channel whatsapp ## Формати журналів -### Журнали у файлах (JSONL) +### Журнали файлів (JSONL) Кожен рядок у файлі журналу є об’єктом JSON. CLI та інтерфейс керування розбирають ці записи, щоб відображати структурований вивід (час, рівень, підсистема, повідомлення). -### Вивід у консолі +### Вивід у консоль Журнали консолі **враховують TTY** і форматуються для зручності читання: - Префікси підсистем (наприклад, `gateway/channels/whatsapp`) -- Кольори рівнів (info/warn/error) -- Необов’язковий компактний або JSON-режим +- Кольорове позначення рівнів (info/warn/error) +- Необов’язковий компактний режим або режим JSON Форматування консолі керується через `logging.consoleStyle`. -### Журнали Gateway WebSocket +### Журнали WebSocket Gateway `openclaw gateway` також має журналювання протоколу WebSocket для RPC-трафіку: -- звичайний режим: лише цікаві результати (помилки, помилки розбору, повільні виклики) +- звичайний режим: лише важливі результати (помилки, помилки розбору, повільні виклики) - `--verbose`: увесь трафік запитів/відповідей -- `--ws-log auto|compact|full`: вибір стилю детального відображення +- `--ws-log auto|compact|full`: вибір стилю розширеного відображення - `--compact`: псевдонім для `--ws-log compact` Приклади: @@ -130,7 +130,7 @@ openclaw gateway --verbose --ws-log full ## Налаштування журналювання -Усі параметри журналювання містяться в `logging` у `~/.openclaw/openclaw.json`. +Уся конфігурація журналювання знаходиться в розділі `logging` у `~/.openclaw/openclaw.json`. ```json { @@ -147,18 +147,18 @@ openclaw gateway --verbose --ws-log full ### Рівні журналювання -- `logging.level`: рівень **журналів у файлах** (JSONL). +- `logging.level`: рівень **журналів файлів** (JSONL). - `logging.consoleLevel`: рівень деталізації **консолі**. -Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має вищий пріоритет за файл конфігурації, тому ви можете підвищити деталізацію для одного запуску без редагування `openclaw.json`. Ви також можете передати глобальний параметр CLI **`--log-level `** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди. +Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має вищий пріоритет, ніж файл конфігурації, тому ви можете підвищити деталізацію для одного запуску без редагування `openclaw.json`. Ви також можете передати глобальний параметр CLI **`--log-level `** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди. -`--verbose` впливає лише на вивід у консоль і деталізацію журналів WS; він не змінює рівні журналів у файлах. +`--verbose` впливає лише на вивід у консоль і деталізацію журналів WS; він не змінює рівні журналів файлів. ### Стилі консолі `logging.consoleStyle`: -- `pretty`: зручний для людини, кольоровий, із часовими мітками. +- `pretty`: зручний для людей, кольоровий, із часовими мітками. - `compact`: щільніший вивід (найкраще для довгих сеансів). - `json`: JSON у кожному рядку (для обробників журналів). @@ -169,56 +169,56 @@ openclaw gateway --verbose --ws-log full - `logging.redactSensitive`: `off` | `tools` (типово: `tools`) - `logging.redactPatterns`: список рядків regex для перевизначення типового набору -Редагування впливає **лише на вивід у консоль** і не змінює журнали у файлах. +Редагування впливає **лише на вивід у консоль** і не змінює журнали файлів. ## Діагностика + OpenTelemetry -Діагностика — це структуровані, машинозчитувані події для запусків моделей **і** -телеметрії потоку повідомлень (webhooks, постановка в чергу, стан сеансу). Вони **не** -замінюють журнали; вони існують для передавання метрик, трасувань та інших експортерів. +Діагностика — це структуровані, машиночитні події для запусків моделей **і** +телеметрії потоку повідомлень (webhook, постановка в чергу, стан сеансу). Вони **не** +замінюють журнали; вони існують для подачі метрик, трасувань та інших експортерів. -Події діагностики генеруються в процесі, але експортери підключаються лише тоді, коли +Події діагностики створюються в процесі, але експортери підключаються лише тоді, коли увімкнено діагностику + Plugin експортера. -### OpenTelemetry проти OTLP +### OpenTelemetry і OTLP - **OpenTelemetry (OTel)**: модель даних + SDK для трасувань, метрик і журналів. -- **OTLP**: мережевий протокол, який використовується для експорту даних OTel до колектора/бекенда. +- **OTLP**: дротовий протокол, який використовується для експорту даних OTel до збирача/бекенда. - Сьогодні OpenClaw експортує через **OTLP/HTTP (protobuf)**. ### Експортовані сигнали -- **Метрики**: лічильники + гістограми (використання токенів, потік повідомлень, постановка в чергу). -- **Трасування**: span-и для використання моделей + обробки webhook/повідомлень. -- **Журнали**: експортуються через OTLP, коли ввімкнено `diagnostics.otel.logs`. Обсяг журналів - може бути високим; враховуйте `logging.level` і фільтри експортера. +- **Metrics**: лічильники + гістограми (використання токенів, потік повідомлень, черги). +- **Traces**: span-и для використання моделей + обробки webhook/повідомлень. +- **Logs**: експортуються через OTLP, коли ввімкнено `diagnostics.otel.logs`. Обсяг журналів + може бути великим; пам’ятайте про `logging.level` і фільтри експортера. ### Каталог подій діагностики -Використання моделей: +Використання моделі: -- `model.usage`: токени, вартість, тривалість, контекст, провайдер/модель/канал, ідентифікатори сеансів. +- `model.usage`: токени, вартість, тривалість, контекст, provider/model/channel, ідентифікатори сеансів. Потік повідомлень: -- `webhook.received`: вхід webhook для кожного каналу. -- `webhook.processed`: webhook оброблено + тривалість. +- `webhook.received`: вхідний webhook для кожного каналу. +- `webhook.processed`: оброблений webhook + тривалість. - `webhook.error`: помилки обробника webhook. - `message.queued`: повідомлення поставлено в чергу на обробку. - `message.processed`: результат + тривалість + необов’язкова помилка. Черга + сеанс: -- `queue.lane.enqueue`: постановка в lane черги команд + глибина. -- `queue.lane.dequeue`: зняття з lane черги команд + час очікування. +- `queue.lane.enqueue`: додавання в lane черги команд + глибина. +- `queue.lane.dequeue`: виймання з lane черги команд + час очікування. - `session.state`: перехід стану сеансу + причина. - `session.stuck`: попередження про завислий сеанс + вік. -- `run.attempt`: метадані повторної спроби/спроби запуску. -- `diagnostic.heartbeat`: агреговані лічильники (webhooks/черга/сеанс). +- `run.attempt`: метадані повтору/спроби запуску. +- `diagnostic.heartbeat`: агреговані лічильники (webhook/черга/сеанс). ### Увімкнення діагностики (без експортера) -Використовуйте це, якщо хочете, щоб події діагностики були доступні для плагінів або власних приймачів: +Використовуйте це, якщо хочете, щоб події діагностики були доступні для Plugin-ів або користувацьких приймачів: ```json { @@ -231,7 +231,7 @@ openclaw gateway --verbose --ws-log full ### Прапорці діагностики (цільові журнали) Використовуйте прапорці, щоб увімкнути додаткові, цільові журнали налагодження без підвищення `logging.level`. -Прапорці нечутливі до регістру та підтримують шаблони з wildcard (наприклад, `telegram.*` або `*`). +Прапорці нечутливі до регістру та підтримують шаблони (наприклад, `telegram.*` або `*`). ```json { @@ -241,7 +241,7 @@ openclaw gateway --verbose --ws-log full } ``` -Перевизначення через змінну середовища (для разового запуску): +Перевизначення через змінну середовища (разово): ``` OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload @@ -249,14 +249,14 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload Примітки: -- Журнали за прапорцями записуються у стандартний файл журналу (той самий, що й `logging.file`). +- Журнали за прапорцями записуються до стандартного файлу журналу (того самого, що й `logging.file`). - Вивід усе одно редагується відповідно до `logging.redactSensitive`. - Повний посібник: [/diagnostics/flags](/uk/diagnostics/flags). ### Експорт до OpenTelemetry Діагностику можна експортувати через Plugin `diagnostics-otel` (OTLP/HTTP). Це -працює з будь-яким колектором/бекендом OpenTelemetry, який приймає OTLP/HTTP. +працює з будь-яким збирачем/бекендом OpenTelemetry, який приймає OTLP/HTTP. ```json { @@ -295,58 +295,62 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload Примітки: -- Ви також можете ввімкнути Plugin за допомогою `openclaw plugins enable diagnostics-otel`. +- Ви також можете ввімкнути Plugin командою `openclaw plugins enable diagnostics-otel`. - `protocol` наразі підтримує лише `http/protobuf`. `grpc` ігнорується. -- Метрики включають використання токенів, вартість, розмір контексту, тривалість запуску та - лічильники/гістограми потоку повідомлень (webhooks, постановка в чергу, стан сеансу, глибина/очікування черги). -- Трасування/метрики можна перемикати через `traces` / `metrics` (типово: увімкнено). Трасування - включають span-и використання моделей, а також span-и обробки webhook/повідомлень, коли це ввімкнено. -- Вміст сирих моделей/інструментів типово не експортується. Використовуйте - `diagnostics.otel.captureContent` лише тоді, коли ваш колектор і політика зберігання - схвалені для тексту підказок, відповідей, інструментів або системних підказок. -- Установіть `headers`, якщо ваш колектор вимагає автентифікації. +- Metrics включають використання токенів, вартість, розмір контексту, тривалість запуску та + лічильники/гістограми потоку повідомлень (webhook, черги, стан сеансу, глибина/очікування черги). +- Traces/metrics можна вмикати або вимикати через `traces` / `metrics` (типово: увімкнено). Traces + включають span-и використання моделей, а також span-и обробки webhook/повідомлень, якщо це ввімкнено. +- Сирий вміст моделі/інструментів типово не експортується. Використовуйте + `diagnostics.otel.captureContent` лише тоді, коли ваш збирач і політика зберігання + схвалені для тексту prompt, відповіді, інструментів або системного prompt. +- Установіть `headers`, якщо ваш збирач вимагає автентифікацію. - Підтримувані змінні середовища: `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_PROTOCOL`. +- Установіть `OPENCLAW_OTEL_PRELOADED=1`, якщо інший preload або хост-процес уже + зареєстрував глобальний OpenTelemetry SDK. У цьому режимі Plugin не запускає + і не завершує власний SDK, але все одно підключає слухачі діагностики OpenClaw і + враховує `diagnostics.otel.traces`, `metrics` і `logs`. -### Експортовані метрики (назви + типи) +### Експортовані metrics (назви + типи) -Використання моделей: +Використання моделі: -- `openclaw.tokens` (лічильник, атрибути: `openclaw.token`, `openclaw.channel`, +- `openclaw.tokens` (counter, атрибути: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `openclaw.cost.usd` (лічильник, атрибути: `openclaw.channel`, `openclaw.provider`, +- `openclaw.cost.usd` (counter, атрибути: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `openclaw.run.duration_ms` (гістограма, атрибути: `openclaw.channel`, +- `openclaw.run.duration_ms` (histogram, атрибути: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `openclaw.context.tokens` (гістограма, атрибути: `openclaw.context`, +- `openclaw.context.tokens` (histogram, атрибути: `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) Потік повідомлень: -- `openclaw.webhook.received` (лічильник, атрибути: `openclaw.channel`, +- `openclaw.webhook.received` (counter, атрибути: `openclaw.channel`, `openclaw.webhook`) -- `openclaw.webhook.error` (лічильник, атрибути: `openclaw.channel`, +- `openclaw.webhook.error` (counter, атрибути: `openclaw.channel`, `openclaw.webhook`) -- `openclaw.webhook.duration_ms` (гістограма, атрибути: `openclaw.channel`, +- `openclaw.webhook.duration_ms` (histogram, атрибути: `openclaw.channel`, `openclaw.webhook`) -- `openclaw.message.queued` (лічильник, атрибути: `openclaw.channel`, +- `openclaw.message.queued` (counter, атрибути: `openclaw.channel`, `openclaw.source`) -- `openclaw.message.processed` (лічильник, атрибути: `openclaw.channel`, +- `openclaw.message.processed` (counter, атрибути: `openclaw.channel`, `openclaw.outcome`) -- `openclaw.message.duration_ms` (гістограма, атрибути: `openclaw.channel`, +- `openclaw.message.duration_ms` (histogram, атрибути: `openclaw.channel`, `openclaw.outcome`) Черги + сеанси: -- `openclaw.queue.lane.enqueue` (лічильник, атрибути: `openclaw.lane`) -- `openclaw.queue.lane.dequeue` (лічильник, атрибути: `openclaw.lane`) -- `openclaw.queue.depth` (гістограма, атрибути: `openclaw.lane` або +- `openclaw.queue.lane.enqueue` (counter, атрибути: `openclaw.lane`) +- `openclaw.queue.lane.dequeue` (counter, атрибути: `openclaw.lane`) +- `openclaw.queue.depth` (histogram, атрибути: `openclaw.lane` або `openclaw.channel=heartbeat`) -- `openclaw.queue.wait_ms` (гістограма, атрибути: `openclaw.lane`) -- `openclaw.session.state` (лічильник, атрибути: `openclaw.state`, `openclaw.reason`) -- `openclaw.session.stuck` (лічильник, атрибути: `openclaw.state`) -- `openclaw.session.stuck_age_ms` (гістограма, атрибути: `openclaw.state`) -- `openclaw.run.attempt` (лічильник, атрибути: `openclaw.attempt`) +- `openclaw.queue.wait_ms` (histogram, атрибути: `openclaw.lane`) +- `openclaw.session.state` (counter, атрибути: `openclaw.state`, `openclaw.reason`) +- `openclaw.session.stuck` (counter, атрибути: `openclaw.state`) +- `openclaw.session.stuck_age_ms` (histogram, атрибути: `openclaw.state`) +- `openclaw.run.attempt` (counter, атрибути: `openclaw.attempt`) ### Експортовані span-и (назви + ключові атрибути) @@ -374,14 +378,14 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload - `openclaw.session.stuck` - `openclaw.state`, `openclaw.ageMs`, `openclaw.queueDepth` -Коли захоплення вмісту явно ввімкнено, span-и моделі/інструментів також можуть містити +Коли захоплення вмісту явно ввімкнено, span-и моделей/інструментів також можуть містити обмежені, відредаговані атрибути `openclaw.content.*` для конкретних класів вмісту, -які ви дозволили. +які ви явно дозволили. -### Вибірка + скидання +### Вибірка + скидання буфера -- Вибірка трасувань: `diagnostics.otel.sampleRate` (0.0–1.0, лише кореневі span-и). -- Інтервал експорту метрик: `diagnostics.otel.flushIntervalMs` (мінімум 1000 мс). +- Вибірка traces: `diagnostics.otel.sampleRate` (0.0–1.0, лише кореневі span-и). +- Інтервал експорту metrics: `diagnostics.otel.flushIntervalMs` (мінімум 1000ms). ### Примітки щодо протоколу @@ -389,23 +393,25 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload `OTEL_EXPORTER_OTLP_ENDPOINT`. - Якщо кінцева точка вже містить `/v1/traces` або `/v1/metrics`, вона використовується як є. - Якщо кінцева точка вже містить `/v1/logs`, вона використовується як є для журналів. -- `diagnostics.otel.logs` вмикає експорт журналів OTLP для основного виводу журналювача. +- `OPENCLAW_OTEL_PRELOADED=1` повторно використовує зовнішньо зареєстрований OpenTelemetry SDK + для traces/metrics замість запуску NodeSDK, яким володіє Plugin. +- `diagnostics.otel.logs` вмикає експорт журналів OTLP для основного виводу logger. ### Поведінка експорту журналів - Журнали OTLP використовують ті самі структуровані записи, що записуються до `logging.file`. -- Враховується `logging.level` (рівень журналів у файлах). Редагування консолі **не** застосовується +- Дотримуються `logging.level` (рівень журналів файлів). Редагування консолі **не** застосовується до журналів OTLP. -- Для інсталяцій із великим обсягом даних варто віддавати перевагу вибірці/фільтрації в колекторі OTLP. +- Для інсталяцій із великим обсягом даних краще використовувати вибірку/фільтрацію на рівні OTLP collector. ## Поради з усунення несправностей - **Gateway недоступний?** Спочатку виконайте `openclaw doctor`. -- **Журнали порожні?** Перевірте, що Gateway запущений і записує у шлях файлу, +- **Журнали порожні?** Перевірте, що Gateway запущено і він записує у шлях файлу, вказаний у `logging.file`. -- **Потрібно більше деталей?** Установіть `logging.level` на `debug` або `trace` і повторіть спробу. +- **Потрібно більше деталей?** Установіть `logging.level` у `debug` або `trace` і повторіть спробу. ## Пов’язане -- [Внутрішня будова журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі +- [Внутрішня реалізація журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі - [Діагностика](/uk/gateway/configuration-reference#diagnostics) — експорт OpenTelemetry і конфігурація трасування кешу diff --git a/docs/uk/plugins/google-meet.md b/docs/uk/plugins/google-meet.md index 7916ec277..40b00e119 100644 --- a/docs/uk/plugins/google-meet.md +++ b/docs/uk/plugins/google-meet.md @@ -1,36 +1,43 @@ --- read_when: - - Ви хочете, щоб агент OpenClaw приєднався до виклику Google Meet - - Ви хочете, щоб агент OpenClaw створив новий виклик Google Meet - - Ви налаштовуєте Chrome, Node Chrome або Twilio як транспорт Google Meet -summary: 'Plugin Google Meet: приєднання до явних URL-адрес Meet через Chrome або Twilio з типовими налаштуваннями голосу в реальному часі' -title: Plugin Google Meet + - Ви хочете, щоб агент OpenClaw приєднався до дзвінка Google Meet + - Ви хочете, щоб агент OpenClaw створив новий дзвінок Google Meet + - Ви налаштовуєте Chrome, Node Chrome або Twilio як транспорт для Google Meet +summary: 'Плагін Google Meet: приєднання до явних URL-адрес Meet через Chrome або Twilio з типовими налаштуваннями голосу в реальному часі' +title: Плагін Google Meet x-i18n: - generated_at: "2026-04-25T06:39:36Z" + generated_at: "2026-04-25T07:02:31Z" model: gpt-5.4 provider: openai - source_hash: b4ba4dd272e9951f19f2f2cc17be8e2c30b698137d77b4c589cbe33c34bc6d95 + source_hash: 0c632ec97b38c6b21ed1ea9d748f8ade94a6ad0921bd13c0d22134ae679ed9cc source_path: plugins/google-meet.md workflow: 15 --- -Підтримка учасника Google Meet для OpenClaw — Plugin є навмисно явним за дизайном: +Підтримка учасника Google Meet для OpenClaw — Plugin за задумом є явним: - Він приєднується лише до явного URL `https://meet.google.com/...`. -- Він може створити новий простір Meet через API Google Meet, а потім приєднатися за поверненим URL. -- Голос `realtime` є типовим режимом. -- Голос у реальному часі може повертатися до повного агента OpenClaw, коли потрібні глибше міркування або інструменти. -- Агенти обирають поведінку приєднання через `mode`: використовуйте `realtime` для живого прослуховування/зворотної розмови, або `transcribe`, щоб приєднатися/керувати браузером без мосту голосу в реальному часі. -- Автентифікація починається як особистий Google OAuth або вже виконаний вхід у профіль Chrome. -- Автоматичного оголошення про згоду немає. +- Він може створити новий простір Meet через API Google Meet, а потім приєднатися за + поверненим URL. +- `realtime` voice є режимом за замовчуванням. +- Голос у реальному часі може повертатися до повного агента OpenClaw, коли потрібні + глибше міркування або інструменти. +- Агенти обирають поведінку приєднання через `mode`: використовуйте `realtime` для живого + прослуховування/зворотної розмови або `transcribe`, щоб приєднатися/керувати браузером без + мосту голосу в реальному часі. +- Автентифікація починається як персональний Google OAuth або вже виконаний вхід у профіль Chrome. +- Автоматичного оголошення згоди немає. - Типовим аудіобекендом Chrome є `BlackHole 2ch`. -- Chrome може працювати локально або на підключеному вузлі host. -- Twilio приймає номер для дозвону та необов’язковий PIN або послідовність DTMF. -- Команда CLI — `googlemeet`; `meet` зарезервовано для ширших робочих процесів телеконференцій агента. +- Chrome може працювати локально або на прив’язаному вузлі. +- Twilio приймає номер для дозвону, а також необов’язкову послідовність PIN або DTMF. +- Команда CLI — `googlemeet`; `meet` зарезервовано для ширших + робочих процесів телеконференцій агентів. ## Швидкий старт -Встановіть локальні аудіозалежності та налаштуйте backend-провайдера голосу в реальному часі. OpenAI є типовим; Google Gemini Live також працює з `realtime.provider: "google"`: +Установіть локальні аудіозалежності та налаштуйте провайдера голосу в реальному часі для бекенда. +OpenAI є типовим варіантом; Google Gemini Live також працює з +`realtime.provider: "google"`: ```bash brew install blackhole-2ch sox @@ -39,13 +46,14 @@ export OPENAI_API_KEY=sk-... export GEMINI_API_KEY=... ``` -`blackhole-2ch` встановлює віртуальний аудіопристрій `BlackHole 2ch`. Інсталятор Homebrew вимагає перезавантаження, перш ніж macOS зробить пристрій доступним: +`blackhole-2ch` установлює віртуальний аудіопристрій `BlackHole 2ch`. Інсталятор +Homebrew вимагає перезавантаження, перш ніж macOS покаже цей пристрій: ```bash sudo reboot ``` -Після перезавантаження перевірте обидві складові: +Після перезавантаження перевірте обидва компоненти: ```bash system_profiler SPAudioDataType | grep -i BlackHole @@ -73,8 +81,10 @@ command -v rec play openclaw googlemeet setup ``` -Вивід налаштування призначений для читання агентом. Він повідомляє про профіль Chrome, аудіоміст, закріплення Node, відкладений вступ у `realtime`, а також, коли налаштовано делегування Twilio, чи готові Plugin `voice-call` і облікові дані Twilio. -Вважайте будь-яку перевірку `ok: false` блокером перед тим, як просити агента приєднатися. +Вивід налаштування призначено для читання агентом. Він повідомляє про профіль Chrome, +аудіоміст, прив’язку вузла, відкладений вступ у реальному часі та, коли налаштовано делегування Twilio, +чи готові Plugin `voice-call` і облікові дані Twilio. +Розглядайте будь-яку перевірку `ok: false` як блокер, перш ніж просити агента приєднатися. Використовуйте `openclaw googlemeet setup --json` для скриптів або машинозчитуваного виводу. Приєднайтеся до зустрічі: @@ -108,14 +118,27 @@ openclaw googlemeet create --no-join `googlemeet create` має два шляхи: -- Створення через API: використовується, коли налаштовано облікові дані Google Meet OAuth. Це найбільш детермінований шлях, який не залежить від стану UI браузера. -- Резервний шлях через браузер: використовується, коли облікові дані OAuth відсутні. OpenClaw використовує закріплений Node Chrome, відкриває `https://meet.google.com/new`, чекає, поки Google перенаправить на справжній URL з кодом зустрічі, а потім повертає цей URL. Цей шлях вимагає, щоб профіль OpenClaw Chrome на вузлі вже мав виконаний вхід у Google. - Автоматизація браузера обробляє власний початковий запит Meet на мікрофон; цей запит не вважається помилкою входу в Google. - Потоки приєднання та створення також намагаються повторно використати наявну вкладку Meet перед відкриттям нової. Під час зіставлення ігноруються нешкідливі рядки запиту URL, такі як `authuser`, тому повторна спроба агента має сфокусувати вже відкриту зустріч замість створення другої вкладки Chrome. +- Створення через API: використовується, коли налаштовано облікові дані Google Meet OAuth. Це + найдетермінованіший шлях, який не залежить від стану UI браузера. +- Резервний варіант через браузер: використовується, коли облікові дані OAuth відсутні. OpenClaw використовує + закріплений вузол Chrome, відкриває `https://meet.google.com/new`, чекає, поки Google + перенаправить на реальний URL із кодом зустрічі, а потім повертає цей URL. Цей шлях вимагає, + щоб профіль Chrome OpenClaw на вузлі вже мав виконаний вхід у Google. + Автоматизація браузера обробляє власний початковий запит Meet на доступ до мікрофона; цей запит + не вважається збоєм входу Google. + Потоки приєднання та створення також намагаються повторно використовувати наявну вкладку Meet перед відкриттям + нової. Зіставлення ігнорує нешкідливі рядки запиту URL, такі як `authuser`, тому + повторна спроба агента має сфокусувати вже відкриту зустріч, а не створювати другу + вкладку Chrome. -Вивід команди/інструмента містить поле `source` (`api` або `browser`), щоб агенти могли пояснити, який шлях було використано. `create` типово приєднується до нової зустрічі та повертає `joined: true` разом із сеансом приєднання. Щоб лише згенерувати URL, використовуйте `create --no-join` у CLI або передайте `"join": false` в інструмент. +Вивід команди/інструмента містить поле `source` (`api` або `browser`), щоб агенти +могли пояснити, який шлях було використано. `create` типово приєднується до нової зустрічі та +повертає `joined: true` разом із сеансом приєднання. Щоб лише згенерувати URL, використовуйте +`create --no-join` у CLI або передайте `"join": false` до інструмента. -Або скажіть агенту: "Створи Google Meet, приєднайся до нього з голосом у реальному часі та надішли мені посилання." Агент має викликати `google_meet` з `action: "create"`, а потім поділитися поверненим `meetingUri`. +Або скажіть агенту: «Створи Google Meet, приєднайся до нього з голосом у реальному часі та надішли +мені посилання». Агент має викликати `google_meet` з `action: "create"` і +потім поділитися поверненим `meetingUri`. ```json { @@ -125,29 +148,46 @@ openclaw googlemeet create --no-join } ``` -Для приєднання лише для спостереження/керування браузером задайте `"mode": "transcribe"`. Це не запускає дуплексний міст моделі в реальному часі, тож він не відповідатиме голосом у зустрічі. +Для приєднання лише для спостереження/керування браузером установіть `"mode": "transcribe"`. Це +не запускає двобічний міст моделі в реальному часі, тож він не відповідатиме голосом у +зустрічі. -Під час сеансів `realtime` статус `google_meet` містить дані про стан браузера та аудіомосту, такі як `inCall`, `manualActionRequired`, `providerConnected`, `realtimeReady`, `audioInputActive`, `audioOutputActive`, часові мітки останнього входу/виходу, лічильники байтів і стан закриття мосту. Якщо з’являється безпечний запит сторінки Meet, автоматизація браузера обробляє його, коли це можливо. Запити на вхід, допуск host, а також дозволи браузера/ОС повідомляються як ручна дія з причиною та повідомленням, яке агент має передати. +Під час сеансів у реальному часі статус `google_meet` містить стан браузера та аудіомосту, +наприклад `inCall`, `manualActionRequired`, `providerConnected`, +`realtimeReady`, `audioInputActive`, `audioOutputActive`, часові мітки останнього входу/виходу, +лічильники байтів і стан закриття мосту. Якщо з’являється безпечний запит сторінки Meet, +автоматизація браузера обробляє його, коли це можливо. Вхід, допуск хостом, а також запити +дозволів браузера/ОС повідомляються як ручна дія з причиною та повідомленням, +яке агент має передати. -Chrome приєднується як профіль Chrome з виконаним входом. У Meet виберіть `BlackHole 2ch` для шляху мікрофона/динаміка, який використовує OpenClaw. Для чистого дуплексного аудіо використовуйте окремі віртуальні пристрої або граф на кшталт Loopback; одного пристрою BlackHole достатньо для першого smoke-тесту, але може з’являтися відлуння. +Chrome приєднується як профіль Chrome з уже виконаним входом. У Meet виберіть `BlackHole 2ch` для +шляху мікрофона/динаміка, який використовує OpenClaw. Для чистого двобічного аудіо використовуйте +окремі віртуальні пристрої або граф у стилі Loopback; одного пристрою BlackHole достатньо +для першого smoke-тесту, але може бути луна. ### Локальний Gateway + Parallels Chrome -Вам **не** потрібен повний OpenClaw Gateway або ключ API моделі всередині macOS VM лише для того, щоб VM володіла Chrome. Запустіть Gateway та агента локально, а потім запустіть вузол host у VM. Увімкніть вбудований Plugin на VM один раз, щоб вузол рекламував команду Chrome: +Вам **не** потрібен повний Gateway OpenClaw або ключ API моделі всередині macOS VM +лише для того, щоб Chrome працював у VM. Запустіть Gateway і агента локально, а потім запустіть +хост вузла у VM. Увімкніть у комплекті Plugin у VM один раз, щоб вузол +рекламував команду Chrome: -Що де запускається: +Що де працює: -- Host Gateway: OpenClaw Gateway, робочий простір агента, ключі моделі/API, провайдер `realtime` і конфігурація Plugin Google Meet. -- Parallels macOS VM: OpenClaw CLI/вузол host, Google Chrome, SoX, BlackHole 2ch і профіль Chrome з виконаним входом у Google. -- Не потрібно у VM: сервіс Gateway, конфігурація агента, ключ OpenAI/GPT або налаштування провайдера моделі. +- Хост Gateway: Gateway OpenClaw, робоча область агента, ключі моделей/API, провайдер + реального часу та конфігурація Plugin Google Meet. +- Parallels macOS VM: CLI/хост вузла OpenClaw, Google Chrome, SoX, BlackHole 2ch + і профіль Chrome з виконаним входом у Google. +- Не потрібно у VM: служба Gateway, конфігурація агента, ключ OpenAI/GPT або + налаштування провайдера моделі. -Встановіть залежності VM: +Установіть залежності у VM: ```bash brew install blackhole-2ch sox ``` -Перезавантажте VM після встановлення BlackHole, щоб macOS зробила `BlackHole 2ch` доступним: +Перезавантажте VM після встановлення BlackHole, щоб macOS показала `BlackHole 2ch`: ```bash sudo reboot @@ -160,27 +200,27 @@ system_profiler SPAudioDataType | grep -i BlackHole command -v rec play ``` -Встановіть або оновіть OpenClaw у VM, а потім увімкніть там вбудований Plugin: +Установіть або оновіть OpenClaw у VM, а потім увімкніть там Plugin з комплекту: ```bash openclaw plugins enable google-meet ``` -Запустіть вузол host у VM: +Запустіть хост вузла у VM: ```bash openclaw node run --host --port 18789 --display-name parallels-macos ``` -Якщо `` — це LAN IP і ви не використовуєте TLS, вузол відхилить -простий WebSocket, якщо ви явно не дозволите це для цієї довіреної приватної мережі: +Якщо `` є LAN IP і ви не використовуєте TLS, вузол відхиляє +WebSocket у відкритому тексті, якщо ви явно не дозволите це для цієї довіреної приватної мережі: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -Використовуйте ту саму змінну середовища, коли встановлюєте вузол як LaunchAgent: +Використовуйте ту саму змінну середовища під час встановлення вузла як LaunchAgent: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -188,11 +228,11 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node restart ``` -`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` — це змінна середовища процесу, а не параметр -`openclaw.json`. `openclaw node install` зберігає її в середовищі LaunchAgent, -коли вона присутня в команді встановлення. +`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` — це середовище процесу, а не +параметр `openclaw.json`. `openclaw node install` зберігає його в середовищі LaunchAgent, +коли воно присутнє в команді встановлення. -Схваліть вузол із host Gateway: +Схваліть вузол із хоста Gateway: ```bash openclaw devices list @@ -206,7 +246,7 @@ openclaw devices approve openclaw nodes status ``` -Спрямуйте Meet через цей вузол на host Gateway: +Спрямуйте Meet через цей вузол на хості Gateway: ```json5 { @@ -236,7 +276,7 @@ openclaw nodes status } ``` -Тепер приєднуйтеся як зазвичай із host Gateway: +Тепер приєднуйтесь звичайним способом із хоста Gateway: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij @@ -244,66 +284,76 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij або попросіть агента використати інструмент `google_meet` з `transport: "chrome-node"`. -Для однокомандного smoke-тесту, який створює або повторно використовує сеанс, промовляє відому фразу та виводить стан сеансу: +Для smoke-тесту однією командою, який створює або повторно використовує сеанс, вимовляє відому +фразу та виводить стан сеансу: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` -Під час приєднання автоматизація браузера OpenClaw заповнює ім’я гостя, натискає Join/Ask to join і приймає початковий вибір Meet "Use microphone", коли з’являється цей запит. Під час створення зустрічі лише через браузер вона також може продовжити після цього ж запиту без мікрофона, якщо Meet не показує кнопку використання мікрофона. -Якщо в профілі браузера не виконано вхід, Meet очікує допуску host, Chrome потребує дозволу на мікрофон/камеру або Meet застряг на запиті, який автоматизація не змогла обробити, результат join/test-speech повідомляє -`manualActionRequired: true` з `manualActionReason` і -`manualActionMessage`. Агенти мають припинити повторні спроби приєднання, повідомити саме це повідомлення разом із поточними `browserUrl`/`browserTitle` і повторити спробу лише після завершення ручної дії в браузері. +Під час приєднання автоматизація браузера OpenClaw заповнює ім’я гостя, натискає Join/Ask +to join і приймає початковий вибір Meet "Use microphone", коли з’являється цей запит. +Під час створення зустрічі лише через браузер вона також може продовжити після +того самого запиту без мікрофона, якщо Meet не показує кнопку використання мікрофона. +Якщо у профілі браузера не виконано вхід, Meet очікує на +допуск хостом, Chrome потребує дозволу на мікрофон/камеру або Meet застряг на +запиті, який автоматизація не змогла обробити, результат join/test-speech повідомляє +`manualActionRequired: true` разом із `manualActionReason` і +`manualActionMessage`. Агенти повинні припинити повторні спроби приєднання, +повідомити саме це повідомлення разом із поточними `browserUrl`/`browserTitle` +і повторити спробу лише після завершення ручної дії в браузері. -Якщо `chromeNode.node` пропущено, OpenClaw виконує автоматичний вибір лише тоді, коли рівно один +Якщо `chromeNode.node` пропущено, OpenClaw автоматично вибирає вузол лише тоді, коли рівно один підключений вузол рекламує і `googlemeet.chrome`, і керування браузером. Якщо -підключено кілька придатних вузлів, задайте `chromeNode.node` як id вузла, -display name або віддалену IP-адресу. +підключено кілька придатних вузлів, установіть `chromeNode.node` на id вузла, +відображуване ім’я або віддалену IP-адресу. Поширені перевірки збоїв: - `No connected Google Meet-capable node`: запустіть `openclaw node run` у VM, - схваліть спарювання та переконайтеся, що в VM було виконано `openclaw plugins enable google-meet` і + схваліть сполучення та переконайтеся, що у VM виконано `openclaw plugins enable google-meet` і `openclaw plugins enable browser`. Також підтвердьте, що - host Gateway дозволяє обидві команди вузла через + хост Gateway дозволяє обидві команди вузла через `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]`. -- `BlackHole 2ch audio device not found on the node`: встановіть `blackhole-2ch` +- `BlackHole 2ch audio device not found on the node`: установіть `blackhole-2ch` у VM і перезавантажте VM. -- Chrome відкривається, але не може приєднатися: виконайте вхід у профіль браузера всередині VM або - залиште `chrome.guestName` заданим для гостьового приєднання. Автоматичне гостьове приєднання використовує автоматизацію браузера OpenClaw через проксі браузера вузла; переконайтеся, що конфігурація браузера вузла +- Chrome відкривається, але не може приєднатися: увійдіть у профіль браузера всередині VM або + залиште `chrome.guestName` установленим для гостьового приєднання. Автоматичне приєднання гостя використовує + автоматизацію браузера OpenClaw через проксі браузера вузла; переконайтеся, що конфігурація браузера вузла вказує на потрібний профіль, наприклад `browser.defaultProfile: "user"` або іменований профіль наявного сеансу. -- Дубльовані вкладки Meet: залиште `chrome.reuseExistingTab: true` увімкненим. OpenClaw +- Дубльовані вкладки Meet: залишайте `chrome.reuseExistingTab: true` увімкненим. OpenClaw активує наявну вкладку для того самого URL Meet перед відкриттям нової, а - створення зустрічі через браузер повторно використовує вкладку з поточним `https://meet.google.com/new` - або запитом Google account перед відкриттям ще однієї. -- Немає аудіо: у Meet спрямовуйте мікрофон/динамік через шлях віртуального аудіопристрою, який використовує OpenClaw; використовуйте окремі віртуальні пристрої або маршрутизацію в стилі Loopback - для чистого дуплексного аудіо. + створення зустрічі через браузер повторно використовує поточну вкладку `https://meet.google.com/new` + або вкладку запиту облікового запису Google перед відкриттям іншої. +- Немає аудіо: у Meet спрямовуйте мікрофон/динамік через шлях віртуального аудіопристрою, + який використовує OpenClaw; використовуйте окремі віртуальні пристрої або маршрутизацію в стилі Loopback + для чистого двобічного аудіо. ## Примітки щодо встановлення -Типове використання `realtime` у Chrome використовує два зовнішні інструменти: +Типовий режим Chrome у реальному часі використовує два зовнішні інструменти: -- `sox`: утиліта командного рядка для аудіо. Plugin використовує її команди `rec` і `play` +- `sox`: утиліта командного рядка для роботи з аудіо. Plugin використовує її команди `rec` і `play` для типового аудіомосту G.711 mu-law 8 кГц. -- `blackhole-2ch`: віртуальний аудіодрайвер macOS. Він створює аудіопристрій `BlackHole 2ch`, +- `blackhole-2ch`: віртуальний аудіодрайвер для macOS. Він створює аудіопристрій `BlackHole 2ch`, через який Chrome/Meet можуть маршрутизувати звук. -OpenClaw не включає й не розповсюджує жоден із цих пакетів. У документації користувачам пропонується -встановлювати їх як залежності host через Homebrew. SoX ліцензовано як -`LGPL-2.0-only AND GPL-2.0-only`; BlackHole — за GPL-3.0. Якщо ви створюєте -інсталятор або appliance, що містить BlackHole разом з OpenClaw, перегляньте -умови ліцензування BlackHole в upstream або отримайте окрему ліцензію від Existential Audio. +OpenClaw не постачає і не розповсюджує жоден із цих пакетів. У документації користувачам +пропонується встановити їх як залежності хоста через Homebrew. SoX ліцензовано як +`LGPL-2.0-only AND GPL-2.0-only`; BlackHole — GPL-3.0. Якщо ви збираєте інсталятор або +пристрій, який постачає BlackHole разом з OpenClaw, перегляньте +умови ліцензування BlackHole в першоджерелі або отримайте окрему ліцензію від Existential Audio. ## Транспорти ### Chrome -Транспорт Chrome відкриває URL Meet у Google Chrome і приєднується як профіль -Chrome з виконаним входом. На macOS Plugin перед запуском перевіряє наявність `BlackHole 2ch`. -Якщо налаштовано, він також виконує команду перевірки стану аудіомосту та команду запуску -перед відкриттям Chrome. Використовуйте `chrome`, коли Chrome/аудіо працюють на host Gateway; -використовуйте `chrome-node`, коли Chrome/аудіо працюють на підключеному вузлі, наприклад у Parallels +Транспорт Chrome відкриває URL Meet у Google Chrome і приєднується як профіль Chrome +з уже виконаним входом. У macOS Plugin перед запуском перевіряє наявність `BlackHole 2ch`. +Якщо налаштовано, він також запускає команду перевірки стану аудіомосту та команду запуску +перед відкриттям Chrome. Використовуйте `chrome`, коли Chrome/аудіо працюють на хості Gateway; +використовуйте `chrome-node`, коли Chrome/аудіо працюють на прив’язаному вузлі, такому як Parallels macOS VM. ```bash @@ -311,16 +361,20 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node ``` -Спрямуйте аудіо мікрофона та динаміка Chrome через локальний аудіоміст OpenClaw. Якщо `BlackHole 2ch` не встановлено, приєднання завершується з помилкою налаштування, а не мовчки приєднується без аудіошляху. +Спрямовуйте звук мікрофона та динаміка Chrome через локальний аудіоміст OpenClaw. +Якщо `BlackHole 2ch` не встановлено, приєднання завершується помилкою налаштування +замість тихого приєднання без аудіошляху. ### Twilio Транспорт Twilio — це строгий план набору, делегований Plugin Voice Call. Він -не аналізує сторінки Meet, щоб знаходити телефонні номери. +не аналізує сторінки Meet у пошуках телефонних номерів. -Використовуйте це, коли участь через Chrome недоступна або коли вам потрібен резервний варіант дозвону телефоном. Google Meet має надавати телефонний номер для дозвону та PIN для зустрічі; OpenClaw не визначає їх зі сторінки Meet. +Використовуйте це, коли участь через Chrome недоступна або коли вам потрібен резервний +варіант із телефонним дозвоном. Google Meet має показувати телефонний номер для дозвону та PIN для +зустрічі; OpenClaw не визначає їх зі сторінки Meet. -Увімкніть Plugin Voice Call на host Gateway, а не на вузлі Chrome: +Увімкніть Plugin Voice Call на хості Gateway, а не на вузлі Chrome: ```json5 { @@ -345,8 +399,8 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome } ``` -Надайте облікові дані Twilio через середовище або конфігурацію. Середовище дозволяє -не зберігати секрети в `openclaw.json`: +Надайте облікові дані Twilio через середовище або конфігурацію. Середовище зберігає +секрети поза `openclaw.json`: ```bash export TWILIO_ACCOUNT_SID=AC... @@ -354,8 +408,8 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -Перезапустіть або перезавантажте Gateway після ввімкнення `voice-call`; зміни -конфігурації Plugin не з’являються в уже запущеному процесі Gateway, доки його не буде перезавантажено. +Перезапустіть або перезавантажте Gateway після ввімкнення `voice-call`; зміни конфігурації Plugin +не з’являються в уже запущеному процесі Gateway, доки його не буде перезавантажено. Потім перевірте: @@ -365,8 +419,8 @@ openclaw plugins list | grep -E 'google-meet|voice-call' openclaw googlemeet setup ``` -Коли делегування Twilio налаштовано, `googlemeet setup` містить успішні -перевірки `twilio-voice-call-plugin` і `twilio-voice-call-credentials`. +Коли делегування Twilio підключено, `googlemeet setup` містить успішні перевірки +`twilio-voice-call-plugin` і `twilio-voice-call-credentials`. ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -375,7 +429,7 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --pin 123456 ``` -Використовуйте `--dtmf-sequence`, коли зустріч потребує користувацької послідовності: +Використовуйте `--dtmf-sequence`, коли зустріч потребує власної послідовності: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -387,30 +441,178 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ ## OAuth і попередня перевірка OAuth є необов’язковим для створення посилання Meet, оскільки `googlemeet create` може -використовувати резервний шлях через автоматизацію браузера. Налаштуйте OAuth, якщо вам потрібне офіційне створення через API, -визначення простору або перевірки перед початком роботи Meet Media API. +використовувати резервний варіант через автоматизацію браузера. Налаштуйте OAuth, коли вам потрібні офіційне створення через API, +визначення простору або попередні перевірки Meet Media API. -Доступ до API Google Meet спочатку використовує особистий OAuth client. Налаштуйте -`oauth.clientId` і, за потреби, `oauth.clientSecret`, а потім виконайте: +Доступ до Google Meet API використовує OAuth користувача: створіть клієнт Google Cloud OAuth, +запросіть потрібні області доступу, авторизуйте обліковий запис Google, а потім збережіть +отриманий refresh token у конфігурації Plugin Google Meet або надайте змінні середовища +`OPENCLAW_GOOGLE_MEET_*`. + +OAuth не замінює шлях приєднання через Chrome. Транспорти Chrome і Chrome-node +усе одно приєднуються через профіль Chrome з виконаним входом, BlackHole/SoX і підключений +вузол, коли ви використовуєте участь через браузер. OAuth призначений лише для офіційного +шляху Google Meet API: створення просторів зустрічей, визначення просторів і запуску +попередніх перевірок Meet Media API. + +### Створення облікових даних Google + +У Google Cloud Console: + +1. Створіть або виберіть проєкт Google Cloud. +2. Увімкніть **Google Meet REST API** для цього проєкту. +3. Налаштуйте екран згоди OAuth. + - **Internal** є найпростішим варіантом для організації Google Workspace. + - **External** працює для особистих/тестових налаштувань; поки застосунок у стані Testing, + додайте кожен обліковий запис Google, який авторизуватиме застосунок, як тестового користувача. +4. Додайте області доступу, які запитує OpenClaw: + - `https://www.googleapis.com/auth/meetings.space.created` + - `https://www.googleapis.com/auth/meetings.space.readonly` + - `https://www.googleapis.com/auth/meetings.conference.media.readonly` +5. Створіть OAuth client ID. + - Тип застосунку: **Web application**. + - Дозволений URI перенаправлення: + + ```text + http://localhost:8085/oauth2callback + ``` + +6. Скопіюйте client ID і client secret. + +`meetings.space.created` потрібен для Google Meet `spaces.create`. +`meetings.space.readonly` дозволяє OpenClaw визначати простори для URL/кодів Meet. +`meetings.conference.media.readonly` призначено для попередніх перевірок Meet Media API і роботи з медіа; +Google може вимагати участі в Developer Preview для фактичного використання Media API. +Якщо вам потрібні лише приєднання через Chrome на основі браузера, повністю пропустіть OAuth. + +### Створення refresh token + +Налаштуйте `oauth.clientId` і, за потреби, `oauth.clientSecret`, або передайте їх як +змінні середовища, а потім виконайте: ```bash openclaw googlemeet auth login --json ``` -Команда виводить блок конфігурації `oauth` з refresh token. Вона використовує PKCE, +Команда виводить блок конфігурації `oauth` із refresh token. Вона використовує PKCE, локальний callback на `http://localhost:8085/oauth2callback` і ручний потік копіювання/вставлення з `--manual`. -Згода OAuth включає створення просторів Meet, доступ на читання просторів Meet і доступ -на читання медіаданих конференції Meet. Якщо ви проходили автентифікацію до появи підтримки -створення зустрічей, повторно виконайте `openclaw googlemeet auth login --json`, щоб refresh -token мав область дії `meetings.space.created`. +Приклади: -Для резервного варіанта через браузер облікові дані OAuth не потрібні. У цьому режимі Google -автентифікація походить із профілю Chrome з виконаним входом на вибраному вузлі, а не з +```bash +OPENCLAW_GOOGLE_MEET_CLIENT_ID="your-client-id" \ +OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \ +openclaw googlemeet auth login --json +``` + +Використовуйте ручний режим, коли браузер не може досягти локального callback: + +```bash +OPENCLAW_GOOGLE_MEET_CLIENT_ID="your-client-id" \ +OPENCLAW_GOOGLE_MEET_CLIENT_SECRET="your-client-secret" \ +openclaw googlemeet auth login --json --manual +``` + +Вивід JSON містить: + +```json +{ + "oauth": { + "clientId": "your-client-id", + "clientSecret": "your-client-secret", + "refreshToken": "refresh-token", + "accessToken": "access-token", + "expiresAt": 1770000000000 + }, + "scope": "..." +} +``` + +Збережіть об’єкт `oauth` у конфігурації Plugin Google Meet: + +```json5 +{ + plugins: { + entries: { + "google-meet": { + enabled: true, + config: { + oauth: { + clientId: "your-client-id", + clientSecret: "your-client-secret", + refreshToken: "refresh-token", + }, + }, + }, + }, + }, +} +``` + +Надавайте перевагу змінним середовища, якщо не хочете зберігати refresh token у конфігурації. +Якщо присутні і значення конфігурації, і значення середовища, Plugin спочатку визначає конфігурацію, +а потім використовує резервний варіант із середовища. + +Згода OAuth охоплює створення простору Meet, доступ до читання простору Meet і доступ до читання +медіа конференції Meet. Якщо ви автентифікувалися до появи підтримки +створення зустрічей, повторно запустіть `openclaw googlemeet auth login --json`, щоб refresh +token мав область доступу `meetings.space.created`. + +### Перевірка OAuth за допомогою doctor + +Запускайте doctor для OAuth, коли вам потрібна швидка перевірка стану без секретів: + +```bash +openclaw googlemeet doctor --oauth --json +``` + +Це не завантажує середовище виконання Chrome і не потребує підключеного вузла Chrome. Команда +перевіряє, що конфігурація OAuth існує і що refresh token може створити access +token. Звіт JSON містить лише поля стану, такі як `ok`, `configured`, +`tokenSource`, `expiresAt` і повідомлення перевірок; він не виводить access +token, refresh token або client secret. + +Поширені результати: + +| Перевірка | Значення | +| -------------------- | --------------------------------------------------------------------------------------- | +| `oauth-config` | Присутні `oauth.clientId` плюс `oauth.refreshToken`, або кешований access token. | +| `oauth-token` | Кешований access token усе ще чинний, або refresh token створив новий access token. | +| `meet-spaces-get` | Необов’язкова перевірка `--meeting` визначила наявний простір Meet. | +| `meet-spaces-create` | Необов’язкова перевірка `--create-space` створила новий простір Meet. | + +Щоб також підтвердити ввімкнення Google Meet API та область доступу `spaces.create`, запустіть +перевірку створення з побічним ефектом: + +```bash +openclaw googlemeet doctor --oauth --create-space --json +openclaw googlemeet create --no-join --json +``` + +`--create-space` створює тимчасовий URL Meet. Використовуйте його, коли потрібно підтвердити, +що в проєкті Google Cloud увімкнено Meet API і що авторизований +обліковий запис має область доступу `meetings.space.created`. + +Щоб підтвердити доступ на читання для наявного простору зустрічі: + +```bash +openclaw googlemeet doctor --oauth --meeting https://meet.google.com/abc-defg-hij --json +openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij +``` + +`doctor --oauth --meeting` і `resolve-space` підтверджують доступ на читання до наявного +простору, до якого має доступ авторизований обліковий запис Google. `403` від цих перевірок +зазвичай означає, що Google Meet REST API вимкнено, у refresh token, +на який надано згоду, відсутня потрібна область доступу, або обліковий запис Google не має доступу до цього +простору Meet. Помилка refresh token означає, що потрібно повторно виконати `openclaw googlemeet auth login +--json` і зберегти новий блок `oauth`. + +Для резервного варіанта через браузер облікові дані OAuth не потрібні. У цьому режимі автентифікація Google +надходить із профілю Chrome з виконаним входом на вибраному вузлі, а не з конфігурації OpenClaw. -Як резервні варіанти підтримуються такі змінні середовища: +Як резервні варіанти приймаються такі змінні середовища: - `OPENCLAW_GOOGLE_MEET_CLIENT_ID` або `GOOGLE_MEET_CLIENT_ID` - `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET` або `GOOGLE_MEET_CLIENT_SECRET` @@ -433,22 +635,36 @@ openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij ``` -Перелічіть артефакти зустрічі та відвідуваність після того, як Meet створить записи конференції: +Покажіть артефакти зустрічі та відвідуваність після того, як Meet створить записи конференції: ```bash openclaw googlemeet artifacts --meeting https://meet.google.com/abc-defg-hij openclaw googlemeet attendance --meeting https://meet.google.com/abc-defg-hij ``` -Якщо ви вже знаєте id запису конференції, звертайтеся до нього напряму: +Якщо ви вже знаєте id запису конференції, звертайтеся до нього безпосередньо: ```bash openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 --json openclaw googlemeet attendance --conference-record conferenceRecords/abc123 --json ``` -`artifacts` повертає метадані запису конференції, а також метадані ресурсів учасників, запису, -транскрипту та smart-note, коли Google надає їх для зустрічі. `attendance` розгортає учасників у рядки сеансів учасників із часовими мітками приєднання/виходу. Ці команди використовують лише Meet REST API; завантаження тіла документа транскрипту або smart-note навмисно не входить до області дії, оскільки для цього потрібен окремий доступ до Google Docs/Drive. +Запишіть зручний для читання звіт: + +```bash +openclaw googlemeet artifacts --conference-record conferenceRecords/abc123 \ + --format markdown --output meet-artifacts.md +openclaw googlemeet attendance --conference-record conferenceRecords/abc123 \ + --format markdown --output meet-attendance.md +``` + +`artifacts` повертає метадані запису конференції, а також метадані ресурсів +учасників, записів, транскрипту, структурованих записів транскрипту та smart-note, +коли Google надає їх для зустрічі. Використовуйте `--no-transcript-entries`, щоб пропустити +пошук записів для великих зустрічей. `attendance` розгортає учасників у рядки +сеансів учасників із часовими мітками входу/виходу. Ці команди використовують лише Meet +REST API; завантаження вмісту документів Google Docs/Drive навмисно виходить за межі +області дії, оскільки для цього потрібен окремий доступ до Google Docs/Drive. Створіть новий простір Meet: @@ -456,13 +672,13 @@ openclaw googlemeet attendance --conference-record conferenceRecords/abc123 --js openclaw googlemeet create ``` -Команда виводить нові `meeting uri`, джерело та сеанс приєднання. За наявності облікових даних OAuth -використовується офіційний API Google Meet. Без облікових даних OAuth вона -використовує профіль браузера з виконаним входом на закріпленому Node Chrome як резервний варіант. Агенти можуть +Команда виводить новий `meeting uri`, джерело та сеанс приєднання. За наявності облікових даних OAuth +вона використовує офіційний Google Meet API. Без облікових даних OAuth вона +використовує профіль браузера з виконаним входом на закріпленому вузлі Chrome як резервний варіант. Агенти можуть використовувати інструмент `google_meet` з `action: "create"`, щоб створити й приєднатися за один крок. Для створення лише URL передайте `"join": false`. -Приклад JSON-виводу з резервного варіанта через браузер: +Приклад виводу JSON із резервного варіанта через браузер: ```json { @@ -482,31 +698,31 @@ openclaw googlemeet create } ``` -Якщо резервний варіант через браузер натрапляє на вхід у Google або блокувальник дозволів Meet до того, як -він зможе створити URL, метод Gateway повертає відповідь з помилкою, а -інструмент `google_meet` повертає структуровані деталі замість звичайного рядка: +Якщо резервний варіант через браузер стикається з входом Google або блокером дозволів Meet до того, +як може створити URL, метод Gateway повертає відповідь із помилкою, а інструмент +`google_meet` повертає структуровані подробиці замість звичайного рядка: ```json { "source": "browser", - "error": "google-login-required: Sign in to Google in the OpenClaw browser profile, then retry meeting creation.", + "error": "google-login-required: Увійдіть у Google в профілі браузера OpenClaw, а потім повторіть спробу створення зустрічі.", "manualActionRequired": true, "manualActionReason": "google-login-required", - "manualActionMessage": "Sign in to Google in the OpenClaw browser profile, then retry meeting creation.", + "manualActionMessage": "Увійдіть у Google в профілі браузера OpenClaw, а потім повторіть спробу створення зустрічі.", "browser": { "nodeId": "ba0f4e4bc...", "targetId": "tab-1", "browserUrl": "https://accounts.google.com/signin", - "browserTitle": "Sign in - Google Accounts" + "browserTitle": "Вхід — Облікові записи Google" } } ``` Коли агент бачить `manualActionRequired: true`, він має повідомити -`manualActionMessage` разом із контекстом вузла/вкладки браузера і припинити відкривати нові -вкладки Meet, доки оператор не завершить крок у браузері. +`manualActionMessage` разом із контекстом вузла/вкладки браузера та припинити відкривати нові +вкладки Meet, доки оператор не виконає крок у браузері. -Приклад JSON-виводу зі створення через API: +Приклад виводу JSON для створення через API: ```json { @@ -527,20 +743,20 @@ openclaw googlemeet create } ``` -Створення Meet типово виконує приєднання. Транспорт Chrome або Chrome-node усе ще +Створення Meet типово також виконує приєднання. Транспорт Chrome або Chrome-node усе одно потребує профілю Google Chrome з виконаним входом, щоб приєднатися через браузер. Якщо -у профілі виконано вихід, OpenClaw повідомляє `manualActionRequired: true` або -помилку резервного варіанта браузера і просить оператора завершити вхід у Google перед +у профілі виконано вихід, OpenClaw повідомляє `manualActionRequired: true` або помилку +резервного варіанта через браузер і просить оператора завершити вхід у Google перед повторною спробою. -Встановлюйте `preview.enrollmentAcknowledged: true` лише після підтвердження, що ваш Cloud -project, OAuth principal і учасники зустрічі зареєстровані в Google -Workspace Developer Preview Program для медіа-API Meet. +Установлюйте `preview.enrollmentAcknowledged: true` лише після підтвердження, що ваш Cloud- +проєкт, суб’єкт OAuth і учасники зустрічі зареєстровані в програмі Google +Workspace Developer Preview Program для Meet media APIs. ## Конфігурація -Поширений шлях Chrome `realtime` потребує лише ввімкненого Plugin, BlackHole, SoX -і ключа backend-провайдера голосу в реальному часі. OpenAI є типовим; задайте +Поширений шлях Chrome у реальному часі потребує лише ввімкненого Plugin, BlackHole, SoX +та ключа провайдера голосу в реальному часі для бекенда. OpenAI є типовим варіантом; установіть `realtime.provider: "google"`, щоб використовувати Google Gemini Live: ```bash @@ -550,7 +766,7 @@ export OPENAI_API_KEY=sk-... export GEMINI_API_KEY=... ``` -Задайте конфігурацію Plugin у `plugins.entries.google-meet.config`: +Установіть конфігурацію Plugin у `plugins.entries.google-meet.config`: ```json5 { @@ -573,22 +789,22 @@ export GEMINI_API_KEY=... - `chrome.audioBackend: "blackhole-2ch"` - `chrome.guestName: "OpenClaw Agent"`: ім’я, що використовується на екрані гостя Meet без входу -- `chrome.autoJoin: true`: заповнення імені гостя за принципом best-effort і натискання Join Now - через автоматизацію браузера OpenClaw на `chrome-node` +- `chrome.autoJoin: true`: заповнення імені гостя та натискання Join Now у + міру можливості через автоматизацію браузера OpenClaw на `chrome-node` - `chrome.reuseExistingTab: true`: активувати наявну вкладку Meet замість відкриття дублікатів -- `chrome.waitForInCallMs: 20000`: очікувати, доки вкладка Meet не повідомить стан in-call, - перш ніж буде запущено вступ у `realtime` -- `chrome.audioInputCommand`: команда SoX `rec`, що записує аудіо G.711 mu-law 8 кГц +- `chrome.waitForInCallMs: 20000`: чекати, поки вкладка Meet повідомить про стан in-call, + перш ніж буде запущено вступ у реальному часі +- `chrome.audioInputCommand`: команда SoX `rec`, що записує аудіо 8 кГц G.711 mu-law у stdout -- `chrome.audioOutputCommand`: команда SoX `play`, що читає аудіо G.711 mu-law 8 кГц +- `chrome.audioOutputCommand`: команда SoX `play`, що читає аудіо 8 кГц G.711 mu-law зі stdin - `realtime.provider: "openai"` - `realtime.toolPolicy: "safe-read-only"` - `realtime.instructions`: короткі усні відповіді, з `openclaw_agent_consult` для глибших відповідей -- `realtime.introMessage`: коротка усна перевірка готовності, коли міст `realtime` - підключається; задайте `""`, щоб приєднуватися беззвучно +- `realtime.introMessage`: коротка усна перевірка готовності, коли міст реального часу + підключається; установіть `""`, щоб приєднуватися беззвучно Необов’язкові перевизначення: @@ -608,7 +824,7 @@ export GEMINI_API_KEY=... realtime: { provider: "google", toolPolicy: "owner", - introMessage: "Say exactly: I'm here.", + introMessage: "Скажи точно: Я тут.", providers: { google: { model: "gemini-2.5-flash-native-audio-preview-12-2025", @@ -634,10 +850,10 @@ export GEMINI_API_KEY=... } ``` -`voiceCall.enabled` типово має значення `true`; з транспортом Twilio він делегує -фактичний виклик PSTN і DTMF Plugin Voice Call. Якщо `voice-call` не ввімкнено, -Google Meet все одно може перевіряти й записувати план набору, але він не може -виконати виклик Twilio. +`voiceCall.enabled` типово має значення `true`; із транспортом Twilio він делегує +фактичний PSTN-дзвінок і DTMF Plugin Voice Call. Якщо `voice-call` не ввімкнено, +Google Meet усе одно може перевіряти й записувати план набору, але не може +виконати дзвінок Twilio. ## Інструмент @@ -652,97 +868,96 @@ Google Meet все одно може перевіряти й записуват } ``` -Використовуйте `transport: "chrome"`, коли Chrome працює на host Gateway. Використовуйте -`transport: "chrome-node"`, коли Chrome працює на підключеному вузлі, наприклад у Parallels -VM. В обох випадках модель `realtime` і `openclaw_agent_consult` працюють на -host Gateway, тож облікові дані моделі залишаються там. +Використовуйте `transport: "chrome"`, коли Chrome працює на хості Gateway. Використовуйте +`transport: "chrome-node"`, коли Chrome працює на прив’язаному вузлі, такому як Parallels +VM. В обох випадках модель реального часу і `openclaw_agent_consult` працюють на +хості Gateway, тож облікові дані моделі залишаються там. -Використовуйте `action: "status"`, щоб перелічити активні сеанси або перевірити ID сеансу. Використовуйте -`action: "speak"` із `sessionId` і `message`, щоб змусити агента `realtime` +Використовуйте `action: "status"`, щоб показати активні сеанси або перевірити id сеансу. Використовуйте +`action: "speak"` із `sessionId` і `message`, щоб змусити агента реального часу говорити негайно. Використовуйте `action: "test_speech"`, щоб створити або повторно використати сеанс, -запустити відому фразу та повернути стан `inCall`, якщо host Chrome може -його повідомити. Використовуйте `action: "leave"`, щоб позначити сеанс завершеним. +запустити відому фразу й повернути стан `inCall`, коли хост Chrome може +його повідомити. Використовуйте `action: "leave"`, щоб позначити сеанс як завершений. -`status` включає стан Chrome, коли він доступний: +`status` містить стан Chrome, коли він доступний: -- `inCall`: здається, що Chrome перебуває у виклику Meet -- `micMuted`: стан мікрофона Meet за принципом best-effort -- `manualActionRequired` / `manualActionReason` / `manualActionMessage`: профіль - браузера потребує ручного входу, допуску від host Meet, дозволів або - відновлення керування браузером, перш ніж мовлення запрацює -- `providerConnected` / `realtimeReady`: стан мосту голосу в реальному часі -- `lastInputAt` / `lastOutputAt`: час останнього аудіо, отриманого від мосту або - надісланого до нього +- `inCall`: схоже, що Chrome перебуває всередині дзвінка Meet +- `micMuted`: найкраща доступна оцінка стану мікрофона Meet +- `manualActionRequired` / `manualActionReason` / `manualActionMessage`: профілю + браузера потрібні ручний вхід, допуск хостом у Meet, дозволи або + відновлення керування браузером, перш ніж мовлення зможе працювати +- `providerConnected` / `realtimeReady`: стан мосту голосу реального часу +- `lastInputAt` / `lastOutputAt`: час останнього аудіо, отриманого мостом або надісланого до нього ```json { "action": "speak", "sessionId": "meet_...", - "message": "Say exactly: I'm here and listening." + "message": "Скажи точно: Я тут і слухаю." } ``` ## Консультація агента в реальному часі -Режим Chrome `realtime` оптимізовано для живого голосового циклу. Провайдер голосу -в реальному часі чує аудіо зустрічі та говорить через налаштований аудіоміст. -Коли моделі `realtime` потрібні глибше міркування, актуальна інформація або звичайні +Режим Chrome у реальному часі оптимізовано для живого голосового циклу. Провайдер голосу +реального часу чує аудіо зустрічі та говорить через налаштований аудіоміст. +Коли моделі реального часу потрібні глибші міркування, актуальна інформація або звичайні інструменти OpenClaw, вона може викликати `openclaw_agent_consult`. -Інструмент консультації запускає звичайного агента OpenClaw у фоновому режимі з контекстом -нещодавнього транскрипту зустрічі та повертає стислу усну відповідь до сеансу -голосу в реальному часі. Потім голосова модель може озвучити цю відповідь назад у зустріч. -Він використовує той самий спільний інструмент консультації `realtime`, що й Voice Call. +Інструмент консультації запускає звичайного агента OpenClaw за лаштунками з контекстом +нещодавнього транскрипту зустрічі й повертає стислу усну відповідь до сеансу +голосу реального часу. Потім голосова модель може озвучити цю відповідь назад у зустріч. +Він використовує той самий спільний інструмент консультації реального часу, що й Voice Call. `realtime.toolPolicy` керує запуском консультації: -- `safe-read-only`: надає інструмент консультації та обмежує звичайного агента +- `safe-read-only`: показувати інструмент консультації та обмежувати звичайного агента інструментами `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. -- `owner`: надає інструмент консультації та дозволяє звичайному агенту використовувати звичайну +- `owner`: показувати інструмент консультації та дозволяти звичайному агенту використовувати звичайну політику інструментів агента. -- `none`: не надає інструмент консультації моделі голосу в реальному часі. +- `none`: не показувати інструмент консультації моделі голосу реального часу. -Ключ сеансу консультації має область дії на рівні сеансу Meet, тож наступні виклики консультації -можуть повторно використовувати попередній контекст консультації в межах тієї самої зустрічі. +Ключ сеансу консультації обмежено кожним сеансом Meet, тож наступні виклики консультації +можуть повторно використовувати попередній контекст консультації протягом тієї самої зустрічі. -Щоб примусово виконати усну перевірку готовності після того, як Chrome повністю приєднався до виклику: +Щоб примусово виконати усну перевірку готовності після того, як Chrome повністю приєднався до дзвінка: ```bash -openclaw googlemeet speak meet_... "Say exactly: I'm here and listening." +openclaw googlemeet speak meet_... "Скажи точно: Я тут і слухаю." ``` -Для повного smoke-тесту приєднання та мовлення: +Для повного smoke-тесту приєднання й мовлення: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ --transport chrome-node \ - --message "Say exactly: I'm here and listening." + --message "Скажи точно: Тест мовлення Google Meet завершено." ``` -## Контрольний список live-тесту +## Контрольний список живого тесту -Використовуйте цю послідовність перед передачею зустрічі агенту без нагляду: +Використовуйте цю послідовність перед тим, як передати зустріч агенту без нагляду: ```bash openclaw googlemeet setup openclaw nodes status openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ --transport chrome-node \ - --message "Say exactly: Google Meet speech test complete." + --message "Скажи точно: Тест мовлення Google Meet завершено." ``` -Очікуваний стан `chrome-node`: +Очікуваний стан Chrome-node: - `googlemeet setup` повністю зелений. -- `googlemeet setup` містить `chrome-node-connected`, коли `chrome-node` є - типовим транспортом або коли вузол закріплено. +- `googlemeet setup` містить `chrome-node-connected`, коли Chrome-node є + транспортом за замовчуванням або вузол закріплено. - `nodes status` показує, що вибраний вузол підключено. - Вибраний вузол рекламує і `googlemeet.chrome`, і `browser.proxy`. -- Вкладка Meet приєднується до виклику, а `test-speech` повертає стан Chrome з +- Вкладка Meet приєднується до дзвінка, а `test-speech` повертає стан Chrome з `inCall: true`. -Для віддаленого host Chrome, наприклад Parallels macOS VM, це найкоротша +Для віддаленого хоста Chrome, такого як Parallels macOS VM, це найкоротша безпечна перевірка після оновлення Gateway або VM: ```bash @@ -754,11 +969,11 @@ openclaw nodes invoke \ --params '{"action":"setup"}' ``` -Це доводить, що Plugin Gateway завантажено, вузол VM підключено з -поточним token, а аудіоміст Meet доступний до того, як агент відкриє -справжню вкладку зустрічі. +Це підтверджує, що Plugin Gateway завантажено, вузол VM підключено з +поточним токеном, а аудіоміст Meet доступний, перш ніж агент відкриє реальну +вкладку зустрічі. -Для smoke-тесту Twilio використовуйте зустріч, яка надає деталі телефонного дозвону: +Для smoke-тесту Twilio використовуйте зустріч, яка показує дані для телефонного дозвону: ```bash openclaw googlemeet setup @@ -774,7 +989,7 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ `twilio-voice-call-credentials`. - `voicecall` доступний у CLI після перезавантаження Gateway. - Повернений сеанс має `transport: "twilio"` і `twilio.voiceCallId`. -- `googlemeet leave ` завершує делегований голосовий виклик. +- `googlemeet leave ` завершує делегований голосовий дзвінок. ## Усунення несправностей @@ -787,13 +1002,13 @@ openclaw plugins list | grep google-meet openclaw googlemeet setup ``` -Якщо ви щойно відредагували `plugins.entries.google-meet`, перезапустіть або перезавантажте Gateway. -Запущений агент бачить лише інструменти Plugin, зареєстровані поточним -процесом Gateway. +Якщо ви щойно редагували `plugins.entries.google-meet`, перезапустіть або перезавантажте Gateway. +Запущений агент бачить лише інструменти Plugin, зареєстровані поточним процесом +Gateway. ### Немає підключеного вузла з підтримкою Google Meet -На host вузла виконайте: +На хості вузла виконайте: ```bash openclaw plugins enable google-meet @@ -802,7 +1017,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -На host Gateway схваліть вузол і перевірте команди: +На хості Gateway схваліть вузол і перевірте команди: ```bash openclaw devices list @@ -823,8 +1038,8 @@ openclaw nodes status } ``` -Якщо `googlemeet setup` завершується помилкою `chrome-node-connected` або в журналі Gateway є -`gateway token mismatch`, перевстановіть або перезапустіть вузол з поточним token Gateway. +Якщо `googlemeet setup` завершується помилкою `chrome-node-connected` або в журналі Gateway повідомляється +`gateway token mismatch`, перевстановіть або перезапустіть вузол із поточним токеном Gateway. Для Gateway у LAN це зазвичай означає: ```bash @@ -836,7 +1051,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ --force ``` -Потім перезавантажте службу вузла і повторно виконайте: +Потім перезавантажте службу вузла й повторно виконайте: ```bash openclaw googlemeet setup @@ -847,54 +1062,55 @@ openclaw nodes status --connected Запустіть `googlemeet test-speech` і перевірте повернений стан Chrome. Якщо він повідомляє `manualActionRequired: true`, покажіть оператору `manualActionMessage` -і припиніть повторні спроби, доки дію в браузері не буде завершено. +і припиніть повторні спроби, доки дія в браузері не буде завершена. Поширені ручні дії: -- Виконати вхід у профіль Chrome. -- Допустити гостя з облікового запису host Meet. -- Надати Chrome дозволи на мікрофон/камеру, коли з’являється власний запит дозволу Chrome. -- Закрити або виправити завислий діалог дозволів Meet. +- Увійти в профіль Chrome. +- Дозволити гостя з облікового запису хоста Meet. +- Надати Chrome дозволи на мікрофон/камеру, коли з’являється власний запит + дозволів Chrome. +- Закрити або відновити завислий діалог дозволів Meet. -Не повідомляйте "not signed in" лише тому, що Meet показує "Do you want people to -hear you in the meeting?" Це проміжний екран вибору аудіо Meet; OpenClaw +Не повідомляйте «вхід не виконано» лише тому, що Meet показує «Do you want people to +hear you in the meeting?». Це проміжний екран вибору аудіо Meet; OpenClaw натискає **Use microphone** через автоматизацію браузера, коли це можливо, і продовжує -очікувати на справжній стан зустрічі. Для резервного створення лише через браузер OpenClaw -може натиснути **Continue without microphone**, оскільки для створення URL -аудіошлях `realtime` не потрібен. +чекати на справжній стан зустрічі. Для резервного варіанта створення лише через браузер OpenClaw +може натиснути **Continue without microphone**, оскільки для створення URL не потрібен +аудіошлях реального часу. ### Не вдається створити зустріч -`googlemeet create` спочатку використовує endpoint `spaces.create` API Google Meet, -коли налаштовано облікові дані OAuth. Без облікових даних OAuth він переходить -до резервного варіанта через браузер закріпленого вузла Chrome. Підтвердьте: +`googlemeet create` спочатку використовує endpoint Google Meet API `spaces.create`, +коли налаштовано облікові дані OAuth. Без облікових даних OAuth команда використовує резервний варіант +через браузер закріпленого вузла Chrome. Підтвердьте: - Для створення через API: налаштовано `oauth.clientId` і `oauth.refreshToken`, або присутні відповідні змінні середовища `OPENCLAW_GOOGLE_MEET_*`. -- Для створення через API: refresh token було створено після додавання підтримки - створення. Старіші token можуть не мати області дії `meetings.space.created`; повторно виконайте +- Для створення через API: refresh token було створено після додавання + підтримки створення. У старих токенів може бути відсутня область доступу `meetings.space.created`; повторно виконайте `openclaw googlemeet auth login --json` і оновіть конфігурацію Plugin. - Для резервного варіанта через браузер: `defaultTransport: "chrome-node"` і - `chromeNode.node` вказують на підключений вузол з `browser.proxy` і + `chromeNode.node` вказують на підключений вузол із `browser.proxy` і `googlemeet.chrome`. -- Для резервного варіанта через браузер: профіль OpenClaw Chrome на цьому вузлі має виконаний вхід +- Для резервного варіанта через браузер: профіль Chrome OpenClaw на цьому вузлі має виконаний вхід у Google і може відкривати `https://meet.google.com/new`. - Для резервного варіанта через браузер: повторні спроби повторно використовують наявну вкладку `https://meet.google.com/new` - або вкладку із запитом Google account перед відкриттям нової вкладки. Якщо в агента стався timeout, - повторіть виклик інструмента замість того, щоб вручну відкривати ще одну вкладку Meet. + або вкладку запиту облікового запису Google перед відкриттям нової вкладки. Якщо в агента стався тайм-аут, + повторіть виклик інструмента замість ручного відкриття ще однієї вкладки Meet. - Для резервного варіанта через браузер: якщо інструмент повертає `manualActionRequired: true`, використовуйте повернені `browser.nodeId`, `browser.targetId`, `browserUrl` і - `manualActionMessage`, щоб зорієнтувати оператора. Не повторюйте спроби циклічно, доки цю + `manualActionMessage`, щоб спрямувати оператора. Не повторюйте спроби в циклі, доки цю дію не буде завершено. - Для резервного варіанта через браузер: якщо Meet показує "Do you want people to hear you in the meeting?", залиште вкладку відкритою. OpenClaw має натиснути **Use microphone** або, для - резервного створення лише URL, **Continue without microphone** через автоматизацію - браузера і продовжити очікування згенерованого URL Meet. Якщо це неможливо, у + резервного варіанта лише створення, **Continue without microphone** через + автоматизацію браузера та продовжити очікування згенерованого URL Meet. Якщо це не вдається, у помилці має згадуватися `meet-audio-choice-required`, а не `google-login-required`. ### Агент приєднується, але не говорить -Перевірте шлях `realtime`: +Перевірте шлях реального часу: ```bash openclaw googlemeet setup @@ -902,44 +1118,46 @@ openclaw googlemeet doctor ``` Використовуйте `mode: "realtime"` для прослуховування/зворотної розмови. `mode: "transcribe"` навмисно -не запускає дуплексний голосовий міст `realtime`. +не запускає двобічний міст голосу реального часу. Також перевірте: -- На host Gateway доступний ключ провайдера `realtime`, наприклад +- На хості Gateway доступний ключ провайдера реального часу, наприклад `OPENAI_API_KEY` або `GEMINI_API_KEY`. -- `BlackHole 2ch` видно на host Chrome. -- `rec` і `play` існують на host Chrome. -- Мікрофон і динамік Meet спрямовано через шлях віртуального аудіо, який використовує +- `BlackHole 2ch` видимий на хості Chrome. +- `rec` і `play` існують на хості Chrome. +- Мікрофон і динамік Meet спрямовано через віртуальний аудіошлях, який використовує OpenClaw. `googlemeet doctor [session-id]` виводить сеанс, вузол, стан in-call, -причину ручної дії, підключення провайдера `realtime`, `realtimeReady`, активність -аудіовходу/виходу, часові мітки останнього аудіо, лічильники байтів і URL браузера. -Використовуйте `googlemeet status [session-id]`, коли вам потрібен сирий JSON. +причину ручної дії, підключення провайдера реального часу, `realtimeReady`, активність аудіовходу/виходу, +часові мітки останнього аудіо, лічильники байтів і URL браузера. +Використовуйте `googlemeet status [session-id]`, коли вам потрібен сирий JSON. Використовуйте +`googlemeet doctor --oauth`, коли потрібно перевірити оновлення Google Meet OAuth +без показу токенів; додайте `--meeting` або `--create-space`, коли також потрібне підтвердження через Google Meet API. -Якщо в агента стався timeout і ви бачите вже відкриту вкладку Meet, перевірте цю вкладку -без відкриття ще однієї: +Якщо в агента стався тайм-аут і ви бачите, що вкладка Meet уже відкрита, перевірте цю вкладку +без відкриття іншої: ```bash openclaw googlemeet recover-tab openclaw googlemeet recover-tab https://meet.google.com/abc-defg-hij ``` -Еквівалентна дія інструмента — `recover_current_tab`. Вона фокусує та перевіряє +Еквівалентна дія інструмента — `recover_current_tab`. Вона фокусує й перевіряє наявну вкладку Meet на налаштованому вузлі Chrome. Вона не відкриває нову вкладку і не -створює новий сеанс; вона повідомляє про поточний блокувальник, такий як вхід, допуск, +створює новий сеанс; натомість повідомляє про поточний блокер, наприклад вхід, допуск, дозволи або стан вибору аудіо. Команда CLI звертається до налаштованого -Gateway, тому Gateway має бути запущений, а вузол Chrome має бути підключений. +Gateway, тому Gateway має бути запущений, а вузол Chrome — підключений. ### Перевірки налаштування Twilio завершуються помилкою -`twilio-voice-call-plugin` завершується помилкою, коли `voice-call` не дозволено або не увімкнено. +`twilio-voice-call-plugin` завершується помилкою, коли `voice-call` не дозволено або не ввімкнено. Додайте його до `plugins.allow`, увімкніть `plugins.entries.voice-call` і перезавантажте Gateway. -`twilio-voice-call-credentials` завершується помилкою, коли в backend Twilio відсутні account -SID, auth token або номер абонента. Задайте це на host Gateway: +`twilio-voice-call-credentials` завершується помилкою, коли в бекенді Twilio відсутні account +SID, auth token або номер абонента. Установіть це на хості Gateway: ```bash export TWILIO_ACCOUNT_SID=AC... @@ -961,17 +1179,17 @@ openclaw voicecall smoke openclaw voicecall smoke --to "+15555550123" ``` -Додавайте `--yes` лише тоді, коли ви навмисно хочете здійснити реальний вихідний -виклик сповіщення: +Додавайте `--yes` лише тоді, коли навмисно хочете виконати реальний вихідний +дзвінок-сповіщення: ```bash openclaw voicecall smoke --to "+15555550123" --yes ``` -### Виклик Twilio починається, але ніколи не входить у зустріч +### Дзвінок Twilio починається, але ніколи не входить у зустріч -Підтвердьте, що подія Meet надає деталі телефонного дозвону. Передайте точний номер -для дозвону та PIN або користувацьку послідовність DTMF: +Підтвердьте, що подія Meet показує деталі телефонного дозвону. Передайте точний номер +для дозвону та PIN або власну DTMF-послідовність: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -980,34 +1198,34 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -Використовуйте початковий `w` або коми в `--dtmf-sequence`, якщо провайдеру потрібна пауза +Використовуйте початкові `w` або коми в `--dtmf-sequence`, якщо провайдеру потрібна пауза перед введенням PIN. ## Примітки -Офіційний медіа-API Google Meet орієнтований на прийом, тому мовлення у виклику Meet -усе ще потребує шляху учасника. Цей Plugin залишає цю межу видимою: +Офіційний media API Google Meet орієнтовано на прийом, тож для мовлення в дзвінок Meet +усе одно потрібен шлях участі. Цей Plugin зберігає цю межу видимою: Chrome обробляє участь через браузер і локальну маршрутизацію аудіо; Twilio обробляє участь через телефонний дозвін. -Режиму Chrome `realtime` потрібне одне з такого: +Режим Chrome у реальному часі потребує одного з варіантів: - `chrome.audioInputCommand` плюс `chrome.audioOutputCommand`: OpenClaw керує - мостом моделі `realtime` і передає аудіо G.711 mu-law 8 кГц між цими - командами та вибраним провайдером голосу в реальному часі. + мостом моделі реального часу й передає аудіо 8 кГц G.711 mu-law між цими + командами та вибраним провайдером голосу реального часу. - `chrome.audioBridgeCommand`: зовнішня команда мосту керує всім локальним - аудіошляхом і має завершитися після запуску або перевірки свого daemon. + аудіошляхом і має завершитися після запуску або перевірки свого демона. -Для чистого дуплексного аудіо маршрутизуйте вихід Meet і мікрофон Meet через окремі +Для чистого двобічного аудіо маршрутизуйте вихід Meet і мікрофон Meet через окремі віртуальні пристрої або граф віртуальних пристроїв у стилі Loopback. Один спільний -пристрій BlackHole може повертати голоси інших учасників назад у виклик. +пристрій BlackHole може повертати голоси інших учасників назад у дзвінок. -`googlemeet speak` запускає активний аудіоміст `realtime` для сеансу Chrome. -`googlemeet leave` зупиняє цей міст. Для сеансів Twilio, делегованих -через Plugin Voice Call, `leave` також завершує базовий голосовий виклик. +`googlemeet speak` запускає активний аудіоміст реального часу для сеансу +Chrome. `googlemeet leave` зупиняє цей міст. Для сеансів Twilio, делегованих +через Plugin Voice Call, `leave` також завершує базовий голосовий дзвінок. ## Пов’язане - [Plugin Voice Call](/uk/plugins/voice-call) - [Режим розмови](/uk/nodes/talk) -- [Створення Plugin](/uk/plugins/building-plugins) +- [Створення плагінів](/uk/plugins/building-plugins)