diff --git a/docs/uk/automation/tasks.md b/docs/uk/automation/tasks.md index 9d91aa85a..5224a48ab 100644 --- a/docs/uk/automation/tasks.md +++ b/docs/uk/automation/tasks.md @@ -1,16 +1,16 @@ --- read_when: - - Перегляд фонової роботи, що триває або нещодавно завершилася - - Налагодження збоїв доставки для відокремлених запусків агента + - Перегляд фонової роботи, яка виконується або нещодавно завершилася + - Налагодження збоїв доставки для відокремлених запусків агентів - Розуміння того, як фонові запуски пов’язані із сеансами, Cron і Heartbeat sidebarTitle: Background tasks -summary: Відстеження фонових завдань для запусків ACP, субагентів, ізольованих завдань Cron і операцій CLI +summary: Відстеження фонових завдань для запусків ACP, субагентів, ізольованих завдань Cron та операцій CLI title: Фонові завдання x-i18n: - generated_at: "2026-05-01T02:52:47Z" + generated_at: "2026-05-05T00:49:29Z" model: gpt-5.5 provider: openai - source_hash: 8782987a79989264ae3bd1ca4b16755bdfb7e295e4f77933bf3a38c136d837f4 + source_hash: 60d6ea6178535b19b95d761b8e8b05a665234584ae69852fd21097988aa32991 source_path: automation/tasks.md workflow: 16 --- @@ -19,27 +19,27 @@ x-i18n: Шукаєте планування? Див. [Автоматизація та завдання](/uk/automation), щоб вибрати правильний механізм. Ця сторінка є журналом активності для фонової роботи, а не планувальником. -Фонові завдання відстежують роботу, що виконується **поза основним сеансом розмови**: запуски ACP, створення підagentів, ізольовані виконання cron-завдань і операції, ініційовані з CLI. +Фонові завдання відстежують роботу, що виконується **поза вашим основним сеансом розмови**: запуски ACP, створення субагентів, ізольовані виконання cron-завдань і операції, ініційовані CLI. -Завдання **не** замінюють сеанси, cron-завдання чи heartbeats — це **журнал активності**, який записує, яка відокремлена робота відбулася, коли саме та чи завершилася вона успішно. +Завдання **не** замінюють сеанси, cron-завдання чи Heartbeat — вони є **журналом активності**, який записує, яка від’єднана робота відбулася, коли саме та чи була вона успішною. -Не кожен запуск агента створює завдання. Heartbeat-ходи та звичайний інтерактивний чат не створюють. Усі виконання cron, створення ACP, створення підagentів і команди агента з CLI створюють. +Не кожен запуск агента створює завдання. Ходи Heartbeat і звичайний інтерактивний чат цього не роблять. Усі виконання cron, створення ACP, створення субагентів і команди агента CLI це роблять. -## Коротко +## TL;DR -- Завдання — це **записи**, а не планувальники — cron і Heartbeat вирішують, _коли_ виконується робота, а завдання відстежують, _що сталося_. -- ACP, підagенти, усі cron-завдання та операції CLI створюють завдання. Heartbeat-ходи — ні. +- Завдання — це **записи**, а не планувальники: cron і Heartbeat вирішують, _коли_ виконується робота, а завдання відстежують, _що сталося_. +- ACP, субагенти, усі cron-завдання й операції CLI створюють завдання. Ходи Heartbeat цього не роблять. - Кожне завдання проходить через `queued → running → terminal` (succeeded, failed, timed_out, cancelled або lost). - Cron-завдання залишаються активними, доки cron-середовище виконання все ще володіє завданням; якщо - стан середовища виконання в пам’яті зник, обслуговування завдань спершу перевіряє довговічну історію + стан середовища виконання в пам’яті втрачено, обслуговування завдань спершу перевіряє збережену історію запусків cron, перш ніж позначити завдання як lost. -- Завершення керується push-механізмом: відокремлена робота може сповістити напряму або пробудити +- Завершення керується push-механізмом: від’єднана робота може сповістити напряму або розбудити сеанс/Heartbeat запитувача після завершення, тому цикли опитування статусу зазвичай мають неправильну форму. -- Ізольовані cron-запуски та завершення підagentів у режимі best-effort очищають відстежувані вкладки браузера/процеси для свого дочірнього сеансу перед фінальним службовим очищенням. -- Доставка ізольованого cron пригнічує застарілі проміжні відповіді батьківського сеансу, доки робота підagentів-нащадків ще завершується, і віддає перевагу фінальному виводу нащадка, якщо він надходить до доставки. +- Ізольовані cron-запуски та завершення субагентів у міру можливості очищають відстежувані вкладки браузера/процеси для свого дочірнього сеансу перед фінальним службовим очищенням. +- Ізольована доставка cron приглушує застарілі проміжні відповіді батьківського сеансу, доки робота нащадків-субагентів ще завершується, і надає перевагу фінальному виводу нащадка, якщо він надходить до доставки. - Сповіщення про завершення доставляються напряму в канал або ставляться в чергу до наступного Heartbeat. - `openclaw tasks list` показує всі завдання; `openclaw tasks audit` виявляє проблеми. - Термінальні записи зберігаються 7 днів, а потім автоматично видаляються. @@ -47,7 +47,7 @@ x-i18n: ## Швидкий старт - + ```bash # List all tasks (newest first) openclaw tasks list @@ -58,13 +58,13 @@ x-i18n: ``` - + ```bash # Show details for a specific task (by ID, run ID, or session key) openclaw tasks show ``` - + ```bash # Cancel a running task (kills the child session) openclaw tasks cancel @@ -74,7 +74,7 @@ x-i18n: ``` - + ```bash # Run a health audit openclaw tasks audit @@ -85,7 +85,7 @@ x-i18n: ``` - + ```bash # Inspect TaskFlow state openclaw tasks flow list @@ -97,26 +97,26 @@ x-i18n: ## Що створює завдання -| Джерело | Тип середовища виконання | Коли створюється запис завдання | Типова політика сповіщень | -| --------------------- | ------------------------ | ----------------------------------------------------- | ------------------------- | -| Фонові запуски ACP | `acp` | Створення дочірнього сеансу ACP | `done_only` | -| Оркестрація підagentів | `subagent` | Створення підagента через `sessions_spawn` | `done_only` | -| Cron-завдання (усі типи) | `cron` | Кожне виконання cron (основний сеанс та ізольоване) | `silent` | -| Операції CLI | `cli` | Команди `openclaw agent`, що виконуються через Gateway | `silent` | -| Медіазавдання агента | `cli` | Запуски `music_generate`/`video_generate` із підтримкою сеансу | `silent` | +| Джерело | Тип середовища виконання | Коли створюється запис завдання | Типова політика сповіщень | +| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- | +| Фонові запуски ACP | `acp` | Створення дочірнього сеансу ACP | `done_only` | +| Оркестрація субагентів | `subagent` | Створення субагента через `sessions_spawn` | `done_only` | +| Cron-завдання (усі типи) | `cron` | Кожне виконання cron (основний сеанс та ізольоване) | `silent` | +| Операції CLI | `cli` | Команди `openclaw agent`, що виконуються через Gateway | `silent` | +| Медіазавдання агента | `cli` | Запуски `music_generate`/`video_generate` на основі сеансу | `silent` | - - Cron-завдання основного сеансу за замовчуванням використовують політику сповіщень `silent` — вони створюють записи для відстеження, але не генерують сповіщень. Ізольовані cron-завдання також за замовчуванням мають `silent`, але помітніші, бо виконуються у власному сеансі. + + Cron-завдання основного сеансу типово використовують політику сповіщень `silent` — вони створюють записи для відстеження, але не генерують сповіщення. Ізольовані cron-завдання також типово мають `silent`, але вони помітніші, бо виконуються у власному сеансі. - Запуски `music_generate` і `video_generate` із підтримкою сеансу також використовують політику сповіщень `silent`. Вони все одно створюють записи завдань, але завершення повертається до початкового сеансу агента як внутрішнє пробудження, щоб агент міг сам написати подальше повідомлення та прикріпити готовий медіафайл. Якщо ви вмикаєте `tools.media.asyncCompletion.directSend`, асинхронні завершення `video_generate` можуть спершу спробувати пряму доставку в канал; асинхронні завершення `music_generate` залишаються на шляху пробудження сеансу запитувача. + Запуски `music_generate` і `video_generate` на основі сеансу також використовують політику сповіщень `silent`. Вони все одно створюють записи завдань, але завершення повертається до початкового сеансу агента як внутрішнє пробудження, щоб агент міг написати подальше повідомлення й сам прикріпити готове медіа. Завершення в групах/каналах дотримуються звичайної політики видимої відповіді, тому агент використовує інструмент повідомлень, коли цього вимагає вихідна доставка. - - Поки завдання `video_generate` із підтримкою сеансу ще активне, інструмент також працює як запобіжник: повторні виклики `video_generate` у тому самому сеансі повертають статус активного завдання замість запуску другої паралельної генерації. Використовуйте `action: "status"`, коли потрібен явний перегляд прогресу/статусу з боку агента. + + Поки завдання `video_generate` на основі сеансу все ще активне, інструмент також працює як обмежувач: повторні виклики `video_generate` у тому самому сеансі повертають статус активного завдання замість запуску другого паралельного генерування. Використовуйте `action: "status"`, коли потрібен явний запит прогресу/статусу з боку агента. - - - Heartbeat-ходи — основний сеанс; див. [Heartbeat](/uk/gateway/heartbeat) + + - Ходи Heartbeat — основний сеанс; див. [Heartbeat](/uk/gateway/heartbeat) - Звичайні інтерактивні ходи чату - Прямі відповіді `/command` @@ -145,48 +145,48 @@ stateDiagram-v2 | `failed` | Завершено з помилкою | | `timed_out` | Перевищено налаштований час очікування | | `cancelled` | Зупинено оператором через `openclaw tasks cancel` | -| `lost` | Середовище виконання втратило авторитетний базовий стан після 5-хвилинного пільгового періоду | +| `lost` | Середовище виконання втратило авторитетний опорний стан після 5-хвилинного пільгового періоду | Переходи відбуваються автоматично — коли пов’язаний запуск агента завершується, статус завдання оновлюється відповідно. -Завершення запуску агента є авторитетним для активних записів завдань. Успішний відокремлений запуск фіналізується як `succeeded`, звичайні помилки запуску — як `failed`, а результати тайм-ауту або переривання — як `timed_out`. Якщо оператор уже скасував завдання або середовище виконання вже записало сильніший термінальний стан, наприклад `failed`, `timed_out` чи `lost`, пізніший сигнал успіху не понижує цей термінальний статус. +Завершення запуску агента є авторитетним для активних записів завдань. Успішний від’єднаний запуск фіналізується як `succeeded`, звичайні помилки запуску фіналізуються як `failed`, а результати тайм-ауту чи переривання фіналізуються як `timed_out`. Якщо оператор уже скасував завдання або середовище виконання вже записало сильніший термінальний стан, як-от `failed`, `timed_out` чи `lost`, пізніший сигнал успіху не понижує цей термінальний статус. `lost` враховує середовище виконання: -- ACP-завдання: зникли метадані базового дочірнього сеансу ACP. -- Завдання підagentів: базовий дочірній сеанс зник із цільового сховища агента. -- Cron-завдання: cron-середовище виконання більше не відстежує завдання як активне, а довговічна +- Завдання ACP: метадані опорного дочірнього сеансу ACP зникли. +- Завдання субагентів: опорний дочірній сеанс зник зі сховища цільового агента. +- Cron-завдання: cron-середовище виконання більше не відстежує завдання як активне, а збережена історія запусків cron не показує термінального результату для цього запуску. Офлайн-аудит CLI не вважає власний порожній внутрішньопроцесний стан cron-середовища виконання авторитетним. -- CLI-завдання: ізольовані завдання дочірнього сеансу використовують дочірній сеанс; CLI-завдання - з підтримкою чату натомість використовують живий контекст запуску, тож завислі - рядки сеансів каналу/групи/приватного чату не підтримують їх активними. Запуски - `openclaw agent` із підтримкою Gateway також фіналізуються за результатом свого запуску, тому завершені запуски - не залишаються активними, доки прибиральник позначить їх як `lost`. +- Завдання CLI: ізольовані завдання дочірніх сеансів використовують дочірній сеанс; CLI-завдання на основі чату + натомість використовують живий контекст запуску, тому залишкові + рядки сеансів каналу/групи/прямих повідомлень не підтримують їх активними. Запуски `openclaw agent` + на основі Gateway також фіналізуються за результатом свого запуску, тому завершені запуски + не залишаються активними, доки прибиральник не позначить їх як `lost`. ## Доставка та сповіщення Коли завдання досягає термінального стану, OpenClaw сповіщає вас. Є два шляхи доставки: -**Пряма доставка** — якщо завдання має цільовий канал (`requesterOrigin`), повідомлення про завершення надсилається прямо в цей канал (Telegram, Discord, Slack тощо). Для завершень підagentів OpenClaw також зберігає прив’язану маршрутизацію гілки/теми, коли вона доступна, і може заповнити відсутні `to` / обліковий запис із збереженого маршруту сеансу запитувача (`lastChannel` / `lastTo` / `lastAccountId`), перш ніж відмовитися від прямої доставки. +**Пряма доставка** — якщо завдання має цільовий канал (`requesterOrigin`), повідомлення про завершення надходить прямо в цей канал (Telegram, Discord, Slack тощо). Для завершень субагентів OpenClaw також зберігає прив’язану маршрутизацію гілки/теми, коли вона доступна, і може заповнити відсутній `to` / обліковий запис зі збереженого маршруту сеансу запитувача (`lastChannel` / `lastTo` / `lastAccountId`), перш ніж відмовитися від прямої доставки. **Доставка через чергу сеансу** — якщо пряма доставка не вдається або origin не задано, оновлення ставиться в чергу як системна подія в сеансі запитувача й з’являється під час наступного Heartbeat. -Завершення завдання запускає негайне пробудження Heartbeat, щоб ви швидко побачили результат — вам не потрібно чекати наступного запланованого Heartbeat-тику. +Завершення завдання запускає негайне пробудження Heartbeat, тож ви швидко бачите результат — не потрібно чекати наступного запланованого такту Heartbeat. -Це означає, що звичайний робочий процес базується на push-механізмі: один раз запустіть відокремлену роботу, а потім дозвольте середовищу виконання пробудити або сповістити вас після завершення. Опитуйте стан завдання лише тоді, коли потрібні налагодження, втручання або явний аудит. +Це означає, що звичний робочий процес базується на push-механізмі: запустіть від’єднану роботу один раз, а потім дозвольте середовищу виконання розбудити вас або сповістити про завершення. Опитуйте стан завдання лише тоді, коли потрібне налагодження, втручання або явний аудит. ### Політики сповіщень -Керуйте тим, скільки повідомлень отримувати про кожне завдання: +Керуйте тим, скільки повідомлень отримуєте щодо кожного завдання: -| Політика | Що доставляється | -| -------------------- | ---------------------------------------------------------------------- | -| `done_only` (типова) | Лише термінальний стан (succeeded, failed тощо) — **це типове значення** | -| `state_changes` | Кожен перехід стану та оновлення прогресу | -| `silent` | Нічого | +| Політика | Що доставляється | +| --------------------- | ----------------------------------------------------------------------- | +| `done_only` (типово) | Лише термінальний стан (succeeded, failed тощо) — **це типове значення** | +| `state_changes` | Кожен перехід стану й оновлення прогресу | +| `silent` | Узагалі нічого | Змініть політику, поки завдання виконується: @@ -202,7 +202,7 @@ openclaw tasks notify state_changes openclaw tasks list [--runtime ] [--status ] [--json] ``` - Стовпці виводу: ID завдання, тип, статус, доставка, ID запуску, дочірній сеанс, підсумок. + Стовпці виводу: ID завдання, вид, статус, доставка, ID запуску, дочірній сеанс, підсумок. @@ -210,7 +210,7 @@ openclaw tasks notify state_changes openclaw tasks show ``` - Токен пошуку приймає ID завдання, ID запуску або ключ сеансу. Показує повний запис, зокрема таймінг, стан доставки, помилку та термінальний підсумок. + Токен пошуку приймає ID завдання, ID запуску або ключ сеансу. Показує повний запис, включно з часом, станом доставки, помилкою та термінальним підсумком. @@ -218,7 +218,7 @@ openclaw tasks notify state_changes openclaw tasks cancel ``` - Для ACP-завдань і завдань підagentів це завершує дочірній сеанс. Для завдань, відстежуваних CLI, скасування записується в реєстрі завдань (окремого дескриптора дочірнього середовища виконання немає). Статус переходить у `cancelled`, а сповіщення про доставку надсилається, коли це застосовно. + Для завдань ACP і субагентів це завершує дочірній сеанс. Для завдань, відстежуваних CLI, скасування записується в реєстрі завдань (окремого дочірнього дескриптора середовища виконання немає). Статус переходить у `cancelled`, і за потреби надсилається сповіщення доставки. @@ -233,14 +233,14 @@ openclaw tasks notify state_changes Виявляє операційні проблеми. Знахідки також з’являються в `openclaw status`, коли виявлено проблеми. - | Виявлення | Серйозність | Тригер | - | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------ | - | `stale_queued` | warn | У черзі понад 10 хвилин | - | `stale_running` | error | Виконується понад 30 хвилин | - | `lost` | warn/error | Власність завдання, підтримувана runtime, зникла; збережені втрачені завдання попереджають до `cleanupAfter`, потім стають помилками | - | `delivery_failed` | warn | Доставлення не вдалося, а політика сповіщення не є `silent` | - | `missing_cleanup` | warn | Термінальне завдання без часової позначки очищення | - | `inconsistent_timestamps` | warn | Порушення часової шкали (наприклад, завершено до початку) | + | Виявлення | Серйозність | Умова спрацювання | + | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------- | + | `stale_queued` | warn | У черзі понад 10 хвилин | + | `stale_running` | error | Виконується понад 30 хвилин | + | `lost` | warn/error | Володіння завданням, підкріпленим середовищем виконання, зникло; збережені втрачені завдання попереджають до `cleanupAfter`, а потім стають помилками | + | `delivery_failed` | warn | Доставка не вдалася, і політика сповіщень не є `silent` | + | `missing_cleanup` | warn | Завершальне завдання без часової мітки очищення | + | `inconsistent_timestamps` | warn | Порушення часової шкали (наприклад, завершилося до початку) | @@ -249,43 +249,43 @@ openclaw tasks notify state_changes openclaw tasks maintenance --apply [--json] ``` - Використовуйте це, щоб попередньо переглянути або застосувати узгодження, проставлення міток очищення та обрізання для завдань і стану Task Flow. + Використовуйте це для попереднього перегляду або застосування узгодження, проставлення міток очищення та обрізання для завдань і стану потоку завдань. - Узгодження враховує runtime: + Узгодження враховує середовище виконання: - - Завдання ACP/subagent перевіряють свій базовий дочірній сеанс. - - Завдання subagent, дочірній сеанс яких має tombstone відновлення після перезапуску, позначаються як втрачені, а не обробляються як відновлювані базові сеанси. - - Завдання Cron перевіряють, чи runtime cron досі володіє job, потім відновлюють термінальний статус зі збережених журналів запусків cron/стану job, перш ніж fallback до `lost`. Лише процес Gateway є авторитетним для in-memory набору активних job cron; офлайн-аудит CLI використовує довготривалу історію, але не позначає завдання cron як втрачене лише через те, що цей локальний Set порожній. - - Завдання CLI на основі чату перевіряють власний live run контекст, а не лише рядок сеансу чату. + - Завдання ACP/subagent перевіряють свій резервний дочірній сеанс. + - Завдання subagent, дочірній сеанс яких має tombstone відновлення після перезапуску, позначаються як втрачені замість того, щоб розглядатися як придатні до відновлення резервні сеанси. + - Завдання Cron перевіряють, чи cron-середовище виконання все ще володіє job, а потім відновлюють завершальний статус зі збережених журналів cron-запусків/стану job, перш ніж повертатися до `lost`. Лише процес Gateway є авторитетним для набору активних cron-job у пам'яті; офлайн-аудит CLI використовує довговічну історію, але не позначає cron-завдання втраченим лише тому, що цей локальний Set порожній. + - Завдання CLI, підкріплені чатом, перевіряють власний live run context, а не лише рядок chat session. - Очищення після завершення також враховує runtime: + Очищення після завершення також враховує середовище виконання: - - Завершення subagent best-effort закриває відстежувані вкладки браузера/процеси для дочірнього сеансу, перш ніж триває очищення оголошення. - - Завершення ізольованого cron best-effort закриває відстежувані вкладки браузера/процеси для сеансу cron, перш ніж запуск повністю завершується. - - Доставлення ізольованого cron за потреби очікує подальші дії нащадкового subagent і пригнічує застарілий текст підтвердження батьківського процесу замість його оголошення. - - Доставлення завершення subagent віддає перевагу найновішому видимому тексту assistant; якщо він порожній, воно fallback до sanitized найновішого тексту tool/toolResult, а запуски викликів інструментів лише з timeout можуть згортатися до короткого підсумку часткового прогресу. Термінальні невдалі запуски оголошують статус помилки без повторного відтворення захопленого тексту відповіді. + - Завершення subagent за можливості закриває відстежувані вкладки браузера/процеси для дочірнього сеансу, перш ніж триває очищення після оголошення. + - Завершення ізольованого cron за можливості закриває відстежувані вкладки браузера/процеси для cron-сеансу, перш ніж запуск повністю розбирається. + - Доставка ізольованого cron за потреби очікує подальшої роботи descendant subagent і пригнічує застарілий текст підтвердження батьківського завдання замість його оголошення. + - Доставка завершення subagent надає перевагу найсвіжішому видимому тексту assistant; якщо він порожній, вона повертається до очищеного найсвіжішого тексту tool/toolResult, а запуски з викликами інструментів лише через тайм-аут можуть зводитися до короткого підсумку часткового прогресу. Завершальні невдалі запуски оголошують статус помилки без повторного відтворення захопленого тексту відповіді. - Помилки очищення не маскують реальний результат завдання. - + ```bash openclaw tasks flow list [--status ] [--json] openclaw tasks flow show [--json] openclaw tasks flow cancel ``` - Використовуйте ці команди, коли вас цікавить оркеструвальний Task Flow, а не один окремий запис фонового завдання. + Використовуйте це, коли вас цікавить оркеструвальний потік завдань, а не один окремий запис фонового завдання. -## Дошка завдань чату (`/tasks`) +## Дошка чат-завдань (`/tasks`) -Використовуйте `/tasks` у будь-якому сеансі чату, щоб побачити фонові завдання, пов’язані з цим сеансом. Дошка показує активні та нещодавно завершені завдання з runtime, статусом, часом, а також прогресом або деталями помилки. +Використовуйте `/tasks` у будь-якому chat session, щоб переглянути фонові завдання, пов'язані з цим сеансом. Дошка показує активні та нещодавно завершені завдання із середовищем виконання, статусом, часом, а також деталями прогресу або помилки. -Коли поточний сеанс не має видимих пов’язаних завдань, `/tasks` fallback до локальних для агента лічильників завдань, тож ви все одно отримуєте огляд без витоку деталей інших сеансів. +Коли поточний сеанс не має видимих пов'язаних завдань, `/tasks` повертається до локальних для агента лічильників завдань, щоб ви все одно отримали огляд без розкриття деталей інших сеансів. -Для повного операторського журналу використовуйте CLI: `openclaw tasks list`. +Для повного операторського реєстру використовуйте CLI: `openclaw tasks list`. ## Інтеграція статусу (навантаження завдань) @@ -299,9 +299,9 @@ Tasks: 3 queued · 2 running · 1 issues - **active** — кількість `queued` + `running` - **failures** — кількість `failed` + `timed_out` + `lost` -- **byRuntime** — розподіл за `acp`, `subagent`, `cron`, `cli` +- **byRuntime** — розбивка за `acp`, `subagent`, `cron`, `cli` -І `/status`, і інструмент `session_status` використовують task snapshot з урахуванням очищення: активні завдання мають пріоритет, застарілі завершені рядки приховуються, а нещодавні помилки показуються лише тоді, коли не залишилося активної роботи. Це зберігає картку статусу зосередженою на тому, що важливо зараз. +І `/status`, і інструмент `session_status` використовують знімок завдань з урахуванням очищення: активні завдання мають пріоритет, застарілі завершені рядки приховано, а нещодавні помилки показуються лише тоді, коли не лишається активної роботи. Це утримує картку статусу сфокусованою на тому, що важливо саме зараз. ## Зберігання та обслуговування @@ -313,9 +313,8 @@ Tasks: 3 queued · 2 running · 1 issues $OPENCLAW_STATE_DIR/tasks/runs.sqlite ``` -Registry завантажується в пам’ять під час запуску gateway і синхронізує записи в SQLite для довговічності між перезапусками. -Gateway тримає write-ahead log SQLite обмеженим, використовуючи стандартний поріг -autocheckpoint SQLite, а також періодичні та shutdown `TRUNCATE` checkpoints. +Реєстр завантажується в пам'ять під час запуску Gateway і синхронізує записи в SQLite для довговічності між перезапусками. +Gateway утримує журнал попереднього запису SQLite в обмежених межах, використовуючи стандартний поріг autocheckpoint SQLite, а також періодичні та завершальні контрольні точки `TRUNCATE`. ### Автоматичне обслуговування @@ -323,13 +322,13 @@ Sweeper запускається кожні **60 секунд** і викону - Перевіряє, чи активні завдання досі мають авторитетну runtime-підтримку. Завдання ACP/subagent використовують стан дочірнього сеансу, завдання cron використовують володіння active-job, а завдання CLI на основі чату використовують власний run context. Якщо цей базовий стан відсутній понад 5 хвилин, завдання позначається як `lost`. + Перевіряє, чи активні завдання все ще мають авторитетне резервне середовище виконання. Завдання ACP/subagent використовують стан дочірнього сеансу, завдання cron використовують володіння active-job, а завдання CLI, підкріплені чатом, використовують власний run context. Якщо цей резервний стан зник більш ніж на 5 хвилин, завдання позначається як `lost`. - - Закриває термінальні або осиротілі parent-owned одноразові сеанси ACP, а також закриває застарілі термінальні або осиротілі persistent сеанси ACP лише тоді, коли не залишається активної прив’язки розмови. + + Закриває завершальні або осиротілі одноразові ACP-сеанси, якими володіє батьківський елемент, і закриває застарілі завершальні або осиротілі постійні ACP-сеанси лише тоді, коли не лишається активного прив'язування розмови. - Установлює часову позначку `cleanupAfter` для термінальних завдань (endedAt + 7 днів). Під час retention втрачені завдання все ще з’являються в аудиті як попередження; після завершення строку `cleanupAfter` або коли метадані очищення відсутні, вони є помилками. + Установлює часову мітку `cleanupAfter` для завершальних завдань (endedAt + 7 днів). Протягом періоду зберігання втрачені завдання все ще відображаються в аудиті як попередження; після завершення строку `cleanupAfter` або коли метадані очищення відсутні, вони стають помилками. Видаляє записи після їхньої дати `cleanupAfter`. @@ -337,42 +336,42 @@ Sweeper запускається кожні **60 секунд** і викону -**Retention:** записи термінальних завдань зберігаються **7 днів**, потім автоматично обрізаються. Налаштування не потрібне. +**Зберігання:** записи завершальних завдань зберігаються **7 днів**, а потім автоматично обрізаються. Налаштування не потрібне. -## Як завдання пов’язані з іншими системами +## Як завдання пов'язані з іншими системами - - [Task Flow](/uk/automation/taskflow) — це шар оркестрації потоків над фоновими завданнями. Один flow може координувати кілька завдань протягом свого життєвого циклу, використовуючи керовані або mirrored режими sync. Використовуйте `openclaw tasks`, щоб перевіряти окремі записи завдань, і `openclaw tasks flow`, щоб перевіряти оркеструвальний flow. + + [Потік завдань](/uk/automation/taskflow) — це шар оркестрації потоків над фоновими завданнями. Один потік може координувати кілька завдань протягом свого життєвого циклу, використовуючи керовані або віддзеркалені режими синхронізації. Використовуйте `openclaw tasks`, щоб переглядати окремі записи завдань, і `openclaw tasks flow`, щоб переглядати оркеструвальний потік. - Див. [Task Flow](/uk/automation/taskflow) для деталей. + Докладніше див. [Потік завдань](/uk/automation/taskflow). - - **Визначення** cron job зберігається в `~/.openclaw/cron/jobs.json`; runtime-стан виконання зберігається поруч у `~/.openclaw/cron/jobs-state.json`. **Кожне** виконання cron створює запис завдання — і main-session, і isolated. Завдання cron main-session типово мають політику сповіщення `silent`, щоб їх можна було відстежувати без створення сповіщень. + + **Визначення** cron job зберігається в `~/.openclaw/cron/jobs.json`; стан виконання середовища зберігається поруч у `~/.openclaw/cron/jobs-state.json`. **Кожне** виконання cron створює запис завдання — як main-session, так і isolated. Cron-завдання main-session за замовчуванням мають політику сповіщень `silent`, тож вони відстежуються без створення сповіщень. Див. [Cron Jobs](/uk/automation/cron-jobs). - - Запуски Heartbeat — це ходи main-session, вони не створюють записів завдань. Коли завдання завершується, воно може ініціювати heartbeat wake, щоб ви швидко побачили результат. + + Запуски Heartbeat є ходами main-session — вони не створюють записів завдань. Коли завдання завершується, воно може ініціювати пробудження Heartbeat, щоб ви швидко побачили результат. Див. [Heartbeat](/uk/gateway/heartbeat). - + Завдання може посилатися на `childSessionKey` (де виконується робота) і `requesterSessionKey` (хто його запустив). Сеанси — це контекст розмови; завдання — це відстеження активності поверх нього. - - `runId` завдання пов’язує його із запуском агента, який виконує роботу. Події життєвого циклу агента (початок, завершення, помилка) автоматично оновлюють статус завдання — вам не потрібно керувати життєвим циклом вручну. + + `runId` завдання пов'язує його із запуском агента, який виконує роботу. Події життєвого циклу агента (початок, завершення, помилка) автоматично оновлюють статус завдання — вам не потрібно керувати життєвим циклом вручну. -## Пов’язане +## Пов'язане -- [Автоматизація і завдання](/uk/automation) — усі механізми автоматизації з першого погляду +- [Автоматизація та завдання](/uk/automation) — усі механізми автоматизації з першого погляду - [CLI: Завдання](/uk/cli/tasks) — довідник команд CLI - [Heartbeat](/uk/gateway/heartbeat) — періодичні ходи main-session - [Заплановані завдання](/uk/automation/cron-jobs) — планування фонової роботи -- [Task Flow](/uk/automation/taskflow) — оркестрація flow над завданнями +- [Потік завдань](/uk/automation/taskflow) — оркестрація потоків над завданнями diff --git a/docs/uk/cli/gateway.md b/docs/uk/cli/gateway.md index 171586fb7..697b0a71a 100644 --- a/docs/uk/cli/gateway.md +++ b/docs/uk/cli/gateway.md @@ -1,35 +1,35 @@ --- read_when: - - Запуск Gateway з CLI (розробка або сервери) - - Налагодження автентифікації Gateway, режимів прив’язування та підключення + - Запуск Gateway із CLI (для розробки або серверів) + - Налагодження автентифікації Gateway, режимів прив’язки та підключення - Виявлення Gateway через Bonjour (локальний + широкозонний DNS-SD) sidebarTitle: Gateway summary: OpenClaw Gateway CLI (`openclaw gateway`) — запускайте, опитуйте та виявляйте екземпляри Gateway title: Gateway x-i18n: - generated_at: "2026-05-04T18:03:56Z" + generated_at: "2026-05-05T00:49:35Z" model: gpt-5.5 provider: openai - source_hash: 310867c59148577f2e8ce6f708da6bce936e09243ce7fbe5daeb453c6b3b370d + source_hash: 521558189b150b2faa22f95ec32419ac9e02c5f47c72b9095f40d1432840c038 source_path: cli/gateway.md workflow: 16 --- -Gateway — це WebSocket-сервер OpenClaw (канали, вузли, сеанси, хуки). Підкоманди на цій сторінці розміщені в `openclaw gateway …`. +Gateway — це WebSocket-сервер OpenClaw (канали, вузли, сесії, хуки). Підкоманди на цій сторінці знаходяться в `openclaw gateway …`. - - Налаштування локального mDNS + wide-area DNS-SD. + + Налаштування локального mDNS + широкозонного DNS-SD. - + Як OpenClaw оголошує та знаходить Gateway. - - Ключі конфігурації Gateway верхнього рівня. + + Ключі конфігурації gateway верхнього рівня. -## Запуск Gateway +## Запустіть Gateway Запустіть локальний процес Gateway: @@ -44,13 +44,13 @@ openclaw gateway run ``` - - - За замовчуванням Gateway відмовляється запускатися, якщо в `~/.openclaw/openclaw.json` не задано `gateway.mode=local`. Використовуйте `--allow-unconfigured` для ситуативних/dev запусків. - - Очікується, що `openclaw onboard --mode local` і `openclaw setup` записують `gateway.mode=local`. Якщо файл існує, але `gateway.mode` відсутній, вважайте це пошкодженою або перезаписаною конфігурацією та виправте її, а не припускайте локальний режим неявно. + + - За замовчуванням Gateway відмовляється запускатися, якщо `gateway.mode=local` не задано в `~/.openclaw/openclaw.json`. Використовуйте `--allow-unconfigured` для разових/розробницьких запусків. + - Очікується, що `openclaw onboard --mode local` і `openclaw setup` запишуть `gateway.mode=local`. Якщо файл існує, але `gateway.mode` відсутній, розглядайте це як пошкоджену або перезаписану конфігурацію та відновіть її, замість неявно припускати локальний режим. - Якщо файл існує, а `gateway.mode` відсутній, Gateway вважає це підозрілим пошкодженням конфігурації та відмовляється "вгадувати local" за вас. - - Прив'язування за межами loopback без автентифікації заблоковано (захисне обмеження). - - `SIGUSR1` запускає перезапуск у межах процесу, коли це дозволено (`commands.restart` увімкнено за замовчуванням; установіть `commands.restart: false`, щоб заблокувати ручний перезапуск, тоді як застосування/оновлення через інструменти/конфігурацію Gateway залишаються дозволеними). - - Обробники `SIGINT`/`SIGTERM` зупиняють процес Gateway, але вони не відновлюють жодний власний стан термінала. Якщо ви обгортаєте CLI за допомогою TUI або введення в raw-mode, відновіть термінал перед виходом. + - Прив’язування поза межами loopback без автентифікації заблоковано (захисне обмеження). + - `SIGUSR1` запускає перезапуск усередині процесу, коли це авторизовано (`commands.restart` увімкнено за замовчуванням; задайте `commands.restart: false`, щоб заблокувати ручний перезапуск, водночас застосування/оновлення через інструмент і конфігурацію gateway лишаються дозволеними). + - Обробники `SIGINT`/`SIGTERM` зупиняють процес gateway, але не відновлюють жодний спеціальний стан термінала. Якщо ви обгортаєте CLI за допомогою TUI або введення в raw-mode, відновіть термінал перед виходом. @@ -61,7 +61,7 @@ openclaw gateway run Порт WebSocket (значення за замовчуванням береться з конфігурації/env; зазвичай `18789`). - Режим прив'язування слухача. + Режим прив’язування слухача. Перевизначення режиму автентифікації. @@ -73,46 +73,46 @@ openclaw gateway run Перевизначення пароля. - Зчитати пароль Gateway з файлу. + Зчитати пароль gateway з файла. - Відкрити доступ до Gateway через Tailscale. + Надати доступ до Gateway через Tailscale. - Скинути конфігурацію Tailscale serve/funnel під час завершення роботи. + Скинути конфігурацію Tailscale serve/funnel під час завершення. - Дозволити запуск Gateway без `gateway.mode=local` у конфігурації. Обходить захисну перевірку запуску лише для ситуативного/dev bootstrap; не записує й не виправляє файл конфігурації. + Дозволити запуск gateway без `gateway.mode=local` у конфігурації. Обходить захист запуску лише для разового/розробницького bootstrap; не записує й не відновлює файл конфігурації. - Створити dev-конфігурацію + робочу область, якщо їх немає (пропускає BOOTSTRAP.md). + Створити dev-конфігурацію + робочий простір, якщо їх немає (пропускає BOOTSTRAP.md). - Скинути dev-конфігурацію + облікові дані + сеанси + робочу область (потребує `--dev`). + Скинути dev-конфігурацію + облікові дані + сесії + робочий простір (потребує `--dev`). Завершити будь-який наявний слухач на вибраному порту перед запуском. - Докладні журнали. + Докладні логи. - Показувати в консолі лише журнали бекенда CLI (і ввімкнути stdout/stderr). + Показувати в консолі лише логи backend CLI (і ввімкнути stdout/stderr). - Стиль журналу WebSocket. + Стиль логів Websocket. Псевдонім для `--ws-log compact`. - Записувати необроблені події потоку моделі в jsonl. + Логувати сирі події потоку моделі в jsonl. - Шлях до jsonl необробленого потоку. + Шлях jsonl для сирого потоку. -## Перезапуск Gateway +## Перезапустіть Gateway ```bash openclaw gateway restart @@ -120,41 +120,41 @@ openclaw gateway restart --safe openclaw gateway restart --force ``` -`openclaw gateway restart --safe` просить запущений Gateway попередньо перевірити активну роботу OpenClaw перед перезапуском. Якщо активні операції в черзі, доставлення відповідей, вбудовані запуски або виконання завдань, Gateway повідомляє про блокувальники, об'єднує дублікати запитів безпечного перезапуску та перезапускається, коли активна робота завершується. Звичайний `restart` зберігає наявну поведінку менеджера служби для сумісності. Використовуйте `--force` лише тоді, коли явно потрібен шлях негайного перевизначення. +`openclaw gateway restart --safe` просить запущений Gateway попередньо перевірити активну роботу OpenClaw перед перезапуском. Якщо активні операції в черзі, доставлення відповідей, вбудовані запуски або запуски завдань, Gateway повідомляє про блокувальники, об’єднує дублікати безпечних запитів на перезапуск і перезапускається після завершення активної роботи. Звичайний `restart` зберігає наявну поведінку service-manager для сумісності. Використовуйте `--force` лише тоді, коли явно потрібен шлях негайного перевизначення. -Вбудований `--password` може бути видимим у локальних списках процесів. Надавайте перевагу `--password-file`, env або `gateway.auth.password` на основі SecretRef. +Вбудований `--password` може бути видимим у локальних списках процесів. Надавайте перевагу `--password-file`, env або `gateway.auth.password`, підкріпленому SecretRef. ### Профілювання запуску -- Задайте `OPENCLAW_GATEWAY_STARTUP_TRACE=1`, щоб журналювати тривалість фаз під час запуску Gateway, включно із затримкою `eventLoopMax` для кожної фази та таймінгами lookup-таблиць Plugin для installed-index, manifest registry, планування запуску й роботи owner-map. -- Задайте `OPENCLAW_DIAGNOSTICS=timeline` з `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=`, щоб записати best-effort JSONL timeline діагностики запуску для зовнішніх QA harnesses. Також можна ввімкнути прапорець через `diagnostics.flags: ["timeline"]` у конфігурації; шлях усе одно надається через env. Додайте `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1`, щоб включити вибірки event-loop. -- Запустіть `pnpm test:startup:gateway -- --runs 5 --warmup 1`, щоб виконати бенчмарк запуску Gateway. Бенчмарк записує перший вивід процесу, `/healthz`, `/readyz`, таймінги трасування запуску, затримку event-loop і деталі таймінгів lookup-таблиць Plugin. +- Задайте `OPENCLAW_GATEWAY_STARTUP_TRACE=1`, щоб логувати таймінги фаз під час запуску Gateway, включно із затримкою `eventLoopMax` для кожної фази та таймінгами lookup-table плагінів для installed-index, manifest registry, startup planning і owner-map. +- Задайте `OPENCLAW_DIAGNOSTICS=timeline` з `OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=`, щоб записати best-effort JSONL-хронологію діагностики запуску для зовнішніх QA harnesses. Також можна ввімкнути прапорець через `diagnostics.flags: ["timeline"]` у конфігурації; шлях усе одно задається через env. Додайте `OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1`, щоб включити зразки event-loop. +- Запустіть `pnpm test:startup:gateway -- --runs 5 --warmup 1`, щоб виконати benchmark запуску Gateway. Benchmark записує перший вивід процесу, `/healthz`, `/readyz`, таймінги startup trace, затримку event-loop і деталі таймінгів lookup-table плагінів. -## Запит до запущеного Gateway +## Опитайте запущений Gateway Усі команди запитів використовують WebSocket RPC. - - - За замовчуванням: зручно для читання людиною (кольорово в TTY). + + - За замовчуванням: зручно для читання людиною (кольорове в TTY). - `--json`: машинозчитуваний JSON (без стилізації/spinner). - `--no-color` (або `NO_COLOR=1`): вимкнути ANSI, зберігаючи людський макет. - + - `--url `: WebSocket URL Gateway. - `--token `: токен Gateway. - `--password `: пароль Gateway. - - `--timeout `: таймаут/бюджет (залежить від команди). - - `--expect-final`: чекати на "final" відповідь (виклики агента). + - `--timeout `: timeout/budget (залежить від команди). + - `--expect-final`: чекати на відповідь "final" (виклики агента). -Коли ви задаєте `--url`, CLI не повертається до облікових даних із конфігурації або середовища. Передайте `--token` або `--password` явно. Відсутність явних облікових даних є помилкою. +Коли ви задаєте `--url`, CLI не повертається до облікових даних із конфігурації чи середовища. Передайте `--token` або `--password` явно. Відсутність явних облікових даних є помилкою. ### `gateway health` @@ -163,11 +163,11 @@ openclaw gateway restart --force openclaw gateway health --url ws://127.0.0.1:18789 ``` -HTTP endpoint `/healthz` — це liveness probe: він повертає відповідь, щойно сервер може відповідати через HTTP. HTTP endpoint `/readyz` суворіший і лишається червоним, поки startup Plugin sidecars, канали або налаштовані хуки ще стабілізуються. Локальні або автентифіковані докладні відповіді готовності містять діагностичний блок `eventLoop` із затримкою event-loop, utilization event-loop, співвідношенням ядер CPU та прапорцем `degraded`. +HTTP endpoint `/healthz` є liveness probe: він повертає відповідь, щойно сервер може відповідати через HTTP. HTTP endpoint `/readyz` суворіший і лишається червоним, доки sidecar-и плагінів запуску, канали або налаштовані хуки ще стабілізуються. Локальні або автентифіковані докладні відповіді readiness містять діагностичний блок `eventLoop` із затримкою event-loop, використанням event-loop, співвідношенням ядер CPU та прапорцем `degraded`. ### `gateway usage-cost` -Отримати зведення usage-cost із журналів сеансів. +Отримайте підсумки usage-cost із логів сесій. ```bash openclaw gateway usage-cost @@ -181,7 +181,7 @@ openclaw gateway usage-cost --json ### `gateway stability` -Отримати нещодавній реєстратор діагностичної стабільності із запущеного Gateway. +Отримайте нещодавній diagnostic stability recorder із запущеного Gateway. ```bash openclaw gateway stability @@ -192,7 +192,7 @@ openclaw gateway stability --json ``` - Максимальна кількість нещодавніх подій для включення (максимум `1000`). + Максимальна кількість нещодавніх подій для включення (макс. `1000`). Фільтрувати за типом діагностичної події, наприклад `payload.large` або `diagnostic.memory.pressure`. @@ -201,26 +201,26 @@ openclaw gateway stability --json Включати лише події після номера діагностичної послідовності. - Зчитати збережений bundle стабільності замість виклику запущеного Gateway. Використовуйте `--bundle latest` (або просто `--bundle`) для найновішого bundle у каталозі стану, або передайте шлях до JSON bundle напряму. + Читати збережений stability bundle замість виклику запущеного Gateway. Використовуйте `--bundle latest` (або просто `--bundle`) для найновішого bundle у каталозі стану або передайте шлях до JSON bundle напряму. - Записати zip діагностики підтримки, придатний для поширення, замість друку деталей стабільності. + Записати придатний для поширення zip із діагностикою підтримки замість друку деталей стабільності. Шлях виводу для `--export`. - - - Записи зберігають операційні метадані: назви подій, кількості, розміри в байтах, показники пам'яті, стан черг/сеансів, назви каналів/Plugin і відредаговані зведення сеансів. Вони не зберігають текст чату, тіла webhook, виводи інструментів, необроблені тіла запитів або відповідей, токени, cookies, секретні значення, імена хостів або необроблені ідентифікатори сеансів. Установіть `diagnostics.enabled: false`, щоб повністю вимкнути реєстратор. - - Під час фатальних завершень Gateway, таймаутів завершення роботи та збоїв startup restart OpenClaw записує той самий діагностичний snapshot у `~/.openclaw/logs/stability/openclaw-stability-*.json`, коли реєстратор має події. Перегляньте найновіший bundle за допомогою `openclaw gateway stability --bundle latest`; `--limit`, `--type` і `--since-seq` також застосовуються до виводу bundle. + + - Записи зберігають операційні метадані: назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сесії, назви каналів/плагінів і редаговані підсумки сесій. Вони не зберігають текст чату, тіла webhook, виводи інструментів, сирі тіла запитів або відповідей, токени, cookies, секретні значення, hostnames або сирі ідентифікатори сесій. Задайте `diagnostics.enabled: false`, щоб повністю вимкнути recorder. + - Під час фатальних завершень Gateway, timeout під час shutdown і збоїв startup restart OpenClaw записує той самий діагностичний snapshot у `~/.openclaw/logs/stability/openclaw-stability-*.json`, коли recorder має події. Перегляньте найновіший bundle за допомогою `openclaw gateway stability --bundle latest`; `--limit`, `--type` і `--since-seq` також застосовуються до виводу bundle. ### `gateway diagnostics export` -Записати локальний zip діагностики, призначений для додавання до звітів про помилки. Щоб дізнатися про модель приватності та вміст bundle, див. [Diagnostics Export](/uk/gateway/diagnostics). +Запишіть локальний zip із діагностикою, призначений для додавання до bug reports. Модель конфіденційності та вміст bundle див. у [Експорті діагностики](/uk/gateway/diagnostics). ```bash openclaw gateway diagnostics export @@ -229,40 +229,40 @@ openclaw gateway diagnostics export --json ``` - Шлях до zip виводу. За замовчуванням це support export у каталозі стану. + Шлях zip-виводу. За замовчуванням це експорт підтримки в каталозі стану. - Максимальна кількість санітизованих рядків журналу для включення. + Максимальна кількість очищених рядків логів для включення. - Максимальна кількість байтів журналу для перевірки. + Максимальна кількість байтів логів для перевірки. - WebSocket URL Gateway для snapshot здоров'я. + WebSocket URL Gateway для snapshot health. - Токен Gateway для snapshot здоров'я. + Токен Gateway для snapshot health. - Пароль Gateway для snapshot здоров'я. + Пароль Gateway для snapshot health. - Таймаут snapshot статусу/здоров'я. + Timeout для snapshot status/health. - Пропустити пошук збереженого bundle стабільності. + Пропустити пошук збереженого stability bundle. - Надрукувати записаний шлях, розмір і маніфест як JSON. + Надрукувати записаний шлях, розмір і manifest як JSON. -Експорт містить маніфест, Markdown-зведення, форму конфігурації, санітизовані деталі конфігурації, санітизовані зведення журналів, санітизовані snapshots статусу/здоров'я Gateway і найновіший bundle стабільності, якщо він існує. +Експорт містить manifest, підсумок Markdown, форму конфігурації, очищені деталі конфігурації, очищені підсумки логів, очищені snapshot-и status/health Gateway і найновіший stability bundle, якщо він існує. -Його призначено для поширення. Він зберігає операційні деталі, які допомагають налагодженню, як-от безпечні поля журналів OpenClaw, назви підсистем, коди стану, тривалості, налаштовані режими, порти, ідентифікатори Plugin, ідентифікатори провайдерів, несекретні налаштування функцій і відредаговані операційні повідомлення журналів. Він пропускає або редагує текст чату, тіла webhook, виводи інструментів, облікові дані, cookies, ідентифікатори акаунтів/повідомлень, текст prompt/instruction, імена хостів і секретні значення. Коли повідомлення в стилі LogTape схоже на текст корисного навантаження користувача/чату/інструмента, експорт зберігає лише факт, що повідомлення було пропущено, разом із його кількістю байтів. +Він призначений для поширення. Він зберігає операційні деталі, що допомагають у налагодженні, як-от безпечні поля логів OpenClaw, назви підсистем, коди статусу, тривалості, налаштовані режими, порти, ідентифікатори плагінів, ідентифікатори providers, несекретні налаштування функцій і редаговані операційні повідомлення логів. Він пропускає або редагує текст чату, тіла webhook, виводи інструментів, облікові дані, cookies, ідентифікатори облікових записів/повідомлень, текст prompts/instructions, hostnames і секретні значення. Коли повідомлення в стилі LogTape схоже на текст payload користувача/чату/інструмента, експорт зберігає лише факт, що повідомлення було пропущено, плюс його кількість байтів. ### `gateway status` -`gateway status` показує службу Gateway (launchd/systemd/schtasks), а також необов'язкову перевірку можливостей підключення/автентифікації. +`gateway status` показує службу Gateway (launchd/systemd/schtasks) плюс необов’язкову перевірку можливості підключення/автентифікації. ```bash openclaw gateway status @@ -271,63 +271,63 @@ openclaw gateway status --require-rpc ``` - Додати явну ціль перевірки. Налаштовані віддалена ціль і localhost усе одно перевіряються. + Додайте явну ціль зондування. Налаштовані віддалений вузол і localhost все одно зондуються. - Автентифікація токеном для перевірки. + Автентифікація токеном для зондування. - Автентифікація паролем для перевірки. + Автентифікація паролем для зондування. - Тайм-аут перевірки. + Час очікування зондування. - Пропустити перевірку підключення (подання лише сервісу). + Пропустити зондування з’єднання (перегляд лише сервісу). - Також сканувати сервіси системного рівня. + Також сканувати служби системного рівня. - Підвищити стандартну перевірку підключення до перевірки читання та завершити роботу з ненульовим кодом, якщо ця перевірка читання не вдасться. Не можна поєднувати з `--no-probe`. + Підвищити стандартне зондування з’єднання до зондування читання й завершити з ненульовим кодом, якщо це зондування читання завершується невдало. Не можна поєднувати з `--no-probe`. - `gateway status` залишається доступною для діагностики, навіть коли локальна конфігурація CLI відсутня або недійсна. - - Стандартна `gateway status` підтверджує стан сервісу, підключення WebSocket і можливість автентифікації, видиму під час рукостискання. Вона не підтверджує операції читання/запису/адміністрування. - - Діагностичні перевірки не вносять змін для первинної автентифікації пристрою: вони повторно використовують наявний кешований токен пристрою, якщо він існує, але не створюють нову ідентичність пристрою CLI або запис сполучення пристрою лише для читання тільки для перевірки статусу. - - `gateway status` за можливості розв’язує налаштовані auth SecretRefs для автентифікації перевірки. - - Якщо обов’язковий auth SecretRef не розв’язано в цьому шляху команди, `gateway status --json` повідомляє `rpc.authWarning`, коли підключення/автентифікація перевірки не вдається; явно передайте `--token`/`--password` або спочатку розв’яжіть джерело секрету. - - Якщо перевірка успішна, попередження про нерозв’язані auth-ref пригнічуються, щоб уникнути хибних спрацювань. - - Використовуйте `--require-rpc` у скриптах і автоматизації, коли сервісу, що прослуховує, недостатньо і потрібна справність RPC-викликів із областю читання. - - `--deep` додає best-effort сканування додаткових встановлень launchd/systemd/schtasks. Коли виявлено кілька сервісів, схожих на Gateway, вивід для людини друкує підказки з очищення та попереджає, що більшість налаштувань мають запускати один gateway на машину. - - Вивід для людини містить розв’язаний шлях до файлового журналу, а також знімок шляхів/дійсності конфігурацій CLI та сервісу, щоб допомогти діагностувати зміщення профілю або state-dir. + - Стандартна `gateway status` підтверджує стан сервісу, WebSocket-з’єднання та можливість автентифікації, видиму під час handshake. Вона не підтверджує операції читання/запису/адміністрування. + - Діагностичні зондування не змінюють стан для першої автентифікації пристрою: вони повторно використовують наявний кешований токен пристрою, якщо він існує, але не створюють нову ідентичність пристрою CLI або запис read-only сполучення пристрою лише для перевірки статусу. + - `gateway status` за можливості розв’язує налаштовані SecretRefs автентифікації для автентифікації зондування. + - Якщо потрібний SecretRef автентифікації не розв’язано в цьому шляху команди, `gateway status --json` повідомляє `rpc.authWarning`, коли з’єднання/автентифікація зондування завершується невдало; передайте `--token`/`--password` явно або спершу розв’яжіть джерело секрету. + - Якщо зондування успішне, попередження про нерозв’язані auth-ref приглушуються, щоб уникнути хибних спрацьовувань. + - Використовуйте `--require-rpc` у скриптах і автоматизації, коли сервісу, що прослуховує порт, недостатньо й потрібно, щоб RPC-виклики з областю читання також були працездатними. + - `--deep` додає best-effort сканування додаткових інсталяцій launchd/systemd/schtasks. Коли виявлено кілька gateway-подібних сервісів, текстовий вивід друкує підказки з очищення та попереджає, що більшість налаштувань мають запускати один gateway на машину. + - Текстовий вивід містить розв’язаний шлях до файлового журналу, а також знімок шляхів/чинності конфігурації CLI і сервісу, щоб допомогти діагностувати розбіжність профілю або state-dir. - - - У встановленнях Linux systemd перевірки розходження автентифікації сервісу читають значення `Environment=` і `EnvironmentFile=` з unit (включно з `%h`, шляхами в лапках, кількома файлами й необов’язковими файлами з `-`). - - Перевірки розходження розв’язують SecretRefs `gateway.auth.token` за допомогою об’єднаного runtime env (спочатку env команди сервісу, потім fallback до env процесу). - - Якщо автентифікація токеном фактично не активна (явний `gateway.auth.mode` зі значенням `password`/`none`/`trusted-proxy` або mode не задано, коли password може перемогти й жоден кандидат токена не може перемогти), перевірки розходження токена пропускають розв’язання токена конфігурації. + + - В інсталяціях Linux systemd перевірки auth drift сервісу читають як значення `Environment=`, так і `EnvironmentFile=` з unit (включно з `%h`, шляхами в лапках, кількома файлами та необов’язковими файлами `-`). + - Перевірки drift розв’язують SecretRefs `gateway.auth.token` за допомогою об’єднаного runtime env (спершу env команди сервісу, потім fallback до process env). + - Якщо автентифікація токеном фактично не активна (явний `gateway.auth.mode` зі значенням `password`/`none`/`trusted-proxy` або mode не задано, де пароль може перемогти й жоден кандидат токена не може перемогти), перевірки token-drift пропускають розв’язання токена конфігурації. ### `gateway probe` -`gateway probe` — це команда «налагодити все». Вона завжди перевіряє: +`gateway probe` — це команда «налагодити все». Вона завжди зондує: - ваш налаштований віддалений gateway (якщо задано), і -- localhost (loopback) **навіть якщо налаштовано віддалений**. +- localhost (loopback) **навіть якщо віддалений вузол налаштовано**. -Якщо передати `--url`, ця явна ціль додається перед обома. Вивід для людини позначає цілі як: +Якщо передати `--url`, цю явну ціль буде додано перед обома. Текстовий вивід позначає цілі так: - `URL (explicit)` - `Remote (configured)` або `Remote (configured, inactive)` - `Local loopback` -Якщо доступні кілька gateways, вона друкує їх усі. Кілька gateways підтримуються, коли ви використовуєте ізольовані профілі/порти (наприклад, rescue bot), але більшість встановлень усе одно запускають один gateway. +Якщо доступні кілька gateway, команда виводить усі. Кілька gateway підтримуються, коли ви використовуєте ізольовані профілі/порти (наприклад, rescue bot), але більшість інсталяцій усе одно запускають один gateway. ```bash @@ -337,51 +337,51 @@ openclaw gateway probe --json - - `Reachable: yes` означає, що принаймні одна ціль прийняла підключення WebSocket. - - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` повідомляє, що перевірка змогла підтвердити щодо автентифікації. Це окремо від доступності. - - `Read probe: ok` означає, що RPC-виклики деталей з областю читання (`health`/`status`/`system-presence`/`config.get`) також успішні. - - `Read probe: limited - missing scope: operator.read` означає, що підключення успішне, але RPC з областю читання обмежений. Це повідомляється як **погіршена** доступність, а не повна помилка. - - `Read probe: failed` після `Connect: ok` означає, що Gateway прийняв WebSocket-з’єднання, але подальша діагностика читання перевищила час очікування або не вдалася. Це також **погіршена** доступність, а не недоступний Gateway. - - Як і `gateway status`, перевірка повторно використовує наявну кешовану автентифікацію пристрою, але не створює первинну ідентичність пристрою або стан сполучення. - - Код виходу ненульовий лише тоді, коли жодна перевірена ціль недоступна. + - `Reachable: yes` означає, що принаймні одна ціль прийняла WebSocket-з’єднання. + - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` повідомляє, що зондування змогло підтвердити щодо автентифікації. Це окремо від досяжності. + - `Read probe: ok` означає, що RPC-виклики деталізації з областю читання (`health`/`status`/`system-presence`/`config.get`) також виконалися успішно. + - `Read probe: limited - missing scope: operator.read` означає, що з’єднання успішне, але RPC з областю читання обмежений. Це повідомляється як **погіршена** досяжність, а не повний збій. + - `Read probe: failed` після `Connect: ok` означає, що Gateway прийняв WebSocket-з’єднання, але подальша діагностика читання перевищила час очікування або завершилася невдало. Це також **погіршена** досяжність, а не недосяжний Gateway. + - Як і `gateway status`, зондування повторно використовує наявну кешовану автентифікацію пристрою, але не створює першу ідентичність пристрою або стан сполучення. + - Код виходу ненульовий лише тоді, коли жодна зондувана ціль недосяжна. - + Верхній рівень: - - `ok`: принаймні одна ціль доступна. - - `degraded`: принаймні одна ціль прийняла підключення, але не завершила повну RPC-діагностику деталей. - - `capability`: найкраща можливість, побачена серед доступних цілей (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` або `unknown`). - - `primaryTargetId`: найкраща ціль, яку слід вважати активним переможцем у такому порядку: явний URL, SSH-тунель, налаштована віддалена ціль, потім local loopback. - - `warnings[]`: best-effort записи попереджень із `code`, `message` і необов’язковими `targetIds`. - - `network`: підказки URL local loopback/tailnet, отримані з поточної конфігурації та мережі хоста. - - `discovery.timeoutMs` і `discovery.count`: фактичний бюджет виявлення/кількість результатів, використані для цього проходу перевірки. + - `ok`: принаймні одна ціль досяжна. + - `degraded`: принаймні одна ціль прийняла з’єднання, але не завершила повну деталізовану RPC-діагностику. + - `capability`: найкраща можливість, побачена серед досяжних цілей (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope` або `unknown`). + - `primaryTargetId`: найкраща ціль, яку слід вважати активним переможцем, у такому порядку: явний URL, SSH tunnel, налаштований віддалений вузол, потім local loopback. + - `warnings[]`: best-effort записи попереджень із `code`, `message` та необов’язковими `targetIds`. + - `network`: підказки URL для local loopback/tailnet, отримані з поточної конфігурації та мережі хоста. + - `discovery.timeoutMs` і `discovery.count`: фактичний бюджет/кількість результатів discovery, використані для цього проходу зондування. Для кожної цілі (`targets[].connect`): - - `ok`: доступність після підключення + класифікація погіршення. - - `rpcOk`: повний успіх RPC деталей. - - `scopeLimited`: RPC деталей не вдалося через відсутню область operator. + - `ok`: досяжність після класифікації connect + degraded. + - `rpcOk`: успіх повної деталізованої RPC. + - `scopeLimited`: деталізована RPC завершилася невдало через відсутню область operator. Для кожної цілі (`targets[].auth`): - `role`: роль автентифікації, повідомлена в `hello-ok`, коли доступна. - `scopes`: надані області, повідомлені в `hello-ok`, коли доступні. - - `capability`: показана класифікація можливості автентифікації для цієї цілі. + - `capability`: відображена класифікація можливості автентифікації для цієї цілі. - - `ssh_tunnel_failed`: налаштування SSH-тунелю не вдалося; команда повернулася до прямих перевірок. - - `multiple_gateways`: було доступно більше ніж одну ціль; це незвично, якщо ви навмисно не запускаєте ізольовані профілі, наприклад rescue bot. - - `auth_secretref_unresolved`: налаштований auth SecretRef не вдалося розв’язати для невдалої цілі. - - `probe_scope_limited`: підключення WebSocket успішне, але перевірку читання обмежено через відсутній `operator.read`. + - `ssh_tunnel_failed`: налаштування SSH tunnel завершилося невдало; команда повернулася до прямих зондувань. + - `multiple_gateways`: досяжною була більш ніж одна ціль; це незвично, якщо ви навмисно не запускаєте ізольовані профілі, наприклад rescue bot. + - `auth_secretref_unresolved`: налаштований SecretRef автентифікації не вдалося розв’язати для цілі, що завершилася невдало. + - `probe_scope_limited`: WebSocket-з’єднання успішне, але зондування читання було обмежене через відсутній `operator.read`. -#### Віддалено через SSH (паритет Mac app) +#### Віддалено через SSH (паритет із Mac app) -Режим macOS app "Remote over SSH" використовує локальне перенаправлення порту, тому віддалений gateway (який може бути прив’язаний лише до loopback) стає доступним за `ws://127.0.0.1:`. +Режим macOS app «Remote over SSH» використовує локальне перенаправлення порту, щоб віддалений gateway (який може бути прив’язаний лише до loopback) став доступним за `ws://127.0.0.1:`. Еквівалент CLI: @@ -390,13 +390,13 @@ openclaw gateway probe --ssh user@gateway-host ``` - `user@host` або `user@host:port` (порт за замовчуванням `22`). + `user@host` або `user@host:port` (port за замовчуванням `22`). Файл ідентичності. - Вибрати перший виявлений хост gateway як ціль SSH з розв’язаного endpoint виявлення (`local.` плюс налаштований wide-area domain, якщо є). Підказки лише TXT ігноруються. + Вибрати перший виявлений хост gateway як ціль SSH з розв’язаного endpoint discovery (`local.` плюс налаштований wide-area domain, якщо є). Підказки лише TXT ігноруються. Конфігурація (необов’язкова, використовується як значення за замовчуванням): @@ -406,7 +406,7 @@ openclaw gateway probe --ssh user@gateway-host ### `gateway call ` -Низькорівневий допоміжний засіб RPC. +Низькорівневий RPC-помічник. ```bash openclaw gateway call status @@ -417,7 +417,7 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' Рядок JSON-об’єкта для params. - URL WebSocket Gateway. + WebSocket URL Gateway. Токен Gateway. @@ -426,13 +426,13 @@ openclaw gateway call logs.tail --params '{"sinceMs": 60000}' Пароль Gateway. - Бюджет тайм-ауту. + Бюджет часу очікування. - Переважно для RPC в стилі agent, які транслюють проміжні події перед фінальним payload. + Переважно для RPC у стилі агентів, які передають проміжні події перед фінальним payload. - Машиночитний JSON-вивід. + Машинозчитуваний JSON-вивід. @@ -449,9 +449,9 @@ openclaw gateway restart openclaw gateway uninstall ``` -### Установлення з wrapper +### Інсталяція з wrapper -Використовуйте `--wrapper`, коли керований сервіс має запускатися через інший виконуваний файл, наприклад shim менеджера секретів або helper запуску від іншого користувача. Wrapper отримує звичайні аргументи Gateway і відповідає за те, щоб зрештою виконати `openclaw` або Node із цими аргументами. +Використовуйте `--wrapper`, коли керований сервіс має запускатися через інший виконуваний файл, наприклад shim менеджера секретів або run-as helper. Wrapper отримує звичайні аргументи Gateway і відповідає за те, щоб зрештою виконати `openclaw` або Node з цими аргументами. ```bash cat > ~/.local/bin/openclaw-doppler <<'EOF' @@ -465,7 +465,7 @@ openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force openclaw gateway restart ``` -Також можна задати wrapper через середовище. `gateway install` перевіряє, що шлях є виконуваним файлом, записує wrapper у service `ProgramArguments` і зберігає `OPENCLAW_WRAPPER` у середовищі сервісу для подальших примусових перевстановлень, оновлень і виправлень doctor. +Також можна задати wrapper через середовище. `gateway install` перевіряє, що шлях є виконуваним файлом, записує wrapper у `ProgramArguments` сервісу та зберігає `OPENCLAW_WRAPPER` у середовищі сервісу для подальших примусових перевстановлень, оновлень і виправлень doctor. ```bash OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force @@ -483,45 +483,46 @@ openclaw gateway restart - `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json` - `gateway install`: `--port`, `--runtime `, `--token`, `--wrapper `, `--force`, `--json` - - `gateway restart`: `--force`, `--wait `, `--json` + - `gateway restart`: `--safe`, `--force`, `--wait `, `--json` - `gateway uninstall|start|stop`: `--json` - - Використовуйте `gateway restart`, щоб перезапустити керований сервіс. Не зв’язуйте `gateway stop` і `gateway start` як заміну перезапуску; на macOS `gateway stop` навмисно вимикає LaunchAgent перед зупинкою. - - `gateway restart --wait 30s` перевизначає налаштований бюджет drain перезапуску для цього перезапуску. Числа без одиниць — це мілісекунди; приймаються одиниці на кшталт `s`, `m` і `h`. `--wait 0` чекає безстроково. - - `gateway restart --force` пропускає drain активної роботи й перезапускає негайно. Використовуйте це, коли оператор уже перевірив перелічені блокувальники завдань і хоче повернути gateway зараз. + - Використовуйте `gateway restart`, щоб перезапустити керований сервіс. Не об’єднуйте `gateway stop` і `gateway start` як заміну перезапуску; на macOS `gateway stop` навмисно вимикає LaunchAgent перед його зупинкою. + - `gateway restart --safe` просить запущений Gateway виконати preflight активної роботи OpenClaw і відкласти перезапуск, доки доставлення відповідей, вбудовані запуски та запуски завдань не завершаться. `--safe` не можна поєднувати з `--force` або `--wait`. + - `gateway restart --wait 30s` перевизначає налаштований бюджет drain для перезапуску. Голі числа означають мілісекунди; приймаються одиниці, як-от `s`, `m` і `h`. `--wait 0` чекає безстроково. + - `gateway restart --force` пропускає drain активної роботи й перезапускає негайно. Використовуйте це, коли оператор уже перевірив перелічені блокери завдань і хоче повернути gateway зараз. - Команди життєвого циклу приймають `--json` для скриптів. - - - Коли автентифікація токеном потребує токена, а `gateway.auth.token` керується SecretRef, `gateway install` перевіряє, що SecretRef можна розв’язати, але не зберігає розв’язаний токен у metadata середовища сервісу. - - Якщо автентифікація токеном потребує токена, а налаштований token SecretRef не розв’язано, установлення закривається помилкою замість збереження fallback plaintext. - - Для автентифікації паролем у `gateway run` віддавайте перевагу `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` або `gateway.auth.password` на базі SecretRef замість inline `--password`. - - В режимі inferred auth лише shell `OPENCLAW_GATEWAY_PASSWORD` не послаблює вимоги до токена під час установлення; використовуйте durable config (`gateway.auth.password` або config `env`) під час установлення керованого сервісу. - - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, установлення блокується, доки mode не буде задано явно. + + - Коли автентифікація за токеном потребує токен і `gateway.auth.token` керується через SecretRef, `gateway install` перевіряє, що SecretRef можна розв'язати, але не зберігає розв'язаний токен у метаданих середовища сервісу. + - Якщо автентифікація за токеном потребує токен, а налаштований SecretRef токена не розв'язано, встановлення завершується закритою відмовою замість збереження резервного відкритого тексту. + - Для автентифікації паролем у `gateway run` віддавайте перевагу `OPENCLAW_GATEWAY_PASSWORD`, `--password-file` або `gateway.auth.password` на основі SecretRef замість вбудованого `--password`. + - У режимі виведеної автентифікації лише shell-змінна `OPENCLAW_GATEWAY_PASSWORD` не послаблює вимоги до токена під час встановлення; використовуйте сталу конфігурацію (`gateway.auth.password` або config `env`) під час встановлення керованого сервісу. + - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, встановлення блокується, доки режим не буде задано явно. -## Виявлення gateways (Bonjour) +## Виявлення Gateway (Bonjour) -`gateway discover` сканує маяки Gateway (`_openclaw-gw._tcp`). +`gateway discover` сканує маячки Gateway (`_openclaw-gw._tcp`). -- Багатоадресний DNS-SD: `local.` -- Одноадресний DNS-SD (Wide-Area Bonjour): виберіть домен (приклад: `openclaw.internal.`) і налаштуйте split DNS + DNS-сервер; див. [Bonjour](/uk/gateway/bonjour). +- Multicast DNS-SD: `local.` +- Unicast DNS-SD (Wide-Area Bonjour): виберіть домен (приклад: `openclaw.internal.`) і налаштуйте split DNS + DNS-сервер; див. [Bonjour](/uk/gateway/bonjour). -Лише Gateway з увімкненим виявленням Bonjour (за замовчуванням) оголошують маяк. +Лише екземпляри Gateway з увімкненим виявленням Bonjour (типово) оголошують маячок. -Записи виявлення Wide-Area містять (TXT): +Записи Wide-Area виявлення містять (TXT): - `role` (підказка ролі Gateway) - `transport` (підказка транспорту, напр. `gateway`) - `gatewayPort` (порт WebSocket, зазвичай `18789`) -- `sshPort` (необов’язково; клієнти за замовчуванням використовують SSH-цілі на `22`, коли його немає) -- `tailnetDns` (ім’я хоста MagicDNS, якщо доступне) +- `sshPort` (необов'язково; клієнти типово використовують `22` для SSH-цілей, коли він відсутній) +- `tailnetDns` (ім'я хоста MagicDNS, коли доступне) - `gatewayTls` / `gatewayTlsSha256` (TLS увімкнено + відбиток сертифіката) -- `cliPath` (підказка віддаленого встановлення, записана в зону Wide-Area) +- `cliPath` (підказка віддаленого встановлення, записана в wide-area зону) ### `gateway discover` @@ -530,10 +531,10 @@ openclaw gateway discover ``` - Тайм-аут для команди (перегляд/розв’язання). + Таймаут для команди (browse/resolve). - Машинозчитуваний вивід (також вимикає стилізацію/індикатор завантаження). + Машиночитний вивід (також вимикає стилізацію/індикатор). Приклади: @@ -544,13 +545,13 @@ openclaw gateway discover --json | jq '.beacons[].wsUrl' ``` -- CLI сканує `local.` плюс налаштований домен Wide-Area, коли його увімкнено. -- `wsUrl` у виводі JSON походить із розв’язаної кінцевої точки сервісу, а не з підказок лише TXT, як-от `lanHost` або `tailnetDns`. -- У mDNS `local.` `sshPort` і `cliPath` транслюються лише тоді, коли `discovery.mdns.mode` дорівнює `full`. Wide-Area DNS-SD усе одно записує `cliPath`; `sshPort` там теж залишається необов’язковим. +- CLI сканує `local.` плюс налаштований wide-area домен, коли його ввімкнено. +- `wsUrl` у JSON-виводі походить із розв'язаного endpoint сервісу, а не лише з TXT-підказок, таких як `lanHost` або `tailnetDns`. +- У `local.` mDNS, `sshPort` і `cliPath` транслюються лише тоді, коли `discovery.mdns.mode` дорівнює `full`. Wide-area DNS-SD все одно записує `cliPath`; `sshPort` там також залишається необов'язковим. -## Пов’язане +## Пов'язане - [Довідник CLI](/uk/cli) - [Runbook Gateway](/uk/gateway) diff --git a/docs/uk/gateway/config-tools.md b/docs/uk/gateway/config-tools.md index a93245fef..af5bdd261 100644 --- a/docs/uk/gateway/config-tools.md +++ b/docs/uk/gateway/config-tools.md @@ -1,30 +1,30 @@ --- read_when: - - Налаштування політики `tools.*`, списків дозволених елементів або експериментальних функцій - - Реєстрація користувацьких провайдерів або перевизначення базових URL-адрес - - Налаштування OpenAI-сумісних самостійно розгорнутих кінцевих точок + - Налаштування політики `tools.*`, списків дозволеного або експериментальних функцій + - Реєстрація власних провайдерів або перевизначення базових URL-адрес + - Налаштування OpenAI-сумісних самостійно розміщених кінцевих точок sidebarTitle: Tools and custom providers summary: Конфігурація інструментів (політика, експериментальні перемикачі, інструменти на базі провайдера) і налаштування власного провайдера/базової URL-адреси -title: Конфігурація — інструменти та власні провайдери +title: Конфігурація — інструменти та користувацькі провайдери x-i18n: - generated_at: "2026-05-03T17:25:19Z" + generated_at: "2026-05-05T00:49:32Z" model: gpt-5.5 provider: openai - source_hash: 75a39342f40e9c329a7c61855e805ec43532cbdb89fbe801acc26830fd63b4da + source_hash: 9196bff46d8b0f9447fb46b47fc764f5bbc4f0b19eb252d4db611e94e57b4883 source_path: gateway/config-tools.md workflow: 16 --- -`tools.*` ключі конфігурації та налаштування власного провайдера / базової URL-адреси. Для agents, channels та інших ключів конфігурації верхнього рівня див. [Довідник конфігурації](/uk/gateway/configuration-reference). +`tools.*` ключі конфігурації та налаштування користувацького провайдера / базової URL-адреси. Для агентів, каналів та інших ключів конфігурації верхнього рівня див. [Довідник конфігурації](/uk/gateway/configuration-reference). ## Інструменти ### Профілі інструментів -`tools.profile` задає базовий список дозволених інструментів перед `tools.allow`/`tools.deny`: +`tools.profile` задає базовий список дозволеного перед `tools.allow`/`tools.deny`: -Локальне початкове налаштування за замовчуванням встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явно задані профілі зберігаються). +Локальний onboarding за замовчуванням установлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо його не задано (наявні явно задані профілі зберігаються). | Профіль | Містить | @@ -32,7 +32,7 @@ x-i18n: | `minimal` | лише `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Без обмежень (так само, як якщо не задано) | +| `full` | Без обмежень (те саме, що й не задано) | ### Групи інструментів @@ -49,11 +49,11 @@ x-i18n: | `group:nodes` | `nodes` | | `group:agents` | `agents_list` | | `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Усі вбудовані інструменти (без provider plugins) | +| `group:openclaw` | Усі вбудовані інструменти (не включає плагіни провайдерів) | ### `tools.allow` / `tools.deny` -Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Не чутлива до регістру, підтримує символи узагальнення `*`. Застосовується навіть коли пісочницю Docker вимкнено. +Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Не залежить від регістру, підтримує маски `*`. Застосовується навіть коли Docker sandbox вимкнено. ```json5 { @@ -71,7 +71,7 @@ x-i18n: ### `tools.byProvider` -Додатково обмежує інструменти для конкретних провайдерів або моделей. Порядок: базовий профіль → профіль провайдера → дозвіл/заборона. +Додатково обмежує інструменти для певних провайдерів або моделей. Порядок: базовий профіль → профіль провайдера → дозвіл/заборона. ```json5 { @@ -87,7 +87,7 @@ x-i18n: ### `tools.elevated` -Керує підвищеним доступом `exec` поза пісочницею: +Керує підвищеним доступом `exec` поза sandbox: ```json5 { @@ -103,9 +103,9 @@ x-i18n: } ``` -- Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. +- Перевизначення для агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. - `/elevated on|off|ask|full` зберігає стан для кожної сесії; вбудовані директиви застосовуються до одного повідомлення. -- Підвищений `exec` обходить пісочницю та використовує налаштований шлях виходу (`gateway` за замовчуванням або `node`, коли ціль `exec` — `node`). +- Підвищений `exec` обходить sandboxing і використовує налаштований шлях виходу (`gateway` за замовчуванням або `node`, коли ціль `exec` — `node`). ### `tools.exec` @@ -129,7 +129,7 @@ x-i18n: ### `tools.loopDetection` -Перевірки безпеки циклів інструментів **вимкнені за замовчуванням**. Установіть `enabled: true`, щоб активувати виявлення. Налаштування можна визначити глобально в `tools.loopDetection` і перевизначити для окремого агента в `agents.list[].tools.loopDetection`. +Перевірки безпеки циклів інструментів **вимкнені за замовчуванням**. Установіть `enabled: true`, щоб активувати виявлення. Налаштування можна визначити глобально в `tools.loopDetection` і перевизначити для кожного агента в `agents.list[].tools.loopDetection`. ```json5 { @@ -154,13 +154,13 @@ x-i18n: Максимальна історія викликів інструментів, що зберігається для аналізу циклів. - Порогове значення повторюваного шаблону без прогресу для попереджень. + Поріг повторюваного шаблону без прогресу для попереджень. - Вище порогове значення повторень для блокування критичних циклів. + Вищий поріг повторень для блокування критичних циклів. - Порогове значення жорсткої зупинки для будь-якого виконання без прогресу. + Поріг жорсткої зупинки для будь-якого виконання без прогресу. Попереджати про повторювані виклики того самого інструмента з тими самими аргументами. @@ -169,11 +169,11 @@ x-i18n: Попереджати/блокувати відомі інструменти опитування (`process.poll`, `command_status` тощо). - Попереджати/блокувати шаблони пар, що чергуються без прогресу. + Попереджати/блокувати чергування парних шаблонів без прогресу. -Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, валідація не проходить. +Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, перевірка не проходить. ### `tools.web` @@ -216,7 +216,7 @@ x-i18n: media: { concurrency: 2, asyncCompletion: { - directSend: false, // opt-in: send finished async video directly to the channel + directSend: false, // deprecated: completions stay agent-mediated }, audio: { enabled: true, @@ -247,9 +247,9 @@ x-i18n: - **Запис постачальника** (`type: "provider"` або пропущено): + **Запис провайдера** (`type: "provider"` або опущено): - - `provider`: ідентифікатор постачальника API (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) + - `provider`: ідентифікатор API-провайдера (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) - `model`: перевизначення ідентифікатора моделі - `profile` / `preferredProfile`: вибір профілю `auth-profiles.json` @@ -260,16 +260,16 @@ x-i18n: **Спільні поля:** - - `capabilities`: необов’язковий список (`image`, `audio`, `video`). Значення за замовчуванням: `openai`/`anthropic`/`minimax` → зображення, `google` → зображення+аудіо+відео, `groq` → аудіо. + - `capabilities`: необов’язковий список (`image`, `audio`, `video`). Стандартні значення: `openai`/`anthropic`/`minimax` → зображення, `google` → зображення+аудіо+відео, `groq` → аудіо. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису. - - Записи `tools.media.image.timeoutSeconds` і відповідні записи `timeoutSeconds` моделі зображень також застосовуються, коли агент викликає явний інструмент `image`. + - `tools.media.image.timeoutSeconds` і відповідні записи `timeoutSeconds` моделі зображень також застосовуються, коли агент викликає явний інструмент `image`. - У разі збоїв використовується наступний запис. - Автентифікація постачальника дотримується стандартного порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`. + Автентифікація провайдера дотримується стандартного порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`. **Поля асинхронного завершення:** - - `asyncCompletion.directSend`: коли `true`, завершені асинхронні медіазавдання, що підтримують пряму доставку завершення, спочатку намагаються виконати пряму доставку в канал. За замовчуванням: `false` (шлях пробудження сеансу запитувача/доставки моделлю). Наразі це застосовується до асинхронного `video_generate`; завершення асинхронного `music_generate` залишаються опосередкованими сеансом запитувача, навіть коли це ввімкнено. + - `asyncCompletion.directSend`: застарілий прапорець сумісності. Завершені асинхронні медіазавдання залишаються опосередкованими сеансом запитувача, щоб агент отримав результат, вирішив, як повідомити користувача, і використав інструмент повідомлень, коли цього потребує доставка джерелу. @@ -289,9 +289,9 @@ x-i18n: ### `tools.sessions` -Керує тим, на які сеанси можуть націлюватися інструменти сеансів (`sessions_list`, `sessions_history`, `sessions_send`). +Керує тим, які сеанси можуть бути ціллю інструментів сеансів (`sessions_list`, `sessions_history`, `sessions_send`). -За замовчуванням: `tree` (поточний сеанс + сеанси, створені ним, наприклад субагенти). +Стандартно: `tree` (поточний сеанс + сеанси, створені ним, наприклад субагенти). ```json5 { @@ -308,8 +308,8 @@ x-i18n: - `self`: лише ключ поточного сеансу. - `tree`: поточний сеанс + сеанси, створені поточним сеансом (субагенти). - - `agent`: будь-який сеанс, що належить поточному ідентифікатору агента (може включати інших користувачів, якщо ви запускаєте сеанси для кожного відправника з тим самим ідентифікатором агента). - - `all`: будь-який сеанс. Націлювання між агентами все одно потребує `tools.agentToAgent`. + - `agent`: будь-який сеанс, що належить ідентифікатору поточного агента (може включати інших користувачів, якщо ви запускаєте сеанси для кожного відправника під тим самим ідентифікатором агента). + - `all`: будь-який сеанс. Цілювання між агентами все одно потребує `tools.agentToAgent`. - Обмеження пісочниці: коли поточний сеанс перебуває в пісочниці й `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється на `tree`, навіть якщо `tools.sessions.visibility="all"`. @@ -336,13 +336,13 @@ x-i18n: ``` - + - Вкладення підтримуються лише для `runtime: "subagent"`. Середовище виконання ACP відхиляє їх. - - Файли матеріалізуються в дочірньому робочому просторі в `.openclaw/attachments//` з `.manifest.json`. - - Вміст вкладень автоматично редагується під час збереження транскрипта. - - Вхідні дані Base64 перевіряються суворими перевірками алфавіту/заповнення та запобіжником розміру перед декодуванням. - - Дозволи файлів: `0700` для каталогів і `0600` для файлів. - - Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. + - Файли матеріалізуються в дочірньому робочому просторі за шляхом `.openclaw/attachments//` із `.manifest.json`. + - Вміст вкладень автоматично редагується під час збереження транскрипту. + - Вхідні дані Base64 перевіряються суворими перевірками алфавіту/доповнення та захистом розміру перед декодуванням. + - Дозволи файлів: `0700` для директорій і `0600` для файлів. + - Очищення відповідає політиці `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. @@ -351,7 +351,7 @@ x-i18n: ### `tools.experimental` -Експериментальні прапорці вбудованих інструментів. Типово вимкнено, якщо не застосовується правило автоматичного ввімкнення strict-agentic для GPT-5. +Експериментальні вбудовані прапорці інструментів. Типово вимкнено, якщо не застосовується правило автоматичного ввімкнення для strict-agentic GPT-5. ```json5 { @@ -364,7 +364,7 @@ x-i18n: ``` - `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатоетапної роботи. -- Типово: `false`, якщо `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено на `"strict-agentic"` для запуску OpenAI або OpenAI Codex із сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цією областю, або `false`, щоб залишити його вимкненим навіть для запусків GPT-5 у режимі strict-agentic. +- Типово: `false`, якщо `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено на `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цією областю, або `false`, щоб залишити його вимкненим навіть для strict-agentic запусків GPT-5. - Коли ввімкнено, системний промпт також додає настанови з використання, щоб модель застосовувала його лише для суттєвої роботи й тримала щонайбільше один крок `in_progress`. ### `agents.defaults.subagents` @@ -386,13 +386,13 @@ x-i18n: ``` - `model`: типова модель для породжених субагентів. Якщо пропущено, субагенти успадковують модель викликача. -- `allowAgents`: типовий allowlist цільових ідентифікаторів агентів для `sessions_spawn`, коли агент-запитувач не задає власне `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). +- `allowAgents`: типовий список дозволених ідентифікаторів цільових агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). - `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента пропускає `runTimeoutSeconds`. `0` означає без тайм-ауту. - Політика інструментів для кожного субагента: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Користувацькі провайдери та базові URL +## Користувацькі провайдери й базові URL-адреси OpenClaw використовує вбудований каталог моделей. Додавайте користувацьких провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. @@ -427,81 +427,81 @@ OpenClaw використовує вбудований каталог модел - Використовуйте `authHeader: true` + `headers` для користувацьких потреб автентифікації. - Перевизначайте корінь конфігурації агента за допомогою `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілого псевдоніма змінної середовища). - - Пріоритет злиття для збіжних ID провайдерів: + - Пріоритет злиття для збіжних ідентифікаторів провайдерів: - Непорожні значення `baseUrl` з агентського `models.json` мають перевагу. - Непорожні значення `apiKey` агента мають перевагу лише тоді, коли цей провайдер не керується SecretRef у поточному контексті конфігурації/профілю автентифікації. - - Значення `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`. - - Збереження маркерів спирається на джерело як авторитетне: маркери записуються з активного знімка конфігурації джерела (до розв'язання), а не з розв'язаних значень секретів середовища виконання. + - Значення `apiKey` провайдера, керованого SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для посилань на env, `secretref-managed` для посилань на file/exec), замість збереження розв'язаних секретів. + - Значення заголовків провайдера, керованого SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для посилань на env, `secretref-managed` для посилань на file/exec). + - Порожні або відсутні `apiKey`/`baseUrl` агента повертаються до `models.providers` у конфігурації. + - Збіжні `contextWindow`/`maxTokens` моделі використовують більше значення між явною конфігурацією та неявними значеннями каталогу. + - Збіжний `contextTokens` моделі зберігає явне обмеження середовища виконання, коли воно наявне; використовуйте його, щоб обмежити ефективний контекст без зміни нативних метаданих моделі. + - Використовуйте `models.mode: "replace"`, коли хочете, щоб конфігурація повністю переписала `models.json`. + - Збереження маркерів є джерело-авторитетним: маркери записуються з активного знімка конфігурації джерела (до розв'язання), а не з розв'язаних значень секретів середовища виконання. -### Подробиці полів провайдера +### Докладно про поля провайдера - `models.mode`: поведінка каталогу провайдерів (`merge` або `replace`). - - `models.providers`: мапа користувацьких провайдерів, ключована за ID провайдера. - - Безпечні редагування: використовуйте `openclaw config set models.providers. '' --strict-json --merge` або `openclaw config set models.providers..models '' --strict-json --merge` для додавальних оновлень. `config set` відмовляє в руйнівних замінах, якщо не передати `--replace`. + - `models.providers`: мапа користувацьких провайдерів із ключем за ідентифікатором провайдера. + - Безпечні редагування: використовуйте `openclaw config set models.providers. '' --strict-json --merge` або `openclaw config set models.providers..models '' --strict-json --merge` для адитивних оновлень. `config set` відмовляє в деструктивних замінах, якщо не передати `--replace`. - - `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо). Для самостійно розгорнутих бекендів `/v1/chat/completions`, таких як MLX, vLLM, SGLang і більшість локальних серверів, сумісних з OpenAI, використовуйте `openai-completions`. Користувацький провайдер із `baseUrl`, але без `api`, типово використовує `openai-completions`; установлюйте `openai-responses` лише коли бекенд підтримує `/v1/responses`. - - `models.providers.*.apiKey`: облікові дані провайдера (надавайте перевагу SecretRef/підстановці змінних середовища). + - `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо). Для самостійно розгорнутих бекендів `/v1/chat/completions`, таких як MLX, vLLM, SGLang і більшість локальних серверів, сумісних з OpenAI, використовуйте `openai-completions`. Користувацький провайдер із `baseUrl`, але без `api`, типово використовує `openai-completions`; задавайте `openai-responses` лише коли бекенд підтримує `/v1/responses`. + - `models.providers.*.apiKey`: облікові дані провайдера (надавайте перевагу SecretRef/підстановці env). - `models.providers.*.auth`: стратегія автентифікації (`api-key`, `token`, `oauth`, `aws-sdk`). - - `models.providers.*.contextWindow`: типове власне вікно контексту для моделей цього провайдера, коли запис моделі не задає `contextWindow`. + - `models.providers.*.contextWindow`: типове нативне контекстне вікно для моделей цього провайдера, коли запис моделі не задає `contextWindow`. - `models.providers.*.contextTokens`: типове ефективне обмеження контексту середовища виконання для моделей цього провайдера, коли запис моделі не задає `contextTokens`. - `models.providers.*.maxTokens`: типове обмеження вихідних токенів для моделей цього провайдера, коли запис моделі не задає `maxTokens`. - - `models.providers.*.timeoutSeconds`: необов'язковий тайм-аут HTTP-запиту моделі для окремого провайдера в секундах, включно з підключенням, заголовками, тілом і обробкою переривання всього запиту. + - `models.providers.*.timeoutSeconds`: необов'язковий тайм-аут HTTP-запиту до моделі для окремого провайдера в секундах, включно з підключенням, заголовками, тілом і загальною обробкою переривання запиту. - `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вставляє `options.num_ctx` у запити (типово: `true`). - `models.providers.*.authHeader`: примусово передає облікові дані в заголовку `Authorization`, коли це потрібно. - - `models.providers.*.baseUrl`: базовий URL висхідного API. + - `models.providers.*.baseUrl`: базова URL-адреса upstream API. - `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації проксі/орендаря. - `models.providers.*.request`: перевизначення транспорту для HTTP-запитів провайдера моделі. + `models.providers.*.request`: перевизначення транспорту для HTTP-запитів до провайдера моделей. - - `request.headers`: додаткові заголовки (об'єднуються з типовими значеннями провайдера). Значення приймають SecretRef. + - `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). URL потоків провайдера моделі для loopback, такі як `localhost`, `127.0.0.1` і `[::1]`, дозволені автоматично, якщо це явно не встановлено на `false`; хости LAN, tailnet і приватного DNS усе ще потребують згоди. WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-запобіжник fetch. Типово `false`. + - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, коли DNS розв'язується в приватні, CGNAT або подібні діапазони, через захист HTTP fetch провайдера (явна згода оператора для довірених самостійно розгорнутих кінцевих точок, сумісних з OpenAI). URL-адреси потоків провайдера моделей через Loopback, такі як `localhost`, `127.0.0.1` і `[::1]`, дозволяються автоматично, якщо це явно не встановлено на `false`; хости LAN, tailnet і приватні DNS усе ще потребують явної згоди. WebSocket використовує той самий `request` для заголовків/TLS, але не цей fetch SSRF gate. Типово `false`. - `models.providers.*.models`: явні записи каталогу моделей провайдера. - - `models.providers.*.models.*.input`: модальності входу моделі. Використовуйте `["text"]` для моделей лише з текстом і `["text", "image"]` для власних моделей із зображеннями/комп'ютерним зором. Вкладення зображень вставляються в ходи агента лише коли вибрану модель позначено як здатну працювати із зображеннями. - - `models.providers.*.models.*.contextWindow`: метадані власного вікна контексту моделі. Це перевизначає `contextWindow` рівня провайдера для цієї моделі. - - `models.providers.*.models.*.contextTokens`: необов'язкове обмеження контексту середовища виконання. Це перевизначає `contextTokens` рівня провайдера; використовуйте його, коли потрібен менший ефективний бюджет контексту, ніж власний `contextWindow` моделі; `openclaw models list` показує обидва значення, коли вони різняться. - - `models.providers.*.models.*.compat.supportsDeveloperRole`: необов'язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім невласним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це на `false` під час виконання. Порожній/пропущений `baseUrl` зберігає типову поведінку OpenAI. - - `models.providers.*.models.*.compat.requiresStringContent`: необов'язкова підказка сумісності для текстових лише рядкових кінцевих точок чату, сумісних з OpenAI. Коли `true`, OpenClaw згортає масиви `messages[].content` із чистим текстом у прості рядки перед надсиланням запиту. + - `models.providers.*.models.*.input`: модальності введення моделі. Використовуйте `["text"]` для моделей лише з текстом і `["text", "image"]` для нативних image/vision моделей. Вкладення зображень вставляються в ходи агента лише коли вибрану модель позначено як здатну обробляти зображення. + - `models.providers.*.models.*.contextWindow`: метадані нативного контекстного вікна моделі. Це перевизначає `contextWindow` рівня провайдера для цієї моделі. + - `models.providers.*.models.*.contextTokens`: необов'язкове обмеження контексту середовища виконання. Це перевизначає `contextTokens` рівня провайдера; використовуйте його, коли хочете менший ефективний бюджет контексту, ніж нативний `contextWindow` моделі; `openclaw models list` показує обидва значення, коли вони відрізняються. + - `models.providers.*.models.*.compat.supportsDeveloperRole`: необов'язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім ненативним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це на `false` під час виконання. Порожній/пропущений `baseUrl` зберігає типову поведінку OpenAI. + - `models.providers.*.models.*.compat.requiresStringContent`: необов'язкова підказка сумісності для текстових кінцевих точок чату, сумісних з OpenAI. Коли `true`, OpenClaw сплющує масиви чистого тексту `messages[].content` у звичайні рядки перед надсиланням запиту. - - `plugins.entries.amazon-bedrock.config.discovery`: корінь налаштувань автоматичного виявлення Bedrock. + - `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`: необов'язковий фільтр ID провайдера для цільового виявлення. + - `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.defaultContextWindow`: резервне контекстне вікно для виявлених моделей. + - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервна максимальна кількість вихідних токенів для виявлених моделей. -Інтерактивний onboarding користувацького провайдера визначає вхід зображень для поширених ID моделей із комп'ютерним зором, таких як GPT-4o, Claude, Gemini, Qwen-VL, LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V і GLM-4V, та пропускає додаткове запитання для відомих текстових сімейств. Невідомі ID моделей усе ще запитують про підтримку зображень. Неінтерактивний onboarding використовує той самий висновок; передайте `--custom-image-input`, щоб примусово встановити метадані здатності працювати із зображеннями, або `--custom-text-input`, щоб примусово встановити метадані лише тексту. +Інтерактивне налаштування користувацького провайдера визначає введення зображень для поширених ідентифікаторів vision-моделей, таких як GPT-4o, Claude, Gemini, Qwen-VL, LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V і GLM-4V, та пропускає додаткове запитання для відомих сімейств лише з текстом. Невідомі ідентифікатори моделей усе ще запитують про підтримку зображень. Неінтерактивне налаштування використовує той самий висновок; передайте `--custom-image-input`, щоб примусово встановити метадані здатності до зображень, або `--custom-text-input`, щоб примусово встановити метадані лише для тексту. ### Приклади провайдерів - Укомплектований Plugin провайдера `cerebras` може налаштувати це через `openclaw onboard --auth-choice cerebras-api-key`. Використовуйте явну конфігурацію провайдера лише коли перевизначаєте типові значення. + Вбудований Plugin провайдера `cerebras` може налаштувати це через `openclaw onboard --auth-choice cerebras-api-key`. Використовуйте явну конфігурацію провайдера лише під час перевизначення типових значень. ```json5 { @@ -535,7 +535,7 @@ OpenClaw використовує вбудований каталог модел } ``` - Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` для прямого підключення Z.AI. + Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` для прямого Z.AI. @@ -551,11 +551,11 @@ OpenClaw використовує вбудований каталог модел } ``` - Вбудований провайдер, сумісний з Anthropic. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. + Сумісний з Anthropic, вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. - Див. [Локальні моделі](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; залишайте розміщені моделі об’єднаними для резервного варіанта. + Див. [Локальні моделі](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; залишайте розміщені моделі об'єднаними для резервного варіанта. ```json5 @@ -592,7 +592,7 @@ OpenClaw використовує вбудований каталог модел } ``` - Задайте `MINIMAX_API_KEY`. Скорочення: `openclaw onboard --auth-choice minimax-global-api` або `openclaw onboard --auth-choice minimax-cn-api`. Каталог моделей за замовчуванням містить лише M2.7. На потоковому шляху, сумісному з Anthropic, OpenClaw за замовчуванням вимикає мислення MiniMax, якщо ви явно не задасте `thinking` самостійно. `/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. + Задайте `MINIMAX_API_KEY`. Скорочення: `openclaw onboard --auth-choice minimax-global-api` або `openclaw onboard --auth-choice minimax-cn-api`. Каталог моделей типово містить лише M2.7. На сумісному з Anthropic шляху потокового передавання OpenClaw типово вимикає мислення MiniMax, якщо ви явно не задасте `thinking` самостійно. `/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. @@ -629,9 +629,9 @@ OpenClaw використовує вбудований каталог модел } ``` - Для кінцевої точки в Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. + Для китайського ендпоінта: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. - Нативні кінцеві точки Moonshot оголошують сумісність використання потокового передавання на спільному транспорті `openai-completions`, і OpenClaw визначає це за можливостями кінцевої точки, а не лише за ідентифікатором вбудованого провайдера. + Нативні ендпоінти Moonshot заявляють сумісність із використанням потокового передавання на спільному транспорті `openai-completions`, а OpenClaw визначає це за можливостями ендпоінта, а не лише за ідентифікатором вбудованого провайдера. @@ -646,10 +646,10 @@ 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`. - + ```json5 { env: { SYNTHETIC_API_KEY: "sk-..." }, @@ -683,7 +683,7 @@ OpenClaw використовує вбудований каталог модел } ``` - Базова URL-адреса має не містити `/v1` (клієнт Anthropic додає її). Швидкий варіант: `openclaw onboard --auth-choice synthetic-api-key`. + Базова URL-адреса має не містити `/v1` (клієнт Anthropic додає її). Скорочення: `openclaw onboard --auth-choice synthetic-api-key`. @@ -698,18 +698,18 @@ OpenClaw використовує вбудований каталог модел } ``` - Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` приймаються як псевдоніми. Швидкий варіант: `openclaw onboard --auth-choice zai-api-key`. + Задайте `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` приймаються як псевдоніми. Скорочення: `openclaw onboard --auth-choice zai-api-key`. - - Загальна кінцева точка: `https://api.z.ai/api/paas/v4` - - Кінцева точка для кодування (за замовчуванням): `https://api.z.ai/api/coding/paas/v4` - - Для загальної кінцевої точки визначте власного провайдера з перевизначенням базової URL-адреси. + - Загальний ендпоінт: `https://api.z.ai/api/paas/v4` + - Ендпоінт для кодування (типовий): `https://api.z.ai/api/coding/paas/v4` + - Для загального ендпоінта визначте власного провайдера з перевизначенням базової URL-адреси. --- -## Пов’язане +## Пов'язане - [Конфігурація — агенти](/uk/gateway/config-agents) - [Конфігурація — канали](/uk/gateway/config-channels) diff --git a/docs/uk/help/faq-models.md b/docs/uk/help/faq-models.md index d7fb46986..a1a497688 100644 --- a/docs/uk/help/faq-models.md +++ b/docs/uk/help/faq-models.md @@ -1,22 +1,22 @@ --- read_when: - Вибір або перемикання моделей, налаштування псевдонімів - - Налагодження резервного перемикання моделей / «Не спрацювала жодна модель» + - Налагодження аварійного перемикання моделей / «Усі моделі завершилися помилкою» - Розуміння профілів автентифікації та керування ними sidebarTitle: Models FAQ summary: 'Поширені запитання: типові налаштування моделей, вибір, псевдоніми, перемикання, аварійне перемикання та профілі автентифікації' title: 'Поширені запитання: моделі та автентифікація' x-i18n: - generated_at: "2026-05-04T22:20:04Z" + generated_at: "2026-05-05T00:49:30Z" model: gpt-5.5 provider: openai - source_hash: bf06266926cecc06d8799cb17f42d96cdaa09ad83c20e8d4dcc3bcccbd840abc + source_hash: 1e60abcd6aa99121200de0e45cc3efa6334e668cbe6a4b590610c53d17e03a54 source_path: help/faq-models.md workflow: 16 --- - Питання й відповіді про моделі та профілі автентифікації. Про налаштування, сесії, Gateway, канали й - усунення несправностей див. основний [FAQ](/uk/help/faq). + Питання й відповіді про моделі та профілі автентифікації. Про налаштування, сесії, gateway, канали та + усунення несправностей див. основні [часті запитання](/uk/help/faq). ## Моделі: стандартні значення, вибір, псевдоніми, перемикання @@ -28,32 +28,32 @@ x-i18n: agents.defaults.model.primary ``` - Моделі вказуються як `provider/model` (приклад: `openai/gpt-5.5` або `openai-codex/gpt-5.5`). Якщо ви пропустите постачальника, OpenClaw спочатку спробує псевдонім, потім унікальний збіг налаштованого постачальника для цього точного ідентифікатора моделі, і лише після цього повернеться до налаштованого постачальника за замовчуванням як застарілого шляху сумісності. Якщо цей постачальник більше не надає налаштовану модель за замовчуванням, OpenClaw повертається до першої налаштованої пари постачальник/модель, замість показу застарілого значення постачальника, який було вилучено. Утім, вам варто **явно** задавати `provider/model`. + На моделі посилаються як на `provider/model` (приклад: `openai/gpt-5.5` або `openai-codex/gpt-5.5`). Якщо ви пропустите провайдера, OpenClaw спершу спробує псевдонім, потім унікальний збіг налаштованого провайдера для цього точного id моделі, і лише після цього повернеться до налаштованого провайдера за замовчуванням як до застарілого шляху сумісності. Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw повернеться до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле стандартне значення для видаленого провайдера. Вам усе одно слід **явно** встановити `provider/model`. - **Рекомендоване значення за замовчуванням:** використовуйте найсильнішу модель найновішого покоління, доступну у вашому стеку постачальників. - **Для агентів з інструментами або недовіреним введенням:** надавайте перевагу потужності моделі, а не вартості. - **Для звичайного чату з низькими ризиками:** використовуйте дешевші резервні моделі й маршрутизуйте за роллю агента. + **Рекомендоване значення за замовчуванням:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів. + **Для агентів з інструментами або ненадійними вхідними даними:** віддавайте пріоритет силі моделі, а не вартості. + **Для звичайного чату з низькими ризиками:** використовуйте дешевші резервні моделі та маршрутизуйте за роллю агента. MiniMax має власну документацію: [MiniMax](/uk/providers/minimax) і - [Локальні моделі](/uk/gateway/local-models). + [локальні моделі](/uk/gateway/local-models). - Практичне правило: використовуйте **найкращу модель, яку можете собі дозволити** для роботи з високими ризиками, а дешевшу - модель — для звичайного чату або підсумків. Ви можете маршрутизувати моделі для кожного агента й використовувати субагентів для - паралелізації довгих завдань (кожен субагент споживає токени). Див. [Моделі](/uk/concepts/models) і + Правило: використовуйте **найкращу модель, яку можете собі дозволити**, для роботи з високими ризиками, і дешевшу + модель для звичайного чату або підсумків. Ви можете маршрутизувати моделі для кожного агента й використовувати субагентів, щоб + паралелізувати довгі завдання (кожен субагент споживає токени). Див. [Моделі](/uk/concepts/models) і [Субагенти](/uk/tools/subagents). - Важливе попередження: слабші або надмірно квантовані моделі вразливіші до prompt + Суворе застереження: слабші або надмірно квантизовані моделі вразливіші до prompt injection і небезпечної поведінки. Див. [Безпека](/uk/gateway/security). Більше контексту: [Моделі](/uk/concepts/models). - - Використовуйте **команди моделі** або редагуйте лише поля **model**. Уникайте повної заміни конфігурації. + + Використовуйте **команди моделей** або редагуйте лише поля **model**. Уникайте повної заміни конфігурації. Безпечні варіанти: @@ -62,46 +62,46 @@ x-i18n: - `openclaw configure --section model` (інтерактивно) - редагуйте `agents.defaults.model` у `~/.openclaw/openclaw.json` - Уникайте `config.apply` з частковим об'єктом, якщо ви не маєте наміру замінити всю конфігурацію. - Для редагувань через RPC спочатку перегляньте за допомогою `config.schema.lookup` і віддавайте перевагу `config.patch`. Дані lookup надають нормалізований шлях, коротку документацію/обмеження схеми та підсумки безпосередніх дочірніх елементів + Уникайте `config.apply` з частковим об’єктом, якщо не маєте наміру замінити всю конфігурацію. + Для RPC-редагувань спершу перевірте через `config.schema.lookup` і віддавайте перевагу `config.patch`. Корисне навантаження lookup дає нормалізований шлях, поверхневу документацію/обмеження схеми та підсумки безпосередніх дочірніх елементів для часткових оновлень. - Якщо ви перезаписали конфігурацію, відновіть її з резервної копії або повторно запустіть `openclaw doctor` для виправлення. + Якщо ви перезаписали конфігурацію, відновіть її з резервної копії або повторно запустіть `openclaw doctor`, щоб виправити. Документація: [Моделі](/uk/concepts/models), [Налаштування](/uk/cli/configure), [Конфігурація](/uk/cli/config), [Doctor](/uk/gateway/doctor). - + Так. Ollama — найпростіший шлях для локальних моделей. Найшвидше налаштування: 1. Установіть Ollama з `https://ollama.com/download` 2. Завантажте локальну модель, наприклад `ollama pull gemma4` - 3. Якщо також потрібні хмарні моделі, запустіть `ollama signin` + 3. Якщо також потрібні хмарні моделі, виконайте `ollama signin` 4. Запустіть `openclaw onboard` і виберіть `Ollama` 5. Виберіть `Local` або `Cloud + Local` - Нотатки: + Примітки: - - `Cloud + Local` дає вам хмарні моделі разом із вашими локальними моделями Ollama - - хмарні моделі на кшталт `kimi-k2.5:cloud` не потребують локального завантаження + - `Cloud + Local` дає хмарні моделі разом із вашими локальними моделями Ollama + - хмарні моделі, як-от `kimi-k2.5:cloud`, не потребують локального завантаження - для ручного перемикання використовуйте `openclaw models list` і `openclaw models set ollama/` - Примітка щодо безпеки: менші або сильно квантовані моделі вразливіші до prompt + Примітка щодо безпеки: менші або сильно квантизовані моделі вразливіші до prompt injection. Ми наполегливо рекомендуємо **великі моделі** для будь-якого бота, який може використовувати інструменти. - Якщо ви все одно хочете малі моделі, увімкніть ізоляцію та суворі allowlist інструментів. + Якщо ви все ж хочете малі моделі, увімкніть sandboxing і суворі списки дозволених інструментів. - Документація: [Ollama](/uk/providers/ollama), [Локальні моделі](/uk/gateway/local-models), - [Постачальники моделей](/uk/concepts/model-providers), [Безпека](/uk/gateway/security), - [Ізоляція](/uk/gateway/sandboxing). + Документація: [Ollama](/uk/providers/ollama), [локальні моделі](/uk/gateway/local-models), + [провайдери моделей](/uk/concepts/model-providers), [безпека](/uk/gateway/security), + [sandboxing](/uk/gateway/sandboxing). - - Ці розгортання можуть відрізнятися й змінюватися з часом; фіксованої рекомендації щодо постачальника немає. - - Перевірте поточне runtime-налаштування на кожному gateway за допомогою `openclaw models status`. - - Для агентів із вимогами до безпеки або з інструментами використовуйте найсильнішу модель найновішого покоління з доступних. + - Ці розгортання можуть відрізнятися й змінюватися з часом; фіксованої рекомендації щодо провайдера немає. + - Перевіряйте поточне налаштування runtime на кожному Gateway за допомогою `openclaw models status`. + - Для агентів із підвищеними вимогами до безпеки або з інструментами використовуйте найсильнішу модель останнього покоління, доступну вам. @@ -120,7 +120,7 @@ x-i18n: Це вбудовані псевдоніми. Користувацькі псевдоніми можна додати через `agents.defaults.models`. - Ви можете переглянути доступні моделі за допомогою `/model`, `/model list` або `/model status`. + Ви можете перелічити доступні моделі за допомогою `/model`, `/model list` або `/model status`. `/model` (і `/model list`) показує компактний нумерований вибір. Виберіть за номером: @@ -128,17 +128,17 @@ x-i18n: /model 3 ``` - Також можна примусово задати конкретний профіль автентифікації для постачальника (для окремої сесії): + Також можна примусово вказати конкретний профіль автентифікації для провайдера (для окремої сесії): ``` /model opus@anthropic:default /model opus@anthropic:work ``` - Порада: `/model status` показує, який агент активний, який файл `auth-profiles.json` використовується і який профіль автентифікації буде спробувано наступним. - Він також показує налаштований endpoint постачальника (`baseUrl`) і режим API (`api`), якщо доступно. + Порада: `/model status` показує, який агент активний, який файл `auth-profiles.json` використовується і який профіль автентифікації буде спробовано наступним. + Він також показує налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), коли вони доступні. - **Як скасувати закріплення профілю, заданого через @profile?** + **Як відкріпити профіль, який я встановив через @profile?** Повторно запустіть `/model` **без** суфікса `@profile`: @@ -151,23 +151,23 @@ x-i18n: - + Так. Розглядайте вибір моделі та вибір runtime окремо: - - **Нативний агент програмування Codex:** установіть `agents.defaults.model.primary` у `openai/gpt-5.5`, а `agents.defaults.agentRuntime.id` у `"codex"`. Увійдіть через `openclaw models auth login --provider openai-codex`, коли хочете використовувати автентифікацію підписки ChatGPT/Codex. + - **Нативний агент кодування Codex:** встановіть `agents.defaults.model.primary` на `openai/gpt-5.5`, а `agents.defaults.agentRuntime.id` на `"codex"`. Увійдіть через `openclaw models auth login --provider openai-codex`, коли хочете використовувати автентифікацію підписки ChatGPT/Codex. - **Прямі завдання OpenAI API через PI:** використовуйте `/model openai/gpt-5.5` без перевизначення runtime Codex і налаштуйте `OPENAI_API_KEY`. - - **Codex OAuth через PI:** використовуйте `/model openai-codex/gpt-5.5` лише тоді, коли навмисно хочете звичайний runner PI з Codex OAuth. - - **Субагенти:** маршрутизуйте завдання програмування до агента лише для Codex із власною моделлю та стандартним `agentRuntime`. + - **Codex OAuth через PI:** використовуйте `/model openai-codex/gpt-5.5` лише тоді, коли свідомо хочете звичайний runner PI з Codex OAuth. + - **Субагенти:** маршрутизуйте завдання кодування до агента лише для Codex із власною моделлю та стандартним `agentRuntime`. - Див. [Моделі](/uk/concepts/models) і [Slash-команди](/uk/tools/slash-commands). + Див. [Моделі](/uk/concepts/models) і [слеш-команди](/uk/tools/slash-commands). - Використовуйте перемикач сесії або стандартне значення в конфігурації: + Використовуйте перемикач сесії або стандартне значення конфігурації: - - **Для окремої сесії:** надішліть `/fast on`, коли сесія використовує `openai/gpt-5.5` або `openai-codex/gpt-5.5`. - - **Стандартне значення для моделі:** установіть `agents.defaults.models["openai/gpt-5.5"].params.fastMode` або `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` у `true`. + - **Для окремої сесії:** надішліть `/fast on`, поки сесія використовує `openai/gpt-5.5` або `openai-codex/gpt-5.5`. + - **Стандартне значення для моделі:** встановіть `agents.defaults.models["openai/gpt-5.5"].params.fastMode` або `agents.defaults.models["openai-codex/gpt-5.5"].params.fastMode` на `true`. Приклад: @@ -187,15 +187,15 @@ x-i18n: } ``` - Для OpenAI швидкий режим відповідає `service_tier = "priority"` у підтримуваних нативних запитах Responses. Перевизначення сесії `/fast` мають пріоритет над стандартними значеннями конфігурації. + Для OpenAI швидкий режим відображається на `service_tier = "priority"` у підтримуваних нативних запитах Responses. Сесійні перевизначення `/fast` мають пріоритет над стандартними значеннями конфігурації. - Див. [Thinking і швидкий режим](/uk/tools/thinking) та [Швидкий режим OpenAI](/uk/providers/openai#fast-mode). + Див. [мислення та швидкий режим](/uk/tools/thinking) і [швидкий режим OpenAI](/uk/providers/openai#fast-mode). - Якщо задано `agents.defaults.models`, він стає **allowlist** для `/model` і будь-яких - перевизначень сесії. Вибір моделі, якої немає в цьому списку, повертає: + Якщо задано `agents.defaults.models`, він стає **списком дозволених** для `/model` і будь-яких + сесійних перевизначень. Вибір моделі, якої немає в цьому списку, повертає: ``` Model "provider/model" is not allowed. Use /models to list providers, or /models to list models. @@ -203,26 +203,27 @@ x-i18n: ``` Ця помилка повертається **замість** звичайної відповіді. Виправлення: додайте модель до - `agents.defaults.models`, видаліть allowlist або виберіть модель з `/model list`. - Якщо команда також містила `--runtime codex`, спочатку додайте модель, а потім повторіть + `agents.defaults.models`, видаліть список дозволених або виберіть модель з `/model list`. + Якщо команда також містила `--runtime codex`, спершу додайте модель, а потім повторіть ту саму команду `/model provider/model --runtime codex`. - Це означає, що **постачальника не налаштовано** (не знайдено конфігурації постачальника MiniMax або профілю автентифікації), тому модель неможливо розв'язати. + Це означає, що **провайдера не налаштовано** (не знайдено конфігурацію провайдера MiniMax або профіль автентифікації), + тому модель не можна розпізнати. - Контрольний список виправлення: + Контрольний список для виправлення: - 1. Оновіться до поточного релізу OpenClaw (або запустіть із вихідного коду `main`), потім перезапустіть gateway. - 2. Переконайтеся, що MiniMax налаштовано (майстер або JSON), або що автентифікація MiniMax - існує в env/профілях автентифікації, щоб відповідного постачальника можна було інжектувати + 1. Оновіться до поточного випуску OpenClaw (або запустіть із source `main`), потім перезапустіть gateway. + 2. Переконайтеся, що MiniMax налаштовано (майстром або JSON), або що автентифікація MiniMax + існує в env/профілях автентифікації, щоб можна було інжектувати відповідного провайдера (`MINIMAX_API_KEY` для `minimax`, `MINIMAX_OAUTH_TOKEN` або збережений MiniMax OAuth для `minimax-portal`). - 3. Використовуйте точний ідентифікатор моделі (з урахуванням регістру) для вашого шляху автентифікації: + 3. Використовуйте точний id моделі (з урахуванням регістру) для вашого шляху автентифікації: `minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed` для налаштування - з API-ключем, або `minimax-portal/MiniMax-M2.7` / - `minimax-portal/MiniMax-M2.7-highspeed` для налаштування OAuth. + через API-ключ, або `minimax-portal/MiniMax-M2.7` / + `minimax-portal/MiniMax-M2.7-highspeed` для налаштування через OAuth. 4. Запустіть: ```bash @@ -235,7 +236,7 @@ x-i18n: - + Так. Використовуйте **MiniMax як стандартну модель** і перемикайте моделі **для окремої сесії**, коли потрібно. Резервні варіанти призначені для **помилок**, а не для "складних завдань", тому використовуйте `/model` або окремого агента. @@ -268,12 +269,12 @@ x-i18n: - Стандартна модель агента B: OpenAI - Маршрутизуйте за агентом або використовуйте `/agent` для перемикання - Документація: [Моделі](/uk/concepts/models), [Маршрутизація кількох агентів](/uk/concepts/multi-agent), [MiniMax](/uk/providers/minimax), [OpenAI](/uk/providers/openai). + Документація: [Моделі](/uk/concepts/models), [маршрутизація Multi-Agent](/uk/concepts/multi-agent), [MiniMax](/uk/providers/minimax), [OpenAI](/uk/providers/openai). - - Так. OpenClaw постачається з кількома стандартними скороченнями (застосовуються лише тоді, коли модель існує в `agents.defaults.models`): + + Так. OpenClaw постачає кілька стандартних скорочень (застосовуються лише тоді, коли модель існує в `agents.defaults.models`): - `opus` → `anthropic/claude-opus-4-6` - `sonnet` → `anthropic/claude-sonnet-4-6` @@ -284,7 +285,7 @@ x-i18n: - `gemini-flash` → `google/gemini-3-flash-preview` - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` - Якщо ви задасте власний псевдонім із тією самою назвою, ваше значення матиме пріоритет. + Якщо ви задасте власний псевдонім із такою самою назвою, ваше значення матиме пріоритет. @@ -306,12 +307,12 @@ x-i18n: } ``` - Потім `/model sonnet` (або `/`, коли підтримується) розв'язується до цього ідентифікатора моделі. + Тоді `/model sonnet` (або `/`, коли підтримується) розпізнається як цей ID моделі. - - OpenRouter (оплата за токен; багато моделей): + + OpenRouter (оплата за токени; багато моделей): ```json5 { @@ -341,9 +342,9 @@ x-i18n: Якщо ви посилаєтеся на провайдера/модель, але потрібний ключ провайдера відсутній, ви отримаєте помилку автентифікації під час виконання (наприклад, `No API key found for provider "zai"`). - **Ключ API для провайдера не знайдено після додавання нового агента** + **Після додавання нового агента ключ API для провайдера не знайдено** - Зазвичай це означає, що **новий агент** має порожнє сховище автентифікації. Автентифікація налаштовується окремо для кожного агента та + Зазвичай це означає, що **новий агент** має порожнє сховище автентифікації. Автентифікація налаштовується для кожного агента окремо та зберігається в: ``` @@ -354,64 +355,64 @@ x-i18n: - Запустіть `openclaw agents add ` і налаштуйте автентифікацію під час роботи майстра. - Або скопіюйте лише переносні статичні профілі `api_key` / `token` зі сховища автентифікації основного агента до сховища автентифікації нового агента. - - Для профілів OAuth увійдіть із нового агента, коли йому потрібен власний обліковий запис; інакше OpenClaw може читати з типового/основного агента без клонування токенів оновлення. + - Для профілів OAuth увійдіть із нового агента, коли йому потрібен власний обліковий запис; інакше OpenClaw може читати дані через стандартного/основного агента без клонування токенів оновлення. - **Не** використовуйте повторно `agentDir` для різних агентів; це спричиняє конфлікти автентифікації/сеансів. + **Не** використовуйте повторно `agentDir` для різних агентів; це спричиняє конфлікти автентифікації/сесій. -## Перемикання моделі після збою та "Усі моделі зазнали збою" +## Резервне перемикання моделей і "All models failed" - - Перемикання після збою відбувається у два етапи: + + Резервне перемикання відбувається у два етапи: - 1. **Ротація профілю автентифікації** в межах того самого провайдера. - 2. **Резервне перемикання моделі** на наступну модель у `agents.defaults.model.fallbacks`. + 1. **Ротація профілів автентифікації** у межах того самого провайдера. + 2. **Резервний вибір моделі** до наступної моделі в `agents.defaults.model.fallbacks`. - До проблемних профілів застосовуються періоди очікування (експоненційне відкладення), тому OpenClaw може продовжувати відповідати, навіть коли провайдер обмежує частоту запитів або тимчасово дає збій. + Періоди охолодження застосовуються до профілів, які дають збої (експоненційна затримка), тому OpenClaw може продовжувати відповідати, навіть коли провайдер обмежує частоту запитів або тимчасово не працює. - Кошик обмеження частоти охоплює не лише звичайні відповіді `429`. OpenClaw - також розглядає повідомлення на кшталт `Too many concurrent requests`, + До кошика обмежень частоти входять не лише звичайні відповіді `429`. OpenClaw + також вважає повідомлення на кшталт `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `resource exhausted` і періодичні - обмеження вікна використання (`weekly/monthly limit reached`) як - обмеження частоти, що потребують перемикання після збою. + обмеження вікна використання (`weekly/monthly limit reached`) обмеженнями + частоти, для яких варто виконати резервне перемикання. - Деякі відповіді, схожі на білінгові, не є `402`, а деякі HTTP-відповіді `402` + Деякі відповіді, схожі на помилки білінгу, не є `402`, а деякі HTTP-відповіді `402` також залишаються в цьому тимчасовому кошику. Якщо провайдер повертає - явний білінговий текст для `401` або `403`, OpenClaw усе одно може залишити це - в білінговій категорії, але текстові зіставники для окремих провайдерів залишаються обмеженими - провайдером, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Якщо повідомлення `402` + явний текст про білінг для `401` або `403`, OpenClaw усе одно може залишити це + в напрямі білінгу, але провайдер-специфічні текстові зіставлення залишаються + обмеженими провайдером, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Якщо повідомлення `402` натомість схоже на повторюване обмеження вікна використання або ліміт витрат організації/робочого простору (`daily limit reached, resets tomorrow`, - `organization spending limit exceeded`), OpenClaw розглядає його як + `organization spending limit exceeded`), OpenClaw трактує його як `rate_limit`, а не як тривале вимкнення через білінг. Помилки переповнення контексту відрізняються: сигнатури на кшталт `request_too_large`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model` або `ollama error: context length - exceeded` залишаються на шляху Compaction/повторної спроби замість переходу до - резервного перемикання моделі. + exceeded` залишаються на шляху Compaction/повторної спроби, а не переводять до + резервної моделі. - Узагальнений текст помилки сервера навмисно вужчий, ніж «будь-що з - unknown/error у тексті». OpenClaw розглядає тимчасові форми, обмежені провайдером, - як-от чисте Anthropic `An unknown error occurred`, чисте OpenRouter + Загальний текст помилки сервера навмисно вужчий, ніж "усе, що містить + unknown/error". OpenClaw справді трактує провайдер-специфічні тимчасові форми, + такі як чисте Anthropic `An unknown error occurred`, чисте OpenRouter `Provider returned error`, помилки причини зупинки на кшталт `Unhandled stop reason: - error`, JSON-навантаження `api_error` з тимчасовим серверним текстом + error`, JSON-навантаження `api_error` із тимчасовим текстом сервера (`internal server error`, `unknown error, 520`, `upstream error`, `backend - error`) і помилки зайнятості провайдера, як-от `ModelNotReadyException`, як - сигнали тайм-ауту/перевантаження, що потребують перемикання після збою, коли контекст провайдера + error`) і помилки зайнятості провайдера, такі як `ModelNotReadyException`, як + сигнали тайм-ауту/перевантаження, для яких варто виконати резервне перемикання, коли контекст провайдера збігається. - Узагальнений внутрішній текст резервного сценарію, як-от `LLM request failed with an unknown + Загальний внутрішній текст резервного збою, як-от `LLM request failed with an unknown error.`, залишається консервативним і сам по собі не запускає резервне перемикання моделі. - - Це означає, що система спробувала використати ідентифікатор профілю автентифікації `anthropic:default`, але не змогла знайти для нього облікові дані в очікуваному сховищі автентифікації. + + Це означає, що система спробувала використати ID профілю автентифікації `anthropic:default`, але не змогла знайти для нього облікові дані в очікуваному сховищі автентифікації. **Контрольний список виправлення:** @@ -419,80 +420,82 @@ x-i18n: - Поточний: `~/.openclaw/agents//agent/auth-profiles.json` - Застарілий: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`) - **Підтвердьте, що вашу змінну середовища завантажує Gateway** - - Якщо ви встановили `ANTHROPIC_API_KEY` у своїй оболонці, але запускаєте Gateway через systemd/launchd, він може її не успадкувати. Помістіть її в `~/.openclaw/.env` або увімкніть `env.shellEnv`. - - **Переконайтеся, що ви редагуєте правильного агента** - - У конфігураціях із кількома агентами може бути кілька файлів `auth-profiles.json`. - - **Перевірте стан моделі/автентифікації** - - Використайте `openclaw models status`, щоб переглянути налаштовані моделі та чи автентифіковані провайдери. + - Якщо ви задали `ANTHROPIC_API_KEY` у своїй оболонці, але запускаєте Gateway через systemd/launchd, він може її не успадкувати. Помістіть її в `~/.openclaw/.env` або ввімкніть `env.shellEnv`. + - **Переконайтеся, що редагуєте правильного агента** + - Налаштування з кількома агентами означають, що може існувати кілька файлів `auth-profiles.json`. + - **Виконайте базову перевірку стану моделі/автентифікації** + - Використайте `openclaw models status`, щоб побачити налаштовані моделі та чи автентифіковані провайдери. - **Контрольний список виправлення для "Облікові дані для профілю anthropic не знайдено"** + **Контрольний список виправлення для "No credentials found for profile anthropic"** - Це означає, що запуск закріплено за профілем автентифікації Anthropic, але Gateway + Це означає, що запуск прив’язано до профілю автентифікації Anthropic, але Gateway не може знайти його у своєму сховищі автентифікації. - **Використайте Claude CLI** - - Запустіть `openclaw models auth login --provider anthropic --method cli --set-default` на хості gateway. - - **Якщо натомість ви хочете використати ключ API** - - Помістіть `ANTHROPIC_API_KEY` у `~/.openclaw/.env` на **хості gateway**. - - Очистьте будь-який закріплений порядок, який примусово вимагає відсутній профіль: + - Запустіть `openclaw models auth login --provider anthropic --method cli --set-default` на хості Gateway. + - **Якщо натомість хочете використовувати ключ API** + - Помістіть `ANTHROPIC_API_KEY` у `~/.openclaw/.env` на **хості Gateway**. + - Очистьте будь-який закріплений порядок, який примусово використовує відсутній профіль: ```bash openclaw models auth order clear --provider anthropic ``` - - **Підтвердьте, що виконуєте команди на хості gateway** - - У віддаленому режимі профілі автентифікації зберігаються на машині gateway, а не на вашому ноутбуці. + - **Підтвердьте, що запускаєте команди на хості Gateway** + - У віддаленому режимі профілі автентифікації зберігаються на машині Gateway, а не на вашому ноутбуці. - - Якщо ваша конфігурація моделі включає Google Gemini як резервний варіант (або ви перемкнулися на скорочення Gemini), OpenClaw спробує його під час резервного перемикання моделі. Якщо ви не налаштували облікові дані Google, ви побачите `No API key found for provider "google"`. + + Якщо ваша конфігурація моделі містить Google Gemini як резервний варіант (або ви перемкнулися на скорочення Gemini), OpenClaw спробує його під час резервного перемикання моделі. Якщо ви не налаштували облікові дані Google, побачите `No API key found for provider "google"`. - Виправлення: або надайте автентифікацію Google, або приберіть/уникайте моделей Google у `agents.defaults.model.fallbacks` / псевдонімах, щоб резервний перехід не спрямовував туди. + Виправлення: або надайте автентифікацію Google, або вилучіть/уникайте моделей Google у `agents.defaults.model.fallbacks` / псевдонімах, щоб резервне перемикання не маршрутизувалося туди. - **Запит LLM відхилено: потрібен підпис мислення (Google Antigravity)** + **Запит LLM відхилено: потрібна сигнатура thinking (Google Antigravity)** - Причина: історія сеансу містить **блоки мислення без підписів** (часто з - перерваного/часткового потоку). Google Antigravity вимагає підписи для блоків мислення. + Причина: історія сесії містить **блоки thinking без сигнатур** (часто з + перерваного/часткового потоку). Google Antigravity вимагає сигнатури для блоків thinking. - Виправлення: OpenClaw тепер вилучає непідписані блоки мислення для Google Antigravity Claude. Якщо це все ще з'являється, почніть **новий сеанс** або встановіть `/thinking off` для цього агента. + Виправлення: OpenClaw тепер вилучає непідписані блоки thinking для Google Antigravity Claude. Якщо проблема все ще з’являється, почніть **нову сесію** або задайте `/thinking off` для цього агента. ## Профілі автентифікації: що це таке і як ними керувати -Пов'язано: [/concepts/oauth](/uk/concepts/oauth) (потоки OAuth, зберігання токенів, шаблони кількох облікових записів) +Пов’язано: [/concepts/oauth](/uk/concepts/oauth) (потоки OAuth, зберігання токенів, шаблони кількох облікових записів) - Профіль автентифікації - це іменований запис облікових даних (OAuth або API-ключ), прив'язаний до провайдера. Профілі зберігаються в: + Профіль автентифікації — це іменований запис облікових даних (OAuth або ключ API), прив’язаний до провайдера. Профілі зберігаються в: ``` ~/.openclaw/agents//agent/auth-profiles.json ``` + Щоб переглянути збережені профілі без виведення секретів, запустіть `openclaw models auth list` (за потреби з `--provider ` або `--json`). Докладніше див. [Models CLI](/uk/cli/models#openclaw-models-auth-list). + OpenClaw використовує ID із префіксом провайдера, наприклад: - - `anthropic:default` (типово, коли немає ідентичності email) + - `anthropic:default` (поширено, коли немає ідентичності з електронною поштою) - `anthropic:` для ідентичностей OAuth - - власні ID, які ви обираєте (наприклад, `anthropic:work`) + - власні ID, які ви вибираєте (наприклад, `anthropic:work`) - Так. Конфігурація підтримує необов'язкові метадані для профілів і порядок для кожного провайдера (`auth.order.`). Це **не** зберігає секрети; воно зіставляє ID з провайдером/режимом і задає порядок ротації. + Так. Конфігурація підтримує необов’язкові метадані для профілів і порядок для кожного провайдера (`auth.order.`). Це **не** зберігає секрети; воно зіставляє ID із провайдером/режимом і задає порядок ротації. - OpenClaw може тимчасово пропустити профіль, якщо він перебуває в короткому **періоді охолодження** (ліміти частоти/тайм-аути/помилки автентифікації) або довшому стані **вимкнено** (білінг/недостатньо кредитів). Щоб це перевірити, виконайте `openclaw models status --json` і перегляньте `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`. + OpenClaw може тимчасово пропустити профіль, якщо він перебуває в короткому **періоді охолодження** (обмеження частоти/тайм-аути/збої автентифікації) або довшому **вимкненому** стані (білінг/недостатньо кредитів). Щоб це перевірити, запустіть `openclaw models status --json` і перегляньте `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`. - Періоди охолодження через ліміти частоти можуть бути прив'язані до моделі. Профіль, який перебуває в охолодженні + Періоди охолодження через обмеження частоти можуть бути прив’язані до моделі. Профіль, який охолоджується для однієї моделі, усе ще може бути придатним для спорідненої моделі того самого провайдера, тоді як вікна білінгу/вимкнення все ще блокують увесь профіль. - Також можна задати перевизначення порядку **для окремого агента** (зберігається в `auth-state.json` цього агента) через CLI: + Ви також можете задати перевизначення порядку **для окремого агента** (зберігається в `auth-state.json` цього агента) через CLI: ```bash # Defaults to the configured default agent (omit --agent) @@ -520,23 +523,23 @@ x-i18n: openclaw models status --probe ``` - Якщо збережений профіль пропущено в явному порядку, проба повідомляє - `excluded_by_auth_order` для цього профілю замість того, щоб мовчки пробувати його. + Якщо збережений профіль пропущено в явному порядку, probe повідомляє + `excluded_by_auth_order` для цього профілю замість того, щоб непомітно його пробувати. - + OpenClaw підтримує обидва варіанти: - - **OAuth** часто використовує доступ за підпискою (де застосовно). - - **API-ключі** використовують оплату за токени. + - **OAuth** часто використовує доступ за підпискою (де це застосовно). + - **Ключі API** використовують оплату за токени. - Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і API-ключі. + Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і ключі API. -## Пов'язане +## Пов’язане - [FAQ](/uk/help/faq) — основний FAQ - [FAQ — швидкий старт і налаштування першого запуску](/uk/help/faq-first-run) diff --git a/docs/uk/security/network-proxy.md b/docs/uk/security/network-proxy.md index c5b556438..b6c47cc53 100644 --- a/docs/uk/security/network-proxy.md +++ b/docs/uk/security/network-proxy.md @@ -1,40 +1,40 @@ --- read_when: - - Вам потрібен багаторівневий захист від SSRF-атак і атак із переприв’язуванням DNS + - Вам потрібен багаторівневий захист від SSRF і атак переприв’язування DNS - Налаштування зовнішнього прямого проксі для трафіку середовища виконання OpenClaw -summary: Як маршрутизувати HTTP- та WebSocket-трафік середовища виконання OpenClaw через керований оператором фільтрувальний проксі +summary: Як спрямовувати HTTP- і WebSocket-трафік середовища виконання OpenClaw через керований оператором фільтрувальний проксі title: Мережевий проксі x-i18n: - generated_at: "2026-05-04T11:08:46Z" + generated_at: "2026-05-05T00:49:21Z" model: gpt-5.5 provider: openai - source_hash: eedbf3bac14800c34c7ca2e3b6879dac360a88d51b5b7449ddf41a4dd471648b + source_hash: f7ab345d172d63e388ff1221535efd19934dcbf3173f95bc69131f9ad672e0df source_path: security/network-proxy.md workflow: 16 --- # Мережевий проксі -OpenClaw може спрямовувати runtime HTTP- і WebSocket-трафік через керований оператором прямий проксі. Це необов'язковий додатковий рівень захисту для розгортань, яким потрібні централізований контроль вихідного трафіку, сильніший захист від SSRF і краща аудитованість мережі. +OpenClaw може маршрутизувати runtime HTTP- і WebSocket-трафік через керований оператором forward proxy. Це необов’язковий додатковий захист для розгортань, яким потрібні централізований контроль вихідного трафіку, сильніший захист від SSRF і краща аудитованість мережі. -OpenClaw не постачає, не завантажує, не запускає, не налаштовує й не сертифікує проксі. Ви запускаєте проксі-технологію, яка підходить для вашого середовища, а OpenClaw спрямовує через неї звичайні локальні для процесу HTTP- і WebSocket-клієнти. +OpenClaw не постачає, не завантажує, не запускає, не налаштовує й не сертифікує проксі. Ви запускаєте проксі-технологію, що відповідає вашому середовищу, а OpenClaw маршрутизує через неї звичайні process-local HTTP- і WebSocket-клієнти. ## Навіщо використовувати проксі? -Проксі дає операторам одну точку мережевого контролю для вихідного HTTP- і WebSocket-трафіку. Це може бути корисно навіть поза посиленням захисту від SSRF: +Проксі дає операторам одну мережеву точку керування для вихідного HTTP- і WebSocket-трафіку. Це може бути корисно навіть поза посиленням захисту від SSRF: -- Централізована політика: підтримуйте одну політику вихідного трафіку замість того, щоб покладатися на правильність мережевих правил у кожній точці HTTP-виклику застосунку. -- Перевірки під час підключення: оцінюйте призначення після DNS-резолюції та безпосередньо перед тим, як проксі відкриє висхідне з'єднання. -- Захист від DNS rebinding: зменште проміжок між DNS-перевіркою на рівні застосунку та фактичним вихідним з'єднанням. -- Ширше покриття JavaScript: спрямовуйте звичайні `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch і подібні клієнти одним шляхом. -- Аудитованість: записуйте дозволені й заборонені призначення на межі вихідного трафіку. -- Операційний контроль: застосовуйте правила призначень, сегментацію мережі, обмеження швидкості або списки дозволених вихідних адрес без повторного збирання OpenClaw. +- Централізована політика: підтримуйте одну політику вихідного трафіку замість того, щоб покладатися на правильність мережевих правил у кожному місці HTTP-виклику застосунку. +- Перевірки під час підключення: оцінюйте призначення після DNS-резолюції та безпосередньо перед тим, як проксі відкриє upstream-з’єднання. +- Захист від DNS rebinding: зменшуйте проміжок між DNS-перевіркою на рівні застосунку та фактичним вихідним з’єднанням. +- Ширше покриття JavaScript: маршрутизуйте звичайні `fetch`, `node:http`, `node:https`, WebSocket, axios, got, node-fetch і подібні клієнти тим самим шляхом. +- Аудитованість: журналюйте дозволені й заборонені призначення на межі вихідного трафіку. +- Операційний контроль: застосовуйте правила призначень, сегментацію мережі, обмеження частоти або allowlist-и вихідного трафіку без перебудови OpenClaw. -Маршрутизація через проксі — це процесний захисний бар'єр для звичайного вихідного HTTP- і WebSocket-трафіку. Вона дає операторам шлях із закриттям у разі помилки для маршрутизації підтримуваних JavaScript HTTP-клієнтів через їхній власний фільтрувальний проксі, але це не мережевий sandbox на рівні ОС і не означає, що OpenClaw сертифікує політику призначень проксі. +Маршрутизація через проксі є процесним обмежувачем для звичайного вихідного HTTP- і WebSocket-трафіку. Вона дає операторам fail-closed шлях для маршрутизації підтримуваних JavaScript HTTP-клієнтів через власний фільтрувальний проксі, але не є мережевою пісочницею рівня ОС і не змушує OpenClaw сертифікувати політику призначень проксі. -## Як OpenClaw спрямовує трафік +## Як OpenClaw маршрутизує трафік -Коли `proxy.enabled=true` і налаштовано URL проксі, захищені runtime-процеси, як-от `openclaw gateway run`, `openclaw node run` і `openclaw agent --local`, спрямовують звичайний вихідний HTTP- і WebSocket-трафік через налаштований проксі: +Коли `proxy.enabled=true` і налаштовано URL проксі, захищені runtime-процеси, як-от `openclaw gateway run`, `openclaw node run` і `openclaw agent --local`, маршрутизують звичайний вихідний HTTP- і WebSocket-трафік через налаштований проксі: ```text OpenClaw process @@ -43,27 +43,28 @@ OpenClaw process WebSocket clients -> operator-managed filtering proxy -> public internet ``` -Публічний контракт — це поведінка маршрутизації, а не внутрішні хуки Node, які використовуються для її реалізації. Клієнти WebSocket контрольної площини OpenClaw Gateway використовують вузький прямий шлях для local loopback Gateway RPC-трафіку, коли URL Gateway використовує `localhost` або буквальну loopback IP-адресу, як-от `127.0.0.1` чи `[::1]`. Цей шлях контрольної площини має бути здатний досягати loopback Gateway, навіть коли операторський проксі блокує loopback-призначення. Звичайні runtime HTTP- і WebSocket-запити й надалі використовують налаштований проксі. +Публічним контрактом є поведінка маршрутизації, а не внутрішні хуки Node, використані для її реалізації. WebSocket-клієнти control-plane OpenClaw Gateway використовують вузький прямий шлях для RPC-трафіку Gateway через local loopback, коли URL Gateway використовує `localhost` або буквальну IP-адресу loopback, як-от `127.0.0.1` чи `[::1]`. Цей шлях control-plane має мати змогу досягати loopback Gateway навіть тоді, коли операторський проксі блокує loopback-призначення. Звичайні runtime HTTP- і WebSocket-запити й надалі використовують налаштований проксі. -Внутрішньо OpenClaw використовує для цієї функції два процесні хуки маршрутизації: +Внутрішньо OpenClaw використовує два процесні хуки маршрутизації для цієї можливості: -- Маршрутизація диспетчера Undici покриває `fetch`, клієнти на основі undici та транспорти, які надають власний диспетчер undici. -- Маршрутизація `global-agent` покриває викликачів ядра Node `node:http` і `node:https`, включно з багатьма бібліотеками, побудованими поверх `http.request`, `https.request`, `http.get` і `https.get`. Керований режим проксі примусово використовує цей глобальний агент, щоб явні HTTP-агенти Node випадково не обходили операторський проксі. +- Маршрутизація через dispatcher Undici охоплює `fetch`, клієнти на основі undici та транспорти, що надають власний undici dispatcher. +- Маршрутизація `global-agent` охоплює викликачі ядра Node `node:http` і `node:https`, зокрема багато бібліотек, побудованих поверх `http.request`, `https.request`, `http.get` і `https.get`. Керований режим проксі примусово використовує цей глобальний агент, щоб явні Node HTTP-агенти випадково не обходили операторський проксі. -Деякі plugins володіють власними транспортами, яким потрібне явне підключення проксі навіть за наявності процесної маршрутизації. Наприклад, транспорт Telegram Bot API використовує власний HTTP/1-диспетчер undici і тому враховує змінні середовища процесного проксі плюс керований fallback `OPENCLAW_PROXY_URL` у цьому специфічному для власника транспортному шляху. +Деякі Plugin-и володіють власними транспортами, яким потрібне явне підключення проксі, навіть коли існує процесна маршрутизація. Наприклад, транспорт Bot API Telegram використовує власний HTTP/1 undici dispatcher і тому враховує process proxy env, а також керований fallback `OPENCLAW_PROXY_URL` у цьому owner-specific транспортному шляху. -Сам URL проксі має використовувати `http://`. HTTPS-призначення все одно підтримуються через проксі за допомогою HTTP `CONNECT`; це лише означає, що OpenClaw очікує звичайний HTTP-слухач прямого проксі, наприклад `http://127.0.0.1:3128`. +Сам URL проксі має використовувати `http://`. HTTPS-призначення все одно підтримуються через проксі за допомогою HTTP `CONNECT`; це означає лише, що OpenClaw очікує звичайний HTTP forward-proxy listener, як-от `http://127.0.0.1:3128`. -Поки проксі активний, OpenClaw очищає `no_proxy`, `NO_PROXY` і `GLOBAL_AGENT_NO_PROXY`. Ці списки обходу базуються на призначеннях, тому залишення там `localhost` або `127.0.0.1` дозволило б високоризиковим SSRF-цілям оминати фільтрувальний проксі. +Поки проксі активний, OpenClaw очищає `no_proxy`, `NO_PROXY` і `GLOBAL_AGENT_NO_PROXY`. Ці списки обходу базуються на призначеннях, тому залишені там `localhost` або `127.0.0.1` дали б змогу високоризиковим SSRF-цілям оминати фільтрувальний проксі. -Під час завершення роботи OpenClaw відновлює попереднє проксі-середовище й скидає кешований стан процесної маршрутизації. +Під час завершення роботи OpenClaw відновлює попереднє середовище проксі та скидає кешований стан процесної маршрутизації. -## Пов'язані терміни проксі +## Пов’язані терміни проксі -- `proxy.enabled` / `proxy.proxyUrl`: маршрутизація вихідного трафіку OpenClaw runtime через прямий проксі. Ця сторінка документує цю функцію. -- `gateway.auth.mode: "trusted-proxy"`: вхідна автентифікація через identity-aware зворотний проксі для доступу до Gateway. Див. [Автентифікація через довірений проксі](/uk/gateway/trusted-proxy-auth). -- `openclaw proxy`: локальний debug-проксі та інспектор захоплення для розробки й підтримки. Див. [openclaw proxy](/uk/cli/proxy). -- Налаштування проксі, специфічні для каналу або провайдера: перевизначення, специфічні для власника, для певного транспорту. Надавайте перевагу керованому мережевому проксі, коли мета — централізований контроль вихідного трафіку в межах runtime. +- `proxy.enabled` / `proxy.proxyUrl`: маршрутизація вихідного forward-proxy для runtime-вихідного трафіку OpenClaw. Ця сторінка документує цю можливість. +- `gateway.auth.mode: "trusted-proxy"`: вхідна identity-aware автентифікація reverse-proxy для доступу до Gateway. Див. [Автентифікація через довірений проксі](/uk/gateway/trusted-proxy-auth). +- `openclaw proxy`: локальний debug proxy та інспектор захоплення для розробки й підтримки. Див. [openclaw proxy](/uk/cli/proxy). +- `tools.web.fetch.useTrustedEnvProxy`: opt-in для `web_fetch`, що дозволяє контрольованому оператором HTTP(S) env proxy виконувати DNS-резолюцію, зберігаючи стандартне суворе DNS pinning і політику hostname. Див. [Web fetch](/uk/tools/web-fetch#trusted-env-proxy). +- Налаштування проксі, специфічні для каналу або провайдера: owner-specific перевизначення для конкретного транспорту. Надавайте перевагу керованому мережевому проксі, коли мета — централізований контроль вихідного трафіку в усьому runtime. ## Конфігурація @@ -81,9 +82,9 @@ OPENCLAW_PROXY_URL=http://127.0.0.1:3128 openclaw gateway run `proxy.proxyUrl` має пріоритет над `OPENCLAW_PROXY_URL`. -Якщо `enabled=true`, але не налаштовано чинний URL проксі, захищені команди завершують запуск із помилкою замість fallback до прямого мережевого доступу. +Якщо `enabled=true`, але не налаштовано чинний URL проксі, захищені команди завершуються помилкою запуску замість fallback до прямого мережевого доступу. -Для керованих сервісів Gateway, запущених за допомогою `openclaw gateway start`, надавайте перевагу збереженню URL у конфігурації: +Для керованих сервісів Gateway, запущених через `openclaw gateway start`, бажано зберігати URL у конфігурації: ```bash openclaw config set proxy.enabled true @@ -92,9 +93,9 @@ openclaw gateway install --force openclaw gateway start ``` -Fallback через середовище найкраще підходить для запусків у передньому плані. Якщо ви використовуєте його зі встановленим сервісом, помістіть `OPENCLAW_PROXY_URL` у сталe середовище сервісу, наприклад `$OPENCLAW_STATE_DIR/.env` або `~/.openclaw/.env`, а потім перевстановіть сервіс, щоб launchd, systemd або Scheduled Tasks запускали gateway з цим значенням. +Fallback через середовище найкраще підходить для запусків у foreground. Якщо ви використовуєте його з інстальованим сервісом, помістіть `OPENCLAW_PROXY_URL` у довговічне середовище сервісу, наприклад `$OPENCLAW_STATE_DIR/.env` або `~/.openclaw/.env`, а потім перевстановіть сервіс, щоб launchd, systemd або Scheduled Tasks запускали Gateway із цим значенням. -Для команд `openclaw --container ...` OpenClaw передає `OPENCLAW_PROXY_URL` у дочірній CLI, націлений на контейнер, коли його встановлено. URL має бути досяжним ізсередини контейнера; `127.0.0.1` вказує на сам контейнер, а не на хост. OpenClaw відхиляє loopback URL проксі для команд, націлених на контейнер, якщо ви явно не перевизначите цю перевірку безпеки. +Для команд `openclaw --container ...` OpenClaw передає `OPENCLAW_PROXY_URL` у container-targeted дочірній CLI, коли його встановлено. URL має бути доступний зсередини контейнера; `127.0.0.1` посилається на сам контейнер, а не на хост. OpenClaw відхиляє loopback URL проксі для container-targeted команд, якщо ви явно не перевизначите цю перевірку безпеки. ## Вимоги до проксі @@ -102,53 +103,53 @@ Fallback через середовище найкраще підходить д Налаштуйте проксі так, щоб він: -- Прив'язувався лише до loopback або приватного довіреного інтерфейсу. -- Обмежував доступ так, щоб ним міг користуватися лише процес OpenClaw, хост, контейнер або сервісний обліковий запис. +- Прив’язувався лише до loopback або приватного довіреного інтерфейсу. +- Обмежував доступ так, щоб ним могли користуватися лише процес OpenClaw, хост, контейнер або обліковий запис сервісу. - Самостійно резолвив призначення та блокував IP-адреси призначень після DNS-резолюції. - Застосовував політику під час підключення як для звичайних HTTP-запитів, так і для HTTPS-тунелів `CONNECT`. -- Відхиляв обходи на основі призначення для loopback, приватних, link-local, metadata, multicast, reserved або documentation діапазонів. -- Уникав списків дозволених імен хостів, якщо ви повністю не довіряєте шляху DNS-резолюції. -- Записував призначення, рішення, статус і причину без логування тіл запитів, заголовків авторизації, cookies або інших секретів. -- Тримав політику проксі під контролем версій і переглядав зміни як конфігурацію, чутливу до безпеки. +- Відхиляв destination-based обходи для loopback, приватних, link-local, metadata, multicast, reserved або documentation діапазонів. +- Уникав allowlist-ів hostname, якщо ви не повністю довіряєте шляху DNS-резолюції. +- Журналював призначення, рішення, статус і причину без журналювання тіл запитів, authorization headers, cookies або інших секретів. +- Тримав політику проксі під контролем версій і переглядав зміни як security-sensitive конфігурацію. ## Рекомендовані заблоковані призначення -Використовуйте цей список заборон як відправну точку для будь-якого прямого проксі, firewall або політики вихідного трафіку. +Використовуйте цей denylist як початкову точку для будь-якого forward proxy, firewall або політики вихідного трафіку. -Логіка класифікатора OpenClaw на рівні застосунку міститься в `src/infra/net/ssrf.ts` і `src/shared/net/ip.ts`. Відповідні хуки паритету — це `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` і вбудована обробка IPv4 sentinel для NAT64, 6to4, Teredo, ISATAP та IPv4-mapped форм. Ці файли є корисними довідковими матеріалами під час підтримки зовнішньої політики проксі, але OpenClaw не експортує й не застосовує ці правила у вашому проксі автоматично. +Логіка application-level класифікатора OpenClaw міститься в `src/infra/net/ssrf.ts` і `src/shared/net/ip.ts`. Відповідні parity hooks — це `BLOCKED_HOSTNAMES`, `BLOCKED_IPV4_SPECIAL_USE_RANGES`, `BLOCKED_IPV6_SPECIAL_USE_RANGES`, `RFC2544_BENCHMARK_PREFIX` і обробка вбудованого IPv4 sentinel для NAT64, 6to4, Teredo, ISATAP та IPv4-mapped форм. Ці файли є корисними довідковими матеріалами під час підтримки зовнішньої політики проксі, але OpenClaw не експортує й не застосовує ці правила автоматично у вашому проксі. -| Діапазон або хост | Навіщо блокувати | -| ------------------------------------------------------------------------------------ | ------------------------------------------------- | -| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 loopback | -| `::1/128` | IPv6 loopback | -| `0.0.0.0/8`, `::/128` | Невизначені адреси та адреси цієї мережі | -| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Приватні мережі RFC1918 | -| `169.254.0.0/16`, `fe80::/10` | Link-local адреси та поширені шляхи cloud metadata | -| `169.254.169.254`, `metadata.google.internal` | Сервіси cloud metadata | -| `100.64.0.0/10` | Спільний адресний простір carrier-grade NAT | -| `198.18.0.0/15`, `2001:2::/48` | Діапазони для benchmark | -| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Діапазони special-use і documentation | -| `224.0.0.0/4`, `ff00::/8` | Multicast | -| `240.0.0.0/4` | Зарезервований IPv4 | -| `fc00::/7`, `fec0::/10` | Локальні/приватні діапазони IPv6 | -| `100::/64`, `2001:20::/28` | IPv6 discard і ORCHIDv2 діапазони | -| `64:ff9b::/96`, `64:ff9b:1::/48` | Префікси NAT64 з вбудованим IPv4 | -| `2002::/16`, `2001::/32` | 6to4 і Teredo з вбудованим IPv4 | -| `::/96`, `::ffff:0:0/96` | IPv4-compatible та IPv4-mapped IPv6 | +| Діапазон або хост | Навіщо блокувати | +| ------------------------------------------------------------------------------------ | ----------------------------------------------------- | +| `127.0.0.0/8`, `localhost`, `localhost.localdomain` | IPv4 loopback | +| `::1/128` | IPv6 loopback | +| `0.0.0.0/8`, `::/128` | Невизначені адреси та адреси цієї мережі | +| `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16` | Приватні мережі RFC1918 | +| `169.254.0.0/16`, `fe80::/10` | Link-local адреси та поширені шляхи cloud metadata | +| `169.254.169.254`, `metadata.google.internal` | Сервіси cloud metadata | +| `100.64.0.0/10` | Спільний адресний простір carrier-grade NAT | +| `198.18.0.0/15`, `2001:2::/48` | Діапазони для benchmark | +| `192.0.0.0/24`, `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`, `2001:db8::/32` | Special-use і documentation діапазони | +| `224.0.0.0/4`, `ff00::/8` | Multicast | +| `240.0.0.0/4` | Reserved IPv4 | +| `fc00::/7`, `fec0::/10` | Локальні/приватні діапазони IPv6 | +| `100::/64`, `2001:20::/28` | IPv6 discard і ORCHIDv2 діапазони | +| `64:ff9b::/96`, `64:ff9b:1::/48` | Префікси NAT64 із вбудованим IPv4 | +| `2002::/16`, `2001::/32` | 6to4 і Teredo із вбудованим IPv4 | +| `::/96`, `::ffff:0:0/96` | IPv4-compatible і IPv4-mapped IPv6 | -Якщо ваш cloud-провайдер або мережева платформа документує додаткові metadata-хости чи зарезервовані діапазони, додайте їх також. +Якщо ваш cloud provider або мережева платформа документує додаткові metadata hosts чи reserved ranges, додайте також їх. ## Валідація -Перевіряйте проксі з того самого хоста, контейнера або сервісного облікового запису, який запускає OpenClaw: +Перевіряйте проксі з того самого хоста, контейнера або облікового запису сервісу, що запускає OpenClaw: ```bash openclaw proxy validate --proxy-url http://127.0.0.1:3128 ``` -За замовчуванням, коли не надано власні призначення, команда перевіряє, що `https://example.com/` успішно відкривається, і запускає тимчасовий loopback canary, якого проксі не має досягти. Стандартна перевірка заборони проходить, коли проксі повертає non-2xx відповідь відмови або блокує canary через транспортну помилку; вона не проходить, якщо успішна відповідь досягає canary. Якщо проксі не ввімкнено й не налаштовано, валідація повідомляє про проблему конфігурації; використовуйте `--proxy-url` для одноразового preflight перед зміною конфігурації. Використовуйте `--allowed-url` і `--denied-url`, щоб перевірити очікування, специфічні для розгортання. Додайте `--apns-reachable`, щоб також перевірити, що пряма доставка APNs HTTP/2 може відкрити тунель CONNECT через проксі й отримати відповідь sandbox APNs; probe використовує навмисно недійсний токен провайдера, тому очікується `403 InvalidProviderToken`, і це зараховується як досяжність. Власні заборонені призначення є fail-closed: будь-яка HTTP-відповідь означає, що призначення було досяжне через проксі, а будь-яка транспортна помилка повідомляється як непереконлива, оскільки OpenClaw не може довести, що проксі заблокував досяжне джерело. У разі помилки валідації команда завершується з кодом 1. +За замовчуванням, коли користувацькі призначення не надано, команда перевіряє, що `https://example.com/` успішний, і запускає тимчасовий loopback canary, до якого проксі не має дістатися. Стандартна перевірка заборони проходить, коли проксі повертає non-2xx відповідь відмови або блокує canary через transport failure; вона не проходить, якщо успішна відповідь досягає canary. Якщо проксі не ввімкнено й не налаштовано, валідація повідомляє про проблему конфігурації; використовуйте `--proxy-url` для одноразового preflight перед зміною конфігурації. Використовуйте `--allowed-url` і `--denied-url`, щоб перевірити deployment-specific очікування. Додайте `--apns-reachable`, щоб також перевірити, що пряма доставка APNs HTTP/2 може відкрити CONNECT-тунель через проксі й отримати відповідь sandbox APNs; проба використовує навмисно недійсний provider token, тому `403 InvalidProviderToken` очікується й зараховується як reachable. Користувацькі заборонені призначення є fail-closed: будь-яка HTTP-відповідь означає, що призначення було reachable через проксі, а будь-яка transport error повідомляється як inconclusive, бо OpenClaw не може довести, що проксі заблокував reachable origin. У разі помилки валідації команда завершується з кодом 1. -Використовуйте `--json` для автоматизації. JSON-вивід містить загальний результат, ефективне джерело конфігурації проксі, будь-які помилки конфігурації та кожну перевірку призначення. Облікові дані URL проксі редагуються в текстовому та JSON-виводі: +Використовуйте `--json` для автоматизації. JSON-вивід містить загальний результат, джерело ефективної конфігурації проксі, будь-які помилки конфігурації та перевірку кожного призначення. Облікові дані URL проксі редагуються в текстовому та JSON-виводі: ```json { @@ -184,9 +185,9 @@ curl -x http://127.0.0.1:3128 http://127.0.0.1/ curl -x http://127.0.0.1:3128 http://169.254.169.254/ ``` -Публічний запит має виконатися успішно. Запити до loopback і метаданих мають бути заблоковані проксі. Для `openclaw proxy validate` вбудований loopback-канарковий тест може відрізнити відмову проксі від доступного джерела. Користувацькі перевірки `--denied-url` не мають такого канаркового тесту, тому вважайте як HTTP-відповіді, так і неоднозначні транспортні збої помилками перевірки, якщо ваш проксі не надає специфічний для розгортання сигнал відмови, який можна перевірити окремо. +Публічний запит має успішно виконатися. Запити до локальної петлі та метаданих мають блокуватися проксі. Для `openclaw proxy validate` вбудований контрольний запит до локальної петлі може відрізнити відмову проксі від доступного джерела. Користувацькі перевірки `--denied-url` не мають такого контрольного запиту, тому вважайте як HTTP-відповіді, так і неоднозначні транспортні збої помилками перевірки, якщо ваш проксі не надає специфічний для розгортання сигнал відмови, який можна перевірити окремо. -Потім увімкніть проксі-маршрутизацію OpenClaw: +Потім увімкніть маршрутизацію OpenClaw через проксі: ```bash openclaw config set proxy.enabled true @@ -204,11 +205,11 @@ proxy: ## Обмеження -- Проксі покращує покриття для локальних у межах процесу клієнтів JavaScript HTTP і WebSocket, але це не мережевий sandbox рівня ОС. -- Необроблені сокети `net`, `tls` і `http2`, нативні аддони та дочірні процеси можуть обходити проксі-маршрутизацію на рівні Node, якщо вони не успадковують і не дотримуються змінних середовища проксі. -- IRC — це необроблений TCP/TLS-канал поза маршрутизацією через керований оператором прямий проксі. У розгортаннях, які вимагають, щоб увесь вихідний трафік проходив через цей прямий проксі, задайте `channels.irc.enabled=false`, якщо прямий вихідний IRC-трафік не схвалено явно. -- Локальний налагоджувальний проксі є діагностичним інструментом, а його пряме переспрямування до upstream для проксі-запитів і тунелів CONNECT типово вимкнене, доки активний керований режим проксі; вмикайте пряме переспрямування лише для схваленої локальної діагностики. -- Локальні WebUI користувача та локальні сервери моделей слід додавати до списку дозволених у політиці проксі оператора, коли це потрібно; OpenClaw не надає для них загального обходу локальної мережі. -- Обхід проксі для площини керування Gateway навмисно обмежений `localhost` і URL з буквальними loopback-IP. Використовуйте `ws://127.0.0.1:18789`, `ws://[::1]:18789` або `ws://localhost:18789` для локальних прямих з’єднань із площиною керування Gateway; інші імена хостів маршрутизуються як звичайний трафік на основі імен хостів. +- Проксі покращує покриття для локальних у процесі JavaScript HTTP- і WebSocket-клієнтів, але не є мережевою пісочницею на рівні ОС. +- Необроблені сокети `net`, `tls` і `http2`, нативні доповнення та дочірні процеси можуть обходити маршрутизацію через проксі на рівні Node, якщо вони не успадковують і не дотримуються змінних середовища проксі. +- IRC — це необроблений TCP/TLS-канал поза маршрутизацією через прямий проксі, керованою оператором. У розгортаннях, які вимагають усього вихідного трафіку через цей прямий проксі, задайте `channels.irc.enabled=false`, якщо прямий вихідний IRC-трафік явно не схвалено. +- Локальний налагоджувальний проксі є діагностичним інструментом, а його пряме пересилання до upstream для проксі-запитів і тунелів CONNECT типово вимкнене, коли активний керований режим проксі; вмикайте пряме пересилання лише для схваленої локальної діагностики. +- Локальні вебінтерфейси користувача та локальні сервери моделей за потреби мають бути додані до списку дозволених у політиці проксі оператора; OpenClaw не надає для них загального обходу локальної мережі. +- Обхід проксі площини керування Gateway навмисно обмежений `localhost` і буквальними IP-URL локальної петлі. Використовуйте `ws://127.0.0.1:18789`, `ws://[::1]:18789` або `ws://localhost:18789` для локальних прямих підключень до площини керування Gateway; інші імена хостів маршрутизуються як звичайний трафік на основі імен хостів. - OpenClaw не перевіряє, не тестує й не сертифікує вашу політику проксі. - Розглядайте зміни політики проксі як чутливі до безпеки операційні зміни. diff --git a/docs/uk/tools/media-overview.md b/docs/uk/tools/media-overview.md index 4d0752457..96cf7393b 100644 --- a/docs/uk/tools/media-overview.md +++ b/docs/uk/tools/media-overview.md @@ -7,46 +7,48 @@ sidebarTitle: Media overview summary: Короткий огляд можливостей роботи із зображеннями, відео, музикою, мовленням і розумінням медіа title: Огляд медіа x-i18n: - generated_at: "2026-04-28T11:27:18Z" + generated_at: "2026-05-05T00:49:24Z" model: gpt-5.5 provider: openai - source_hash: b9f40e4fb86832438ae99dd2dc42da93c41937541314d95486c97c210dfef508 + source_hash: 1bd6b93fd79897001d24f3ba5a5c8cb9bd17281116fad17262a6389214db7059 source_path: tools/media-overview.md workflow: 16 --- -OpenClaw генерує зображення, відео та музику, розуміє вхідні медіа -(зображення, аудіо, відео) і озвучує відповіді за допомогою перетворення тексту на мовлення. Усі -медіаможливості керуються інструментами: агент вирішує, коли їх використовувати, на основі -розмови, а кожен інструмент з’являється лише тоді, коли налаштовано принаймні одного -базового провайдера. +OpenClaw генерує зображення, відео й музику, розуміє вхідні медіа +(зображення, аудіо, відео) і озвучує відповіді за допомогою перетворення тексту +на мовлення. Усі медіаможливості керуються інструментами: агент вирішує, коли +їх використовувати, на основі розмови, а кожен інструмент з’являється лише тоді, +коли налаштовано принаймні один базовий провайдер. ## Можливості - Створюйте й редагуйте зображення з текстових підказок або референсних зображень через - `image_generate`. Синхронно — завершується безпосередньо у відповіді. + Створюйте та редагуйте зображення з текстових підказок або референсних + зображень через `image_generate`. Синхронно — завершується безпосередньо + в межах відповіді. - Перетворення тексту на відео, зображення на відео та відео на відео через `video_generate`. - Асинхронно — виконується у фоновому режимі й публікує результат, коли він готовий. + Перетворення тексту на відео, зображення на відео та відео на відео через + `video_generate`. Асинхронно — виконується у фоновому режимі та публікує + результат, коли він готовий. - Генеруйте музику або аудіодоріжки через `music_generate`. Асинхронно на спільних - провайдерах; шлях робочого процесу ComfyUI виконується синхронно. + Генеруйте музику або аудіодоріжки через `music_generate`. Асинхронно на + спільних провайдерах; шлях робочого процесу ComfyUI виконується синхронно. - Перетворюйте вихідні відповіді на озвучене аудіо через інструмент `tts` плюс - конфігурацію `messages.tts`. Синхронно. + Перетворюйте вихідні відповіді на озвучене аудіо через інструмент `tts` + і конфігурацію `messages.tts`. Синхронно. - Узагальнюйте вхідні зображення, аудіо та відео за допомогою провайдерів моделей - із підтримкою зору та спеціалізованих plugins для розуміння медіа. + Підсумовуйте вхідні зображення, аудіо та відео за допомогою модельних + провайдерів із підтримкою зору та спеціалізованих Plugin для розуміння медіа. - Транскрибуйте вхідні голосові повідомлення через пакетні STT або провайдерів потокового STT - Voice Call. + Транскрибуйте вхідні голосові повідомлення через пакетне STT або провайдерів + потокового STT для Voice Call. @@ -63,7 +65,7 @@ OpenClaw генерує зображення, відео та музику, ро | fal | ✓ | ✓ | | | | | | | Google | ✓ | ✓ | ✓ | ✓ | | ✓ | ✓ | | Gradium | | | | ✓ | | | | -| Локальна CLI | | | | ✓ | | | | +| Local CLI | | | | ✓ | | | | | Microsoft | | | | ✓ | | | | | MiniMax | ✓ | ✓ | ✓ | ✓ | | | | | Mistral | | | | | ✓ | | | @@ -78,65 +80,66 @@ OpenClaw генерує зображення, відео та музику, ро | Xiaomi MiMo | ✓ | | | ✓ | | | ✓ | -Розуміння медіа використовує будь-яку модель із підтримкою зору або аудіо, зареєстровану -у вашій конфігурації провайдера. У наведеній вище матриці перелічено провайдерів зі спеціалізованою -підтримкою розуміння медіа; більшість мультимодальних LLM-провайдерів (Anthropic, Google, -OpenAI тощо) також можуть розуміти вхідні медіа, коли їх налаштовано як активну -модель відповідей. +Розуміння медіа використовує будь-яку модель із підтримкою зору або аудіо, +зареєстровану в конфігурації вашого провайдера. Матриця вище перелічує +провайдерів зі спеціалізованою підтримкою розуміння медіа; більшість +мультимодальних LLM-провайдерів (Anthropic, Google, OpenAI тощо) також можуть +розуміти вхідні медіа, коли їх налаштовано як активну модель відповідей. ## Асинхронно чи синхронно | Можливість | Режим | Чому | | --------------- | ------------ | ------------------------------------------------------------------ | -| Зображення | Синхронно | Відповіді провайдера повертаються за секунди; завершується безпосередньо у відповіді. | +| Зображення | Синхронно | Відповіді провайдера повертаються за секунди; завершується в межах відповіді. | | Перетворення тексту на мовлення | Синхронно | Відповіді провайдера повертаються за секунди; додається до аудіо відповіді. | | Відео | Асинхронно | Обробка провайдером триває від 30 с до кількох хвилин. | -| Музика (спільні провайдери) | Асинхронно | Та сама характеристика обробки провайдером, що й для відео. | +| Музика (спільна) | Асинхронно | Така сама характеристика обробки провайдером, як у відео. | | Музика (ComfyUI) | Синхронно | Локальний робочий процес виконується безпосередньо на налаштованому сервері ComfyUI. | -Для асинхронних інструментів OpenClaw надсилає запит провайдеру, негайно повертає id -завдання й відстежує роботу в журналі завдань. Агент продовжує -відповідати на інші повідомлення, поки робота виконується. Коли провайдер завершує, -OpenClaw пробуджує агента, щоб він міг опублікувати готові медіа назад у -початковий канал. +Для асинхронних інструментів OpenClaw надсилає запит провайдеру, одразу +повертає ідентифікатор завдання та відстежує роботу в журналі завдань. Агент +продовжує відповідати на інші повідомлення, поки робота виконується. Коли +провайдер завершує обробку, OpenClaw пробуджує агента зі шляхами до +згенерованих медіа, щоб він міг повідомити користувача і, коли цього вимагає +політика доставки джерела, передати результат через інструмент повідомлень. ## Перетворення мовлення на текст і Voice Call -Deepgram, DeepInfra, ElevenLabs, Mistral, OpenAI, SenseAudio та xAI можуть транскрибувати -вхідне аудіо через пакетний шлях `tools.media.audio`, коли їх налаштовано. -Plugins каналів, які попередньо перевіряють голосову нотатку для фільтрації згадок або розбору -команд, позначають транскрибований вкладений файл у вхідному контексті, тому спільний -прохід розуміння медіа повторно використовує цю транскрипцію замість другого -STT-виклику для того самого аудіо. +Deepgram, DeepInfra, ElevenLabs, Mistral, OpenAI, SenseAudio та xAI можуть +транскрибувати вхідне аудіо через пакетний шлях `tools.media.audio`, коли їх +налаштовано. Channel Plugin, які попередньо перевіряють голосову нотатку для +фільтрації згадок або розбору команд, позначають транскрибований вкладений файл +у вхідному контексті, тож спільний прохід розуміння медіа повторно використовує +цей транскрипт замість другого виклику STT для того самого аудіо. -Deepgram, ElevenLabs, Mistral, OpenAI та xAI також реєструють провайдерів потокового STT -Voice Call, тому живе телефонне аудіо можна переспрямувати вибраному -постачальнику, не чекаючи завершеного запису. +Deepgram, ElevenLabs, Mistral, OpenAI та xAI також реєструють провайдерів +потокового STT для Voice Call, тож живе телефонне аудіо можна пересилати +вибраному постачальнику, не чекаючи завершеного запису. ## Зіставлення провайдерів (як постачальники розподіляються між поверхнями) - Поверхні зображень, відео, музики, пакетного TTS, бекендового голосу в реальному часі та - розуміння медіа. + Поверхні зображень, відео, музики, пакетного TTS, бекендового голосу в + реальному часі та розуміння медіа. - Поверхні зображень, відео, пакетного TTS, пакетного STT, потокового STT Voice Call, бекендового - голосу в реальному часі та embedding пам’яті. + Поверхні зображень, відео, пакетного TTS, пакетного STT, потокового STT + для Voice Call, бекендового голосу в реальному часі та вбудовувань пам’яті. - Поверхні маршрутизації чату/моделі, генерації/редагування зображень, перетворення тексту на відео, пакетного TTS, - пакетного STT, розуміння медіа зображень і embedding пам’яті. - Нативні для DeepInfra моделі rerank/класифікації/виявлення об’єктів не - реєструються, доки OpenClaw не матиме спеціалізованих контрактів провайдерів для цих - категорій. + Маршрутизація чату/моделей, генерація/редагування зображень, перетворення + тексту на відео, пакетний TTS, пакетний STT, розуміння зображень як медіа + та поверхні вбудовувань пам’яті. Нативні для DeepInfra моделі + переупорядкування/класифікації/виявлення об’єктів не реєструються, доки + OpenClaw не матиме спеціалізованих контрактів провайдера для цих категорій. - Зображення, відео, пошук, виконання коду, пакетний TTS, пакетний STT і потоковий STT Voice - Call. Голос xAI Realtime є upstream-можливістю, але - не реєструється в OpenClaw, доки спільний контракт голосу в реальному часі не зможе - його представити. + Зображення, відео, пошук, виконання коду, пакетний TTS, пакетний STT і + потоковий STT для Voice Call. Голос xAI Realtime є можливістю upstream, але + не реєструється в OpenClaw, доки спільний контракт голосу в реальному часі + не зможе її представити. diff --git a/docs/uk/tools/music-generation.md b/docs/uk/tools/music-generation.md index 1bce993f2..8bbd49726 100644 --- a/docs/uk/tools/music-generation.md +++ b/docs/uk/tools/music-generation.md @@ -1,38 +1,47 @@ --- read_when: - - Генерування музики або аудіо за допомогою агента - - Налаштування провайдерів і моделей для генерації музики + - Генерування музики або аудіо через агента + - Налаштування постачальників і моделей генерації музики - Розуміння параметрів інструмента music_generate sidebarTitle: Music generation -summary: Генеруйте музику за допомогою music_generate у робочих процесах Google Lyria, MiniMax і ComfyUI +summary: Генеруйте музику через music_generate у робочих процесах Google Lyria, MiniMax і ComfyUI title: Генерація музики x-i18n: - generated_at: "2026-05-02T08:04:17Z" + generated_at: "2026-05-05T00:49:25Z" model: gpt-5.5 provider: openai - source_hash: 9199afe17b2641efb1a7523c651724af9c312c1415c7e60ca736341699f6bc26 + source_hash: 0e14a5a10dd485c2d3dbbd23a0fc2c12de500d9f7bfb7db471c27ed2a99ad650 source_path: tools/music-generation.md workflow: 16 --- -Інструмент `music_generate` дає агенту змогу створювати музику або аудіо через спільну можливість генерації музики з налаштованими провайдерами — Google, MiniMax і налаштованим через workflow ComfyUI на сьогодні. +Інструмент `music_generate` дає агенту змогу створювати музику або аудіо через +спільну можливість генерації музики з налаштованими провайдерами — Google, +MiniMax і налаштованим через workflow ComfyUI на сьогодні. -Для запусків агентів із підтримкою сесій OpenClaw запускає генерацію музики як фонове завдання, відстежує його в журналі завдань, а потім знову пробуджує агента, коли трек готовий, щоб агент міг опублікувати готове аудіо назад у початковий канал. +Для запусків агента із session-backed OpenClaw запускає генерацію музики як +фонове завдання, відстежує його в журналі завдань, а потім знову пробуджує агента, +коли трек готовий, щоб агент міг повідомити користувача й прикріпити +готове аудіо. У групових/канальних чатах, які використовують видиму доставку +лише через інструмент повідомлень, агент передає результат через інструмент повідомлень. -Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації музики. Якщо ви не бачите `music_generate` серед інструментів свого агента, налаштуйте `agents.defaults.musicGenerationModel` або задайте API-ключ провайдера. +Вбудований спільний інструмент з’являється лише тоді, коли доступний хоча б один +провайдер генерації музики. Якщо ви не бачите `music_generate` серед інструментів +вашого агента, налаштуйте `agents.defaults.musicGenerationModel` або задайте +API-ключ провайдера. ## Швидкий старт - + Задайте API-ключ принаймні для одного провайдера — наприклад `GEMINI_API_KEY` або `MINIMAX_API_KEY`. - + ```json5 { agents: { @@ -46,20 +55,24 @@ x-i18n: ``` - _"Generate an upbeat synthpop track about a night drive through a - neon city."_ + _"Згенеруй бадьорий synthpop-трек про нічну поїздку через + неонове місто."_ - Агент автоматично викликає `music_generate`. Список дозволених інструментів не потрібен. + Агент автоматично викликає `music_generate`. Список дозволених + інструментів не потрібен. - Для прямих синхронних контекстів без запуску агента із підтримкою сесії вбудований інструмент усе ще повертається до вбудованої генерації й повертає кінцевий шлях до медіафайлу в результаті інструмента. + Для прямих синхронних контекстів без запуску агента із session-backed + вбудований інструмент усе одно повертається до inline-генерації та повертає + фінальний шлях до медіа в результаті інструмента. - Налаштуйте `plugins.entries.comfy.config.music` за допомогою workflow JSON і вузлів prompt/output. + Налаштуйте `plugins.entries.comfy.config.music` із workflow + JSON і вузлами prompt/output. Для Comfy Cloud задайте `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY`. @@ -73,7 +86,7 @@ x-i18n: -Приклади запитів: +Приклади prompt: ```text Generate a cinematic piano track with soft strings and no vocals. @@ -85,15 +98,16 @@ Generate an energetic chiptune loop about launching a rocket at sunrise. ## Підтримувані провайдери -| Провайдер | Типова модель | Референсні вхідні дані | Підтримувані параметри керування | Автентифікація | +| Провайдер | Модель за замовчуванням | Вхідні reference | Підтримувані елементи керування | Автентифікація | | -------- | ---------------------- | ---------------- | --------------------------------------------------------- | -------------------------------------- | -| ComfyUI | `workflow` | До 1 зображення | Музика або аудіо, визначені workflow | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` | +| ComfyUI | `workflow` | До 1 зображення | Визначена workflow музика або аудіо | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` | | Google | `lyria-3-clip-preview` | До 10 зображень | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | -| MiniMax | `music-2.6` | Немає | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` або MiniMax OAuth | +| MiniMax | `music-2.6` | Немає | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` або MiniMax OAuth | ### Матриця можливостей -Явний контракт режимів, який використовують `music_generate`, контрактні тести й спільний live sweep: +Явний контракт режимів, який використовують `music_generate`, контрактні тести й +спільний live sweep: | Провайдер | `generate` | `edit` | Ліміт редагування | Спільні live lanes | | -------- | :--------: | :----: | ---------- | ------------------------------------------------------------------------- | @@ -101,13 +115,14 @@ Generate an energetic chiptune loop about launching a rocket at sunrise. | Google | ✓ | ✓ | 10 зображень | `generate`, `edit` | | MiniMax | ✓ | — | Немає | `generate` | -Використовуйте `action: "list"`, щоб перевірити доступних спільних провайдерів і моделі під час виконання: +Використовуйте `action: "list"`, щоб переглянути доступних спільних провайдерів і моделі +під час виконання: ```text /tool music_generate action=list ``` -Використовуйте `action: "status"`, щоб перевірити активне сесійне музичне завдання: +Використовуйте `action: "status"`, щоб переглянути активне session-backed завдання музики: ```text /tool music_generate action=status @@ -122,59 +137,75 @@ Generate an energetic chiptune loop about launching a rocket at sunrise. ## Параметри інструмента - Запит для генерації музики. Обов’язковий для `action: "generate"`. + Prompt для генерації музики. Обов’язковий для `action: "generate"`. - `"status"` повертає поточне сесійне завдання; `"list"` перевіряє провайдерів. + `"status"` повертає поточне завдання сесії; `"list"` перевіряє провайдерів. - Перевизначення провайдера/моделі (наприклад, `google/lyria-3-pro-preview`, + Перевизначення провайдера/моделі (наприклад `google/lyria-3-pro-preview`, `comfy/workflow`). - Необов’язковий текст пісні, коли провайдер підтримує явне введення тексту пісні. + Необов’язковий текст lyrics, коли провайдер підтримує явне введення lyrics. - Запит на вихід лише з інструменталом, коли провайдер це підтримує. + Запросити лише інструментальний результат, коли провайдер це підтримує. - Шлях або URL одного референсного зображення. + Шлях або URL до одного reference-зображення. - Кілька референсних зображень (до 10 у провайдерів, які це підтримують). + Кілька reference-зображень (до 10 у провайдерів, які це підтримують). - Цільова тривалість у секундах, коли провайдер підтримує підказки тривалості. + Цільова тривалість у секундах, коли провайдер підтримує підказки щодо тривалості. - Підказка формату вихідного файлу, коли провайдер це підтримує. + Підказка формату виводу, коли провайдер це підтримує. -Підказка імені вихідного файлу. -Необов’язковий тайм-аут запиту до провайдера в мілісекундах. Значення нижче 10000ms підвищуються до 10000ms і повідомляються в результаті інструмента. +Підказка імені файлу виводу. +Необов’язковий timeout запиту до провайдера в мілісекундах. Значення нижче 10000ms підвищуються до 10000ms і повідомляються в результаті інструмента. -Не всі провайдери підтримують усі параметри. OpenClaw усе одно перевіряє жорсткі обмеження, такі як кількість вхідних даних, перед надсиланням. Коли провайдер підтримує тривалість, але має коротший максимум за запитане значення, OpenClaw обмежує значення найближчою підтримуваною тривалістю. Справді непідтримувані необов’язкові підказки ігноруються з попередженням, коли вибраний провайдер або модель не можуть їх виконати. Результати інструмента повідомляють застосовані налаштування; `details.normalization` фіксує будь-яке зіставлення запитаного із застосованим. +Не всі провайдери підтримують усі параметри. OpenClaw усе одно перевіряє жорсткі +ліміти, як-от кількість вхідних даних, перед надсиланням. Коли провайдер підтримує +тривалість, але має коротший максимум, ніж запитане значення, OpenClaw +обмежує його до найближчої підтримуваної тривалості. Справді непідтримувані +необов’язкові підказки ігноруються з попередженням, коли вибраний провайдер або модель +не може їх виконати. Результати інструмента повідомляють застосовані налаштування; +`details.normalization` фіксує будь-яке зіставлення запитаного із застосованим. ## Асинхронна поведінка -Сесійна генерація музики виконується як фонове завдання: +Session-backed генерація музики виконується як фонове завдання: -- **Фонове завдання:** `music_generate` створює фонове завдання, негайно повертає відповідь про старт/завдання й пізніше публікує готовий трек у наступному повідомленні агента. -- **Запобігання дублюванню:** доки завдання має стан `queued` або `running`, пізніші виклики `music_generate` у тій самій сесії повертають статус завдання замість запуску ще однієї генерації. Використовуйте `action: "status"` для явної перевірки. -- **Перегляд статусу:** `openclaw tasks list` або `openclaw tasks show ` перевіряє статуси в черзі, виконання й завершення. -- **Пробудження після завершення:** OpenClaw вводить внутрішню подію завершення назад у ту саму сесію, щоб модель могла сама написати наступне повідомлення для користувача. -- **Підказка запиту:** пізніші користувацькі/ручні ходи в тій самій сесії отримують невелику runtime-підказку, коли музичне завдання вже виконується, щоб модель не викликала `music_generate` повторно наосліп. -- **Fallback без сесії:** прямі/локальні контексти без справжньої сесії агента виконуються inline і повертають кінцевий аудіорезультат у тому самому ході. +- **Фонове завдання:** `music_generate` створює фонове завдання, негайно повертає + відповідь started/task і публікує готовий трек пізніше в подальшому + повідомленні агента. +- **Запобігання дублікатам:** поки завдання має стан `queued` або `running`, наступні + виклики `music_generate` у тій самій сесії повертають статус завдання замість + запуску ще однієї генерації. Використовуйте `action: "status"` для явної перевірки. +- **Перегляд статусу:** `openclaw tasks list` або `openclaw tasks show ` + перевіряє queued, running і terminal status. +- **Пробудження після завершення:** OpenClaw вводить внутрішню подію завершення назад + у ту саму сесію, щоб модель могла сама написати подальше повідомлення + для користувача. +- **Підказка prompt:** подальші користувацькі/ручні ходи в тій самій сесії отримують невелику + runtime-підказку, коли музичне завдання вже виконується, щоб модель + не викликала `music_generate` знову наосліп. +- **Fallback без сесії:** прямі/локальні контексти без реальної сесії агента + виконуються inline і повертають фінальний аудіорезультат у тому самому ході. ### Життєвий цикл завдання | Стан | Значення | | ----------- | ---------------------------------------------------------------------------------------------- | -| `queued` | Завдання створено, очікує, доки провайдер його прийме. | +| `queued` | Завдання створено, очікує, поки провайдер його прийме. | | `running` | Провайдер обробляє запит (зазвичай від 30 секунд до 3 хвилин залежно від провайдера й тривалості). | -| `succeeded` | Трек готовий; агент пробуджується й публікує його в розмову. | -| `failed` | Помилка провайдера або тайм-аут; агент пробуджується з деталями помилки. | +| `succeeded` | Трек готовий; агент пробуджується й публікує його в розмові. | +| `failed` | Помилка провайдера або timeout; агент пробуджується з деталями помилки. | Перевірте статус із CLI: @@ -201,50 +232,63 @@ openclaw tasks cancel } ``` -### Порядок вибору провайдера +### Порядок вибору провайдерів OpenClaw пробує провайдерів у такому порядку: 1. Параметр `model` із виклику інструмента (якщо агент його вказує). 2. `musicGenerationModel.primary` із конфігурації. -3. `musicGenerationModel.fallbacks` по порядку. -4. Автовиявлення лише за типовими провайдерами з підтримкою автентифікації: - - спочатку поточний типовий провайдер; +3. `musicGenerationModel.fallbacks` за порядком. +4. Автовиявлення лише з використанням стандартних провайдерів із автентифікацією: + - спочатку поточний провайдер за замовчуванням; - решта зареєстрованих провайдерів генерації музики в порядку provider-id. -Якщо провайдер зазнає невдачі, наступний кандидат пробується автоматично. Якщо всі зазнають невдачі, помилка містить деталі кожної спроби. +Якщо провайдер завершується помилкою, наступний кандидат пробується автоматично. Якщо всі +завершуються помилкою, помилка містить деталі кожної спроби. -Задайте `agents.defaults.mediaGenerationAutoProviderFallback: false`, щоб використовувати лише явні записи `model`, `primary` і `fallbacks`. +Задайте `agents.defaults.mediaGenerationAutoProviderFallback: false`, щоб використовувати лише +явні записи `model`, `primary` і `fallbacks`. -## Примітки щодо провайдерів +## Нотатки про провайдерів - Керується workflow і залежить від налаштованого графа та зіставлення вузлів для полів prompt/output. Вбудований plugin `comfy` під’єднується до спільного інструмента `music_generate` через реєстр провайдерів генерації музики. + Керується workflow і залежить від налаштованого графа та зіставлення вузлів + для полів prompt/output. Вбудований Plugin `comfy` підключається до + спільного інструмента `music_generate` через реєстр провайдерів + генерації музики. - Використовує пакетну генерацію Lyria 3. Поточний вбудований потік підтримує prompt, необов’язковий текст пісні й необов’язкові референсні зображення. + Використовує пакетну генерацію Lyria 3. Поточний вбудований потік підтримує + prompt, необов’язковий текст lyrics і необов’язкові reference-зображення. - Використовує пакетний endpoint `music_generation`. Підтримує prompt, необов’язковий текст пісні, інструментальний режим, керування тривалістю та вихід mp3 через автентифікацію API-ключем `minimax` або OAuth `minimax-portal`. + Використовує пакетний endpoint `music_generation`. Підтримує prompt, необов’язкові + lyrics, інструментальний режим, керування тривалістю та mp3-вивід через + автентифікацію API-ключем `minimax` або OAuth `minimax-portal`. ## Вибір правильного шляху -- **Із підтримкою спільного провайдера**, коли вам потрібні вибір моделі, failover провайдера й вбудований асинхронний потік завдання/статусу. -- **Шлях Plugin (ComfyUI)**, коли вам потрібен власний workflow-граф або провайдер, який не входить до спільної вбудованої музичної можливості. +- **На основі спільного провайдера**, коли вам потрібні вибір моделі, відмовостійке + перемикання провайдерів і вбудований async потік завдання/статусу. +- **Шлях Plugin (ComfyUI)**, коли вам потрібен власний граф workflow або + провайдер, який не входить до спільної вбудованої можливості музики. -Якщо ви налагоджуєте специфічну для ComfyUI поведінку, див. [ComfyUI](/uk/providers/comfy). Якщо ви налагоджуєте поведінку спільного провайдера, почніть із [Google (Gemini)](/uk/providers/google) або [MiniMax](/uk/providers/minimax). +Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див. +[ComfyUI](/uk/providers/comfy). Якщо ви налагоджуєте поведінку спільного провайдера, +почніть із [Google (Gemini)](/uk/providers/google) або +[MiniMax](/uk/providers/minimax). ## Режими можливостей провайдера Спільний контракт генерації музики підтримує явні оголошення режимів: - `generate` для генерації лише за prompt. -- `edit`, коли запит містить одне або кілька референсних зображень. +- `edit`, коли запит містить одне або кілька reference-зображень. -Нові реалізації провайдерів мають віддавати перевагу явним блокам режимів: +Нові реалізації провайдерів мають надавати перевагу явним блокам режимів: ```typescript capabilities: { @@ -262,9 +306,13 @@ capabilities: { } ``` -Застарілих плоских полів, таких як `maxInputImages`, `supportsLyrics` і `supportsFormat`, **недостатньо** для оголошення підтримки редагування. Провайдери мають явно оголошувати `generate` і `edit`, щоб live tests, контрактні тести та спільний інструмент `music_generate` могли детерміновано перевіряти підтримку режимів. +Застарілих плоских полів, як-от `maxInputImages`, `supportsLyrics` і +`supportsFormat`, **недостатньо**, щоб оголосити підтримку edit. Провайдери +мають явно оголошувати `generate` і `edit`, щоб live-тести, контрактні +тести та спільний інструмент `music_generate` могли детерміновано перевіряти +підтримку режимів. -## Live tests +## Live-тести Opt-in live-покриття для спільних вбудованих провайдерів: @@ -278,11 +326,13 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.liv pnpm test:live:media music ``` -Цей live-файл завантажує відсутні змінні середовища провайдера з `~/.profile`, за замовчуванням надає перевагу live/env API-ключам перед збереженими профілями автентифікації та запускає покриття і `generate`, і оголошеного `edit`, коли провайдер увімкнув режим edit. Поточне покриття: +Цей live-файл завантажує відсутні env vars провайдерів із `~/.profile`, за замовчуванням надає +перевагу live/env API-ключам перед збереженими auth profiles і запускає покриття +`generate` та оголошене `edit`, коли провайдер вмикає режим edit. Поточне покриття: - `google`: `generate` плюс `edit` - `minimax`: лише `generate` -- `comfy`: окреме live-покриття Comfy, не спільний sweep провайдерів +- `comfy`: окреме live-покриття Comfy, не спільний provider sweep Opt-in live-покриття для вбудованого музичного шляху ComfyUI: @@ -290,14 +340,15 @@ Opt-in live-покриття для вбудованого музичного ш OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts ``` -Файл Comfy live також охоплює робочі процеси зображень і відео Comfy, коли ці розділи налаштовано. +Live-файл Comfy також охоплює робочі процеси зображень і відео comfy, коли ці +розділи налаштовано. ## Пов’язане -- [Фонові завдання](/uk/automation/tasks) — відстеження завдань для від’єднаних запусків `music_generate` +- [Фонові завдання](/uk/automation/tasks) — відстеження завдань для відокремлених запусків `music_generate` - [ComfyUI](/uk/providers/comfy) - [Довідник конфігурації](/uk/gateway/config-agents#agent-defaults) — конфігурація `musicGenerationModel` - [Google (Gemini)](/uk/providers/google) - [MiniMax](/uk/providers/minimax) -- [Моделі](/uk/concepts/models) — конфігурація моделей і перемикання після збою +- [Моделі](/uk/concepts/models) — конфігурація моделей і перемикання в разі збою - [Огляд інструментів](/uk/tools) diff --git a/docs/uk/tools/video-generation.md b/docs/uk/tools/video-generation.md index 31bc67f6d..5cbbd7b0d 100644 --- a/docs/uk/tools/video-generation.md +++ b/docs/uk/tools/video-generation.md @@ -1,24 +1,25 @@ --- read_when: - - Генерування відео за допомогою агента + - Генерування відео через агента - Налаштування постачальників і моделей генерації відео - Розуміння параметрів інструмента video_generate sidebarTitle: Video generation -summary: Генеруйте відео за допомогою video_generate з текстових, графічних або відеореференсів у 16 бекендах провайдерів. +summary: Генеруйте відео через video_generate з текстових, графічних або відеореференсів у 16 бекендах провайдерів title: Генерація відео x-i18n: - generated_at: "2026-04-28T11:28:49Z" + generated_at: "2026-05-05T00:49:28Z" model: gpt-5.5 provider: openai - source_hash: c91409057210af560d389513c2049d643c3e1602df51aa9825ceb01571626cdf + source_hash: 6edce39c3006b748d512fec935b81566ae1a121c280248e9e9439edd1f052d83 source_path: tools/video-generation.md workflow: 16 --- -Агенти OpenClaw можуть генерувати відео з текстових промптів, референсних зображень або -наявних відео. Підтримуються шістнадцять бекендів провайдерів, кожен із -різними варіантами моделей, режимами введення та наборами функцій. Агент вибирає -потрібного провайдера автоматично на основі вашої конфігурації та доступних API-ключів. +Агенти OpenClaw можуть генерувати відео з текстових запитів, еталонних зображень або +наявних відео. Підтримується шістнадцять бекендів провайдерів, кожен із +різними варіантами моделей, режимами введення та наборами функцій. Агент +автоматично вибирає потрібного провайдера на основі вашої конфігурації та доступних API- +ключів. Інструмент `video_generate` з’являється лише тоді, коли доступний принаймні один @@ -28,9 +29,9 @@ API-ключ провайдера або налаштуйте `agents.defaults.v OpenClaw розглядає генерацію відео як три режими виконання: -- `generate` — запити текст-у-відео без референсних медіа. -- `imageToVideo` — запит містить одне або кілька референсних зображень. -- `videoToVideo` — запит містить одне або кілька референсних відео. +- `generate` — запити text-to-video без еталонних медіа. +- `imageToVideo` — запит містить одне або кілька еталонних зображень. +- `videoToVideo` — запит містить одне або кілька еталонних відео. Провайдери можуть підтримувати будь-яку підмножину цих режимів. Інструмент перевіряє активний режим перед надсиланням і повідомляє підтримувані режими в `action=list`. @@ -38,7 +39,7 @@ OpenClaw розглядає генерацію відео як три режим ## Швидкий старт - + Задайте API-ключ для будь-якого підтримуваного провайдера: ```bash @@ -46,15 +47,15 @@ OpenClaw розглядає генерацію відео як три режим ``` - + ```bash openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview" ``` - - > Згенеруй 5-секундне кінематографічне відео про дружнього лобстера, який серфить на заході сонця. + + > Згенеруй 5-секундне кінематографічне відео, де дружній омар серфить на заході сонця. - Агент автоматично викликає `video_generate`. Додавати інструмент до списку дозволених + Агент автоматично викликає `video_generate`. Додавати інструмент до allowlist не потрібно. @@ -65,37 +66,39 @@ OpenClaw розглядає генерацію відео як три режим Генерація відео є асинхронною. Коли агент викликає `video_generate` у сеансі: -1. OpenClaw надсилає запит провайдеру й одразу повертає id завдання. -2. Провайдер обробляє завдання у фоновому режимі (зазвичай від 30 секунд до 5 хвилин, залежно від провайдера та роздільної здатності). +1. OpenClaw надсилає запит провайдеру й одразу повертає ідентифікатор завдання. +2. Провайдер обробляє завдання у фоновому режимі (зазвичай від 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності). 3. Коли відео готове, OpenClaw пробуджує той самий сеанс внутрішньою подією завершення. -4. Агент публікує готове відео назад в оригінальну розмову. +4. Агент повідомляє користувача й додає готове відео. У групових/канальних + чатах, які використовують видиму доставку лише через інструмент повідомлень, агент передає + результат через інструмент повідомлень замість того, щоб OpenClaw публікував його напряму. Поки завдання виконується, повторні виклики `video_generate` у тому самому -сеансі повертають поточний статус завдання замість запуску ще однієї +сеансі повертають поточний стан завдання замість запуску ще однієї генерації. Використовуйте `openclaw tasks list` або `openclaw tasks show `, щоб перевірити прогрес із CLI. -Поза запусками агентів із підтримкою сеансу (наприклад, прямими викликами інструментів) +Поза запусками агента, підтриманими сеансом (наприклад, прямі виклики інструментів), інструмент повертається до inline-генерації та повертає кінцевий шлях до медіа в тому самому ході. -Згенеровані відеофайли зберігаються в керованому OpenClaw медіасховищі, коли -провайдер повертає байти. Обмеження збереження згенерованого відео за замовчуванням відповідає +Згенеровані відеофайли зберігаються в керованому OpenClaw сховищі медіа, коли +провайдер повертає байти. Типове обмеження збереження згенерованих відео відповідає ліміту відеомедіа, а `agents.defaults.mediaMaxMb` підвищує його для більших рендерів. Коли провайдер також повертає URL розміщеного результату, OpenClaw -може доставити цей URL замість того, щоб завершити завдання помилкою, якщо локальне збереження +може доставити цю URL-адресу замість того, щоб завершити завдання помилкою, якщо локальне збереження відхиляє завеликий файл. ### Життєвий цикл завдання -| Стан | Значення | +| Стан | Значення | | ----------- | ------------------------------------------------------------------------------------------------ | -| `queued` | Завдання створено, очікує, поки провайдер його прийме. | -| `running` | Провайдер обробляє його (зазвичай від 30 секунд до 5 хвилин, залежно від провайдера та роздільної здатності). | -| `succeeded` | Відео готове; агент пробуджується та публікує його в розмову. | -| `failed` | Помилка провайдера або тайм-аут; агент пробуджується з деталями помилки. | +| `queued` | Завдання створено, очікує на прийняття провайдером. | +| `running` | Провайдер обробляє (зазвичай від 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності). | +| `succeeded` | Відео готове; агент пробуджується й публікує його в розмові. | +| `failed` | Помилка або тайм-аут провайдера; агент пробуджується з деталями помилки. | -Перевірте статус із CLI: +Перевірте стан із CLI: ```bash openclaw tasks list @@ -104,109 +107,109 @@ openclaw tasks cancel ``` Якщо відеозавдання вже має стан `queued` або `running` для поточного сеансу, -`video_generate` повертає статус наявного завдання замість запуску нового. -Використовуйте `action: "status"`, щоб перевірити явно, не запускаючи нову -генерацію. +`video_generate` повертає наявний стан завдання замість запуску нового. +Використовуйте `action: "status"`, щоб перевірити явно без запуску нової +генерації. ## Підтримувані провайдери -| Провайдер | Модель за замовчуванням | Текст | Референс зображення | Референс відео | Автентифікація | +| Провайдер | Типова модель | Текст | Еталонне зображення | Еталонне відео | Автентифікація | | --------------------- | ------------------------------- | :--: | ---------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- | -| Alibaba | `wan2.6-t2v` | ✓ | Так (віддалений URL) | Так (віддалений URL) | `MODELSTUDIO_API_KEY` | +| Alibaba | `wan2.6-t2v` | ✓ | Так (віддалена URL-адреса) | Так (віддалена URL-адреса) | `MODELSTUDIO_API_KEY` | | BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | До 2 зображень (лише моделі I2V; перший + останній кадр) | — | `BYTEPLUS_API_KEY` | | BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | До 2 зображень (перший + останній кадр через роль) | — | `BYTEPLUS_API_KEY` | -| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | До 9 референсних зображень | До 3 відео | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | До 9 еталонних зображень | До 3 відео | `BYTEPLUS_API_KEY` | | ComfyUI | `workflow` | ✓ | 1 зображення | — | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` | | DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` | | fal | `fal-ai/minimax/video-01-live` | ✓ | 1 зображення; до 9 із Seedance reference-to-video | До 3 відео із Seedance reference-to-video | `FAL_KEY` | | Google | `veo-3.1-fast-generate-preview` | ✓ | 1 зображення | 1 відео | `GEMINI_API_KEY` | | MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 зображення | — | `MINIMAX_API_KEY` або MiniMax OAuth | | OpenAI | `sora-2` | ✓ | 1 зображення | 1 відео | `OPENAI_API_KEY` | -| OpenRouter | `google/veo-3.1-fast` | ✓ | До 4 зображень (перший/останній кадр або референси) | — | `OPENROUTER_API_KEY` | -| Qwen | `wan2.6-t2v` | ✓ | Так (віддалений URL) | Так (віддалений URL) | `QWEN_API_KEY` | +| OpenRouter | `google/veo-3.1-fast` | ✓ | До 4 зображень (перший/останній кадр або еталони) | — | `OPENROUTER_API_KEY` | +| Qwen | `wan2.6-t2v` | ✓ | Так (віддалена URL-адреса) | Так (віддалена URL-адреса) | `QWEN_API_KEY` | | Runway | `gen4.5` | ✓ | 1 зображення | 1 відео | `RUNWAYML_API_SECRET` | | Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 зображення | — | `TOGETHER_API_KEY` | | Vydra | `veo3` | ✓ | 1 зображення (`kling`) | — | `VYDRA_API_KEY` | -| xAI | `grok-imagine-video` | ✓ | 1 зображення першого кадру або до 7 `reference_image`s | 1 відео | `XAI_API_KEY` | +| xAI | `grok-imagine-video` | ✓ | 1 зображення першого кадру або до 7 `reference_image` | 1 відео | `XAI_API_KEY` | Деякі провайдери приймають додаткові або альтернативні змінні середовища API-ключів. Див. -окремі [сторінки провайдерів](#related) для подробиць. +окремі [сторінки провайдерів](#related) для деталей. -Запустіть `video_generate action=list`, щоб під час виконання переглянути доступних провайдерів, моделі та -режими виконання. +Запустіть `video_generate action=list`, щоб переглянути доступних провайдерів, моделі та +режими виконання під час роботи. ### Матриця можливостей Явний контракт режимів, який використовують `video_generate`, контрактні тести та -спільна live-перевірка: +спільний live sweep: -| Провайдер | `generate` | `imageToVideo` | `videoToVideo` | Спільні live-лінії сьогодні | +| Провайдер | `generate` | `imageToVideo` | `videoToVideo` | Спільні live-лінії сьогодні | | ---------- | :--------: | :------------: | :------------: | ---------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` пропущено, бо цьому провайдеру потрібні віддалені `http(s)` URL відео | +| Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` пропущено, бо цьому провайдеру потрібні віддалені URL-адреси відео `http(s)` | | BytePlus | ✓ | ✓ | — | `generate`, `imageToVideo` | -| ComfyUI | ✓ | ✓ | — | Не входить до спільної перевірки; покриття для конкретних workflow міститься в тестах Comfy | -| DeepInfra | ✓ | — | — | `generate`; нативні відеосхеми DeepInfra у вбудованому контракті є text-to-video | -| fal | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` лише за використання Seedance reference-to-video | -| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, бо поточна перевірка Gemini/Veo на основі буфера не приймає такі вхідні дані | +| ComfyUI | ✓ | ✓ | — | Не входить до спільного sweep; покриття, специфічне для workflow, міститься в тестах Comfy | +| DeepInfra | ✓ | — | — | `generate`; нативні відеосхеми DeepInfra є text-to-video у bundled-контракті | +| fal | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` лише за використання Seedance reference-to-video | +| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, бо поточний sweep Gemini/Veo на основі буферів не приймає цей ввід | | MiniMax | ✓ | ✓ | — | `generate`, `imageToVideo` | -| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, бо цей шлях org/input наразі потребує доступу до inpaint/remix на боці провайдера | +| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, бо цьому шляху org/input наразі потрібен доступ provider-side inpaint/remix | | OpenRouter | ✓ | ✓ | — | `generate`, `imageToVideo` | -| Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` пропущено, бо цьому провайдеру потрібні віддалені `http(s)` URL відео | -| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` запускається лише тоді, коли вибрана модель — `runway/gen4_aleph` | +| Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` пропущено, бо цьому провайдеру потрібні віддалені URL-адреси відео `http(s)` | +| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` запускається лише тоді, коли вибрана модель — `runway/gen4_aleph` | | Together | ✓ | ✓ | — | `generate`, `imageToVideo` | -| Vydra | ✓ | ✓ | — | `generate`; спільний `imageToVideo` пропущено, бо вбудований `veo3` підтримує лише текст, а вбудований `kling` потребує віддаленого URL зображення | -| xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` пропущено, бо цьому провайдеру наразі потрібен віддалений MP4 URL | +| Vydra | ✓ | ✓ | — | `generate`; спільний `imageToVideo` пропущено, бо bundled `veo3` є лише текстовим, а bundled `kling` потребує віддаленої URL-адреси зображення | +| xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` пропущено, бо цьому провайдеру наразі потрібна віддалена MP4 URL-адреса | ## Параметри інструмента ### Обов’язкові - Текстовий опис відео, яке потрібно згенерувати. Обов’язково для `action: "generate"`. + Текстовий опис відео для генерації. Обов’язково для `action: "generate"`. ### Вхідні дані вмісту -Одне еталонне зображення (шлях або URL). -Кілька еталонних зображень (до 9). +Одне референсне зображення (шлях або URL). +Кілька референсних зображень (до 9). -Необов'язкові підказки ролей для кожної позиції, паралельні до об'єднаного списку зображень. +Необов’язкові підказки ролей для кожної позиції, паралельні до об’єднаного списку зображень. Канонічні значення: `first_frame`, `last_frame`, `reference_image`. -Одне еталонне відео (шлях або URL). -Кілька еталонних відео (до 4). +Одне референсне відео (шлях або URL). +Кілька референсних відео (до 4). -Необов'язкові підказки ролей для кожної позиції, паралельні до об'єднаного списку відео. +Необов’язкові підказки ролей для кожної позиції, паралельні до об’єднаного списку відео. Канонічне значення: `reference_video`. -Одне еталонне аудіо (шлях або URL). Використовується для фонової музики або голосового -еталона, коли провайдер підтримує аудіовходи. +Одне референсне аудіо (шлях або URL). Використовується для фонової музики або голосового +референсу, коли провайдер підтримує аудіовходи. -Кілька еталонних аудіо (до 3). +Кілька референсних аудіо (до 3). -Необов'язкові підказки ролей для кожної позиції, паралельні до об'єднаного списку аудіо. +Необов’язкові підказки ролей для кожної позиції, паралельні до об’єднаного списку аудіо. Канонічне значення: `reference_audio`. -Підказки ролей передаються провайдеру без змін. Канонічні значення походять з -об'єднання `VideoGenerationAssetRole`, але провайдери можуть приймати додаткові +Підказки ролей передаються провайдеру без змін. Канонічні значення походять із +об’єднання `VideoGenerationAssetRole`, але провайдери можуть приймати додаткові рядки ролей. Масиви `*Roles` не повинні мати більше записів, ніж -відповідний список еталонів; помилки зсуву на один елемент завершуються зрозумілою помилкою. -Використовуйте порожній рядок, щоб залишити слот незаданим. Для xAI задайте кожній ролі зображення -`reference_image`, щоб використати його режим генерації `reference_images`; пропустіть +відповідний список референсів; помилки на один елемент дають зрозумілу помилку. +Використовуйте порожній рядок, щоб залишити слот не заданим. Для xAI задайте для кожної ролі зображення +`reference_image`, щоб використовувати його режим генерації `reference_images`; пропустіть роль або використайте `first_frame` для перетворення одного зображення на відео. ### Керування стилем - `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` або `adaptive`. + `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, або `adaptive`. -`480P`, `720P`, `768P` або `1080P`. +`480P`, `720P`, `768P`, або `1080P`. - Цільова тривалість у секундах (округлюється до найближчого значення, підтримуваного провайдером). + Цільова тривалість у секундах (округлюється до найближчого значення, яке підтримує провайдер). Підказка розміру, коли провайдер її підтримує. @@ -215,9 +218,9 @@ openclaw tasks cancel Перемкнути водяний знак провайдера, коли це підтримується. `adaptive` — це специфічний для провайдера sentinel: він передається без змін -провайдерам, які декларують `adaptive` у своїх можливостях (наприклад, BytePlus -Seedance використовує його для автоматичного визначення співвідношення з розмірів -вхідного зображення). Провайдери, які його не декларують, показують значення через +провайдерам, які оголошують `adaptive` у своїх можливостях (наприклад, BytePlus +Seedance використовує його для автоматичного визначення співвідношення за розмірами +вхідного зображення). Провайдери, які його не оголошують, відображають значення через `details.ignoredOverrides` у результаті інструмента, щоб пропуск був видимим. ### Розширені параметри @@ -226,67 +229,67 @@ Seedance використовує його для автоматичного в `"status"` повертає поточне завдання сесії; `"list"` перевіряє провайдерів. Перевизначення провайдера/моделі (наприклад, `runway/gen4.5`). -Підказка імені вихідного файлу. -Необов'язковий тайм-аут запиту до провайдера в мілісекундах. +Підказка назви вихідного файлу. +Необов’язковий тайм-аут запиту до провайдера в мілісекундах. - Специфічні для провайдера параметри як JSON-об'єкт (наприклад, `{"seed": 42, "draft": true}`). - Провайдери, які декларують типізовану схему, перевіряють ключі та типи; невідомі + Специфічні для провайдера параметри як JSON-об’єкт (наприклад, `{"seed": 42, "draft": true}`). + Провайдери, які оголошують типізовану схему, перевіряють ключі та типи; невідомі ключі або невідповідності пропускають кандидата під час fallback. Провайдери без - задекларованої схеми отримують параметри без змін. Запустіть `video_generate action=list`, + оголошеної схеми отримують параметри без змін. Запустіть `video_generate action=list`, щоб побачити, що приймає кожен провайдер. Не всі провайдери підтримують усі параметри. OpenClaw нормалізує тривалість до -найближчого значення, підтримуваного провайдером, і перепризначає перекладені підказки геометрії, -такі як розмір у співвідношення сторін, коли fallback-провайдер надає іншу -поверхню керування. Справді непідтримувані перевизначення ігноруються за принципом найкращого зусилля -та повідомляються як попередження в результаті інструмента. Жорсткі обмеження можливостей -(наприклад, забагато еталонних входів) завершуються помилкою до надсилання. Результати інструмента +найближчого значення, яке підтримує провайдер, і перепризначає перекладені підказки геометрії, +як-от size-to-aspect-ratio, коли fallback-провайдер має іншу +поверхню керування. Справді непідтримувані перевизначення ігноруються за принципом +best-effort і повідомляються як попередження в результаті інструмента. Жорсткі межі можливостей +(наприклад, забагато референсних входів) завершуються помилкою до надсилання. Результати інструмента повідомляють застосовані налаштування; `details.normalization` фіксує будь-яке перетворення із запитаного в застосоване. -Еталонні входи вибирають режим виконання: +Референсні входи вибирають режим виконання: -- Немає еталонних медіа → `generate` -- Будь-який еталон зображення → `imageToVideo` -- Будь-який еталон відео → `videoToVideo` -- Еталонні аудіовходи **не** змінюють визначений режим; вони застосовуються - поверх будь-якого режиму, який вибирають еталони зображень/відео, і працюють лише - з провайдерами, які декларують `maxInputAudios`. +- Без референсних медіа → `generate` +- Будь-який референс зображення → `imageToVideo` +- Будь-який референс відео → `videoToVideo` +- Референсні аудіовходи **не** змінюють визначений режим; вони застосовуються + поверх будь-якого режиму, який вибирають референси зображень/відео, і працюють лише + з провайдерами, які оголошують `maxInputAudios`. -Змішані еталони зображень і відео не є стабільною спільною поверхнею можливостей. -Надавайте перевагу одному типу еталона на запит. +Змішані референси зображень і відео не є стабільною спільною поверхнею можливостей. +Надавайте перевагу одному типу референсу на запит. #### Fallback і типізовані параметри Деякі перевірки можливостей застосовуються на рівні fallback, а не на -межі інструмента, тому запит, який перевищує обмеження основного провайдера, може -все одно виконатися на здатному fallback: +межі інструмента, тому запит, який перевищує ліміти основного провайдера, все ще може +виконатися на fallback, що має потрібні можливості: -- Активний кандидат, який не декларує `maxInputAudios` (або декларує `0`), пропускається, коли - запит містить аудіоеталони; пробується наступний кандидат. -- `maxDurationSeconds` активного кандидата нижче за запитаний `durationSeconds` - без задекларованого списку `supportedDurationSeconds` → пропускається. +- Активний кандидат, який не оголошує `maxInputAudios` (або має `0`), пропускається, коли + запит містить аудіореференси; пробується наступний кандидат. +- `maxDurationSeconds` активного кандидата менший за запитаний `durationSeconds` + без оголошеного списку `supportedDurationSeconds` → пропускається. - Запит містить `providerOptions`, а активний кандидат явно - декларує типізовану схему `providerOptions` → пропускається, якщо надані ключі + оголошує типізовану схему `providerOptions` → пропускається, якщо надані ключі відсутні в схемі або типи значень не збігаються. Провайдери без - задекларованої схеми отримують параметри без змін (зворотно сумісне + оголошеної схеми отримують параметри без змін (зворотно сумісне наскрізне передавання). Провайдер може відмовитися від усіх параметрів провайдера, - задекларувавши порожню схему (`capabilities.providerOptions: {}`), що + оголосивши порожню схему (`capabilities.providerOptions: {}`), що спричиняє такий самий пропуск, як і невідповідність типів. Перша причина пропуску в запиті логується на рівні `warn`, щоб оператори бачили, коли їхній основний провайдер був пропущений; наступні пропуски логуються на рівні `debug`, щоб -довгі ланцюжки fallback залишалися тихими. Якщо кожен кандидат пропущено, +довгі ланцюжки fallback залишалися тихими. Якщо пропущено кожного кандидата, агрегована помилка містить причину пропуску для кожного. ## Дії | Дія | Що вона робить | | ---------- | -------------------------------------------------------------------------------------------------------- | -| `generate` | За замовчуванням. Створює відео з наданого prompt і необов'язкових еталонних входів. | +| `generate` | За замовчуванням. Створює відео з наданого prompt і необов’язкових референсних входів. | | `status` | Перевіряє стан поточного відеозавдання для поточної сесії без запуску іншої генерації. | | `list` | Показує доступних провайдерів, моделі та їхні можливості. | @@ -297,12 +300,12 @@ OpenClaw визначає модель у такому порядку: 1. **Параметр інструмента `model`** — якщо агент указує його у виклику. 2. **`videoGenerationModel.primary`** з конфігурації. 3. **`videoGenerationModel.fallbacks`** за порядком. -4. **Автовиявлення** — провайдери, які мають чинну автентифікацію, починаючи з - поточного провайдера за замовчуванням, а потім решта провайдерів в алфавітному +4. **Автовиявлення** — провайдери з дійсною автентифікацією, починаючи з + поточного провайдера за замовчуванням, потім решта провайдерів в алфавітному порядку. -Якщо провайдер завершується помилкою, наступний кандидат пробується автоматично. Якщо всі -кандидати завершуються помилкою, помилка містить деталі з кожної спроби. +Якщо провайдер зазнає невдачі, наступний кандидат пробується автоматично. Якщо всі +кандидати зазнають невдачі, помилка містить подробиці кожної спроби. Задайте `agents.defaults.mediaGenerationAutoProviderFallback: false`, щоб використовувати лише явні записи `model`, `primary` і `fallbacks`. @@ -320,33 +323,33 @@ OpenClaw визначає модель у такому порядку: } ``` -## Нотатки провайдерів +## Примітки щодо провайдерів - Використовує асинхронний endpoint DashScope / Model Studio. Еталонні зображення та + Використовує асинхронний endpoint DashScope / Model Studio. Референсні зображення та відео мають бути віддаленими URL `http(s)`. - ID провайдера: `byteplus`. + Ідентифікатор провайдера: `byteplus`. Моделі: `seedance-1-0-pro-250528` (за замовчуванням), `seedance-1-0-pro-t2v-250528`, `seedance-1-0-pro-fast-251015`, `seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`. Моделі T2V (`*-t2v-*`) не приймають входи зображень; моделі I2V і - загальні моделі `*-pro-*` підтримують одне еталонне зображення (перший + загальні моделі `*-pro-*` підтримують одне референсне зображення (перший кадр). Передайте зображення позиційно або задайте `role: "first_frame"`. - ID моделей T2V автоматично перемикаються на відповідний варіант I2V, + Ідентифікатори моделей T2V автоматично перемикаються на відповідний варіант I2V, коли надано зображення. Підтримувані ключі `providerOptions`: `seed` (number), `draft` (boolean — - примусово задає 480p), `camera_fixed` (boolean). + примусово 480p), `camera_fixed` (boolean). Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). - ID провайдера: `byteplus-seedance15`. Модель: + Ідентифікатор провайдера: `byteplus-seedance15`. Модель: `seedance-1-5-pro-251215`. Використовує уніфікований API `content[]`. Підтримує щонайбільше 2 вхідні зображення @@ -361,12 +364,12 @@ OpenClaw визначає модель у такому порядку: Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). - ID провайдера: `byteplus-seedance2`. Моделі: + Ідентифікатор провайдера: `byteplus-seedance2`. Моделі: `dreamina-seedance-2-0-260128`, `dreamina-seedance-2-0-fast-260128`. - Використовує уніфікований API `content[]`. Підтримує до 9 еталонних зображень, - 3 еталонних відео та 3 еталонних аудіо. Усі входи мають бути віддаленими + Використовує уніфікований API `content[]`. Підтримує до 9 референсних зображень, + 3 референсні відео та 3 референсні аудіо. Усі входи мають бути віддаленими URL `https://`. Задайте `role` для кожного ресурсу — підтримувані значення: `"first_frame"`, `"last_frame"`, `"reference_image"`, `"reference_video"`, `"reference_audio"`. @@ -377,20 +380,20 @@ OpenClaw визначає модель у такому порядку: - Локальне або хмарне виконання на основі workflow. Підтримує text-to-video і + Локальне або хмарне виконання на основі workflow. Підтримує text-to-video та image-to-video через налаштований граф. Використовує потік на основі черги для довготривалих завдань. Більшість відеомоделей fal - приймають одне еталонне зображення. Моделі Seedance 2.0 reference-to-video - приймають до 9 зображень, 3 відео та 3 аудіоеталонів, щонайбільше - 12 еталонних файлів загалом. + приймають одне референсне зображення. Моделі Seedance 2.0 reference-to-video + приймають до 9 зображень, 3 відео та 3 аудіореференсів, із + максимум 12 референсними файлами загалом. - Підтримує один еталон зображення або один еталон відео. + Підтримує один референс зображення або один референс відео. - Лише один еталон зображення. + Лише одне референсне зображення. Передається лише перевизначення `size`. Інші перевизначення стилю @@ -398,41 +401,40 @@ OpenClaw визначає модель у такому порядку: попередженням. - Використовує асинхронний API `/videos` OpenRouter. OpenClaw надсилає + Використовує асинхронний API OpenRouter `/videos`. OpenClaw надсилає завдання, опитує `polling_url` і завантажує або `unsigned_urls`, або - документований endpoint вмісту завдання. Вбудований стандартний `google/veo-3.1-fast` - оголошує тривалості 4/6/8 секунд, роздільні здатності `720P`/`1080P` і + задокументований endpoint вмісту завдання. Вбудоване значення за замовчуванням `google/veo-3.1-fast` + оголошує тривалості 4/6/8 секунд, роздільності `720P`/`1080P` та співвідношення сторін `16:9`/`9:16`. - Такий самий backend DashScope, як в Alibaba. Еталонні входи мають бути віддаленими + Той самий backend DashScope, що й Alibaba. Референсні входи мають бути віддаленими URL `http(s)`; локальні файли відхиляються наперед. Підтримує локальні файли через data URI. Video-to-video потребує - `runway/gen4_aleph`. Запуски лише з текстом надають співвідношення сторін - `16:9` і `9:16`. + `runway/gen4_aleph`. Запуски лише з текстом надають співвідношення сторін `16:9` і `9:16`. - Лише один еталон зображення. + Лише одне референсне зображення. - Використовує `https://www.vydra.ai/api/v1` напряму, щоб уникнути редиректів, - які скидають автентифікацію. `veo3` вбудовано лише як text-to-video; `kling` потребує - віддаленого URL зображення. + Використовує `https://www.vydra.ai/api/v1` напряму, щоб уникнути redirect, + які відкидають автентифікацію. `veo3` вбудовано лише як text-to-video; `kling` потребує + віддалений URL зображення. - Підтримує text-to-video, single first-frame image-to-video, до 7 - входів `reference_image` через xAI `reference_images` і віддалені - потоки редагування/продовження відео. + Підтримує text-to-video, перетворення одного зображення першого кадру на відео, до 7 + входів `reference_image` через xAI `reference_images`, а також віддалені + потоки редагування/розширення відео. ## Режими можливостей провайдера Спільний контракт генерації відео підтримує можливості, специфічні для режимів, -а не лише плоскі сукупні обмеження. Нові реалізації постачальників -мають віддавати перевагу явним блокам режимів: +а не лише плоскі агреговані ліміти. Новим реалізаціям провайдерів +слід надавати перевагу явним блокам режимів: ```typescript capabilities: { @@ -457,19 +459,19 @@ capabilities: { } ``` -Плоских сукупних полів, таких як `maxInputImages` і `maxInputVideos`, -**недостатньо**, щоб оголосити підтримку режимів перетворення. Постачальники мають +Плоских агрегованих полів, таких як `maxInputImages` і `maxInputVideos`, +**недостатньо**, щоб оголошувати підтримку режимів перетворення. Провайдерам слід явно оголошувати `generate`, `imageToVideo` і `videoToVideo`, щоб live-тести, контрактні тести та спільний інструмент `video_generate` могли детерміновано перевіряти підтримку режимів. -Коли одна модель у постачальника має ширшу підтримку референсних вхідних даних, ніж -інші, використовуйте `maxInputImagesByModel`, `maxInputVideosByModel` або -`maxInputAudiosByModel` замість підвищення обмеження для всього режиму. +Коли одна модель у провайдера має ширшу підтримку вхідних референсів, ніж +решта, використовуйте `maxInputImagesByModel`, `maxInputVideosByModel` або +`maxInputAudiosByModel` замість підвищення ліміту для всього режиму. ## Live-тести -Увімкніть за згодою live-покриття для спільних вбудованих постачальників: +Увімкніть за згодою live-покриття для спільних вбудованих провайдерів: ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts @@ -481,31 +483,31 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.liv pnpm test:live:media video ``` -Цей live-файл завантажує відсутні змінні середовища постачальника з `~/.profile`, за замовчуванням -надає перевагу API-ключам із live/env перед збереженими профілями автентифікації та за замовчуванням -запускає безпечний для релізу smoke-тест: +Цей live-файл завантажує відсутні змінні середовища провайдера з `~/.profile`, за замовчуванням надає +перевагу API-ключам з live/env перед збереженими профілями автентифікації та запускає +безпечну для релізу smoke-перевірку за замовчуванням: -- `generate` для кожного не-FAL постачальника в перевірці. -- Односекундний prompt із омаром. -- Обмеження операцій для кожного постачальника з +- `generate` для кожного не-FAL провайдера у проході. +- Односекундний промпт із лобстером. +- Ліміт операцій для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням). -FAL вмикається за згодою, оскільки затримка черги на боці постачальника може домінувати -у часі релізу: +FAL вмикається за згодою, оскільки затримка черги на боці провайдера може переважати +час релізу: ```bash pnpm test:live:media video --video-providers fal ``` Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені -режими перетворення, які спільна перевірка може безпечно виконати з локальними медіа: +режими перетворення, які спільний прохід може безпечно виконати з локальними медіа: - `imageToVideo`, коли `capabilities.imageToVideo.enabled`. - `videoToVideo`, коли `capabilities.videoToVideo.enabled` і - постачальник/модель приймає локальний відеоввід на основі буфера у спільній - перевірці. + провайдер/модель приймає локальне відео на основі буфера у спільному + проході. -Наразі спільна live-доріжка `videoToVideo` покриває `runway` лише тоді, коли ви +Сьогодні спільна live-доріжка `videoToVideo` покриває `runway` лише тоді, коли ви вибираєте `runway/gen4_aleph`. ## Конфігурація