From bdc9b1d656c3f58ffb2a7aa35f2b5e48923ca53c Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 03:47:24 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/cli/agent.md | 27 +- docs/uk/concepts/agent-runtimes.md | 118 ++++--- docs/uk/concepts/model-providers.md | 316 +++++++++-------- docs/uk/gateway/config-agents.md | 504 ++++++++++++++-------------- docs/uk/plugins/codex-harness.md | 453 ++++++++++++++----------- docs/uk/providers/openai.md | 412 ++++++++++++----------- docs/uk/providers/openrouter.md | 94 ++++-- docs/uk/tools/acp-agents.md | 422 +++++++++++------------ docs/uk/tools/plugin.md | 414 +++++++++++------------ docs/uk/tools/tts.md | 268 ++++++++------- 10 files changed, 1575 insertions(+), 1453 deletions(-) diff --git a/docs/uk/cli/agent.md b/docs/uk/cli/agent.md index 6cc5a1e0c..852178065 100644 --- a/docs/uk/cli/agent.md +++ b/docs/uk/cli/agent.md @@ -1,13 +1,13 @@ --- read_when: - - Ви хочете запустити один хід агента зі скриптів (необов’язково доставити відповідь) + - Ви хочете запустити один хід агента зі скриптів (за потреби доставити відповідь) summary: Довідка CLI для `openclaw agent` (надіслати один хід агента через Gateway) title: Агент x-i18n: - generated_at: "2026-04-24T03:15:19Z" + generated_at: "2026-04-25T03:44:18Z" model: gpt-5.4 provider: openai - source_hash: c4d57b8e368891a0010b053a7504d6313ad2233b5f5f43b34be1f9aa92caa86c + source_hash: 292559e27907fff3cdeb3b4127e19638934fbb4af50fc5165f9559da62a6b11b source_path: cli/agent.md workflow: 15 --- @@ -29,19 +29,19 @@ x-i18n: ## Параметри -- `-m, --message `: обов’язкове тіло повідомлення -- `-t, --to `: одержувач, що використовується для виведення ключа сесії +- `-m, --message `: обов’язковий текст повідомлення +- `-t, --to `: одержувач, який використовується для визначення ключа сесії - `--session-id `: явний ідентифікатор сесії - `--agent `: ідентифікатор агента; перевизначає прив’язки маршрутизації - `--thinking `: рівень мислення агента (`off`, `minimal`, `low`, `medium`, `high`, а також підтримувані провайдером власні рівні, як-от `xhigh`, `adaptive` або `max`) - `--verbose `: зберегти рівень деталізації для сесії -- `--channel `: канал доставки; пропустіть, щоб використовувати основний канал сесії +- `--channel `: канал доставки; не вказуйте, щоб використовувати основний канал сесії - `--reply-to `: перевизначення цілі доставки - `--reply-channel `: перевизначення каналу доставки - `--reply-account `: перевизначення облікового запису доставки -- `--local`: запустити вбудованого агента безпосередньо (після попереднього завантаження реєстру Plugin) -- `--deliver`: надіслати відповідь назад до вибраного каналу/цілі -- `--timeout `: перевизначити тайм-аут агента (типово 600 або значення конфігурації) +- `--local`: запустити вбудованого агента напряму (після попереднього завантаження реєстру Plugin) +- `--deliver`: надіслати відповідь назад у вибраний канал/ціль +- `--timeout `: перевизначити тайм-аут агента (типово 600 або значення з конфігурації) - `--json`: вивести JSON ## Приклади @@ -57,11 +57,12 @@ openclaw agent --agent ops --message "Run locally" --local ## Примітки -- Режим Gateway повертається до вбудованого агента, коли запит Gateway завершується помилкою. Використовуйте `--local`, щоб одразу примусово виконати вбудований режим. -- `--local` усе одно спочатку попередньо завантажує реєстр Plugin, тому провайдери, інструменти та канали, надані Plugin, залишаються доступними під час вбудованих запусків. +- Режим Gateway повертається до вбудованого агента, якщо запит до Gateway завершується помилкою. Використовуйте `--local`, щоб примусово ввімкнути вбудоване виконання одразу. +- `--local` однаково спочатку попередньо завантажує реєстр Plugin, тому провайдери, інструменти та канали, надані Plugin, залишаються доступними під час вбудованих запусків. - `--channel`, `--reply-channel` і `--reply-account` впливають на доставку відповіді, а не на маршрутизацію сесії. -- Коли ця команда запускає повторну генерацію `models.json`, облікові дані провайдера, керовані SecretRef, зберігаються як не секретні маркери (наприклад, назви змінних середовища, `secretref-env:ENV_VAR_NAME` або `secretref-managed`), а не як розкритий відкритий текст секретів. -- Записи маркерів є авторитетними щодо джерела: OpenClaw зберігає маркери з активного знімка конфігурації джерела, а не з розв’язаних значень секретів середовища виконання. +- `--json` зберігає stdout зарезервованим для JSON-відповіді. Діагностика Gateway, Plugin і вбудованого резервного режиму спрямовується до stderr, щоб скрипти могли напряму розбирати stdout. +- Коли ця команда запускає регенерацію `models.json`, облікові дані провайдера, керовані SecretRef, зберігаються як несекретні маркери (наприклад, назви змінних середовища, `secretref-env:ENV_VAR_NAME` або `secretref-managed`), а не як розкритий відкритий текст секретів. +- Записи маркерів є авторитетними від джерела: OpenClaw зберігає маркери з активного знімка конфігурації джерела, а не з розв’язаних значень секретів під час виконання. ## Пов’язане diff --git a/docs/uk/concepts/agent-runtimes.md b/docs/uk/concepts/agent-runtimes.md index 89fa43464..41746bb06 100644 --- a/docs/uk/concepts/agent-runtimes.md +++ b/docs/uk/concepts/agent-runtimes.md @@ -1,40 +1,40 @@ --- read_when: - - Ви обираєте між PI, Codex, ACP або іншим нативним середовищем виконання агента - - Вас бентежать мітки постачальника/моделі/середовища виконання у статусі або конфігурації + - Ви обираєте між Pi, Codex, ACP або іншим нативним середовищем виконання агента + - Ви плутаєтеся в позначеннях постачальника, моделі та середовища виконання в статусі або конфігурації - Ви документуєте паритет підтримки для нативного harness summary: Як OpenClaw розділяє постачальників моделей, моделі, канали та середовища виконання агентів title: Середовища виконання агентів x-i18n: - generated_at: "2026-04-25T01:53:12Z" + generated_at: "2026-04-25T03:44:19Z" model: gpt-5.4 provider: openai - source_hash: 1e7da189f66ee57a17ea2df1a3364ba9554d94cb4c6ebad30b0c261daf5496af + source_hash: 5ccfdd0ac9e53f7196ff1884016b4bd890978de0c41a661f9264d2dde4c899b3 source_path: concepts/agent-runtimes.md workflow: 15 --- -**Середовище виконання агента** — це компонент, який відповідає за один підготовлений цикл моделі: він +**Середовище виконання агента** — це компонент, який керує одним підготовленим циклом моделі: він отримує промпт, керує виведенням моделі, обробляє нативні виклики інструментів і повертає завершений хід до OpenClaw. Середовища виконання легко сплутати з постачальниками, оскільки обидва з’являються поруч із конфігурацією моделі. Це різні рівні: -| Рівень | Приклади | Що це означає | -| ------------- | ------------------------------------- | ------------------------------------------------------------------- | +| Рівень | Приклади | Що це означає | +| ------------- | ------------------------------------- | ------------------------------------------------------------------ | | Постачальник | `openai`, `anthropic`, `openai-codex` | Як OpenClaw автентифікується, виявляє моделі та називає посилання на моделі. | -| Модель | `gpt-5.5`, `claude-opus-4-6` | Модель, вибрана для ходу агента. | -| Середовище виконання агента | `pi`, `codex`, середовища виконання на базі ACP | Низькорівневий цикл, який виконує підготовлений хід. | -| Канал | Telegram, Discord, Slack, WhatsApp | Звідки повідомлення надходять до OpenClaw і куди виходять. | +| Модель | `gpt-5.5`, `claude-opus-4-6` | Модель, вибрана для ходу агента. | +| Середовище виконання агента | `pi`, `codex`, середовища виконання на основі ACP | Низькорівневий цикл, який виконує підготовлений хід. | +| Канал | Telegram, Discord, Slack, WhatsApp | Де повідомлення входять в OpenClaw і виходять з нього. | Ви також побачите слово **harness** у коді та конфігурації. Harness — це реалізація, яка надає середовище виконання агента. Наприклад, вбудований Codex harness реалізує середовище виконання `codex`. Ключ конфігурації, як і раніше, має назву `embeddedHarness` для сумісності, але в документації для користувачів і виводі статусу -зазвичай слід використовувати термін runtime. +зазвичай слід казати runtime. -Типове налаштування Codex використовує постачальника `openai` із середовищем виконання `codex`: +Поширене налаштування Codex використовує постачальника `openai` із середовищем виконання `codex`: ```json5 { @@ -49,64 +49,70 @@ harness реалізує середовище виконання `codex`. Клю } ``` -Це означає, що OpenClaw вибирає посилання на модель OpenAI, а потім просить -середовище виконання app-server Codex виконати вбудований хід агента. Це не означає, що канал, каталог +Це означає, що OpenClaw вибирає посилання на модель OpenAI, а потім просить середовище виконання +серверного застосунку Codex запустити вбудований хід агента. Це не означає, що канал, каталог постачальника моделей або сховище сесій OpenClaw стає Codex. +Щодо розділення префіксів сімейства OpenAI див. [OpenAI](/uk/providers/openai) і +[Постачальники моделей](/uk/concepts/model-providers). Щодо контракту підтримки +середовища виконання Codex див. [Codex harness](/uk/plugins/codex-harness#v1-support-contract). + ## Відповідальність середовища виконання Різні середовища виконання відповідають за різні частини циклу. -| Поверхня | Вбудований OpenClaw PI | Codex app-server | +| Поверхня | OpenClaw PI embedded | Серверний застосунок Codex | | --------------------------- | --------------------------------------- | --------------------------------------------------------------------------- | -| Власник циклу моделі | OpenClaw через вбудований runner PI | Codex app-server | -| Канонічний стан потоку | Транскрипт OpenClaw | Потік Codex плюс дзеркало транскрипту OpenClaw | -| Динамічні інструменти OpenClaw | Нативний цикл інструментів OpenClaw | Передаються через адаптер Codex | -| Нативні інструменти shell і файлів | Шлях PI/OpenClaw | Нативні інструменти Codex, передані через нативні hooks там, де це підтримується | -| Рушій контексту | Нативне збирання контексту OpenClaw | Контекст проєктів OpenClaw, зібраний у хід Codex | -| Compaction | OpenClaw або вибраний рушій контексту | Нативний Compaction Codex, зі сповіщеннями OpenClaw і підтримкою дзеркала | +| Власник циклу моделі | OpenClaw через вбудований виконавець PI | Серверний застосунок Codex | +| Канонічний стан потоку | Транскрипт OpenClaw | Потік Codex плюс дзеркало транскрипту OpenClaw | +| Динамічні інструменти OpenClaw | Нативний цикл інструментів OpenClaw | Підключено через адаптер Codex | +| Нативні інструменти shell і файлів | Шлях PI/OpenClaw | Нативні інструменти Codex, підключені через нативні хуки там, де це підтримується | +| Рушій контексту | Нативне збирання контексту OpenClaw | Контекст, зібраний проєктами OpenClaw, у хід Codex | +| Compaction | OpenClaw або вибраний рушій контексту | Нативний Compaction у Codex зі сповіщеннями OpenClaw і підтримкою дзеркала | | Доставка каналом | OpenClaw | OpenClaw | Цей розподіл відповідальності — головне правило проєктування: -- Якщо за поверхню відповідає OpenClaw, OpenClaw може надавати звичайну поведінку hooks плагінів. -- Якщо за поверхню відповідає нативне середовище виконання, OpenClaw потребує подій runtime або нативних hooks. -- Якщо нативне середовище виконання відповідає за канонічний стан потоку, OpenClaw має дзеркалити й проєктувати контекст, а не переписувати непідтримувані внутрішні механізми. +- Якщо за поверхню відповідає OpenClaw, OpenClaw може надавати звичайну поведінку хуків Plugin. +- Якщо за поверхню відповідає нативне середовище виконання, OpenClaw потребує подій runtime або нативних хуків. +- Якщо нативне середовище виконання володіє канонічним станом потоку, OpenClaw має дзеркалити його й проєктувати контекст, а не переписувати непідтримувані внутрішні механізми. ## Вибір середовища виконання OpenClaw вибирає вбудоване середовище виконання після визначення постачальника та моделі: -1. Перевагу має runtime, записаний у сесії. Зміни конфігурації не перемикають на льоту - наявний транскрипт на іншу нативну систему потоків. -2. `OPENCLAW_AGENT_RUNTIME=` примусово встановлює це середовище виконання для нових або скинутих сесій. +1. Записане середовище виконання сесії має пріоритет. Зміни конфігурації не перемикають + наявний транскрипт «на гарячу» на іншу нативну систему потоків. +2. `OPENCLAW_AGENT_RUNTIME=` примусово задає це середовище виконання для нових або скинутих сесій. 3. `agents.defaults.embeddedHarness.runtime` або `agents.list[].embeddedHarness.runtime` можуть задавати `auto`, `pi` або зареєстрований - ідентифікатор runtime, наприклад `codex`. -4. У режимі `auto` зареєстровані plugin-середовища виконання можуть заявляти підтримувані пари постачальник/модель. -5. Якщо в режимі `auto` жодне середовище виконання не бере на себе хід, і встановлено `fallback: "pi"` - (це значення за замовчуванням), OpenClaw використовує PI як резервний варіант сумісності. Установіть - `fallback: "none"`, щоб у разі невідповідності вибір у режимі `auto` завершувався помилкою. + ідентифікатор середовища виконання, наприклад `codex`. +4. У режимі `auto` зареєстровані середовища виконання Plugin можуть заявляти про підтримувані пари постачальник/модель. +5. Якщо жодне середовище виконання не бере хід у режимі `auto`, а задано `fallback: "pi"` + (типове значення), OpenClaw використовує PI як сумісний резервний варіант. Установіть + `fallback: "none"`, щоб натомість вибір у режимі `auto` завершувався помилкою для невідповідних випадків. -Явно вказані plugin-середовища виконання за замовчуванням працюють у режимі fail closed. Наприклад, -`runtime: "codex"` означає Codex або явну помилку вибору, якщо тільки ви не встановите -`fallback: "pi"` у тій самій області перевизначення. +Явно вказані середовища виконання Plugin за замовчуванням завершуються без резервного переходу. Наприклад, +`runtime: "codex"` означає Codex або чітку помилку вибору, якщо тільки ви не задасте +`fallback: "pi"` у тій самій області перевизначення. Перевизначення runtime не успадковує +ширше налаштування fallback, тому `runtime: "codex"` на рівні агента не буде непомітно +спрямовано назад до PI лише тому, що в налаштуваннях за замовчуванням використовувався `fallback: "pi"`. ## Контракт сумісності -Коли runtime — не PI, він має документувати, які поверхні OpenClaw підтримує. -Використовуйте таку структуру для документації runtime: +Коли середовище виконання не є PI, воно має документувати, які поверхні OpenClaw воно підтримує. +Для документації середовищ виконання використовуйте таку структуру: -| Питання | Чому це важливо | -| -------------------------------------- | ------------------------------------------------------------------------------------------------- | -| Хто відповідає за цикл моделі? | Визначає, де відбуваються повторні спроби, продовження інструментів і рішення щодо фінальної відповіді. | -| Хто відповідає за канонічну історію потоку? | Визначає, чи може OpenClaw редагувати історію, чи лише дзеркалити її. | -| Чи працюють динамічні інструменти OpenClaw? | На цьому залежать повідомлення, сесії, Cron та інструменти, якими володіє OpenClaw. | -| Чи працюють hooks динамічних інструментів? | Plugins очікують `before_tool_call`, `after_tool_call` і middleware навколо інструментів, якими володіє OpenClaw. | -| Чи працюють hooks нативних інструментів? | Інструменти shell, patch та runtime-owned tools потребують підтримки нативних hooks для політик і спостереження. | -| Чи виконується життєвий цикл рушія контексту? | Plugins пам’яті та контексту залежать від життєвого циклу assemble, ingest, after-turn і compaction. | -| Які дані Compaction доступні? | Деяким plugins потрібні лише сповіщення, тоді як іншим потрібні метадані про те, що збережено/відкинуто. | -| Що навмисно не підтримується? | Користувачі не повинні припускати еквівалентність PI там, де нативне середовище виконання володіє більшою частиною стану. | +| Питання | Чому це важливо | +| ------------------------------------- | ---------------------------------------------------------------------------------------------- | +| Хто володіє циклом моделі? | Визначає, де відбуваються повторні спроби, продовження інструментів і рішення щодо фінальної відповіді. | +| Хто володіє канонічною історією потоку? | Визначає, чи може OpenClaw редагувати історію, чи лише дзеркалити її. | +| Чи працюють динамічні інструменти OpenClaw? | Від цього залежать повідомлення, сесії, Cron та інструменти, якими володіє OpenClaw. | +| Чи працюють хуки динамічних інструментів? | Plugins очікують `before_tool_call`, `after_tool_call` і middleware навколо інструментів, якими володіє OpenClaw. | +| Чи працюють хуки нативних інструментів? | Shell, patch та інструменти, якими володіє runtime, потребують підтримки нативних хуків для політик і спостереження. | +| Чи виконується життєвий цикл рушія контексту? | Plugins пам’яті й контексту залежать від життєвого циклу assemble, ingest, after-turn і compaction. | +| Які дані Compaction доступні? | Деяким Plugin потрібні лише сповіщення, тоді як іншим потрібні метадані про збережене/відкинуте. | +| Що навмисно не підтримується? | Користувачі не повинні припускати еквівалентність PI там, де нативне середовище виконання володіє більшою кількістю стану. | Контракт підтримки середовища виконання Codex задокументовано в [Codex harness](/uk/plugins/codex-harness#v1-support-contract). @@ -114,20 +120,22 @@ OpenClaw вибирає вбудоване середовище виконанн ## Мітки статусу У виводі статусу можуть показуватися мітки `Execution` і `Runtime`. Сприймайте їх як -діагностику, а не як назви постачальників. +діагностичні дані, а не як назви постачальників. -- Посилання на модель, наприклад `openai/gpt-5.5`, показує вибраного постачальника/модель. -- Ідентифікатор runtime, наприклад `codex`, показує, який цикл виконує хід. -- Мітка каналу, наприклад Telegram або Discord, показує, де відбувається розмова. +- Посилання на модель, як-от `openai/gpt-5.5`, показує вибраного постачальника/модель. +- Ідентифікатор середовища виконання, як-от `codex`, показує, який цикл виконує хід. +- Мітка каналу, як-от Telegram або Discord, показує, де відбувається розмова. -Якщо після зміни конфігурації runtime сесія все ще показує PI, почніть нову сесію -за допомогою `/new` або очистьте поточну за допомогою `/reset`. Наявні сесії зберігають свій -записаний runtime, щоб транскрипт не відтворювався через дві несумісні нативні +Якщо сесія все ще показує PI після зміни конфігурації runtime, почніть нову сесію +за допомогою `/new` або очистьте поточну через `/reset`. Наявні сесії зберігають своє +записане середовище виконання, щоб транскрипт не відтворювався через дві несумісні нативні системи сесій. ## Пов’язане - [Codex harness](/uk/plugins/codex-harness) -- [Плагіни harness агентів](/uk/plugins/sdk-agent-harness) +- [OpenAI](/uk/providers/openai) +- [Плагіни harness агента](/uk/plugins/sdk-agent-harness) - [Цикл агента](/uk/concepts/agent-loop) - [Моделі](/uk/concepts/models) +- [Статус](/uk/cli/status) diff --git a/docs/uk/concepts/model-providers.md b/docs/uk/concepts/model-providers.md index 410adc83f..4c5b85b8c 100644 --- a/docs/uk/concepts/model-providers.md +++ b/docs/uk/concepts/model-providers.md @@ -1,85 +1,84 @@ --- read_when: - Вам потрібен довідник із налаштування моделей для кожного постачальника окремо - - Вам потрібні приклади конфігурацій або команди онбордингу CLI для постачальників моделей -summary: Огляд постачальника моделі з прикладами конфігурацій + потоками CLI + - Вам потрібні приклади конфігурацій або команд онбордингу CLI для постачальників моделей +summary: Огляд постачальника моделей із прикладами конфігурацій + потоками CLI title: Постачальники моделей x-i18n: - generated_at: "2026-04-25T02:39:38Z" + generated_at: "2026-04-25T03:44:17Z" model: gpt-5.4 provider: openai - source_hash: f321baaf1bd451b1f5f70d44dda8d914f8cf10b58e404370576a5a7480191e4d + source_hash: 654eb02f8e1909308f9260db7970785fb7218d61b27857323d4abef15983f0bb source_path: concepts/model-providers.md workflow: 15 --- -Ця сторінка охоплює **постачальників LLM/моделей** (а не канали чату, як-от WhatsApp/Telegram). -Правила вибору моделей дивіться в [/concepts/models](/uk/concepts/models). +Ця сторінка охоплює **постачальників LLM/моделей** (а не канали чату на кшталт WhatsApp/Telegram). +Правила вибору моделі дивіться в [/concepts/models](/uk/concepts/models). -## Короткі правила +## Швидкі правила - Посилання на моделі використовують формат `provider/model` (приклад: `opencode/claude-opus-4-6`). - `agents.defaults.models` працює як список дозволених значень, якщо його задано. - Допоміжні команди CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- `models.providers.*.models[].contextWindow` — це вбудовані метадані моделі; `contextTokens` — це фактичний ліміт під час виконання. -- Правила резервного перемикання, перевірки після cooldown і збереження перевизначень сесії дивіться в [Model failover](/uk/concepts/model-failover). -- Маршрути сімейства OpenAI залежать від префікса: `openai/` використовує прямого постачальника API-ключа OpenAI у PI, `openai-codex/` використовує Codex OAuth у PI, а `openai/` разом з `agents.defaults.embeddedHarness.runtime: "codex"` використовує рідний app-server harness Codex. Дивіться [OpenAI](/uk/providers/openai) і [Codex harness](/uk/plugins/codex-harness). -- Автоматичне ввімкнення Plugin дотримується тієї самої межі: `openai-codex/` належить до Plugin OpenAI, тоді як Plugin Codex вмикається через `embeddedHarness.runtime: "codex"` або застарілі посилання `codex/`. -- Середовища виконання CLI використовують той самий поділ: вибирайте канонічні посилання на моделі, як-от `anthropic/claude-*`, `google/gemini-*` або `openai/gpt-*`, а потім установлюйте `agents.defaults.embeddedHarness.runtime` у `claude-cli`, `google-gemini-cli` або `codex-cli`, якщо хочете локальний бекенд CLI. - Застарілі посилання `claude-cli/*`, `google-gemini-cli/*` і `codex-cli/*` мігрують назад до канонічних посилань постачальників, а середовище виконання записується окремо. -- GPT-5.5 наразі доступна через маршрути підписки/OAuth: - `openai-codex/gpt-5.5` у PI або `openai/gpt-5.5` із harness app-server Codex. Прямий маршрут API-ключа для `openai/gpt-5.5` підтримуватиметься, щойно OpenAI увімкне GPT-5.5 у публічному API; до того часу для конфігурацій `OPENAI_API_KEY` використовуйте моделі з доступом через API, наприклад `openai/gpt-5.4`. +- `models.providers.*.models[].contextWindow` — це нативні метадані моделі; `contextTokens` — це фактичне обмеження під час виконання. +- Правила резервного перемикання, перевірки після cooldown і збереження session override дивіться в [Model failover](/uk/concepts/model-failover). +- Маршрути сімейства OpenAI залежать від префікса: `openai/` використовує прямого постачальника з API-ключем OpenAI у Pi, `openai-codex/` використовує Codex OAuth у Pi, а `openai/` разом із `agents.defaults.embeddedHarness.runtime: "codex"` використовує нативний harness app-server Codex. Дивіться [OpenAI](/uk/providers/openai) і [Codex harness](/uk/plugins/codex-harness). Якщо поділ між постачальником і runtime викликає плутанину, спочатку прочитайте [Agent runtimes](/uk/concepts/agent-runtimes). +- Автоматичне вмикання Plugin дотримується тієї самої межі: `openai-codex/` належить Plugin OpenAI, тоді як Plugin Codex вмикається через `embeddedHarness.runtime: "codex"` або застарілі посилання `codex/`. +- Runtime CLI використовують той самий поділ: вибирайте канонічні посилання на моделі, наприклад `anthropic/claude-*`, `google/gemini-*` або `openai/gpt-*`, а потім задавайте `agents.defaults.embeddedHarness.runtime` як `claude-cli`, `google-gemini-cli` або `codex-cli`, якщо хочете локальний бекенд CLI. Застарілі посилання `claude-cli/*`, `google-gemini-cli/*` і `codex-cli/*` мігрують назад до канонічних посилань постачальників, а runtime записується окремо. +- GPT-5.5 наразі доступна через маршрути підписки/OAuth: `openai-codex/gpt-5.5` у Pi або `openai/gpt-5.5` із harness app-server Codex. Прямий маршрут API-ключа для `openai/gpt-5.5` підтримуватиметься, щойно OpenAI увімкне GPT-5.5 у публічному API; до того часу для налаштувань `OPENAI_API_KEY` використовуйте моделі з доступом через API, наприклад `openai/gpt-5.4`. ## Поведінка постачальників, що належить Plugin -Більшість логіки, специфічної для постачальника, живе в Plugin постачальників (`registerProvider(...)`), тоді як OpenClaw зберігає загальний цикл inference. Plugin відповідають за онбординг, каталоги моделей, зіставлення auth зі змінними середовища, нормалізацію транспорту/конфігурації, очищення схем інструментів, класифікацію failover, оновлення OAuth, звітність про використання, профілі thinking/reasoning тощо. +Більшість логіки, специфічної для постачальника, живе в Plugin постачальників (`registerProvider(...)`), тоді як OpenClaw підтримує загальний цикл inference. Plugin відповідають за онбординг, каталоги моделей, зіставлення auth env var, нормалізацію транспорту/конфігурації, очищення схем інструментів, класифікацію failover, оновлення OAuth, звітність про використання, профілі thinking/reasoning та інше. -Повний список хуків provider-SDK і прикладів вбудованих Plugin наведено в [Provider plugins](/uk/plugins/sdk-provider-plugins). Постачальник, якому потрібен повністю кастомний виконавець запитів, використовує окрему, глибшу поверхню розширення. +Повний список хуків SDK постачальників і приклади вбудованих Plugin наведено в [Provider plugins](/uk/plugins/sdk-provider-plugins). Постачальник, якому потрібен повністю кастомний executor запитів, використовує окрему, глибшу поверхню розширення. -`capabilities` середовища виконання постачальника — це спільні метадані раннера (сімейство постачальника, особливості transcript/tooling, підказки для transport/cache). Це не те саме, що [публічна модель capability](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє Plugin (text inference, speech тощо). +`capabilities` runtime постачальника — це спільні метадані runner (сімейство постачальника, особливості transcript/tooling, підказки для transport/cache). Це не те саме, що [public capability model](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє Plugin (текстовий inference, мовлення тощо). ## Ротація API-ключів - Підтримує загальну ротацію ключів постачальника для вибраних постачальників. - Налаштуйте кілька ключів через: - - `OPENCLAW_LIVE__KEY` (одне live-перевизначення, найвищий пріоритет) - - `_API_KEYS` (список через кому або крапку з комою) + - `OPENCLAW_LIVE__KEY` (єдиний live override, найвищий пріоритет) + - `_API_KEYS` (список, розділений комами або крапками з комою) - `_API_KEY` (основний ключ) - `_API_KEY_*` (нумерований список, наприклад `_API_KEY_1`) -- Для постачальників Google `GOOGLE_API_KEY` також включається як резервний варіант. +- Для постачальників Google як fallback також використовується `GOOGLE_API_KEY`. - Порядок вибору ключів зберігає пріоритет і прибирає дублікати значень. -- Запити повторюються з наступним ключем лише у відповідь на rate-limit (наприклад, `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many +- Запити повторюються з наступним ключем лише у відповідь на rate limit + (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміти використання). -- Збої, не пов’язані з rate-limit, завершуються негайно; ротація ключів не виконується. -- Якщо всі кандидати-ключі завершуються помилкою, повертається фінальна помилка з останньої спроби. +- Помилки, не пов’язані з rate limit, одразу завершуються невдачею; ротація ключів не виконується. +- Якщо всі доступні ключі завершуються невдачею, повертається остання помилка з фінальної спроби. ## Вбудовані постачальники (каталог pi-ai) -OpenClaw постачається з каталогом pi‑ai. Для цих постачальників **не потрібна** -конфігурація `models.providers`; достатньо налаштувати auth і вибрати модель. +OpenClaw постачається з каталогом pi‑ai. Ці постачальники **не** +потребують конфігурації `models.providers`; достатньо налаштувати auth і вибрати модель. ### OpenAI - Постачальник: `openai` - Auth: `OPENAI_API_KEY` -- Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення) +- Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (єдиний override) - Приклади моделей: `openai/gpt-5.4`, `openai/gpt-5.4-mini` -- Пряма підтримка GPT-5.5 через API тут готова на майбутнє, щойно OpenAI відкриє GPT-5.5 в API +- Пряма підтримка GPT-5.5 через API тут уже підготовлена на майбутнє, щойно OpenAI відкриє GPT-5.5 в API +- Перш ніж використовувати `openai/gpt-5.5` без runtime app-server Codex, перевірте доступність прямого API через `openclaw models list --provider openai` - CLI: `openclaw onboard --auth-choice openai-api-key` -- Транспорт за замовчуванням — `auto` (спочатку WebSocket, потім резервний SSE) -- Перевизначення для окремої моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- Розігрів OpenAI Responses WebSocket типово ввімкнено через `params.openaiWsWarmup` (`true`/`false`) +- Транспорт за замовчуванням — `auto` (спочатку WebSocket, потім fallback на SSE) +- Override для окремої моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) +- Warm-up WebSocket для OpenAI Responses за замовчуванням увімкнений через `params.openaiWsWarmup` (`true`/`false`) - Пріоритетну обробку OpenAI можна ввімкнути через `agents.defaults.models["openai/"].params.serviceTier` -- `/fast` і `params.fastMode` напряму зіставляють запити `openai/*` Responses із `service_tier=priority` на `api.openai.com` -- Використовуйте `params.serviceTier`, якщо хочете явно вказати tier замість спільного перемикача `/fast` +- `/fast` і `params.fastMode` напряму зіставляють запити `openai/*` Responses з `service_tier=priority` на `api.openai.com` +- Використовуйте `params.serviceTier`, якщо вам потрібен явний tier замість спільного перемикача `/fast` - Приховані заголовки атрибуції OpenClaw (`originator`, `version`, - `User-Agent`) застосовуються лише до рідного трафіку OpenAI на `api.openai.com`, а не до загальних OpenAI-сумісних proxy -- Рідні маршрути OpenAI також зберігають `store` для Responses, підказки prompt-cache і - формування payload для сумісності з OpenAI reasoning; proxy-маршрути — ні -- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, оскільки live-запити до OpenAI API його відхиляють, а поточний каталог Codex його не показує + `User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не до загальних OpenAI-сумісних proxy +- Нативні маршрути OpenAI також зберігають Responses `store`, підказки кешу prompt і сумісне з OpenAI reasoning формування payload; proxy-маршрути цього не роблять +- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, оскільки live-запити OpenAI API його відхиляють, а поточний каталог Codex його не містить ```json5 { @@ -91,12 +90,12 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Постачальник: `anthropic` - Auth: `ANTHROPIC_API_KEY` -- Необов’язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (одне перевизначення) +- Необов’язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (єдиний override) - Приклад моделі: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком API-ключа та OAuth-auth, надісланим до `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) +- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, зокрема для трафіку з auth через API-ключ і OAuth, надісланого до `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) - Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. -- Токен налаштування Anthropic і далі доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли це можливо. +- Setup-token Anthropic залишається доступним як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, якщо вони доступні. ```json5 { @@ -108,22 +107,22 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Постачальник: `openai-codex` - Auth: OAuth (ChatGPT) -- Посилання на модель PI: `openai-codex/gpt-5.5` -- Посилання на рідний harness app-server Codex: `openai/gpt-5.5` з `agents.defaults.embeddedHarness.runtime: "codex"` +- Посилання на модель у Pi: `openai-codex/gpt-5.5` +- Посилання для нативного harness app-server Codex: `openai/gpt-5.5` з `agents.defaults.embeddedHarness.runtime: "codex"` +- Документація для нативного harness app-server Codex: [Codex harness](/uk/plugins/codex-harness) - Застарілі посилання на моделі: `codex/gpt-*` -- Межа Plugin: `openai-codex/*` завантажує Plugin OpenAI; рідний Plugin app-server Codex вибирається лише через середовище виконання harness Codex або застарілі посилання - `codex/*`. +- Межа Plugin: `openai-codex/*` завантажує Plugin OpenAI; нативний Plugin app-server Codex вибирається лише runtime Codex harness або застарілими посиланнями `codex/*`. - CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex` -- Транспорт за замовчуванням — `auto` (спочатку WebSocket, потім резервний SSE) -- Перевизначення для окремої моделі PI через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- `params.serviceTier` також передається в рідних запитах Codex Responses (`chatgpt.com/backend-api`) +- Транспорт за замовчуванням — `auto` (спочатку WebSocket, потім fallback на SSE) +- Override для окремої моделі Pi через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) +- `params.serviceTier` також передається у нативних запитах Codex Responses (`chatgpt.com/backend-api`) - Приховані заголовки атрибуції OpenClaw (`originator`, `version`, - `User-Agent`) додаються лише до рідного трафіку Codex на + `User-Agent`) додаються лише до нативного трафіку Codex на `chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних proxy - Використовує той самий перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` -- `openai-codex/gpt-5.5` зберігає рідний `contextWindow = 1000000` і типовий runtime `contextTokens = 272000`; перевизначте runtime-ліміт через `models.providers.openai-codex.models[].contextTokens` +- `openai-codex/gpt-5.5` зберігає нативний `contextWindow = 1000000` і runtime `contextTokens = 272000` за замовчуванням; override runtime-обмеження задається через `models.providers.openai-codex.models[].contextTokens` - Примітка щодо політики: OpenAI Codex OAuth явно підтримується для зовнішніх інструментів/процесів на кшталт OpenClaw. -- Поточний доступ до GPT-5.5 використовує цей маршрут OAuth/підписки, доки OpenAI не ввімкне GPT-5.5 у публічному API. +- Поточний доступ до GPT-5.5 використовує цей маршрут OAuth/підписки, доки OpenAI не увімкне GPT-5.5 у публічному API. ```json5 { @@ -143,11 +142,11 @@ OpenClaw постачається з каталогом pi‑ai. Для цих } ``` -### Інші хостингові варіанти у стилі підписки +### Інші хостовані варіанти в стилі підписки -- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud, а також зіставлення кінцевих точок Alibaba DashScope і Coding Plan -- [MiniMax](/uk/providers/minimax): доступ MiniMax Coding Plan через OAuth або API-ключ -- [GLM Models](/uk/providers/glm): кінцеві точки Z.AI Coding Plan або загального API +- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud, а також зіставлення endpoint для Alibaba DashScope і Coding Plan +- [MiniMax](/uk/providers/minimax): доступ до MiniMax Coding Plan через OAuth або API-ключ +- [GLM Models](/uk/providers/glm): endpoint Z.AI Coding Plan або загальні API endpoint ### OpenCode @@ -167,33 +166,30 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Постачальник: `google` - Auth: `GEMINI_API_KEY` -- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення) +- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback `GOOGLE_API_KEY`, а також `OPENCLAW_LIVE_GEMINI_KEY` (єдиний override) - Приклади моделей: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - Сумісність: застарілу конфігурацію OpenClaw з `google/gemini-3.1-flash-preview` нормалізовано до `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` -- Thinking: `/think adaptive` використовує динамічне thinking від Google. Gemini 3/3.1 не мають фіксованого - `thinkingLevel`; Gemini 2.5 надсилає `thinkingBudget: -1`. +- Thinking: `/think adaptive` використовує Google dynamic thinking. Gemini 3/3.1 не мають фіксованого `thinkingLevel`; Gemini 2.5 надсилає `thinkingBudget: -1`. - Прямі запуски Gemini також приймають `agents.defaults.models["google/"].params.cachedContent` - (або застаріле `cached_content`) для передачі рідного для постачальника - дескриптора `cachedContents/...`; попадання в кеш Gemini відображаються як OpenClaw `cacheRead` + (або застарілий `cached_content`) для передавання нативного + дескриптора `cachedContents/...`; cache hit Gemini відображаються як OpenClaw `cacheRead` ### Google Vertex і Gemini CLI - Постачальники: `google-vertex`, `google-gemini-cli` - Auth: Vertex використовує gcloud ADC; Gemini CLI використовує власний потік OAuth -- Застереження: Gemini CLI OAuth в OpenClaw — це неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Перегляньте умови Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. -- Gemini CLI OAuth постачається як частина вбудованого Plugin `google`. +- Застереження: OAuth Gemini CLI в OpenClaw є неофіційною інтеграцією. Деякі користувачі повідомляли про обмеження акаунтів Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте не критично важливий акаунт, якщо вирішите продовжити. +- OAuth Gemini CLI постачається як частина вбудованого Plugin `google`. - Спочатку встановіть Gemini CLI: - `brew install gemini-cli` - або `npm install -g @google/gemini-cli` - - Увімкніть: `openclaw plugins enable google` - - Увійдіть: `openclaw models auth login --provider google-gemini-cli --set-default` + - Увімкнення: `openclaw plugins enable google` + - Вхід: `openclaw models auth login --provider google-gemini-cli --set-default` - Модель за замовчуванням: `google-gemini-cli/gemini-3-flash-preview` - - Примітка: **не** вставляйте client id або secret у `openclaw.json`. Потік входу CLI зберігає - токени в auth profiles на хості gateway. - - Якщо після входу запити завершуються помилкою, установіть `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway. - - JSON-відповіді Gemini CLI розбираються з `response`; використання резервно береться з - `stats`, а `stats.cached` нормалізується в OpenClaw `cacheRead`. + - Примітка: вам **не потрібно** вставляти client id або secret у `openclaw.json`. Потік входу CLI зберігає токени в профілях auth на хості gateway. + - Якщо після входу запити завершуються невдачею, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway. + - JSON-відповіді Gemini CLI розбираються з `response`; показники використання беруться з `stats`, а `stats.cached` нормалізується в OpenClaw `cacheRead`. ### Z.AI (GLM) @@ -202,7 +198,7 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Приклад моделі: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - Псевдоніми: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*` - - `zai-api-key` автоматично виявляє відповідну кінцеву точку Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово вибирають конкретну поверхню + - `zai-api-key` автоматично визначає відповідний endpoint Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово задають конкретну поверхню ### Vercel AI Gateway @@ -218,72 +214,71 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Auth: `KILOCODE_API_KEY` - Приклад моделі: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` -- Базовий URL: `https://api.kilo.ai/api/gateway/` -- Статичний резервний каталог постачається з `kilocode/kilo/auto`; live-виявлення через - `https://api.kilo.ai/api/gateway/models` може додатково розширити каталог - runtime. +- Base URL: `https://api.kilo.ai/api/gateway/` +- Статичний fallback-каталог постачається з `kilocode/kilo/auto`; live-виявлення через + `https://api.kilo.ai/api/gateway/models` може додатково розширити runtime-каталог. - Точна upstream-маршрутизація за `kilocode/kilo/auto` належить Kilo Gateway, - а не жорстко задана в OpenClaw. + а не жорстко закодована в OpenClaw. Деталі налаштування дивіться в [/providers/kilocode](/uk/providers/kilocode). ### Інші вбудовані Plugin постачальників -| Постачальник | Id | Змінна середовища auth | Приклад моделі | -| ----------------------- | -------------------------------- | ------------------------------------------------------------- | ---------------------------------------------- | -| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | -| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | -| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | -| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` | -| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — | -| Groq | `groq` | `GROQ_API_KEY` | — | -| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` або `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | -| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | -| Kimi Coding | `kimi` | `KIMI_API_KEY` або `KIMICODE_API_KEY` | `kimi/kimi-code` | -| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` | -| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` | -| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | -| NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | -| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` | -| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` | -| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` | -| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` | -| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` | -| Venice | `venice` | `VENICE_API_KEY` | — | -| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | -| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | -| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | -| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | +| Постачальник | Id | Auth env | Приклад моделі | +| ----------------------- | -------------------------------- | ------------------------------------------------------------ | ---------------------------------------------- | +| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | +| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | +| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | +| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` | +| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — | +| Groq | `groq` | `GROQ_API_KEY` | — | +| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` або `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | +| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | +| Kimi Coding | `kimi` | `KIMI_API_KEY` або `KIMICODE_API_KEY` | `kimi/kimi-code` | +| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` | +| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` | +| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | +| NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | +| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` | +| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` | +| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` | +| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` | +| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` | +| Venice | `venice` | `VENICE_API_KEY` | — | +| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | +| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | +| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | +| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | Варто знати такі особливості: -- **OpenRouter** застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Як proxy-подібний OpenAI-сумісний шлях, він пропускає формування, доступне лише для рідного OpenAI (`serviceTier`, `store` для Responses, підказки prompt-cache, сумісність reasoning OpenAI). Посилання на основі Gemini зберігають лише очищення thought-signature для proxy-Gemini. -- **Kilo Gateway** для посилань на основі Gemini дотримується того самого шляху очищення proxy-Gemini; `kilocode/kilo/auto` та інші посилання, де reasoning через proxy не підтримується, пропускають ін’єкцію reasoning через proxy. -- **MiniMax** під час онбордингу через API-ключ записує явні визначення текстових chat-моделей M2.7; розуміння зображень залишається у медіапостачальника `MiniMax-VL-01`, що належить Plugin. -- **xAI** використовує шлях xAI Responses. `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast`. `tool_stream` типово ввімкнено; вимкніть через `agents.defaults.models["xai/"].params.tool_stream=false`. -- **Cerebras** моделі GLM використовують `zai-glm-4.7` / `zai-glm-4.6`; OpenAI-сумісний базовий URL — `https://api.cerebras.ai/v1`. +- **OpenRouter** застосовує свої заголовки атрибуції app і маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Як proxy-подібний OpenAI-сумісний шлях, він пропускає формування, притаманне лише нативному OpenAI (`serviceTier`, Responses `store`, підказки кешу prompt, сумісність reasoning OpenAI). Посилання, що працюють через Gemini, зберігають лише санітизацію thought signature для proxy-Gemini. +- **Kilo Gateway** для посилань, що працюють через Gemini, дотримується того самого шляху санітизації proxy-Gemini; `kilocode/kilo/auto` та інші посилання, де proxy reasoning не підтримується, пропускають ін’єкцію proxy reasoning. +- **MiniMax** онбординг через API-ключ записує явні визначення чат-моделей лише для тексту M2.7; розуміння зображень залишається на медіа-постачальнику `MiniMax-VL-01`, який належить Plugin. +- **xAI** використовує шлях xAI Responses. `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast`. `tool_stream` увімкнено за замовчуванням; вимкнення через `agents.defaults.models["xai/"].params.tool_stream=false`. +- **Cerebras** моделі GLM використовують `zai-glm-4.7` / `zai-glm-4.6`; Base URL, сумісний з OpenAI: `https://api.cerebras.ai/v1`. -## Постачальники через `models.providers` (кастомні/base URL) +## Постачальники через `models.providers` (custom/Base URL) -Використовуйте `models.providers` (або `models.json`), щоб додати **кастомних** постачальників або +Використовуйте `models.providers` (або `models.json`), щоб додавати **custom** постачальників або OpenAI/Anthropic‑сумісні proxy. -Багато вбудованих нижче Plugin постачальників уже публікують типовий каталог. -Явні записи `models.providers.` використовуйте лише тоді, коли хочете перевизначити -базовий URL, заголовки або список моделей за замовчуванням. +Багато вбудованих Plugin постачальників нижче вже публікують каталог за замовчуванням. +Явні записи `models.providers.` потрібні лише тоді, коли ви хочете перевизначити +Base URL, заголовки або список моделей за замовчуванням. ### Moonshot AI (Kimi) -Moonshot постачається як вбудований Plugin постачальника. Типово використовуйте -вбудованого постачальника й додавайте явний запис `models.providers.moonshot` лише тоді, коли -потрібно перевизначити базовий URL або метадані моделі: +Moonshot постачається як вбудований Plugin постачальника. Використовуйте вбудованого постачальника +за замовчуванням і додавайте явний запис `models.providers.moonshot` лише тоді, коли +потрібно перевизначити Base URL або метадані моделі: - Постачальник: `moonshot` - Auth: `MOONSHOT_API_KEY` - Приклад моделі: `moonshot/kimi-k2.6` - CLI: `openclaw onboard --auth-choice moonshot-api-key` або `openclaw onboard --auth-choice moonshot-api-key-cn` -Id моделей Kimi K2: +Ідентифікатори моделей Kimi K2: [//]: # "moonshot-kimi-k2-model-refs:start" @@ -316,7 +311,7 @@ Id моделей Kimi K2: ### Kimi Coding -Kimi Coding використовує Anthropic-сумісну кінцеву точку Moonshot AI: +Kimi Coding використовує Anthropic-сумісний endpoint Moonshot AI: - Постачальник: `kimi` - Auth: `KIMI_API_KEY` @@ -350,10 +345,10 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши } ``` -Онбординг типово використовує surface для coding, але загальний каталог `volcengine/*` +Онбординг за замовчуванням використовує coding-поверхню, але загальний каталог `volcengine/*` реєструється одночасно. -У засобах вибору моделей для онбордингу/налаштування варіант auth Volcengine надає перевагу рядкам +У засобах вибору моделі для онбордингу/налаштування вибір auth Volcengine віддає перевагу рядкам `volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажені, OpenClaw повертається до нефільтрованого каталогу замість показу порожнього засобу вибору в межах постачальника. @@ -391,10 +386,10 @@ BytePlus ARK надає міжнародним користувачам дост } ``` -Онбординг типово використовує surface для coding, але загальний каталог `byteplus/*` +Онбординг за замовчуванням використовує coding-поверхню, але загальний каталог `byteplus/*` реєструється одночасно. -У засобах вибору моделей для онбордингу/налаштування варіант auth BytePlus надає перевагу рядкам +У засобах вибору моделі для онбордингу/налаштування вибір auth BytePlus віддає перевагу рядкам `byteplus/*` і `byteplus-plan/*`. Якщо ці моделі ще не завантажені, OpenClaw повертається до нефільтрованого каталогу замість показу порожнього засобу вибору в межах постачальника. @@ -443,37 +438,37 @@ Synthetic надає Anthropic-сумісні моделі через поста ### MiniMax -MiniMax налаштовується через `models.providers`, оскільки використовує кастомні кінцеві точки: +MiniMax налаштовується через `models.providers`, оскільки використовує custom endpoint: -- MiniMax OAuth (глобально): `--auth-choice minimax-global-oauth` +- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` -- MiniMax API key (глобально): `--auth-choice minimax-global-api` -- MiniMax API key (CN): `--auth-choice minimax-cn-api` +- API-ключ MiniMax (Global): `--auth-choice minimax-global-api` +- API-ключ MiniMax (CN): `--auth-choice minimax-cn-api` - Auth: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` Деталі налаштування, варіанти моделей і фрагменти конфігурації дивіться в [/providers/minimax](/uk/providers/minimax). -На Anthropic-сумісному потоковому шляху MiniMax OpenClaw типово вимикає thinking, -якщо ви явно його не встановите, а `/fast on` переписує +На Anthropic-сумісному streaming-шляху MiniMax OpenClaw за замовчуванням вимикає thinking, +якщо ви явно його не задасте, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. -Поділ capability, що належить Plugin: +Розподіл можливостей, що належить Plugin: -- Типові параметри text/chat залишаються на `minimax/MiniMax-M2.7` +- Типовий текстовий/chat-сценарій залишається на `minimax/MiniMax-M2.7` - Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01` -- Розуміння зображень — це `MiniMax-VL-01`, що належить Plugin, для обох шляхів auth MiniMax +- Розуміння зображень — це `MiniMax-VL-01`, який належить Plugin, на обох шляхах auth MiniMax - Вебпошук залишається на id постачальника `minimax` ### LM Studio -LM Studio постачається як вбудований Plugin постачальника, який використовує рідний API: +LM Studio постачається як вбудований Plugin постачальника, який використовує нативний API: - Постачальник: `lmstudio` - Auth: `LM_API_TOKEN` -- Базовий URL inference за замовчуванням: `http://localhost:1234/v1` +- Base URL inference за замовчуванням: `http://localhost:1234/v1` -Потім установіть модель (замініть на один з id, повернутих `http://localhost:1234/api/v1/models`): +Потім задайте модель (замініть на один з id, які повертає `http://localhost:1234/api/v1/models`): ```json5 { @@ -483,13 +478,13 @@ LM Studio постачається як вбудований Plugin постач } ``` -OpenClaw використовує рідні `LM Studio` `/api/v1/models` і `/api/v1/models/load` -для виявлення й автозавантаження, а `/v1/chat/completions` — для inference за замовчуванням. -Деталі налаштування й усунення несправностей дивіться в [/providers/lmstudio](/uk/providers/lmstudio). +OpenClaw використовує нативні `LM Studio` `/api/v1/models` і `/api/v1/models/load` +для виявлення й auto-load, а `/v1/chat/completions` — для inference за замовчуванням. +Налаштування й усунення несправностей дивіться в [/providers/lmstudio](/uk/providers/lmstudio). ### Ollama -Ollama постачається як вбудований Plugin постачальника й використовує рідний API Ollama: +Ollama постачається як вбудований Plugin постачальника і використовує нативний API Ollama: - Постачальник: `ollama` - Auth: не потрібен (локальний сервер) @@ -511,8 +506,8 @@ ollama pull llama3.3 Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви вмикаєте її через `OLLAMA_API_KEY`, а вбудований Plugin постачальника додає Ollama безпосередньо до -`openclaw onboard` і засобу вибору моделі. Дивіться [/providers/ollama](/uk/providers/ollama) -для онбордингу, хмарного/локального режиму та кастомної конфігурації. +`openclaw onboard` і засобу вибору моделі. Докладніше про онбординг, хмарний/локальний режим +і custom-конфігурацію дивіться в [/providers/ollama](/uk/providers/ollama). ### vLLM @@ -521,15 +516,15 @@ vLLM постачається як вбудований Plugin постачал - Постачальник: `vllm` - Auth: необов’язковий (залежить від вашого сервера) -- Базовий URL за замовчуванням: `http://127.0.0.1:8000/v1` +- Base URL за замовчуванням: `http://127.0.0.1:8000/v1` -Щоб увімкнути автовиявлення локально (підійде будь-яке значення, якщо ваш сервер не вимагає auth): +Щоб локально ввімкнути auto-discovery (підійде будь-яке значення, якщо ваш сервер не вимагає auth): ```bash export VLLM_API_KEY="vllm-local" ``` -Потім установіть модель (замініть на один з id, повернутих `/v1/models`): +Потім задайте модель (замініть на один з id, які повертає `/v1/models`): ```json5 { @@ -539,7 +534,7 @@ export VLLM_API_KEY="vllm-local" } ``` -Деталі дивіться в [/providers/vllm](/uk/providers/vllm). +Подробиці дивіться в [/providers/vllm](/uk/providers/vllm). ### SGLang @@ -548,16 +543,16 @@ OpenAI-сумісних серверів: - Постачальник: `sglang` - Auth: необов’язковий (залежить від вашого сервера) -- Базовий URL за замовчуванням: `http://127.0.0.1:30000/v1` +- Base URL за замовчуванням: `http://127.0.0.1:30000/v1` -Щоб увімкнути автовиявлення локально (підійде будь-яке значення, якщо ваш сервер не +Щоб локально ввімкнути auto-discovery (підійде будь-яке значення, якщо ваш сервер не вимагає auth): ```bash export SGLANG_API_KEY="sglang-local" ``` -Потім установіть модель (замініть на один з id, повернутих `/v1/models`): +Потім задайте модель (замініть на один з id, які повертає `/v1/models`): ```json5 { @@ -567,7 +562,7 @@ export SGLANG_API_KEY="sglang-local" } ``` -Деталі дивіться в [/providers/sglang](/uk/providers/sglang). +Подробиці дивіться в [/providers/sglang](/uk/providers/sglang). ### Локальні proxy (LM Studio, vLLM, LiteLLM тощо) @@ -606,24 +601,21 @@ export SGLANG_API_KEY="sglang-local" Примітки: -- Для кастомних постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` необов’язкові. - Якщо їх пропущено, OpenClaw використовує такі значення за замовчуванням: +- Для custom-постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими. + Якщо їх не задано, OpenClaw використовує такі значення за замовчуванням: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- Рекомендовано: установлюйте явні значення, що відповідають лімітам вашого proxy/моделі. -- Для `api: "openai-completions"` на нерідних кінцевих точках (будь-який непорожній `baseUrl`, чий хост не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникати помилок постачальника 400 через непідтримувані ролі `developer`. -- Proxy-подібні OpenAI-сумісні маршрути також пропускають формування запитів, доступне лише для рідного OpenAI: - без `service_tier`, без `store` для Responses, без `store` для Completions, без - підказок prompt-cache, без формування payload для сумісності з OpenAI reasoning і без прихованих - заголовків атрибуції OpenClaw. -- Для OpenAI-сумісних proxy Completions, яким потрібні поля, специфічні для постачальника, - установіть `agents.defaults.models["provider/model"].params.extra_body` (або - `extraBody`), щоб об’єднати додатковий JSON із вихідним тілом запиту. -- Якщо `baseUrl` порожній/не вказаний, OpenClaw зберігає типову поведінку OpenAI (яка вказує на `api.openai.com`). -- З міркувань безпеки явне `compat.supportsDeveloperRole: true` усе одно перевизначається на нерідних кінцевих точках `openai-completions`. +- Рекомендовано: задавайте явні значення, що відповідають обмеженням вашої proxy/моделі. +- Для `api: "openai-completions"` на ненативних endpoint (будь-який непорожній `baseUrl`, чий хост не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникнути помилок постачальника 400 через непідтримувані ролі `developer`. +- Proxy-подібні OpenAI-сумісні маршрути також пропускають формування запитів, притаманне лише нативному OpenAI: без `service_tier`, без Responses `store`, без Completions `store`, без підказок кешу prompt, без формування payload для сумісності reasoning OpenAI і без прихованих заголовків атрибуції OpenClaw. +- Для OpenAI-сумісних Completions proxy, яким потрібні поля, специфічні для постачальника, + задайте `agents.defaults.models["provider/model"].params.extra_body` (або + `extraBody`), щоб об’єднати додатковий JSON у вихідне тіло запиту. +- Якщо `baseUrl` порожній або не заданий, OpenClaw зберігає стандартну поведінку OpenAI (яка зводиться до `api.openai.com`). +- Для безпеки явне `compat.supportsDeveloperRole: true` однаково перевизначається на ненативних endpoint `openai-completions`. ## Приклади CLI @@ -633,11 +625,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -Дивіться також: [/gateway/configuration](/uk/gateway/configuration) для повних прикладів конфігурації. +Дивіться також: [/gateway/configuration](/uk/gateway/configuration), де наведено повні приклади конфігурації. -## Пов’язані матеріали +## Пов’язане - [Models](/uk/concepts/models) — конфігурація моделей і псевдоніми -- [Model Failover](/uk/concepts/model-failover) — ланцюжки резервного перемикання й поведінка повторних спроб -- [Configuration Reference](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей -- [Providers](/uk/providers) — посібники з налаштування для кожного постачальника +- [Model Failover](/uk/concepts/model-failover) — ланцюжки fallback і поведінка повторних спроб +- [Configuration Reference](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделі +- [Providers](/uk/providers) — окремі інструкції з налаштування для кожного постачальника diff --git a/docs/uk/gateway/config-agents.md b/docs/uk/gateway/config-agents.md index ae4c14b23..d3b5905b5 100644 --- a/docs/uk/gateway/config-agents.md +++ b/docs/uk/gateway/config-agents.md @@ -1,24 +1,24 @@ --- read_when: - Налаштування типових параметрів агента (моделі, thinking, робочий простір, Heartbeat, медіа, Skills) - - Налаштування маршрутизації між кількома агентами та прив’язок - - Налаштування сеансу, доставки повідомлень і поведінки режиму talk + - Налаштування маршрутизації та прив’язок між кількома агентами + - Налаштування сесії, доставки повідомлень і поведінки режиму talk summary: Типові налаштування агента, маршрутизація між кількома агентами, сесія, повідомлення та конфігурація talk title: Конфігурація — агенти x-i18n: - generated_at: "2026-04-25T03:24:45Z" + generated_at: "2026-04-25T03:44:16Z" model: gpt-5.4 provider: openai - source_hash: 20cf1d6c2d491da51db3f383784a0ef1cc2622d25290987d0a3406147e92f462 + source_hash: 7f90c51056f82494f893eaab9e3d2acf509c05096e5a1f64b33611ca34125c2b source_path: gateway/config-agents.md workflow: 15 --- -Ключі конфігурації в області агента під `agents.*`, `multiAgent.*`, `session.*`, +Ключі конфігурації в межах агента під `agents.*`, `multiAgent.*`, `session.*`, `messages.*` і `talk.*`. Для каналів, інструментів, середовища виконання Gateway та інших ключів верхнього рівня див. [Довідник з конфігурації](/uk/gateway/configuration-reference). -## Типові параметри агента +## Типові налаштування агента ### `agents.defaults.workspace` @@ -32,7 +32,7 @@ x-i18n: ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, який показується в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, піднімаючись угору від робочого простору. +Необов’язковий корінь репозиторію, який показується в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, підіймаючись угору від робочого простору. ```json5 { @@ -42,7 +42,7 @@ x-i18n: ### `agents.defaults.skills` -Необов’язковий типовий список дозволених Skills для агентів, у яких не задано +Необов’язковий типовий список дозволених Skills для агентів, які не задають `agents.list[].skills`. ```json5 @@ -58,9 +58,9 @@ x-i18n: } ``` -- Пропустіть `agents.defaults.skills`, щоб типово дозволити необмежені Skills. -- Пропустіть `agents.list[].skills`, щоб успадкувати типові значення. -- Установіть `agents.list[].skills: []`, щоб не було жодних Skills. +- Опустіть `agents.defaults.skills`, щоб типово дозволити необмежені Skills. +- Опустіть `agents.list[].skills`, щоб успадкувати типові значення. +- Укажіть `agents.list[].skills: []`, щоб не було Skills. - Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він не об’єднується з типовими значеннями. @@ -76,9 +76,9 @@ x-i18n: ### `agents.defaults.contextInjection` -Керує тим, коли bootstrap-файли робочого простору вставляються в системний запит. Типове значення: `"always"`. +Керує тим, коли bootstrap-файли робочого простору вбудовуються в системний запит. Типове значення: `"always"`. -- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне вставлення bootstrap-даних робочого простору, що зменшує розмір запиту. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст. +- `"continuation-skip"`: у безпечних ходах продовження (після завершеної відповіді асистента) повторне вбудовування bootstrap-даних робочого простору пропускається, що зменшує розмір запиту. Запуски Heartbeat і повторні спроби після Compaction все одно перебудовують контекст. ```json5 { @@ -88,7 +88,7 @@ x-i18n: ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів на один bootstrap-файл робочого простору до обрізання. Типове значення: `12000`. +Максимальна кількість символів для кожного bootstrap-файлу робочого простору перед обрізанням. Типове значення: `12000`. ```json5 { @@ -98,7 +98,7 @@ x-i18n: ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що вставляються з усіх bootstrap-файлів робочого простору. Типове значення: `60000`. +Максимальна загальна кількість символів, що вбудовується з усіх bootstrap-файлів робочого простору. Типове значення: `60000`. ```json5 { @@ -108,12 +108,12 @@ x-i18n: ### `agents.defaults.bootstrapPromptTruncationWarning` -Керує видимим для агента попередженням, коли bootstrap-контекст обрізається. +Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається. Типове значення: `"once"`. -- `"off"`: ніколи не вставляти текст попередження в системний запит. -- `"once"`: вставляти попередження один раз для кожного унікального сигнатурного випадку обрізання (рекомендовано). -- `"always"`: вставляти попередження під час кожного запуску, коли є обрізання. +- `"off"`: ніколи не вбудовувати текст попередження в системний запит. +- `"once"`: вбудовувати попередження один раз для кожного унікального підпису обрізання (рекомендовано). +- `"always"`: вбудовувати попередження під час кожного запуску, якщо є обрізання. ```json5 { @@ -121,24 +121,24 @@ x-i18n: } ``` -### Карта відповідальності за бюджет контексту +### Карта володіння бюджетами контексту -OpenClaw має кілька високонавантажених бюджетів запиту/контексту, і вони -навмисно розділені між підсистемами, а не проходять через один загальний -параметр. +В OpenClaw є кілька об’ємних бюджетів запиту/контексту, і вони +навмисно розділені між підсистемами, а не зведені до одного загального +параметра. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - звичайне вставлення bootstrap-даних робочого простору. + звичайне вбудовування bootstrap-даних робочого простору. - `agents.defaults.startupContext.*`: - одноразова стартова преамбула для `/new` і `/reset`, зокрема недавні - файли `memory/*.md` за днями. + одноразова стартова преамбула для `/new` і `/reset`, включно з недавніми + файлами `memory/*.md` за день. - `skills.limits.*`: - компактний список Skills, що вставляється в системний запит. + стиснений список Skills, вбудований у системний запит. - `agents.defaults.contextLimits.*`: - обмежені уривки часу виконання та вставлені блоки, що належать середовищу виконання. + обмежені витяги середовища виконання та вбудовані блоки, якими володіє runtime. - `memory.qmd.limits.*`: - розмір уривків і вставок для індексованого пошуку в пам’яті. + розмір фрагментів індексованого пошуку по пам’яті та їх вбудовування. Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший бюджет: @@ -148,7 +148,7 @@ OpenClaw має кілька високонавантажених бюджеті #### `agents.defaults.startupContext` -Керує стартовою преамбулою першого ходу, що вставляється під час базових запусків `/new` і `/reset`. +Керує стартовою преамбулою першого ходу, яка вбудовується в порожні запуски `/new` і `/reset`. ```json5 { @@ -186,18 +186,18 @@ OpenClaw має кілька високонавантажених бюджеті } ``` -- `memoryGetMaxChars`: типове обмеження уривка `memory_get` до того, як буде додано метадані - обрізання та повідомлення про продовження. +- `memoryGetMaxChars`: типовий ліміт витягу `memory_get` перед додаванням + метаданих обрізання та повідомлення про продовження. - `memoryGetDefaultLines`: типове вікно рядків `memory_get`, коли `lines` - не вказано. -- `toolResultMaxChars`: поточне обмеження результату інструмента, що використовується для збережених результатів і + пропущено. +- `toolResultMaxChars`: ліміт результату інструмента в реальному часі, що використовується для збережених результатів і відновлення після переповнення. -- `postCompactionMaxChars`: обмеження уривка AGENTS.md, що використовується під час вставлення +- `postCompactionMaxChars`: ліміт витягу `AGENTS.md`, що використовується під час вбудовування оновлення після Compaction. #### `agents.list[].contextLimits` -Перевизначення окремого агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються +Перевизначення для окремого агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються з `agents.defaults.contextLimits`. ```json5 @@ -224,7 +224,7 @@ OpenClaw має кілька високонавантажених бюджеті #### `skills.limits.maxSkillsPromptChars` -Глобальне обмеження для компактного списку Skills, що вставляється в системний запит. Це +Глобальний ліміт для стисненого списку Skills, вбудованого в системний запит. Це не впливає на читання файлів `SKILL.md` за потреби. ```json5 @@ -261,8 +261,8 @@ OpenClaw має кілька високонавантажених бюджеті Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень транскрипту/інструментів перед викликами провайдера. Типове значення: `1200`. -Нижчі значення зазвичай зменшують використання vision-токенів і розмір корисного навантаження запиту для сценаріїв із великою кількістю знімків екрана. -Вищі значення зберігають більше візуальних деталей. +Менші значення зазвичай зменшують використання vision-токенів і розмір тіла запиту для сценаріїв із великою кількістю знімків екрана. +Більші значення зберігають більше візуальних деталей. ```json5 { @@ -322,7 +322,7 @@ OpenClaw має кілька високонавантажених бюджеті }, params: { cacheRetention: "long" }, // глобальні типові параметри провайдера embeddedHarness: { - runtime: "pi", // pi | auto | зареєстрований ідентифікатор harness, наприклад codex + runtime: "pi", // pi | auto | registered harness id, e.g. codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -340,51 +340,51 @@ OpenClaw має кілька високонавантажених бюджеті ``` - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Форма рядка задає лише основну модель. - - Форма об’єкта задає основну модель і впорядкований список резервних моделей. + - Рядкова форма задає лише основну модель. + - Об’єктна форма задає основну модель і впорядкований список моделей для перемикання при збої. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується шляхом інструмента `image` як конфігурація його vision-моделі. - - Також використовується як резервна маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення. + - Також використовується для резервної маршрутизації, коли вибрана/типова модель не може приймати вхідні зображення. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/Plugin, що генерує зображення. - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-2` для OpenAI Images. - - Якщо ви вибираєте конкретний provider/model напряму, також налаштуйте відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2`, `FAL_KEY` для `fal/*`). - - Якщо параметр не задано, `image_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку `provider-id`. + - Якщо ви напряму вибираєте `provider/model`, також налаштуйте відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2`, `FAL_KEY` для `fal/*`). + - Якщо значення пропущено, `image_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку `provider-id`. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. + - Використовується спільною можливістю генерації музики і вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`. - - Якщо параметр не задано, `music_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку `provider-id`. - - Якщо ви вибираєте конкретний provider/model напряму, також налаштуйте відповідну автентифікацію провайдера/API key. + - Якщо значення пропущено, `music_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку `provider-id`. + - Якщо ви напряму вибираєте `provider/model`, також налаштуйте відповідну автентифікацію провайдера/API-ключ. - `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`. + - Використовується спільною можливістю генерації відео і вбудованим інструментом `video_generate`. - Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`. - - Якщо параметр не задано, `video_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку `provider-id`. - - Якщо ви вибираєте конкретний provider/model напряму, також налаштуйте відповідну автентифікацію провайдера/API key. + - Якщо значення пропущено, `video_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку `provider-id`. + - Якщо ви напряму вибираєте `provider/model`, також налаштуйте відповідну автентифікацію провайдера/API-ключ. - Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується інструментом `pdf` для маршрутизації моделі. - - Якщо параметр не задано, інструмент PDF використовує `imageModel`, а потім визначену для сеансу/типову модель. -- `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. -- `pdfMaxPages`: типова максимальна кількість сторінок, що враховуються режимом резервного витягування в інструменті `pdf`. + - Якщо значення пропущено, інструмент PDF використовує резервно `imageModel`, а потім визначену модель сесії/типову модель. +- `pdfMaxBytesMb`: типовий ліміт розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. +- `pdfMaxPages`: типова максимальна кількість сторінок, що враховується в режимі резервного витягування в інструменті `pdf`. - `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`. - `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`. -- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4` для доступу за API key або `openai-codex/gpt-5.5` для Codex OAuth). Якщо ви пропустите провайдера, OpenClaw спочатку спробує alias, потім унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише після цього повернеться до налаштованого типового провайдера (застаріла поведінка сумісності, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повернеться до першого налаштованого provider/model замість показу застарілого типового значення від видаленого провайдера. +- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4` для доступу за API-ключем або `openai-codex/gpt-5.5` для Codex OAuth). Якщо провайдера не вказано, OpenClaw спочатку пробує псевдонім, потім унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише після цього повертається до налаштованого типового провайдера (застаріла сумісна поведінка, тому краще вказувати явний `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення видаленого провайдера. - `models`: налаштований каталог моделей і список дозволених значень для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера параметри, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `extra_body`/`extraBody`). - - Безпечне редагування: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відмовиться від замін, які видалили б наявні записи зі списку дозволених, якщо не передати `--replace`. - - Потоки налаштування/онбордингу, прив’язані до провайдера, об’єднують вибрані моделі провайдера в цю мапу та зберігають уже налаштованих сторонніх провайдерів. - - Для прямих моделей OpenAI Responses автоматично вмикається server-side Compaction. Використовуйте `params.responsesServerCompaction: false`, щоб припинити вставлення `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Див. [Server-side compaction OpenAI](/uk/providers/openai#server-side-compaction-responses-api). + - Безпечні зміни: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відмовляється від замін, які видалили б наявні записи зі списку дозволених, якщо ви не передасте `--replace`. + - Потоки налаштування/онбордингу на рівні провайдера об’єднують вибрані моделі провайдера в цю мапу і зберігають уже налаштованих, не пов’язаних із цим, провайдерів. + - Для прямих моделей OpenAI Responses автоматично вмикається серверний Compaction. Використовуйте `params.responsesServerCompaction: false`, щоб припинити додавання `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Див. [Серверний Compaction OpenAI](/uk/providers/openai#server-side-compaction-responses-api). - `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`). -- Пріоритет об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається через `agents.defaults.models["provider/model"].params` (для моделі), а потім `agents.list[].params` (відповідний ідентифікатор агента) перевизначає за ключем. Докладніше див. [Кешування запитів](/uk/reference/prompt-caching). -- `params.extra_body`/`params.extraBody`: розширений JSON прямої передачі, який об’єднується з тілами запитів `api: "openai-completions"` для OpenAI-сумісних проксі. Якщо він конфліктує зі згенерованими ключами запиту, пріоритет має extra body; маршрути completions, що не є нативними, після цього все одно вилучають OpenAI-специфічний `store`. -- `embeddedHarness`: типова політика низькорівневого runtime вбудованого агента. Якщо `runtime` не задано, типовим є OpenClaw Pi. Використовуйте `runtime: "pi"`, щоб примусово вибрати вбудований harness PI, `runtime: "auto"`, щоб зареєстровані Plugin harness могли перехоплювати підтримувані моделі, або зареєстрований ідентифікатор harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичне резервне повернення на PI. Явні runtime Plugin, такі як `codex`, типово завершуються без резервування, якщо ви не вкажете `fallback: "pi"` у тій самій області перевизначення. Зберігайте посилання на моделі в канонічному вигляді `provider/model`; вибирайте Codex, Claude CLI, Gemini CLI та інші бекенди виконання через конфігурацію runtime, а не через застарілі префікси runtime provider. Див. [Середовища виконання агента](/uk/concepts/agent-runtimes), щоб зрозуміти, чим це відрізняється від вибору provider/model. -- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта та, за можливості, зберігають наявні списки fallback. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів у межах сеансів (кожен сеанс усе одно серіалізується). Типове значення: 4. +- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається через `agents.defaults.models["provider/model"].params` (для окремої моделі), а потім `agents.list[].params` (для відповідного `agent id`) перевизначає за ключем. Докладніше див. [Кешування запитів](/uk/reference/prompt-caching). +- `params.extra_body`/`params.extraBody`: розширений JSON для наскрізної передачі, який зливається з тілами запитів `api: "openai-completions"` для OpenAI-сумісних проксі. Якщо він конфліктує зі згенерованими ключами запиту, перемагає додаткове тіло; не нативні маршрути completions після цього все одно видаляють OpenAI-специфічний `store`. +- `embeddedHarness`: типова політика низькорівневого середовища виконання вбудованого агента. Якщо `runtime` пропущено, типово використовується OpenClaw Pi. Використовуйте `runtime: "pi"`, щоб примусово ввімкнути вбудований harness PI, `runtime: "auto"`, щоб дозволити зареєстрованим harness-ам Plugin перехоплювати підтримувані моделі, або ідентифікатор зареєстрованого harness-а, наприклад `runtime: "codex"`. Укажіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. Явні runtime-и Plugin, такі як `codex`, типово працюють у режимі fail closed, якщо в тій самій області перевизначення не задано `fallback: "pi"`. Зберігайте посилання на моделі в канонічному форматі `provider/model`; вибирайте Codex, Claude CLI, Gemini CLI та інші бекенди виконання через конфігурацію runtime, а не через застарілі префікси runtime-провайдера. Див. [Середовища виконання агента](/uk/concepts/agent-runtimes), щоб зрозуміти, чим це відрізняється від вибору провайдера/моделі. +- Записувачі конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення резервних варіантів), зберігають канонічну форму об’єкта і, коли можливо, зберігають наявні списки резервних моделей. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізована). Типове значення: 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness` керує тим, який низькорівневий виконавець обробляє ходи вбудованого агента. -У більшості розгортань слід залишити типовий runtime OpenClaw Pi. -Використовуйте його, коли довірений Plugin надає нативний harness, наприклад вбудований +`embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента. +У більшості розгортань слід залишити типове середовище виконання OpenClaw Pi. +Використовуйте це, коли довірений Plugin надає нативний harness, наприклад вбудований harness сервера застосунку Codex. Для концептуальної моделі див. [Середовища виконання агента](/uk/concepts/agent-runtimes). @@ -402,16 +402,16 @@ harness сервера застосунку Codex. Для концептуаль } ``` -- `runtime`: `"auto"`, `"pi"` або ідентифікатор зареєстрованого Plugin harness. Вбудований Plugin Codex реєструє `codex`. -- `fallback`: `"pi"` або `"none"`. У режимі `runtime: "auto"` пропущене значення `fallback` типово дорівнює `"pi"`, щоб старі конфігурації могли й далі використовувати PI, коли жоден Plugin harness не перехоплює запуск. У режимі явного runtime Plugin, наприклад `runtime: "codex"`, пропущене значення `fallback` типово дорівнює `"none"`, щоб відсутній harness спричиняв помилку замість тихого використання PI. Перевизначення runtime не успадковують `fallback` з ширшої області; задайте `fallback: "pi"` разом з явним runtime, коли ви свідомо хочете таке резервне повернення для сумісності. Помилки вибраного Plugin harness завжди показуються безпосередньо. -- Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` перевизначає `fallback` для цього процесу. -- Для розгортань лише з Codex задайте `model: "openai/gpt-5.5"` і `embeddedHarness.runtime: "codex"`. Ви також можете явно встановити `embeddedHarness.fallback: "none"` для наочності; це типове значення для явних runtime Plugin. -- Вибір harness фіксується для кожного ідентифікатора сеансу після першого вбудованого запуску. Зміни конфігурації/середовища впливають на нові або скинуті сеанси, але не на наявний транскрипт. Застарілі сеанси з історією транскрипту, але без зафіксованого вибору, вважаються закріпленими за PI. `/status` показує ідентифікатори harness, відмінні від PI, такі як `codex`, поруч із `Fast`. -- Це керує лише harness вбудованого чату. Генерація медіа, vision, PDF, музики, відео та TTS, як і раніше, використовують свої параметри provider/model. +- `runtime`: `"auto"`, `"pi"` або ідентифікатор зареєстрованого harness-а Plugin. Вбудований Plugin Codex реєструє `codex`. +- `fallback`: `"pi"` або `"none"`. У режимі `runtime: "auto"` пропущений `fallback` типово дорівнює `"pi"`, щоб старі конфігурації могли й далі використовувати PI, коли жоден harness Plugin не перехоплює запуск. У режимі явного runtime Plugin, наприклад `runtime: "codex"`, пропущений `fallback` типово дорівнює `"none"`, тому відсутній harness спричиняє збій замість тихого використання PI. Перевизначення runtime не успадковують `fallback` із ширшої області; задайте `fallback: "pi"` разом з явним runtime, коли вам свідомо потрібна така сумісність. Помилки вибраного harness-а Plugin завжди показуються безпосередньо. +- Перевизначення через змінні середовища: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` перевизначає `fallback` для цього процесу. +- Для розгортань лише з Codex задайте `model: "openai/gpt-5.5"` і `embeddedHarness.runtime: "codex"`. Ви також можете явно задати `embeddedHarness.fallback: "none"` для наочності; це типове значення для явних runtime-ів Plugin. +- Вибір harness-а фіксується для кожного `session id` після першого вбудованого запуску. Зміни конфігурації/оточення впливають на нові або скинуті сесії, а не на наявний транскрипт. Застарілі сесії з історією транскрипту, але без записаної фіксації, трактуються як прив’язані до PI. `/status` показує ефективний runtime, наприклад `Runtime: OpenClaw Pi Default` або `Runtime: OpenAI Codex`. +- Це керує лише вбудованим chat harness. Генерація медіа, vision, PDF, музика, відео і TTS, як і раніше, використовують свої налаштування провайдера/моделі. -**Вбудовані скорочення alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): +**Вбудовані скорочені псевдоніми** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): -| Alias | Модель | +| Псевдонім | Модель | | ------------------- | -------------------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -422,15 +422,15 @@ harness сервера застосунку Codex. Для концептуаль | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Ваші налаштовані alias завжди мають пріоритет над типовими. +Ваші налаштовані псевдоніми завжди мають пріоритет над типовими. -Для моделей Z.AI GLM-4.x режим thinking вмикається автоматично, якщо ви не встановите `--thinking off` або не визначите `agents.defaults.models["zai/"].params.thinking` самостійно. -Для моделей Z.AI `tool_stream` типово ввімкнено для потокової передачі викликів інструментів. Установіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути його. -Для моделей Anthropic Claude 4.6 типовим є thinking `adaptive`, якщо не задано явний рівень thinking. +Для моделей Z.AI GLM-4.x режим thinking автоматично вмикається, якщо ви не задасте `--thinking off` або самостійно не визначите `agents.defaults.models["zai/"].params.thinking`. +Для моделей Z.AI типово вмикається `tool_stream` для потокової передачі викликів інструментів. Задайте `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. +Для моделей Anthropic Claude 4.6 типово використовується `adaptive` thinking, коли явний рівень thinking не задано. ### `agents.defaults.cliBackends` -Необов’язкові CLI-бекенди для резервних текстових запусків (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють. +Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як резервний варіант, коли API-провайдери не працюють. ```json5 { @@ -459,12 +459,12 @@ harness сервера застосунку Codex. Для концептуаль ``` - CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені. -- Сеанси підтримуються, коли задано `sessionArg`. +- Сесії підтримуються, коли задано `sessionArg`. - Наскрізна передача зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` -Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами. +Замінює весь системний запит, зібраний OpenClaw, на фіксований рядок. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами. ```json5 { @@ -478,7 +478,7 @@ harness сервера застосунку Codex. Для концептуаль ### `agents.defaults.promptOverlays` -Незалежні від провайдера накладки запиту, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки для різних провайдерів; `personality` керує лише шаром дружнього стилю взаємодії. +Незалежні від провайдера накладки запиту, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки між провайдерами; `personality` керує лише шаром дружнього стилю взаємодії. ```json5 { @@ -496,7 +496,7 @@ harness сервера застосунку Codex. Для концептуаль - `"friendly"` (типове значення) і `"on"` вмикають шар дружнього стилю взаємодії. - `"off"` вимикає лише дружній шар; позначений контракт поведінки GPT-5 залишається ввімкненим. -- Застаріле `plugins.entries.openai.config.personality` усе ще зчитується, якщо цей спільний параметр не задано. +- Застаріле `plugins.entries.openai.config.personality` усе ще зчитується, коли цей спільний параметр не задано. ### `agents.defaults.heartbeat` @@ -510,13 +510,13 @@ harness сервера застосунку Codex. Для концептуаль every: "30m", // 0m вимикає model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // типово: true; false виключає розділ Heartbeat із системного запиту - lightContext: false, // типово: false; true залишає лише HEARTBEAT.md серед bootstrap-файлів робочого простору - isolatedSession: false, // типово: false; true запускає кожен heartbeat у новому сеансі (без історії розмови) + includeSystemPromptSection: true, // типове значення: true; false пропускає розділ Heartbeat у системному запиті + lightContext: false, // типове значення: false; true залишає лише HEARTBEAT.md із bootstrap-файлів робочого простору + isolatedSession: false, // типове значення: false; true запускає кожен heartbeat у новій сесії (без історії розмови) session: "main", to: "+15555550123", directPolicy: "allow", // allow (типово) | block - target: "none", // типово: none | варіанти: last | whatsapp | telegram | discord | ... + target: "none", // типове значення: none | варіанти: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -527,15 +527,15 @@ harness сервера застосунку Codex. Для концептуаль } ``` -- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API key) або `1h` (OAuth-автентифікація). Установіть `0m`, щоб вимкнути. -- `includeSystemPromptSection`: якщо `false`, виключає розділ Heartbeat із системного запиту та пропускає вставлення `HEARTBEAT.md` у bootstrap-контекст. Типове значення: `true`. -- `suppressToolErrorWarnings`: якщо `true`, приглушує попередження про помилки інструментів під час запусків Heartbeat. -- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента Heartbeat, після якого його буде перервано. Якщо не задано, використовується `agents.defaults.timeoutSeconds`. -- `directPolicy`: політика прямої доставки/DM. `allow` (типово) дозволяє доставку до прямої цілі. `block` приглушує доставку до прямої цілі та видає `reason=dm-blocked`. -- `lightContext`: якщо `true`, запуски Heartbeat використовують полегшений bootstrap-контекст і залишають лише `HEARTBEAT.md` серед bootstrap-файлів робочого простору. -- `isolatedSession`: якщо `true`, кожен запуск Heartbeat відбувається в новому сеансі без попередньої історії розмови. Такий самий шаблон ізоляції, як і в Cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один Heartbeat приблизно зі ~100K до ~2-5K токенів. -- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, **лише ці агенти** запускають Heartbeat. -- Heartbeat виконує повноцінні ходи агента — коротші інтервали спалюють більше токенів. +- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація за API-ключем) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути. +- `includeSystemPromptSection`: коли `false`, пропускає розділ Heartbeat у системному запиті й не вбудовує `HEARTBEAT.md` у bootstrap-контекст. Типове значення: `true`. +- `suppressToolErrorWarnings`: коли `true`, пригнічує корисне навантаження попереджень про помилки інструментів під час запусків heartbeat. +- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента heartbeat, після чого його буде перервано. Якщо не задано, використовується `agents.defaults.timeoutSeconds`. +- `directPolicy`: політика доставки напряму/у DM. `allow` (типово) дозволяє доставку до прямої цілі. `block` пригнічує доставку до прямої цілі й генерує `reason=dm-blocked`. +- `lightContext`: коли `true`, запуски heartbeat використовують полегшений bootstrap-контекст і залишають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору. +- `isolatedSession`: коли `true`, кожен heartbeat запускається в новій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один heartbeat приблизно зі ~100K до ~2-5K токенів. +- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, heartbeat запускаються **лише для цих агентів**. +- Heartbeat виконують повні ходи агента — коротші інтервали витрачають більше токенів. ### `agents.defaults.compaction` @@ -545,16 +545,16 @@ harness сервера застосунку Codex. Для концептуаль defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id зареєстрованого Plugin провайдера Compaction (необов’язково) + provider: "my-provider", // id зареєстрованого Plugin провайдера compaction (необов’язково) timeoutSeconds: 900, reserveTokensFloor: 24000, keepRecentTokens: 50000, identifierPolicy: "strict", // strict | off | custom identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // використовується, коли identifierPolicy=custom qualityGuard: { enabled: true, maxRetries: 1 }, - postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне вставлення - model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для Compaction - notifyUser: true, // надсилати короткі сповіщення, коли Compaction починається і завершується (типово: false) + postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне вбудовування + model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для compaction + notifyUser: true, // надсилати короткі сповіщення користувачу, коли compaction починається і завершується (типове значення: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -567,21 +567,21 @@ harness сервера застосунку Codex. Для концептуаль } ``` -- `mode`: `default` або `safeguard` (підсумовування частинами для довгих історій). Див. [Compaction](/uk/concepts/compaction). -- `provider`: id зареєстрованого Plugin провайдера Compaction. Якщо задано, замість вбудованого підсумовування LLM викликається `summarize()` провайдера. У разі помилки повертається до вбудованого варіанта. Установлення провайдера примусово задає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). -- `timeoutSeconds`: максимальна кількість секунд, дозволених для однієї операції Compaction, після чого OpenClaw її перериває. Типове значення: `900`. -- `keepRecentTokens`: бюджет точки обрізання Pi для збереження найсвіжішого хвоста транскрипту дослівно. Ручний `/compact` враховує це значення, якщо його явно задано; інакше ручна Compaction є жорсткою контрольною точкою. -- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовану інструкцію щодо збереження непрозорих ідентифікаторів перед підсумовуванням Compaction. -- `identifierInstructions`: необов’язковий власний текст щодо збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. -- `qualityGuard`: перевірки з повторною спробою для неправильно сформованого виводу підсумків safeguard. Типово ввімкнено в режимі safeguard; установіть `enabled: false`, щоб пропустити перевірку. -- `postCompactionSections`: необов’язкові назви розділів H2/H3 з AGENTS.md для повторного вставлення після Compaction. Типове значення `["Session Startup", "Red Lines"]`; установіть `[]`, щоб вимкнути повторне вставлення. Якщо значення не задано або явно встановлено цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як резервний варіант для сумісності. -- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування Compaction. Використовуйте це, коли основний сеанс має залишатися на одній моделі, а підсумки Compaction повинні виконуватися на іншій; якщо не задано, Compaction використовує основну модель сеансу. -- `notifyUser`: якщо `true`, надсилає користувачеві короткі сповіщення, коли Compaction починається і коли вона завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб Compaction відбувалася безшумно. -- `memoryFlush`: тихий агентний хід перед автоматичною Compaction для збереження довготривалої пам’яті. Пропускається, якщо робочий простір доступний лише для читання. +- `mode`: `default` або `safeguard` (підсумовування частинами для довгої історії). Див. [Compaction](/uk/concepts/compaction). +- `provider`: id зареєстрованого Plugin провайдера compaction. Якщо задано, замість вбудованого LLM-підсумовування викликається `summarize()` цього провайдера. У разі збою відбувається повернення до вбудованого варіанта. Установлення провайдера примусово задає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). +- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції compaction, після чого OpenClaw її перериває. Типове значення: `900`. +- `keepRecentTokens`: бюджет точки відсікання Pi для збереження найсвіжішого хвоста транскрипту дослівно. Ручний `/compact` враховує це, коли значення явно задано; інакше ручний compaction є жорсткою контрольною точкою. +- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування compaction. +- `identifierInstructions`: необов’язковий власний текст про збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. +- `qualityGuard`: перевірки із повторною спробою для неправильно сформованого виводу в підсумках safeguard. Увімкнено типово в режимі safeguard; задайте `enabled: false`, щоб пропустити перевірку. +- `postCompactionSections`: необов’язкові назви секцій H2/H3 з `AGENTS.md`, які повторно вбудовуються після compaction. Типове значення — `["Session Startup", "Red Lines"]`; задайте `[]`, щоб вимкнути повторне вбудовування. Коли значення не задано або явно дорівнює цій типовій парі, старіші заголовки `Every Session`/`Safety` також приймаються як резервний варіант для сумісності. +- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а підсумки compaction повинні виконуватися на іншій; якщо не задано, compaction використовує основну модель сесії. +- `notifyUser`: коли `true`, надсилає користувачу короткі сповіщення, коли compaction починається і коли завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб compaction відбувався безшумно. +- `memoryFlush`: тихий агентний хід перед автоматичним compaction для збереження довготривалої пам’яті. Пропускається, якщо робочий простір доступний лише для читання. ### `agents.defaults.contextPruning` -Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сеансу на диску. +Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. ```json5 { @@ -589,7 +589,7 @@ harness сервера застосунку Codex. Для концептуаль defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // тривалість (ms/s/m/h), типова одиниця: хвилини + ttl: "1h", // тривалість (ms/s/m/h), одиниця типово: хвилини keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -606,24 +606,24 @@ harness сервера застосунку Codex. Для концептуаль - `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` визначає, як часто обрізання може запускатися знову (після останнього торкання кешу). -- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім за потреби повністю очищає старіші результати інструментів. +- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього оновлення кешу). +- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім, за потреби, повністю очищує старіші результати інструментів. -**М’яке скорочення** зберігає початок і кінець та вставляє `...` посередині. +**М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині. **Повне очищення** замінює весь результат інструмента заповнювачем. Примітки: -- Блоки зображень ніколи не скорочуються і не очищаються. -- Співвідношення базуються на кількості символів (наближено), а не на точній кількості токенів. +- Блоки зображень ніколи не обрізаються й не очищуються. +- Співвідношення базуються на кількості символів (приблизно), а не на точних кількостях токенів. - Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається. -Докладніше про поведінку див. [Обрізання сеансів](/uk/concepts/session-pruning). +Докладніше про поведінку див. [Обрізання сесії](/uk/concepts/session-pruning). -### Блокове потокове передавання +### Потокова передача блоками ```json5 { @@ -639,13 +639,13 @@ harness сервера застосунку Codex. Для концептуаль } ``` -- Для каналів, відмінних від Telegram, щоб увімкнути блокові відповіді, потрібно явно вказати `*.blockStreaming: true`. -- Перевизначення для каналів: `channels..blockStreamingCoalesce` (і варіанти для окремих акаунтів). Для Signal/Slack/Discord/Google Chat типове значення `minChars: 1500`. -- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500 мс. Перевизначення для окремого агента: `agents.list[].humanDelay`. +- Для каналів, відмінних від Telegram, щоб увімкнути відповіді блоками, потрібно явно задати `*.blockStreaming: true`. +- Перевизначення для каналів: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типове значення `minChars: 1500`. +- `humanDelay`: випадкова пауза між відповідями блоками. `natural` = 800–2500 мс. Перевизначення для окремого агента: `agents.list[].humanDelay`. -Докладніше про поведінку та поділ на фрагменти див. [Потокове передавання](/uk/concepts/streaming). +Докладніше про поведінку та розбиття на частини див. [Потокова передача](/uk/concepts/streaming). -### Індикатори набору тексту +### Індикатори набору ```json5 { @@ -659,15 +659,15 @@ harness сервера застосунку Codex. Для концептуаль ``` - Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. -- Перевизначення для сеансу: `session.typingMode`, `session.typingIntervalSeconds`. +- Перевизначення на рівні сесії: `session.typingMode`, `session.typingIntervalSeconds`. -Див. [Індикатори набору тексту](/uk/concepts/typing-indicators). +Див. [Індикатори набору](/uk/concepts/typing-indicators). ### `agents.defaults.sandbox` -Необов’язкове sandbox-ізолювання для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). +Необов’язкова ізоляція для вбудованого агента. Повний посібник див. у [Ізоляція](/uk/gateway/sandboxing). ```json5 { @@ -766,48 +766,48 @@ harness сервера застосунку Codex. Для концептуаль **Бекенд:** -- `docker`: локальне середовище Docker (типово) -- `ssh`: віддалене середовище загального призначення на основі SSH -- `openshell`: середовище OpenShell +- `docker`: локальне середовище виконання Docker (типово) +- `ssh`: універсальне віддалене середовище виконання на основі SSH +- `openshell`: середовище виконання OpenShell -Коли вибрано `backend: "openshell"`, параметри, специфічні для runtime, переносяться до +Коли вибрано `backend: "openshell"`, специфічні для середовища виконання налаштування переносяться до `plugins.entries.openshell.config`. -**Конфігурація бекенда SSH:** +**Конфігурація SSH-бекенда:** - `target`: ціль SSH у форматі `user@host[:port]` -- `command`: команда клієнта SSH (типово: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів у межах scope -- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються до OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRefs, які OpenClaw матеріалізує в тимчасові файли під час виконання +- `command`: команда клієнта SSH (типове значення: `ssh`) +- `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів відповідно до області видимості +- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, передані до OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRefs, які OpenClaw матеріалізує у тимчасові файли під час виконання - `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH -**Пріоритет SSH-автентифікації:** +**Пріоритет автентифікації SSH:** - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data`, підкріплені SecretRef, визначаються зі знімка активного runtime секретів до початку sandbox-сеансу +- Значення `*Data` на основі SecretRef визначаються з активного знімка середовища виконання secrets до початку сесії sandbox -**Поведінка бекенда SSH:** +**Поведінка SSH-бекенда:** - один раз ініціалізує віддалений робочий простір після створення або повторного створення -- потім підтримує віддалений SSH-робочий простір як канонічний +- далі підтримує віддалений робочий простір SSH як канонічний - маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH -- не синхронізує автоматично віддалені зміни назад на хост -- не підтримує browser-контейнери в sandbox +- не синхронізує віддалені зміни назад на хост автоматично +- не підтримує браузерні контейнери sandbox **Доступ до робочого простору:** -- `none`: робочий простір sandbox у межах scope під `~/.openclaw/sandboxes` +- `none`: робочий простір sandbox відповідно до області видимості в `~/.openclaw/sandboxes` - `ro`: робочий простір sandbox у `/workspace`, робочий простір агента змонтовано лише для читання в `/agent` -- `rw`: робочий простір агента змонтовано для читання/запису в `/workspace` +- `rw`: робочий простір агента змонтовано для читання й запису в `/workspace` -**Scope:** +**Область видимості:** -- `session`: окремий контейнер + робочий простір на сеанс -- `agent`: один контейнер + робочий простір на агента (типово) -- `shared`: спільний контейнер і робочий простір (без ізоляції між сеансами) +- `session`: окремий контейнер + робочий простір для кожної сесії +- `agent`: один контейнер + робочий простір для кожного агента (типово) +- `shared`: спільний контейнер і робочий простір (без ізоляції між сесіями) **Конфігурація Plugin OpenShell:** @@ -837,30 +837,30 @@ harness сервера застосунку Codex. Для концептуаль **Режим OpenShell:** -- `mirror`: ініціалізує віддалене середовище з локального перед `exec`, синхронізує назад після `exec`; локальний робочий простір залишається канонічним -- `remote`: один раз ініціалізує віддалене середовище під час створення sandbox, після чого віддалений робочий простір залишається канонічним +- `mirror`: ініціалізує віддалений простір із локального перед `exec`, синхронізує назад після `exec`; локальний робочий простір залишається канонічним +- `remote`: один раз ініціалізує віддалений простір під час створення sandbox, після чого віддалений робочий простір залишається канонічним -У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються автоматично до sandbox після кроку ініціалізації. -Транспортом є SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою синхронізацією mirror. +У режимі `remote` зміни на локальному хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку ініціалізації. +Транспортом є SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією. **`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного мережевого доступу, доступного для запису кореня та користувача root. -**Для контейнерів типово встановлено `network: "none"`** — задайте `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. +**Контейнери типово мають `network: "none"`** — установіть `"bridge"` (або користувацьку bridge-мережу), якщо агенту потрібен вихідний доступ. `"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний варіант). +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний режим). -**Вхідні вкладення** розміщуються в `media/inbound/*` в активному робочому просторі. +**Вхідні вкладення** розміщуються у `media/inbound/*` в активному робочому просторі. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки окремого агента об’єднуються. +**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремого агента об’єднуються. -**Browser у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вставляється в системний запит. Не потребує `browser.enabled` у `openclaw.json`. -Доступ спостерігача через noVNC типово використовує VNC-автентифікацію, і OpenClaw видає URL із короткоживучим токеном (замість розкриття пароля в спільному URL). +**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в системний запит. Не потребує `browser.enabled` у `openclaw.json`. +Доступ спостерігача noVNC типово використовує автентифікацію VNC, і OpenClaw генерує короткоживучий URL з токеном (замість того, щоб розкривати пароль у спільному URL). -- `allowHostControl: false` (типово) блокує націлювання sandbox-сеансів на browser хоста. -- Для `network` типовим є `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна зв’язність через bridge. +- `allowHostControl: false` (типово) блокує для сесій sandbox націлювання на браузер хоста. +- `network` типово дорівнює `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна зв’язність bridge. - `cdpSourceRange` за потреби обмежує вхідний доступ CDP на межі контейнера до діапазону CIDR (наприклад `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер browser у sandbox. Якщо задано (зокрема `[]`), замінює `docker.binds` для контейнера browser. -- Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для контейнерних хостів: +- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо задано (включно з `[]`), він замінює `docker.binds` для контейнера браузера. +- Типові параметри запуску визначені в `scripts/sandbox-browser-entrypoint.sh` і налаштовані для контейнерних хостів: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -879,26 +879,26 @@ harness сервера застосунку Codex. Для концептуаль - `--metrics-recording-only` - `--disable-extensions` (типово ввімкнено) - `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu` - типово ввімкнені й можуть бути вимкнені через - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо для використання WebGL/3D це потрібно. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо вони - потрібні у вашому сценарії. + типово ввімкнені, і їх можна вимкнути через + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо цього потребує використання WebGL/3D. + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш робочий процес + залежить від них. - `--renderer-process-limit=2` можна змінити через `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати - типове обмеження кількості процесів Chromium. + типовий ліміт процесів Chromium. - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. - - Типові значення є базовими для образу контейнера; щоб змінити типові параметри контейнера, - використовуйте власний образ browser із власним entrypoint. + - Типові значення є базовими для образу контейнера; використовуйте власний образ браузера з власною + точкою входу, щоб змінити типові параметри контейнера. -Sandboxing browser і `sandbox.docker.binds` доступні лише для Docker. +Ізоляція браузера та `sandbox.docker.binds` доступні лише для Docker. -Зберіть образи: +Збірка образів: ```bash -scripts/sandbox-setup.sh # основний sandbox-образ -scripts/sandbox-browser-setup.sh # необов’язковий образ browser +scripts/sandbox-setup.sh # основний образ sandbox +scripts/sandbox-browser-setup.sh # необов’язковий образ браузера ``` ### `agents.list` (перевизначення для окремого агента) @@ -916,9 +916,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br model: "anthropic/claude-opus-4-6", // або { primary, fallbacks } thinkingDefault: "high", // перевизначення рівня thinking для окремого агента reasoningDefault: "on", // перевизначення видимості reasoning для окремого агента - fastModeDefault: false, // перевизначення fast mode для окремого агента + fastModeDefault: false, // перевизначення швидкого режиму для окремого агента embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // перевизначає ключі відповідних params у defaults.models + params: { cacheRetention: "none" }, // перевизначає відповідні defaults.models params за ключем skills: ["docs-search"], // замінює agents.defaults.skills, якщо задано identity: { name: "Samantha", @@ -950,27 +950,27 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br } ``` -- `id`: стабільний ідентифікатор агента (обов’язково). -- `default`: якщо задано для кількох, перемагає перший (записується попередження). Якщо не задано для жодного, типовим стає перший запис у списку. -- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback). Завдання Cron, які перевизначають лише `primary`, усе одно успадковують типові fallback, якщо не встановити `fallbacks: []`. -- `params`: параметри потоку для окремого агента, які об’єднуються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для специфічних для агента перевизначень, як-от `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. -- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо не задано, агент успадковує `agents.defaults.skills`, коли їх задано; явний список замінює типові значення замість об’єднання, а `[]` означає відсутність Skills. -- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не задано перевизначення для повідомлення або сеансу. Вибраний профіль provider/model визначає, які значення є дійсними; для Google Gemini `adaptive` зберігає динамічний thinking, яким керує провайдер (`thinkingLevel` пропускається для Gemini 3/3.1, `thinkingBudget: -1` для Gemini 2.5). -- `reasoningDefault`: необов’язкове типове значення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, якщо не задано перевизначення reasoning для повідомлення або сеансу. -- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, якщо не задано перевизначення fast mode для повідомлення або сеансу. -- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex" }`, щоб зробити один агент лише Codex, поки інші агенти зберігають типовий fallback на PI у режимі `auto`. -- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сеанси harness ACP. +- `id`: стабільний id агента (обов’язково). +- `default`: коли встановлено кілька, перший має пріоритет (записується попередження). Якщо не встановлено жодного, типовим є перший елемент списку. +- `model`: рядкова форма перевизначає лише `primary`; об’єктна форма `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні резервні варіанти). Завдання Cron, які перевизначають лише `primary`, усе одно успадковують типові резервні варіанти, якщо ви не задасте `fallbacks: []`. +- `params`: параметри потоку для окремого агента, що зливаються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень на рівні агента, таких як `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. +- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо пропущено, агент успадковує `agents.defaults.skills`, якщо той задано; явний список замінює типові значення, а не зливається з ними, а `[]` означає відсутність Skills. +- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення для окремого повідомлення або сесії. Вибраний профіль провайдера/моделі керує тим, які значення є припустимими; для Google Gemini значення `adaptive` зберігає динамічний thinking, керований провайдером (`thinkingLevel` пропущено на Gemini 3/3.1, `thinkingBudget: -1` на Gemini 2.5). +- `reasoningDefault`: необов’язкове типове значення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для окремого повідомлення або сесії. +- `fastModeDefault`: необов’язкове типове значення швидкого режиму для окремого агента (`true | false`). Застосовується, коли не задано перевизначення fast-mode для окремого повідомлення або сесії. +- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex" }`, щоб зробити один агент лише Codex, тоді як інші агенти зберігатимуть типовий резервний PI у режимі `auto`. +- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` разом із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сесії harness ACP. - `identity.avatar`: шлях відносно робочого простору, URL `http(s)` або URI `data:`. - `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. - `subagents.allowAgents`: список дозволених id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). -- Захист успадкування sandbox: якщо сеанс запитувача виконується в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. -- `subagents.requireAgentId`: якщо `true`, блокує виклики `sessions_spawn`, які не вказують `agentId` (примушує до явного вибору профілю; типово: false). +- Захист успадкування sandbox: якщо сесія ініціатора працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. +- `subagents.requireAgentId`: коли `true`, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типове значення: false). --- ## Маршрутизація між кількома агентами -Запускайте кількох ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). +Запускайте кілька ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). ```json5 { @@ -989,12 +989,12 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ### Поля збігу прив’язки -- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип не вказано, типовим є route), `acp` для постійних прив’язок розмов ACP. +- `type` (необов’язково): `route` для звичайної маршрутизації (якщо `type` пропущено, типово використовується route), `acp` для постійних прив’язок розмов ACP. - `match.channel` (обов’язково) -- `match.accountId` (необов’язково; `*` = будь-який акаунт; якщо не вказано = типовий акаунт) +- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо пропущено = типовий обліковий запис) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) - `match.guildId` / `match.teamId` (необов’язково; залежить від каналу) -- `acp` (необов’язково; лише для `type: "acp"`): `{ mode, label, cwd, backend }` +- `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }` **Детермінований порядок збігу:** @@ -1007,7 +1007,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br У межах кожного рівня перемагає перший відповідний запис `bindings`. -Для записів `type: "acp"` OpenClaw виконує визначення за точною ідентичністю розмови (`match.channel` + акаунт + `match.peer.id`) і не використовує наведений вище порядок рівнів прив’язки route. +Для записів `type: "acp"` OpenClaw визначає збіг за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує порядок рівнів route-прив’язок, наведений вище. ### Профілі доступу для окремого агента @@ -1104,11 +1104,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br -Докладніше про пріоритети див. [Sandbox і інструменти Multi-Agent](/uk/tools/multi-agent-sandbox-tools). +Детальніше про пріоритети див. [Sandbox і інструменти Multi-Agent](/uk/tools/multi-agent-sandbox-tools). --- -## Сеанс +## Сесія ```json5 { @@ -1130,7 +1130,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // пропускати розгалуження батьківського потоку понад цю кількість токенів (0 вимикає) + parentForkMaxTokens: 100000, // пропускати відгалуження від батьківської гілки вище цього ліміту токенів (0 вимикає) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1143,7 +1143,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br threadBindings: { enabled: true, idleHours: 24, // типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає) - maxAgeHours: 0, // типове жорстке максимальне обмеження віку в годинах (`0` вимикає) + maxAgeHours: 0, // типовий жорсткий максимальний вік у годинах (`0` вимикає) }, mainKey: "main", // застаріле поле (runtime завжди використовує "main") agentToAgent: { maxPingPongTurns: 5 }, @@ -1155,37 +1155,37 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br } ``` - + -- **`scope`**: базова стратегія групування сеансів для контекстів групового чату. - - `per-sender` (типово): кожен відправник отримує ізольований сеанс у межах контексту каналу. - - `global`: усі учасники в контексті каналу спільно використовують один сеанс (використовуйте лише тоді, коли потрібен спільний контекст). +- **`scope`**: базова стратегія групування сесій для контекстів групового чату. + - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу. + - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли потрібен спільний контекст). - **`dmScope`**: як групуються DM. - - `main`: усі DM спільно використовують основний сеанс. + - `main`: усі DM використовують спільну головну сесію. - `per-peer`: ізоляція за id відправника між каналами. - - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для inbox з кількома користувачами). - - `per-account-channel-peer`: ізоляція за акаунтом + каналом + відправником (рекомендовано для кількох акаунтів). -- **`identityLinks`**: мапа канонічних id до peer із префіксом провайдера для спільного використання сеансів між каналами. -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, спрацьовує той, що завершується раніше. -- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застаріле `dm` приймається як alias для `direct`. -- **`parentForkMaxTokens`**: максимальна дозволена кількість `totalTokens` у батьківському сеансі під час створення розгалуженого сеансу потоку (типово `100000`). - - Якщо `totalTokens` у батьківському сеансі перевищує це значення, OpenClaw запускає новий сеанс потоку замість успадкування історії транскрипту батьківського сеансу. - - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти розгалуження від батьківського сеансу. -- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного контейнера прямих чатів. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів між агентами під час обміну між агентами (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжок ping-pong. -- **`sendPolicy`**: збіг за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. -- **`maintenance`**: очищення сховища сеансів + керування зберіганням. - - `mode`: `warn` лише видає попередження; `enforce` застосовує очищення. - - `pruneAfter`: межа віку для застарілих записів (типово `30d`). - - `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`). - - `rotateBytes`: ротує `sessions.json`, коли він перевищує цей розмір (типово `10mb`). - - `resetArchiveRetention`: термін зберігання архівів транскриптів `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. - - `maxDiskBytes`: необов’язковий бюджет дискового простору для каталогу сеансів. У режимі `warn` записує попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сеанси. - - `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово `80%` від `maxDiskBytes`. -- **`threadBindings`**: глобальні типові значення для функцій сеансів, прив’язаних до потоків. + - `per-channel-peer`: ізоляція для кожної пари канал + відправник (рекомендовано для багатокористувацьких inbox). + - `per-account-channel-peer`: ізоляція для кожної пари обліковий запис + канал + відправник (рекомендовано для кількох облікових записів). +- **`identityLinks`**: мапа канонічних id до peer із префіксом провайдера для спільного використання сесії між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва параметри, спрацьовує той, що завершується раніше. +- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`. +- **`parentForkMaxTokens`**: максимальна кількість `totalTokens` у батьківській сесії, дозволена під час створення розгалуженої сесії потоку (типове значення `100000`). + - Якщо значення `totalTokens` у батьківській сесії вище за це, OpenClaw запускає нову сесію потоку замість успадкування історії транскрипту батьківської сесії. + - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти відгалуження від батьківської сесії. +- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для головного кошика прямого чату. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів відповіді між агентами під час обміну агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжок ping-pong. +- **`sendPolicy`**: збіг за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перший deny має пріоритет. +- **`maintenance`**: очищення сховища сесій + керування строками зберігання. + - `mode`: `warn` лише генерує попередження; `enforce` застосовує очищення. + - `pruneAfter`: граничний вік для застарілих записів (типове значення `30d`). + - `maxEntries`: максимальна кількість записів у `sessions.json` (типове значення `500`). + - `rotateBytes`: ротує `sessions.json`, коли він перевищує цей розмір (типове значення `10mb`). + - `resetArchiveRetention`: строк зберігання архівів транскриптів `*.reset.`. Типово дорівнює `pruneAfter`; задайте `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий бюджет дискового простору для каталогу сесій. У режимі `warn` він записує попередження в журнал; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. + - `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово дорівнює `80%` від `maxDiskBytes`. +- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до потоків. - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - `idleHours`: типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає; провайдери можуть перевизначати) - - `maxAgeHours`: типове жорстке максимальне обмеження віку в годинах (`0` вимикає; провайдери можуть перевизначати) + - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати) @@ -1223,38 +1223,38 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ### Префікс відповіді -Перевизначення для каналу/акаунта: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Визначення (перемагає найспецифічніше): акаунт → канал → глобальний параметр. `""` вимикає та зупиняє каскад. `"auto"` формує `[{identity.name}]`. +Визначення значення (найконкретніше має пріоритет): обліковий запис → канал → глобальне. `""` вимикає і зупиняє каскадування. `"auto"` виводить `[{identity.name}]`. **Змінні шаблону:** -| Змінна | Опис | Приклад | -| ----------------- | ---------------------- | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| Змінна | Опис | Приклад | +| ----------------- | ------------------------ | --------------------------- | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | | `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва провайдера | `anthropic` | +| `{provider}` | Назва провайдера | `anthropic` | | `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Назва identity агента | (те саме, що й `"auto"`) | +| `{identity.name}` | Назва identity агента | (те саме, що `"auto"`) | -Змінні нечутливі до регістру. `{think}` — alias для `{thinkingLevel}`. +Змінні нечутливі до регістру. `{think}` є псевдонімом для `{thinkingLevel}`. ### Реакція підтвердження - Типово береться з `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. - Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок визначення: акаунт → канал → `messages.ackReaction` → резервне значення identity. -- Scope: `group-mentions` (типово), `group-all`, `direct`, `all`. +- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення з identity. +- Область дії: `group-mentions` (типово), `group-all`, `direct`, `all`. - `removeAckAfterReply`: видаляє підтвердження після відповіді в Slack, Discord і Telegram. - `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram. - У Slack і Discord, якщо значення не задано, реакції статусу лишаються ввімкненими, коли активні реакції підтвердження. - У Telegram, щоб увімкнути реакції статусу життєвого циклу, явно встановіть `true`. + У Slack і Discord, якщо значення не задано, реакції статусу залишаються ввімкненими, коли активні реакції підтвердження. + У Telegram задайте це явно як `true`, щоб увімкнути реакції статусу життєвого циклу. -### Debounce вхідних повідомлень +### Debounce для вхідних повідомлень -Об’єднує швидку послідовність текстових повідомлень від одного відправника в один хід агента. Медіа/вкладення скидаються негайно. Керувальні команди обходять debounce. +Об’єднує швидкі вхідні текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Команди керування оминають debounce. -### TTS (синтез мовлення) +### TTS (перетворення тексту на мовлення) ```json5 { @@ -1302,19 +1302,19 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br } ``` -- `auto` керує типовим автоматичним режимом TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує фактичний стан. +- `auto` керує типовим режимом автоматичного TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні налаштування, а `/tts status` показує ефективний стан. - `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку. -- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово має значення `false` (за явною згодою). -- API key резервно беруться з `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. -- Вбудовані мовленнєві провайдери належать Plugin. Якщо задано `plugins.allow`, додайте кожен Plugin провайдера TTS, який ви хочете використовувати, наприклад `microsoft` для Edge TTS. Застарілий id провайдера `edge` приймається як alias для `microsoft`. -- `providers.openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. -- Коли `providers.openai.baseUrl` вказує на endpoint, що не належить OpenAI, OpenClaw розглядає його як OpenAI-сумісний сервер TTS і послаблює перевірку моделі/голосу. +- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (увімкнення за згодою). +- API-ключі резервно беруться з `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. +- Вбудовані провайдери мовлення належать Plugin. Якщо задано `plugins.allow`, включіть кожен Plugin провайдера TTS, який ви хочете використовувати, наприклад `microsoft` для Edge TTS. Застарілий id провайдера `edge` приймається як псевдонім для `microsoft`. +- `providers.openai.baseUrl` перевизначає кінцеву точку OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. +- Коли `providers.openai.baseUrl` вказує на кінцеву точку, відмінну від OpenAI, OpenClaw розглядає її як OpenAI-сумісний TTS-сервер і послаблює перевірку моделі/голосу. --- ## Talk -Типові значення для режиму Talk (macOS/iOS/Android). +Типові налаштування для режиму Talk (macOS/iOS/Android). ```json5 { @@ -1338,18 +1338,18 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br } ``` -- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кількох провайдерів Talk. -- Застарілі пласкі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) підтримуються лише для сумісності та автоматично мігруються до `talk.providers.`. +- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька провайдерів Talk. +- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) використовуються лише для сумісності й автоматично мігруються в `talk.providers.`. - Ідентифікатори голосів резервно беруться з `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. -- `providers.*.apiKey` приймає рядки відкритого тексту або об’єкти SecretRef. -- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли API key Talk не налаштовано. -- `providers.*.voiceAliases` дає змогу директивам Talk використовувати дружні назви. -- `silenceTimeoutMs` визначає, скільки часу режим Talk чекає після мовчання користувача перед надсиланням транскрипту. Якщо не задано, зберігається типове для платформи вікно паузи (`700 ms на macOS і Android, 900 ms на iOS`). +- `providers.*.apiKey` приймає звичайні текстові рядки або об’єкти SecretRef. +- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли ключ API для Talk не налаштовано. +- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви. +- `silenceTimeoutMs` керує тим, скільки режим Talk чекає після тиші користувача, перш ніж надіслати транскрипт. Якщо не задано, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). --- ## Пов’язані матеріали - [Довідник з конфігурації](/uk/gateway/configuration-reference) — усі інші ключі конфігурації -- [Конфігурація](/uk/gateway/configuration) — типові завдання й швидке налаштування +- [Конфігурація](/uk/gateway/configuration) — поширені завдання та швидке налаштування - [Приклади конфігурації](/uk/gateway/configuration-examples) diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index 523801daf..6abc8c8de 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -2,97 +2,124 @@ read_when: - Ви хочете використовувати комплектний harness app-server Codex - Вам потрібні приклади конфігурації harness Codex - - Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість переходу до Pi -summary: Запустіть вбудовані цикли агента OpenClaw через комплектний harness app-server Codex + - Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість переходу до PI резервно +summary: Запускайте вбудовані ходи агента OpenClaw через комплектний harness app-server Codex title: harness Codex x-i18n: - generated_at: "2026-04-25T01:53:20Z" + generated_at: "2026-04-25T03:44:22Z" model: gpt-5.4 provider: openai - source_hash: bf0292de4a3e189bb96f02dfeaa42df6e4b1b24cf335cbb83f8821d33585cb5b + source_hash: 67f1bc703e8e45c60f7062f00cd1d68fde146785db649709e9eddce48d0a9941 source_path: plugins/codex-harness.md workflow: 15 --- -Комплектний Plugin `codex` дає змогу OpenClaw запускати вбудовані цикли агента через Codex app-server замість вбудованого harness Pi. +Комплектний Plugin `codex` дає OpenClaw змогу запускати вбудовані ходи агента через +Codex app-server замість вбудованого harness Pi. -Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням моделей, нативним відновленням потоку, нативною Compaction і виконанням app-server. OpenClaw як і раніше керує каналами чату, файлами сесій, вибором моделей, інструментами, погодженнями, доставкою медіа та видимим дзеркалом стенограми. +Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням +моделей, нативним відновленням thread, нативною Compaction та виконанням через app-server. +OpenClaw, як і раніше, керує каналами чату, файлами сесій, вибором моделі, інструментами, +погодженнями, доставкою медіа та видимим дзеркалом транскрипту. Якщо ви намагаєтеся зорієнтуватися, почніть із -[Середовища виконання агента](/uk/concepts/agent-runtimes). Коротко: +[Середовища виконання агентів](/uk/concepts/agent-runtimes). Коротко: `openai/gpt-5.5` — це посилання на модель, `codex` — це середовище виконання, а Telegram, -Discord, Slack або інший канал залишається поверхнею комунікації. +Discord, Slack або інший канал лишається поверхнею комунікації. -Нативні цикли Codex зберігають хуки Plugin OpenClaw як публічний шар сумісності. +Нативні ходи Codex зберігають хуки Plugin OpenClaw як публічний шар сумісності. Це внутрішньопроцесні хуки OpenClaw, а не командні хуки Codex `hooks.json`: - `before_prompt_build` - `before_compaction`, `after_compaction` - `llm_input`, `llm_output` -- `after_tool_call` -- `before_message_write` для дзеркальних записів стенограми +- `before_tool_call`, `after_tool_call` +- `before_message_write` для дзеркальних записів транскрипту - `agent_end` -Plugins також можуть реєструвати незалежне від середовища виконання middleware результатів інструментів, щоб переписувати динамічні результати інструментів OpenClaw після того, як OpenClaw виконає інструмент, і до того, як результат буде повернуто до Codex. Це окремо від публічного хука Plugin `tool_result_persist`, який перетворює записи результатів інструментів у стенограмі, якими керує OpenClaw. +Plugins також можуть реєструвати нейтральне до середовища виконання middleware результатів інструментів, щоб переписувати +динамічні результати інструментів OpenClaw після того, як OpenClaw виконає інструмент, і до того, +як результат буде повернено до Codex. Це окремо від публічного +хука Plugin `tool_result_persist`, який перетворює записи результатів інструментів +у транскрипті, якими володіє OpenClaw. -За замовчуванням harness вимкнений. Нові конфігурації мають зберігати посилання на моделі OpenAI у канонічному вигляді `openai/gpt-*` і явно примусово вказувати -`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли їм потрібне нативне виконання app-server. Застарілі посилання на моделі `codex/*` і далі автоматично вибирають harness для сумісності, але застарілі префікси провайдерів, підкріплені середовищем виконання, не показуються як звичайні варіанти моделі/провайдера. +Щодо семантики самих хуків Plugin дивіться [Хуки Plugin](/uk/plugins/hooks) +і [Поведінка guard Plugin](/uk/tools/plugin). + +За замовчуванням harness вимкнено. У нових конфігураціях слід залишати посилання на моделі OpenAI +канонічними як `openai/gpt-*` і явно примусово вказувати +`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли вони +хочуть нативне виконання через app-server. Застарілі посилання на моделі `codex/*` і далі автоматично вибирають +harness для сумісності, але застарілі префікси провайдерів, підкріплені середовищем виконання, не +показуються як звичайні варіанти моделі/провайдера. ## Виберіть правильний префікс моделі -Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли вам потрібна OAuth-автентифікація Codex через Pi; використовуйте `openai/*`, коли вам потрібен прямий доступ до OpenAI API або -коли ви примусово вмикаєте нативний harness Codex app-server: +Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли вам потрібна +автентифікація Codex OAuth через Pi; використовуйте `openai/*`, коли вам потрібен прямий доступ до OpenAI API або +коли ви примусово використовуєте нативний harness Codex app-server: -| Посилання на модель | Шлях середовища виконання | Використовуйте, коли | -| ---------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------- | -| `openai/gpt-5.4` | Провайдер OpenAI через інфраструктуру OpenClaw/PI | Вам потрібен поточний прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.5` | OAuth OpenAI Codex через OpenClaw/PI | Вам потрібна автентифікація підписки ChatGPT/Codex із типовим runner Pi. | -| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Harness Codex app-server | Вам потрібне нативне виконання Codex app-server для вбудованого циклу агента. | +| Model ref | Шлях середовища виконання | Використовуйте, коли | +| ----------------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------- | +| `openai/gpt-5.4` | Провайдер OpenAI через внутрішню логіку OpenClaw/Pi | Вам потрібен поточний прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.5` | OpenAI Codex OAuth через OpenClaw/Pi | Вам потрібна автентифікація за підпискою ChatGPT/Codex з типовим runner Pi. | +| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | harness Codex app-server | Вам потрібне нативне виконання через Codex app-server для вбудованого ходу агента. | GPT-5.5 наразі в OpenClaw доступний лише через підписку/OAuth. Використовуйте -`openai-codex/gpt-5.5` для OAuth через PI або `openai/gpt-5.5` з harness -Codex app-server. Прямий доступ за API-ключем для `openai/gpt-5.5` підтримуватиметься, -коли OpenAI увімкне GPT-5.5 у публічному API. +`openai-codex/gpt-5.5` для OAuth через Pi або `openai/gpt-5.5` разом із harness Codex +app-server. Прямий доступ за API key для `openai/gpt-5.5` підтримується, +щойно OpenAI увімкне GPT-5.5 у публічному API. -Застарілі посилання `codex/gpt-*` і далі приймаються як псевдоніми сумісності. Міграція сумісності doctor переписує застарілі основні посилання середовища виконання у канонічні посилання на моделі та окремо записує політику середовища виконання, тоді як застарілі посилання лише для fallback залишаються без змін, оскільки середовище виконання налаштовується для всього контейнера агента. -Нові конфігурації PI Codex OAuth мають використовувати `openai-codex/gpt-*`; нові конфігурації нативного harness app-server мають використовувати `openai/gpt-*` плюс +Застарілі посилання `codex/gpt-*` і далі приймаються як псевдоніми сумісності. Doctor +під час міграції сумісності переписує застарілі основні посилання середовища виконання на канонічні посилання моделей +і записує політику середовища виконання окремо, тоді як застарілі посилання лише для fallback +лишаються без змін, оскільки середовище виконання налаштовується для всього контейнера агента. +У нових конфігураціях Pi Codex OAuth слід використовувати `openai-codex/gpt-*`; у нових нативних +конфігураціях harness app-server слід використовувати `openai/gpt-*` разом із `embeddedHarness.runtime: "codex"`. -`agents.defaults.imageModel` дотримується такого самого поділу префіксів. Використовуйте -`openai-codex/gpt-*`, коли розуміння зображень має виконуватися через шлях провайдера OpenAI -Codex OAuth. Використовуйте `codex/gpt-*`, коли розуміння зображень має виконуватися -через обмежений цикл Codex app-server. Модель Codex app-server має -оголошувати підтримку вхідних зображень; текстові моделі Codex завершуються помилкою ще до початку медіациклу. +`agents.defaults.imageModel` дотримується того самого поділу префіксів. Використовуйте +`openai-codex/gpt-*`, коли розуміння зображень має працювати через шлях провайдера OpenAI +Codex OAuth. Використовуйте `codex/gpt-*`, коли розуміння зображень має працювати +через обмежений хід Codex app-server. Модель Codex app-server повинна +оголошувати підтримку вхідних зображень; текстові моделі Codex завершуються помилкою до того, як +почнеться хід із медіа. -Використовуйте `/status`, щоб підтвердити ефективний harness для поточної сесії. Якщо вибір неочікуваний, увімкніть журналювання налагодження для підсистеми `agents/harness` -і перевірте структурований запис шлюзу `agent harness selected`. Він -містить ідентифікатор вибраного harness, причину вибору, політику runtime/fallback та, +Використовуйте `/status`, щоб підтвердити фактичний harness для поточної сесії. Якщо +вибір видається неочікуваним, увімкніть журналювання налагодження для підсистеми `agents/harness` +і перевірте структурований запис gateway `agent harness selected`. Він +містить ідентифікатор вибраного harness, причину вибору, політику runtime/fallback і, у режимі `auto`, результат підтримки для кожного кандидата Plugin. -Вибір harness не є керуванням живою сесією. Коли виконується вбудований цикл, -OpenClaw записує ідентифікатор вибраного harness у цю сесію і продовжує використовувати його для наступних циклів у межах того самого ідентифікатора сесії. Змінюйте конфігурацію `embeddedHarness` або -`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший harness; +Вибір harness не є механізмом керування живою сесією. Коли виконується вбудований хід, +OpenClaw записує ідентифікатор вибраного harness у цій сесії й продовжує використовувати його для +наступних ходів у межах того самого ідентифікатора сесії. Змініть конфігурацію `embeddedHarness` або +`OPENCLAW_AGENT_RUNTIME`, якщо хочете, щоб майбутні сесії використовували інший harness; використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням наявної -розмови між PI і Codex. Це дає змогу уникнути повторного програвання однієї стенограми через дві несумісні нативні системи сесій. +розмови між Pi і Codex. Це запобігає повторному програванню одного транскрипту через +дві несумісні нативні системи сесій. -Застарілі сесії, створені до прив’язок harness, вважаються прив’язаними до PI, щойно вони мають історію стенограми. Використовуйте `/new` або `/reset`, щоб перевести цю розмову на +Застарілі сесії, створені до закріплення harness, вважаються прив’язаними до Pi, щойно вони +мають історію транскрипту. Використовуйте `/new` або `/reset`, щоб перевести таку розмову на Codex після зміни конфігурації. -`/status` показує ефективне середовище виконання моделі. Типовий harness PI відображається як -`Runtime: OpenClaw Pi Default`, а harness Codex app-server — як +`/status` показує фактичне середовище виконання моделі. Типовий harness Pi відображається як +`Runtime: OpenClaw Pi Default`, а harness Codex app-server відображається як `Runtime: OpenAI Codex`. ## Вимоги - OpenClaw із доступним комплектним Plugin `codex`. - Codex app-server `0.118.0` або новіший. -- Автентифікація Codex, доступна для процесу app-server. +- Доступна автентифікація Codex для процесу app-server. -Plugin блокує старіші або неверсіоновані handshake app-server. Це зберігає -OpenClaw на поверхні протоколу, з якою його було протестовано. +Plugin блокує старіші або неверсіоновані handshake app-server. Це дозволяє +OpenClaw залишатися в межах поверхні протоколу, з якою його було протестовано. -Для live- і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також з необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і -`~/.codex/config.toml`. Використовуйте ті самі автентифікаційні матеріали, що й ваш локальний Codex app-server. +Для живих і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також +з необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і +`~/.codex/config.toml`. Використовуйте той самий матеріал автентифікації, який використовує ваш локальний +Codex app-server. ## Мінімальна конфігурація @@ -133,25 +160,27 @@ OpenClaw на поверхні протоколу, з якою його було } ``` -Застарілі конфігурації, у яких `agents.defaults.model` або модель агента встановлено в -`codex/`, усе ще автоматично вмикають комплектний Plugin `codex`. У нових конфігураціях слід -надавати перевагу `openai/` плюс явному запису `embeddedHarness`, наведеному вище. +Застарілі конфігурації, які встановлюють `agents.defaults.model` або модель агента в +`codex/`, і далі автоматично вмикають комплектний Plugin `codex`. У нових конфігураціях слід +надавати перевагу `openai/` разом із явним записом `embeddedHarness`, наведеним вище. -## Додайте Codex поруч з іншими моделями +## Додайте Codex поряд з іншими моделями Не встановлюйте `runtime: "codex"` глобально, якщо той самий агент має вільно перемикатися між Codex і моделями інших провайдерів. Примусове середовище виконання застосовується до кожного -вбудованого циклу для цього агента або сесії. Якщо ви виберете модель Anthropic, поки це середовище виконання примусово встановлене, OpenClaw усе одно спробує harness Codex і завершиться помилкою без fallback замість того, щоб тихо маршрутизувати цей цикл через PI. +вбудованого ходу для цього агента або сесії. Якщо ви виберете модель Anthropic, поки це +середовище виконання примусово задано, OpenClaw однаково спробує harness Codex і завершиться помилкою +замість того, щоб непомітно спрямувати цей хід через Pi. Натомість використовуйте одну з таких форм: -- Розмістіть Codex на окремому агенті з `embeddedHarness.runtime: "codex"`. -- Залиште для типового агента `runtime: "auto"` і fallback до PI для звичайного змішаного +- Розмістіть Codex в окремому агенті з `embeddedHarness.runtime: "codex"`. +- Залиште для типового агента `runtime: "auto"` і fallback до Pi для звичайного змішаного використання провайдерів. -- Використовуйте застарілі посилання `codex/*` лише для сумісності. Нові конфігурації мають віддавати перевагу - `openai/*` плюс явній політиці runtime Codex. +- Використовуйте застарілі посилання `codex/*` лише для сумісності. У нових конфігураціях слід надавати перевагу + `openai/*` разом з явною політикою runtime Codex. -Наприклад, це залишає типовий агент на звичайному автоматичному виборі та +Наприклад, це залишає типовий агент на звичайному автоматичному виборі й додає окремого агента Codex: ```json5 @@ -189,17 +218,17 @@ OpenClaw на поверхні протоколу, з якою його було } ``` -У цій формі: +За такої форми: -- Типовий агент `main` використовує звичайний шлях провайдера та fallback сумісності PI. +- Типовий агент `main` використовує звичайний шлях провайдера та fallback сумісності Pi. - Агент `codex` використовує harness Codex app-server. -- Якщо Codex відсутній або не підтримується для агента `codex`, цикл завершується - помилкою замість тихого використання PI. +- Якщо Codex відсутній або не підтримується для агента `codex`, хід + завершується помилкою замість тихого використання Pi. ## Розгортання лише з Codex -Примусово вкажіть harness Codex, коли вам потрібно довести, що кожен вбудований цикл агента -використовує Codex. Явні середовища виконання Plugin типово не мають fallback до PI, тож +Примусово використовуйте harness Codex, коли вам потрібно довести, що кожен вбудований хід агента +використовує Codex. Явні середовища виконання Plugin типово не мають fallback до Pi, тому `fallback: "none"` необов’язковий, але часто корисний як документація: ```json5 @@ -216,19 +245,20 @@ OpenClaw на поверхні протоколу, з якою його було } ``` -Перевизначення через змінну середовища: +Перевизначення через середовище: ```bash OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -Якщо Codex примусово ввімкнено, OpenClaw завершується помилкою на ранньому етапі, якщо Plugin Codex вимкнено, app-server надто старий або app-server не може запуститися. Установлюйте -`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише якщо ви навмисно хочете, щоб PI обробляв +Коли Codex примусово задано, OpenClaw завершується помилкою на ранньому етапі, якщо Plugin Codex вимкнено, +app-server занадто старий або app-server не може запуститися. Установлюйте +`OPENCLAW_AGENT_HARNESS_FALLBACK=pi`, лише якщо ви свідомо хочете, щоб Pi обробляв відсутній вибір harness. ## Codex для окремого агента -Ви можете зробити одного агента лише для Codex, тоді як типовий агент зберігатиме звичайний +Ви можете зробити одного агента лише для Codex, поки типовий агент зберігає звичайний автовибір: ```json5 @@ -260,15 +290,15 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -Використовуйте звичайні команди сесії для перемикання агентів і моделей. `/new` створює нову -сесію OpenClaw, а harness Codex створює або відновлює свій sidecar-потік app-server -за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього потоку -і дає змогу наступному циклу знову визначити harness із поточної конфігурації. +Використовуйте звичайні команди сесії, щоб перемикати агентів і моделі. `/new` створює нову +сесію OpenClaw, а harness Codex за потреби створює або відновлює свій sidecar thread app-server. +`/reset` очищає прив’язку сесії OpenClaw для цього thread і дозволяє наступному ходу знову +визначити harness із поточної конфігурації. ## Виявлення моделей -За замовчуванням Plugin Codex запитує app-server про доступні моделі. Якщо -виявлення завершується помилкою або за тайм-аутом, він використовує комплектний резервний каталог для: +За замовчуванням Plugin Codex звертається до app-server, щоб отримати доступні моделі. Якщо +виявлення завершується помилкою або перевищує час очікування, він використовує комплектний резервний каталог для: - GPT-5.5 - GPT-5.4 mini @@ -294,7 +324,7 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалося зондування Codex і використовувався +Вимкніть виявлення, якщо хочете, щоб запуск не виконував перевірку Codex і використовував резервний каталог: ```json5 @@ -314,9 +344,9 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -## З’єднання app-server і політика +## Підключення до app-server і політика -За замовчуванням Plugin локально запускає Codex так: +За замовчуванням Plugin запускає Codex локально за допомогою: ```bash codex app-server --listen stdio:// @@ -324,11 +354,11 @@ codex app-server --listen stdio:// За замовчуванням OpenClaw запускає локальні сесії harness Codex у режимі YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` і -`sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, яка використовується -для автономних Heartbeat: Codex може використовувати shell і мережеві інструменти, не -зупиняючись на нативних запитах на погодження, на які нікому відповісти. +`sandbox: "danger-full-access"`. Це модель довіреного локального оператора, яка використовується +для автономних Heartbeat: Codex може використовувати shell та мережеві інструменти, не +зупиняючись на нативних запитах погодження, на які нікому відповідати. -Щоб увімкнути погодження, які перевіряє guardian Codex, установіть `appServer.mode: +Щоб увімкнути погодження, які переглядає guardian Codex, установіть `appServer.mode: "guardian"`: ```json5 @@ -349,11 +379,21 @@ codex app-server --listen stdio:// } ``` -Guardian — це нативний reviewer погоджень Codex. Коли Codex просить вийти із sandbox, записувати поза workspace або додати дозволи, як-от доступ до мережі, Codex спрямовує цей запит на погодження reviewer-субагенту замість показу запиту людині. Reviewer застосовує систему оцінки ризиків Codex і схвалює або відхиляє конкретний запит. Використовуйте Guardian, коли вам потрібно більше запобіжників, ніж у режимі YOLO, але водночас потрібно, щоб агенти без нагляду могли просуватися далі. +Режим Guardian використовує нативний шлях автоперевірки погоджень Codex. Коли Codex просить +вийти за межі sandbox, записати поза межами робочої області або додати дозволи, як-от мережевий +доступ, Codex спрямовує цей запит на погодження до нативного reviewer замість +людського запиту. Reviewer застосовує систему оцінки ризиків Codex і схвалює або відхиляє +конкретний запит. Використовуйте Guardian, коли вам потрібно більше запобіжників, ніж у режимі YOLO, +але все ж потрібно, щоб агенти без нагляду могли просуватися далі. -Пресет `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля політики, як і раніше, мають пріоритет над `mode`, тому розширені розгортання можуть поєднувати пресет із явними виборами. +Preset `guardian` розгортається в `approvalPolicy: "on-request"`, +`approvalsReviewer: "auto_review"` і `sandbox: "workspace-write"`. +Окремі поля політики, як і раніше, перевизначають `mode`, тому в розширених розгортаннях можна поєднувати +preset з явними налаштуваннями. Старіше значення reviewer `guardian_subagent` +і далі приймається як псевдонім сумісності, але в нових конфігураціях слід використовувати +`auto_review`. -Для app-server, який уже запущено, використовуйте транспорт WebSocket: +Для app-server, що вже працює, використовуйте транспорт WebSocket: ```json5 { @@ -377,22 +417,23 @@ Guardian — це нативний reviewer погоджень Codex. Коли C Підтримувані поля `appServer`: -| Поле | Типове значення | Значення | -| ------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | -| `command` | `"codex"` | Виконуваний файл для транспорту stdio. | -| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | -| `url` | не встановлено | URL WebSocket app-server. | -| `authToken` | не встановлено | Bearer-токен для транспорту WebSocket. | -| `headers` | `{}` | Додаткові заголовки WebSocket. | -| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control plane app-server. | -| `mode` | `"yolo"` | Пресет для виконання YOLO або виконання з перевіркою guardian. | -| `approvalPolicy` | `"never"` | Нативна політика погоджень Codex, яка надсилається під час запуску/відновлення потоку/циклу. | -| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, який надсилається під час запуску/відновлення потоку. | -| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб дати змогу Guardian Codex перевіряти запити. | -| `serviceTier` | не встановлено | Необов’язковий рівень сервісу app-server Codex: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. | +| Field | За замовчуванням | Значення | +| ------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | +| `command` | `"codex"` | Виконуваний файл для транспорту stdio. | +| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | +| `url` | не встановлено | URL WebSocket app-server. | +| `authToken` | не встановлено | Bearer token для транспорту WebSocket. | +| `headers` | `{}` | Додаткові заголовки WebSocket. | +| `requestTimeoutMs` | `60000` | Час очікування для викликів control-plane app-server. | +| `mode` | `"yolo"` | Preset для виконання YOLO або guardian-reviewed. | +| `approvalPolicy` | `"never"` | Нативна політика погоджень Codex, що надсилається під час старту/відновлення/ходу thread. | +| `sandbox` | `"danger-full-access"` | Режим нативного sandbox Codex, що надсилається під час старту/відновлення thread. | +| `approvalsReviewer` | `"user"` | Використовуйте `"auto_review"`, щоб дозволити Codex переглядати нативні запити на погодження. `guardian_subagent` лишається застарілим псевдонімом. | +| `serviceTier` | не встановлено | Необов’язковий рівень сервісу Codex app-server: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. | -Старіші змінні середовища все ще працюють як резервні варіанти для локального тестування, коли відповідне поле конфігурації не встановлене: +Старіші змінні середовища і далі працюють як fallback для локального тестування, коли +відповідне поле конфігурації не задане: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -400,11 +441,11 @@ Guardian — це нативний reviewer погоджень Codex. Коли C - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було вилучено. Натомість використовуйте +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було видалено. Натомість використовуйте `plugins.entries.codex.config.appServer.mode: "guardian"` або -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для одноразового локального тестування. Конфігурація є -бажаною для відтворюваних розгортань, оскільки вона зберігає поведінку Plugin у тому самому -перевіреному файлі, що й решта налаштування harness Codex. +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Для +відтворюваних розгортань краще використовувати конфігурацію, оскільки вона зберігає поведінку Plugin +в тому самому перевіреному файлі, що й решта налаштувань harness Codex. ## Поширені рецепти @@ -422,7 +463,7 @@ Guardian — це нативний reviewer погоджень Codex. Коли C } ``` -Перевірка harness лише для Codex: +Перевірка harness лише з Codex: ```json5 { @@ -444,7 +485,7 @@ Guardian — це нативний reviewer погоджень Codex. Коли C } ``` -Погодження Codex із перевіркою Guardian: +Погодження Codex, перевірені Guardian: ```json5 { @@ -456,7 +497,7 @@ Guardian — це нативний reviewer погоджень Codex. Коли C appServer: { mode: "guardian", approvalPolicy: "on-request", - approvalsReviewer: "guardian_subagent", + approvalsReviewer: "auto_review", sandbox: "workspace-write", }, }, @@ -466,7 +507,7 @@ Guardian — це нативний reviewer погоджень Codex. Коли C } ``` -Віддалений app-server з явними заголовками: +Віддалений app-server із явними заголовками: ```json5 { @@ -489,64 +530,66 @@ Guardian — це нативний reviewer погоджень Codex. Коли C } ``` -Перемикання моделей залишається під контролем OpenClaw. Коли сесію OpenClaw прив’язано -до наявного потоку Codex, наступний цикл знову надсилає до -app-server поточну вибрану модель OpenAI, провайдера, політику погоджень, sandbox і рівень сервісу. -Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає прив’язку до потоку, але просить Codex продовжити з нововибраною моделлю. +Перемикання моделей і далі контролюється OpenClaw. Коли сесію OpenClaw приєднано +до наявного thread Codex, наступний хід знову надсилає до +app-server поточну вибрану модель OpenAI, провайдера, політику погоджень, sandbox і +рівень сервісу. Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає +прив’язку thread, але просить Codex продовжити з новою вибраною моделлю. ## Команда Codex Комплектний Plugin реєструє `/codex` як авторизовану slash-команду. Вона є -універсальною і працює в будь-якому каналі, який підтримує текстові команди OpenClaw. +загальною і працює в будь-якому каналі, який підтримує текстові команди OpenClaw. Поширені форми: -- `/codex status` показує актуальне підключення до app-server, моделі, обліковий запис, ліміти швидкості, сервери MCP і skills. -- `/codex models` перелічує актуальні моделі app-server Codex. -- `/codex threads [filter]` перелічує нещодавні потоки Codex. -- `/codex resume ` прив’язує поточну сесію OpenClaw до наявного потоку Codex. -- `/codex compact` просить app-server Codex виконати Compaction прив’язаного потоку. -- `/codex review` запускає нативну перевірку Codex для прив’язаного потоку. +- `/codex status` показує живе підключення до app-server, моделі, обліковий запис, ліміти швидкості, сервери MCP і skills. +- `/codex models` перелічує живі моделі Codex app-server. +- `/codex threads [filter]` перелічує нещодавні threads Codex. +- `/codex resume ` приєднує поточну сесію OpenClaw до наявного thread Codex. +- `/codex compact` просить Codex app-server виконати Compaction для приєднаного thread. +- `/codex review` запускає нативну перевірку Codex для приєднаного thread. - `/codex account` показує стан облікового запису та лімітів швидкості. -- `/codex mcp` перелічує стан серверів MCP app-server Codex. -- `/codex skills` перелічує skills app-server Codex. +- `/codex mcp` показує стан серверів MCP Codex app-server. +- `/codex skills` перелічує Skills Codex app-server. `/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для -звичайних циклів. На наступному повідомленні OpenClaw відновлює цей потік Codex, передає +звичайних ходів. У наступному повідомленні OpenClaw відновлює цей thread Codex, передає поточну вибрану модель OpenClaw до app-server і зберігає увімкнену розширену історію. -Поверхня команд вимагає Codex app-server `0.118.0` або новішої версії. Окремі +Поверхня команд вимагає Codex app-server `0.118.0` або новішого. Окремі методи керування позначаються як `unsupported by this Codex app-server`, якщо -майбутній або спеціальний app-server не надає цей метод JSON-RPC. +майбутній або нетиповий app-server не надає цей метод JSON-RPC. -## Межі хуків +## Межі hook -Harness Codex має три шари хуків: +Harness Codex має три шари hook: -| Шар | Власник | Призначення | -| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| Хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness Pi і Codex. | -| Middleware розширень app-server Codex | Комплектні plugins OpenClaw | Поведінка адаптера на рівні циклу навколо динамічних інструментів OpenClaw. | -| Нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і нативна політика інструментів із конфігурації Codex. | +| Layer | Власник | Призначення | +| ------------------------------------- | ------------------------ | ------------------------------------------------------------------ | +| Хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness Pi і Codex. | +| Middleware розширення Codex app-server | Комплектні plugins OpenClaw | Поведінка адаптера для кожного ходу навколо динамічних інструментів OpenClaw. | +| Нативні hooks Codex | Codex | Низькорівневий життєвий цикл Codex і політика нативних інструментів із конфігурації Codex. | -OpenClaw не використовує проєктні або глобальні файли Codex `hooks.json` для маршрутизації -поведінки Plugin OpenClaw. Нативні хуки Codex корисні для операцій, -якими керує Codex, як-от політика shell, нативна перевірка результатів інструментів, обробка зупинки та -нативний життєвий цикл Compaction/моделі, але вони не є API Plugin OpenClaw. +OpenClaw не використовує файлові `hooks.json` Codex рівня проєкту або глобального рівня для маршрутизації +поведінки Plugin OpenClaw. Для підтримуваного мосту нативних інструментів і дозволів +OpenClaw впроваджує конфігурацію Codex для кожного thread для `PreToolUse`, `PostToolUse` і +`PermissionRequest`. Інші hooks Codex, такі як `SessionStart`, +`UserPromptSubmit` і `Stop`, залишаються елементами керування на рівні Codex; вони не відкриваються +як хуки Plugin OpenClaw у контракті v1. Для динамічних інструментів OpenClaw OpenClaw виконує інструмент після того, як Codex запитує -виклик, тому OpenClaw запускає поведінку Plugin і middleware, якою він володіє, в +виклик, тому OpenClaw запускає поведінку Plugin і middleware, якою він володіє, у адаптері harness. Для нативних інструментів Codex Codex володіє канонічним записом інструмента. -OpenClaw може дзеркалити окремі події, але не може переписувати нативний потік Codex, -якщо Codex не надає цю операцію через app-server або callback-и нативних хуків. +OpenClaw може дзеркалити вибрані події, але не може переписувати нативний thread Codex, +якщо Codex не відкриє цю операцію через app-server або callbacks нативних hook. -Коли новіші збірки app-server Codex надають події нативної Compaction і життєвого циклу моделі, -OpenClaw має керувати підтримкою цього протоколу через версії та зіставляти -події з наявним контрактом хуків OpenClaw там, де семантика є чесною. -До того часу події OpenClaw `before_compaction`, `after_compaction`, `llm_input` і -`llm_output` є спостереженнями на рівні адаптера, а не побайтовими знімками -внутрішнього запиту або payload Compaction у Codex. +Проєкції Compaction і життєвого циклу LLM надходять із +сповіщень Codex app-server і стану адаптера OpenClaw, а не з команд нативних hook Codex. +Події OpenClaw `before_compaction`, `after_compaction`, `llm_input` і +`llm_output` — це спостереження на рівні адаптера, а не побайтні копії +внутрішнього запиту Codex або payload Compaction. Нативні сповіщення app-server Codex `hook/started` і `hook/completed` проєктуються як події агента `codex_app_server.hook` для траєкторії та налагодження. @@ -554,102 +597,112 @@ OpenClaw має керувати підтримкою цього протоко ## Контракт підтримки V1 -Режим Codex — це не PI з іншим викликом моделі в основі. Codex керує більшою частиною -нативного циклу моделі, а OpenClaw адаптує свої поверхні Plugin і сесій +Режим Codex — це не Pi з іншим викликом моделі під ним. Codex бере на себе більшу частину +нативного циклу моделі, а OpenClaw адаптує свої поверхні Plugin і сесії навколо цього кордону. Підтримується в runtime Codex v1: -| Поверхня | Підтримка | Чому | -| --------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| Цикл моделі OpenAI через Codex | Підтримується | Codex app-server керує циклом OpenAI, нативним відновленням потоку та нативним продовженням інструментів. | -| Маршрутизація та доставка каналів OpenClaw | Підтримується | Telegram, Discord, Slack, WhatsApp, iMessage та інші канали залишаються поза runtime моделі. | -| Динамічні інструменти OpenClaw | Підтримується | Codex просить OpenClaw виконати ці інструменти, тому OpenClaw залишається в шляху виконання. | -| Plugins prompt і контексту | Підтримується | OpenClaw будує накладки prompt і проєктує контекст у цикл Codex перед запуском або відновленням потоку. | -| Життєвий цикл рушія контексту | Підтримується | Збирання, ingest або обслуговування після циклу та координація Compaction рушія контексту виконуються для циклів Codex. | -| Хуки динамічних інструментів | Підтримується | `before_tool_call`, `after_tool_call` і middleware результатів інструментів виконуються навколо динамічних інструментів OpenClaw. | -| Хуки життєвого циклу | Підтримуються як спостереження адаптера | `llm_input`, `llm_output`, `agent_end`, `before_compaction` і `after_compaction` спрацьовують із коректними payload у режимі Codex. | -| Блокування або спостереження shell і patch на нативному рівні | Підтримується через relay нативних хуків | `PreToolUse` і `PostToolUse` Codex ретранслюються для підтримуваних нативних інструментів Codex. Блокування підтримується; переписування аргументів — ні. | -| Нативна політика дозволів | Підтримується через relay нативних хуків | `PermissionRequest` Codex може маршрутизуватися через політику OpenClaw там, де runtime це надає. | -| Захоплення траєкторії app-server | Підтримується | OpenClaw записує запит, який він надіслав до app-server, і сповіщення app-server, які він отримує. | +| Surface | Підтримка | Чому | +| --------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| Цикл моделі OpenAI через Codex | Підтримується | Codex app-server володіє ходом OpenAI, нативним відновленням thread і нативним продовженням інструментів. | +| Маршрутизація та доставка каналів OpenClaw | Підтримується | Telegram, Discord, Slack, WhatsApp, iMessage та інші канали лишаються поза runtime моделі. | +| Динамічні інструменти OpenClaw | Підтримується | Codex просить OpenClaw виконати ці інструменти, тому OpenClaw лишається в шляху виконання. | +| Plugins prompt і контексту | Підтримується | OpenClaw будує накладки prompt і проєктує контекст у хід Codex перед запуском або відновленням thread. | +| Життєвий цикл рушія контексту | Підтримується | Збирання, ingest або обслуговування після ходу, а також координація Compaction рушія контексту виконуються для ходів Codex. | +| Хуки динамічних інструментів | Підтримується | `before_tool_call`, `after_tool_call` і middleware результатів інструментів виконуються навколо динамічних інструментів OpenClaw. | +| Хуки життєвого циклу | Підтримуються як спостереження адаптера | `llm_input`, `llm_output`, `agent_end`, `before_compaction` і `after_compaction` спрацьовують із чесними payload у режимі Codex. | +| Блокування або спостереження за нативним shell і patch | Підтримується через relay нативних hook | Codex `PreToolUse` і `PostToolUse` ретранслюються для зафіксованих поверхонь нативних інструментів. Блокування підтримується; переписування аргументів — ні. | +| Нативна політика дозволів | Підтримується через relay нативних hook | Codex `PermissionRequest` можна маршрутизувати через політику OpenClaw там, де runtime це підтримує. | +| Захоплення траєкторії app-server | Підтримується | OpenClaw записує запит, який він надіслав до app-server, і сповіщення, які він від нього отримує. | Не підтримується в runtime Codex v1: -| Поверхня | Межа V1 | Подальший шлях | -| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | -| Нативна мутація аргументів інструментів | Нативні pre-tool хуки Codex можуть блокувати, але OpenClaw не переписує аргументи нативних інструментів Codex. | Потрібна підтримка hook/schema Codex для заміни вхідних даних інструмента. | -| Редагована історія нативної стенограми Codex | Codex володіє канонічною історією нативного потоку. OpenClaw володіє дзеркалом і може проєктувати майбутній контекст, але не повинен змінювати непідтримувані внутрішні елементи. | Додати явні API app-server Codex, якщо потрібна операція над нативним потоком. | -| `tool_result_persist` для записів нативних інструментів Codex | Цей хук перетворює записи стенограми, якими володіє OpenClaw, а не записи нативних інструментів Codex. | Можна дзеркалити перетворені записи, але канонічне переписування потребує підтримки Codex. | -| Розширені нативні метадані Compaction | OpenClaw спостерігає початок і завершення Compaction, але не отримує стабільного списку збереженого/відкинутого, delta токенів або payload підсумку. | Потрібні багатші події Compaction у Codex. | -| Втручання в Compaction | Поточні хуки Compaction OpenClaw у режимі Codex працюють на рівні сповіщень. | Додати pre/post хуки Compaction Codex, якщо plugins мають забороняти або переписувати нативну Compaction. | -| Контроль зупинки або фінальної відповіді | Codex має нативні stop hooks, але OpenClaw не надає контроль фінальної відповіді як контракт Plugin v1. | Майбутній opt-in примітив із запобіжниками циклу та тайм-аутів. | -| Паритет нативних хуків MCP | Codex керує виконанням MCP, і повний паритет payload pre/post hook залежить від підтримки обробника MCP у Codex. | Додати payload хуків MCP Codex, а потім ретранслювати їх через той самий шлях нативних хуків. | -| Побайтове захоплення запиту до API моделі | OpenClaw може захоплювати запити та сповіщення app-server, але ядро Codex внутрішньо формує фінальний запит до OpenAI API. | Потрібна подія трасування запиту моделі Codex або API налагодження. | +| Surface | Межа V1 | Майбутній шлях | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | +| Мутація аргументів нативних інструментів | Нативні pre-tool hooks Codex можуть блокувати, але OpenClaw не переписує аргументи нативних інструментів Codex. | Потрібна підтримка hooks/schema Codex для заміни вхідних даних інструменту. | +| Редагована історія транскрипту Codex-native | Codex володіє канонічною історією нативного thread. OpenClaw володіє дзеркалом і може проєктувати майбутній контекст, але не повинен змінювати непідтримувані внутрішні елементи. | Додати явні API Codex app-server, якщо потрібна операція над нативним thread. | +| `tool_result_persist` для записів нативних інструментів Codex | Цей hook перетворює записи транскрипту, якими володіє OpenClaw, а не записи нативних інструментів Codex. | Можна було б дзеркалити перетворені записи, але канонічне переписування потребує підтримки Codex. | +| Розширені метадані нативної Compaction | OpenClaw спостерігає початок і завершення Compaction, але не отримує стабільного списку збережених/відкинутих елементів, дельти токенів або payload підсумку. | Потрібні багатші події Compaction у Codex. | +| Втручання в Compaction | Поточні хуки Compaction OpenClaw у режимі Codex працюють на рівні сповіщень. | Додати pre/post hooks Compaction у Codex, якщо plugins мають блокувати або переписувати нативну Compaction. | +| Gate для stop або final-answer | Codex має нативні hooks зупинки, але OpenClaw не відкриває gate для final-answer як контракт Plugin v1. | Майбутній opt-in примітив із захистом циклу та тайм-аутів. | +| Паритет нативних hooks MCP як зафіксована поверхня v1 | Relay є загальним, але OpenClaw ще не ввів version-gating і не протестував наскрізну поведінку нативних pre/post hooks MCP. | Додати тести й документацію relay MCP OpenClaw, щойно підтримуваний мінімум протоколу app-server покриє ці payload. | +| Побайтне захоплення запиту до model API | OpenClaw може захоплювати запити й сповіщення app-server, але ядро Codex внутрішньо будує фінальний запит до OpenAI API. | Потрібна подія трасування запиту моделі Codex або API налагодження. | ## Інструменти, медіа та Compaction Harness Codex змінює лише низькорівневий виконавець вбудованого агента. -OpenClaw як і раніше формує список інструментів і отримує результати динамічних інструментів від -harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів обміну повідомленнями +OpenClaw, як і раніше, будує список інструментів і отримує результати динамічних інструментів від +harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів повідомлень і далі проходять через звичайний шлях доставки OpenClaw. -Запити на погодження інструментів Codex MCP маршрутизуються через потік погодження Plugin -OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як -`"mcp_tool_call"`. Запити Codex `request_user_input` надсилаються назад до -початкового чату, а наступне повідомлення в черзі відповідає на цей нативний -запит сервера замість того, щоб спрямовуватися як додатковий контекст. Інші запити еліцитації MCP, як і раніше, завершуються помилкою без fallback. +Relay нативних hook навмисно є загальним, але контракт підтримки v1 +обмежений шляхами нативних інструментів і дозволів Codex, які перевіряє OpenClaw. Не +припускайте, що кожна майбутня подія hook Codex є поверхнею Plugin OpenClaw, доки +контракт runtime прямо цього не визначить. -Коли вибрана модель використовує harness Codex, нативна Compaction потоку делегується -Codex app-server. OpenClaw зберігає дзеркало стенограми для історії каналу, +Запити погодження інструментів MCP Codex маршрутизуються через потік +погоджень Plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як +`"mcp_tool_call"`. Запити Codex `request_user_input` надсилаються назад до +початкового чату, а наступне поставлене в чергу повідомлення-відповідь відповідає на цей нативний +запит сервера замість того, щоб спрямовуватися як додатковий контекст. Інші запити elicitation MCP +і далі завершуються помилкою без fallback. + +Коли вибрана модель використовує harness Codex, нативна Compaction thread делегується +Codex app-server. OpenClaw зберігає дзеркало транскрипту для історії каналу, пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало -включає prompt користувача, фінальний текст помічника та полегшені записи -міркувань або плану Codex, коли app-server їх надсилає. Наразі OpenClaw лише -записує сигнали початку та завершення нативної Compaction. Він ще не надає -людинозрозумілого підсумку Compaction або аудійованого списку того, які записи Codex +містить prompt користувача, фінальний текст асистента та полегшені записи міркувань або плану Codex, коли app-server їх надсилає. Наразі OpenClaw лише +записує сигнали початку та завершення нативної Compaction. Він ще не показує +людинозрозумілий підсумок Compaction або перевірний список того, які записи Codex зберіг після Compaction. -Оскільки Codex володіє канонічним нативним потоком, `tool_result_persist` наразі не +Оскільки Codex володіє канонічним нативним thread, `tool_result_persist` наразі не переписує записи результатів нативних інструментів Codex. Він застосовується лише тоді, коли -OpenClaw записує результат інструмента до стенограми сесії, якою володіє OpenClaw. +OpenClaw записує результат інструмента в транскрипт сесії, яким володіє OpenClaw. -Генерація медіа не вимагає PI. Генерація зображень, відео, музики, PDF, TTS і -розуміння медіа й далі використовують відповідні налаштування провайдера/моделі, такі як +Генерація медіа не вимагає Pi. Генерація зображень, відео, музики, PDF, TTS і +розуміння медіа і далі використовують відповідні налаштування провайдера/моделі, такі як `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і `messages.tts`. -## Усунення проблем +## Усунення несправностей -**Codex не з’являється в `/model`:** увімкніть `plugins.entries.codex.enabled`, -виберіть модель `openai/gpt-*` з `embeddedHarness.runtime: "codex"` (або -застаріле посилання `codex/*`) і перевірте, чи `plugins.allow` не виключає `codex`. +**Codex не з’являється як звичайний провайдер `/model`:** це очікувано для +нових конфігурацій. Виберіть модель `openai/gpt-*` із +`embeddedHarness.runtime: "codex"` (або застаріле посилання `codex/*`), увімкніть +`plugins.entries.codex.enabled` і перевірте, чи `plugins.allow` не виключає +`codex`. -**OpenClaw використовує PI замість Codex:** `runtime: "auto"` усе ще може використовувати PI як -бекенд сумісності, коли жоден harness Codex не бере на себе запуск. Установіть -`embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування. Примусове -середовище виконання Codex тепер завершується помилкою замість fallback до PI, якщо ви +**OpenClaw використовує Pi замість Codex:** `runtime: "auto"` і далі може використовувати Pi як +бекенд сумісності, коли жоден harness Codex не бере виконання на себе. Установіть +`embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування. Тепер +примусове середовище виконання Codex завершується помилкою замість fallback до Pi, якщо ви явно не встановили `embeddedHarness.fallback: "pi"`. Щойно буде вибрано Codex app-server, -його помилки відображаються безпосередньо без додаткової конфігурації fallback. +його помилки відображатимуться безпосередньо без додаткової конфігурації fallback. **app-server відхиляється:** оновіть Codex, щоб handshake app-server повідомляв версію `0.118.0` або новішу. -**Виявлення моделі повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` +**Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` або вимкніть виявлення. -**Транспорт WebSocket одразу завершується помилкою:** перевірте `appServer.url`, `authToken` -і те, що віддалений app-server підтримує ту саму версію протоколу app-server Codex. +**Транспорт WebSocket відразу завершується помилкою:** перевірте `appServer.url`, `authToken` +і переконайтеся, що віддалений app-server використовує ту саму версію протоколу Codex app-server. -**Модель не Codex використовує PI:** це очікувано, якщо ви не примусово встановили +**Модель не Codex використовує Pi:** це очікувано, якщо ви не примусово задали `embeddedHarness.runtime: "codex"` для цього агента або не вибрали застаріле -посилання `codex/*`. Звичайні `openai/gpt-*` та посилання інших провайдерів залишаються на своєму звичайному -шляху провайдера в режимі `auto`. Якщо ви примусово встановите `runtime: "codex"`, кожен вбудований -цикл для цього агента має бути моделлю OpenAI, яку підтримує Codex. +посилання `codex/*`. Звичайні `openai/gpt-*` та посилання інших провайдерів лишаються на своєму +звичайному шляху провайдера в режимі `auto`. Якщо ви примусово задаєте `runtime: "codex"`, кожен вбудований +хід для цього агента має бути моделлю OpenAI, яку підтримує Codex. ## Пов’язане - [Plugins Agent Harness](/uk/plugins/sdk-agent-harness) -- [Середовища виконання агента](/uk/concepts/agent-runtimes) +- [Середовища виконання агентів](/uk/concepts/agent-runtimes) - [Провайдери моделей](/uk/concepts/model-providers) -- [Довідник з конфігурації](/uk/gateway/configuration-reference) +- [Провайдер OpenAI](/uk/providers/openai) +- [Status](/uk/cli/status) +- [Хуки Plugin](/uk/plugins/hooks) +- [Довідник із конфігурації](/uk/gateway/configuration-reference) - [Тестування](/uk/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/uk/providers/openai.md b/docs/uk/providers/openai.md index 0d4bf0ac7..98a52d3c7 100644 --- a/docs/uk/providers/openai.md +++ b/docs/uk/providers/openai.md @@ -1,48 +1,52 @@ --- read_when: - Ви хочете використовувати моделі OpenAI в OpenClaw - - Ви хочете використовувати автентифікацію через підписку Codex замість API-ключів - - Вам потрібна суворіша поведінка виконання агента GPT-5 -summary: Використання OpenAI через API-ключі або підписку Codex в OpenClaw + - Ви хочете автентифікацію за підпискою Codex замість API-ключів + - Вам потрібні суворіші правила виконання агента GPT-5 +summary: Використовуйте OpenAI через API-ключі або підписку Codex в OpenClaw title: OpenAI x-i18n: - generated_at: "2026-04-25T02:41:33Z" + generated_at: "2026-04-25T03:44:15Z" model: gpt-5.4 provider: openai - source_hash: 095452c94074c628352a4c33a41c4c2a708e36124bd1aaf172927c60e167f6a7 + source_hash: 576a453f42fff8d90837ebee3894443c37f177c611c134113944fbf0d11c2455 source_path: providers/openai.md workflow: 15 --- OpenAI надає API для розробників для моделей GPT. OpenClaw підтримує три маршрути сімейства OpenAI. Префікс моделі визначає маршрут: -- **API-ключ** — прямий доступ до OpenAI Platform з тарифікацією за використанням (моделі `openai/*`) +- **API key** — прямий доступ до OpenAI Platform з оплатою за використання (моделі `openai/*`) - **Підписка Codex через PI** — вхід через ChatGPT/Codex із доступом за підпискою (моделі `openai-codex/*`) -- **Обв’язка app-server Codex** — нативне виконання через app-server Codex (моделі `openai/*` плюс `agents.defaults.embeddedHarness.runtime: "codex"`) +- **Харнес app-server Codex** — нативне виконання через app-server Codex (моделі `openai/*` плюс `agents.defaults.embeddedHarness.runtime: "codex"`) -OpenAI явно підтримує використання OAuth підписки в зовнішніх інструментах і робочих процесах, таких як OpenClaw. +OpenAI явно підтримує використання OAuth за підпискою у зовнішніх інструментах і робочих процесах, таких як OpenClaw. + +Провайдер, модель, середовище виконання та канал — це окремі рівні. Якщо ці позначення +плутаються, прочитайте [Середовища виконання агентів](/uk/concepts/agent-runtimes) перед +зміною конфігурації. ## Швидкий вибір | Ціль | Використовуйте | Примітки | | --------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------- | -| Пряма тарифікація за API-ключем | `openai/gpt-5.4` | Установіть `OPENAI_API_KEY` або запустіть онбординг OpenAI API-key. | +| Пряме виставлення рахунків за API key | `openai/gpt-5.4` | Установіть `OPENAI_API_KEY` або запустіть онбординг OpenAI API key. | | GPT-5.5 з автентифікацією через підписку ChatGPT/Codex | `openai-codex/gpt-5.5` | Типовий маршрут PI для Codex OAuth. Найкращий перший вибір для конфігурацій із підпискою. | -| GPT-5.5 з нативною поведінкою app-server Codex | `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"` | Використовує обв’язку app-server Codex, а не публічний маршрут OpenAI API. | +| GPT-5.5 з нативною поведінкою app-server Codex | `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"` | Використовує харнес app-server Codex, а не маршрут публічного API OpenAI. | | Генерація або редагування зображень | `openai/gpt-image-2` | Працює як з `OPENAI_API_KEY`, так і з OpenAI Codex OAuth. | -GPT-5.5 наразі доступна в OpenClaw через маршрути підписки/OAuth: -`openai-codex/gpt-5.5` із runner PI або `openai/gpt-5.5` з -обв’язкою app-server Codex. Прямий доступ за API-ключем до `openai/gpt-5.5` -підтримуватиметься, щойно OpenAI увімкне GPT-5.5 у публічному API; доти використовуйте -модель із підтримкою API, наприклад `openai/gpt-5.4`, для конфігурацій із `OPENAI_API_KEY`. +GPT-5.5 зараз доступна в OpenClaw через маршрути підписки/OAuth: +`openai-codex/gpt-5.5` з виконавцем PI або `openai/gpt-5.5` з +харнесом app-server Codex. Прямий доступ через API key для `openai/gpt-5.5` +підтримується, щойно OpenAI увімкне GPT-5.5 у публічному API; до того часу використовуйте +модель з увімкненим API, наприклад `openai/gpt-5.4`, для конфігурацій із `OPENAI_API_KEY`. Увімкнення Plugin OpenAI або вибір моделі `openai-codex/*` не -вмикає вбудований Plugin app-server Codex. OpenClaw вмикає цей Plugin лише -коли ви явно вибираєте нативну обв’язку Codex через +вмикає комплектний Plugin app-server Codex. OpenClaw вмикає цей Plugin лише +коли ви явно вибираєте нативний харнес Codex через `embeddedHarness.runtime: "codex"` або використовуєте застаріле посилання на модель `codex/*`. @@ -50,17 +54,17 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п | Можливість OpenAI | Поверхня OpenClaw | Статус | | ------------------------- | --------------------------------------------------------- | ------------------------------------------------------ | -| Чат / Responses | провайдер моделей `openai/` | Так | +| Chat / Responses | провайдер моделі `openai/` | Так | | Моделі підписки Codex | `openai-codex/` з OAuth `openai-codex` | Так | -| Обв’язка app-server Codex | `openai/` з `embeddedHarness.runtime: codex` | Так | -| Пошук у вебі на стороні сервера | нативний інструмент OpenAI Responses | Так, коли вебпошук увімкнений і не зафіксовано провайдера | +| Харнес app-server Codex | `openai/` з `embeddedHarness.runtime: codex` | Так | +| Пошук у вебі на стороні сервера | нативний інструмент OpenAI Responses | Так, коли вебпошук увімкнено й провайдер не закріплено | | Зображення | `image_generate` | Так | | Відео | `video_generate` | Так | | Перетворення тексту на мовлення | `messages.tts.provider: "openai"` / `tts` | Так | | Пакетне перетворення мовлення на текст | `tools.media.audio` / розуміння медіа | Так | -| Потокове перетворення мовлення на текст | Voice Call `streaming.provider: "openai"` | Так | -| Голос у realtime | Voice Call `realtime.provider: "openai"` / Control UI Talk | Так | -| Векторні подання | провайдер векторних подань пам’яті | Так | +| Потокове перетворення мовлення на текст | Voice Call `streaming.provider: "openai"` | Так | +| Голос у реальному часі | Voice Call `realtime.provider: "openai"` / Control UI Talk | Так | +| Embeddings | провайдер embedding для пам’яті | Так | ## Початок роботи @@ -68,18 +72,18 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п - **Найкраще для:** прямого API-доступу та тарифікації за використанням. + **Найкраще підходить для:** прямого доступу до API та оплати за використання. - - Створіть або скопіюйте API-ключ з [панелі OpenAI Platform](https://platform.openai.com/api-keys). + + Створіть або скопіюйте API key на [панелі керування OpenAI Platform](https://platform.openai.com/api-keys). ```bash openclaw onboard --auth-choice openai-api-key ``` - Або передайте ключ напряму: + Або передайте key безпосередньо: ```bash openclaw onboard --openai-api-key "$OPENAI_API_KEY" @@ -94,16 +98,18 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п ### Підсумок маршрутів - | Посилання на модель | Маршрут | Автентифікація | + | Model ref | Маршрут | Автентифікація | |-----------|-------|------| | `openai/gpt-5.4` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | | `openai/gpt-5.4-mini` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | - | `openai/gpt-5.5` | Майбутній прямий API-маршрут, щойно OpenAI увімкне GPT-5.5 в API | `OPENAI_API_KEY` | + | `openai/gpt-5.5` | Майбутній прямий маршрут API, щойно OpenAI увімкне GPT-5.5 в API | `OPENAI_API_KEY` | - `openai/*` — це прямий маршрут OpenAI за API-ключем, якщо ви явно не примусите - використання обв’язки app-server Codex. Сама GPT-5.5 наразі доступна лише через підписку/OAuth; - використовуйте `openai-codex/*` для Codex OAuth через типовий runner PI. + `openai/*` — це прямий маршрут API OpenAI через API key, якщо ви явно не примусите + використання харнеса app-server Codex. Сама GPT-5.5 зараз доступна лише через підписку/OAuth; + використовуйте `openai-codex/*` для Codex OAuth через типовий виконавець PI або + використовуйте `openai/gpt-5.5` з `embeddedHarness.runtime: "codex"` для нативного + виконання через app-server Codex. ### Приклад конфігурації @@ -116,13 +122,13 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п ``` - OpenClaw **не** відкриває `openai/gpt-5.3-codex-spark`. Реальні запити до OpenAI API відхиляють цю модель, і поточний каталог Codex також її не відкриває. + OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Реальні запити до OpenAI API відхиляють цю модель, і поточний каталог Codex також її не надає. - - **Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого API-ключа. Codex cloud потребує входу через ChatGPT. + + **Найкраще підходить для:** використання вашої підписки ChatGPT/Codex замість окремого API key. Для хмари Codex потрібен вхід у ChatGPT. @@ -130,19 +136,19 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п openclaw onboard --auth-choice openai-codex ``` - Або запустіть OAuth напряму: + Або запустіть OAuth безпосередньо: ```bash openclaw models auth login --provider openai-codex ``` - Для headless-конфігурацій або середовищ, ворожих до callback, додайте `--device-code`, щоб увійти через потік device-code ChatGPT замість browser callback на localhost: + Для безголових середовищ або конфігурацій, де callback незручний, додайте `--device-code`, щоб увійти через потік device-code ChatGPT замість зворотного виклику браузера на localhost: ```bash openclaw models auth login --provider openai-codex --device-code ``` - + ```bash openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5 ``` @@ -156,15 +162,15 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п ### Підсумок маршрутів - | Посилання на модель | Маршрут | Автентифікація | + | Model ref | Маршрут | Автентифікація | |-----------|-------|------| | `openai-codex/gpt-5.5` | ChatGPT/Codex OAuth через PI | вхід Codex | - | `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | обв’язка app-server Codex | автентифікація app-server Codex | + | `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | харнес app-server Codex | автентифікація app-server Codex | - Продовжуйте використовувати id провайдера `openai-codex` для команд автентифікації/профілю. Префікс моделі + Продовжуйте використовувати ідентифікатор провайдера `openai-codex` для команд автентифікації/профілю. Префікс моделі `openai-codex/*` також є явним маршрутом PI для Codex OAuth. - Він не вибирає і не вмикає автоматично вбудовану обв’язку app-server Codex. + Він не вибирає та не автовмикає комплектний харнес app-server Codex. ### Приклад конфігурації @@ -176,28 +182,28 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п ``` - Онбординг більше не імпортує OAuth-матеріали з `~/.codex`. Увійдіть через browser OAuth (типово) або через наведений вище потік device-code — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агента. + Онбординг більше не імпортує матеріали OAuth з `~/.codex`. Увійдіть через OAuth у браузері (типово) або через потік device-code вище — OpenClaw зберігає отримані облікові дані у власному сховищі автентифікації агентів. ### Індикатор стану - Чат-команда `/status` показує, який runtime моделі активний для поточної сесії. - Типова обв’язка PI відображається як `Runtime: OpenClaw Pi Default`. Коли - вибрано вбудовану обв’язку app-server Codex, `/status` показує - `Runtime: OpenAI Codex`. Наявні сесії зберігають свій записаний id обв’язки, тому використайте + Chat `/status` показує, яке середовище виконання моделі активне для поточної сесії. + Типовий харнес PI відображається як `Runtime: OpenClaw Pi Default`. Коли + вибрано комплектний харнес app-server Codex, `/status` показує + `Runtime: OpenAI Codex`. Наявні сесії зберігають записаний ідентифікатор харнеса, тож використайте `/new` або `/reset` після зміни `embeddedHarness`, якщо хочете, щоб `/status` відображав новий вибір PI/Codex. - ### Обмеження контекстного вікна + ### Обмеження вікна контексту - OpenClaw розглядає метадані моделі та обмеження контексту runtime як окремі значення. + OpenClaw розглядає метадані моделі та обмеження контексту середовища виконання як окремі значення. Для `openai-codex/gpt-5.5` через Codex OAuth: - Нативне `contextWindow`: `1000000` - - Типове обмеження runtime `contextTokens`: `272000` + - Типове обмеження `contextTokens` середовища виконання: `272000` - Менше типове обмеження на практиці дає кращу затримку та якість. Перевизначте його через `contextTokens`: + Менше типове обмеження на практиці дає кращі характеристики затримки та якості. Перевизначте його за допомогою `contextTokens`: ```json5 { @@ -212,35 +218,35 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п ``` - Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту runtime. + Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту середовища виконання. ### Відновлення каталогу - OpenClaw використовує upstream-метадані каталогу Codex для `gpt-5.5`, коли вони - присутні. Якщо живе виявлення Codex пропускає рядок `openai-codex/gpt-5.5`, поки - акаунт автентифікований, OpenClaw синтезує цей рядок OAuth-моделі, щоб - запуски Cron, субагентів і конфігурованих типових моделей не завершувалися з - `Unknown model`. + OpenClaw використовує метадані каталогу Codex з апстриму для `gpt-5.5`, коли вони + доступні. Якщо живе виявлення Codex пропускає рядок `openai-codex/gpt-5.5`, поки + обліковий запис автентифікований, OpenClaw синтезує цей рядок моделі OAuth, щоб + Cron, підлеглий агент і запуски з налаштованою моделлю за замовчуванням не завершувалися + помилкою `Unknown model`. ## Генерація зображень -Вбудований Plugin `openai` реєструє генерацію зображень через інструмент `image_generate`. -Він підтримує як генерацію зображень OpenAI за API-ключем, так і генерацію зображень -через Codex OAuth через те саме посилання на модель `openai/gpt-image-2`. +Комплектний Plugin `openai` реєструє генерацію зображень через інструмент `image_generate`. +Він підтримує як генерацію зображень OpenAI через API key, так і генерацію з +автентифікацією Codex OAuth через те саме посилання на модель `openai/gpt-image-2`. -| Можливість | API-ключ OpenAI | Codex OAuth | -| ------------------------- | ---------------------------------- | ------------------------------------ | -| Посилання на модель | `openai/gpt-image-2` | `openai/gpt-image-2` | -| Автентифікація | `OPENAI_API_KEY` | вхід через OpenAI Codex OAuth | -| Транспорт | OpenAI Images API | бекенд Codex Responses | -| Макс. зображень на запит | 4 | 4 | +| Можливість | OpenAI API key | Codex OAuth | +| ------------------------- | ----------------------------------- | ------------------------------------ | +| Model ref | `openai/gpt-image-2` | `openai/gpt-image-2` | +| Автентифікація | `OPENAI_API_KEY` | вхід через OpenAI Codex OAuth | +| Транспорт | OpenAI Images API | бекенд Codex Responses | +| Максимум зображень на запит | 4 | 4 | | Режим редагування | Увімкнено (до 5 еталонних зображень) | Увімкнено (до 5 еталонних зображень) | | Перевизначення розміру | Підтримується, включно з розмірами 2K/4K | Підтримується, включно з розмірами 2K/4K | -| Співвідношення сторін / роздільна здатність | Не передається в OpenAI Images API | За можливості зіставляється з підтримуваним розміром | +| Співвідношення сторін / роздільна здатність | Не передається в OpenAI Images API | Відображається на підтримуваний розмір, коли це безпечно | ```json5 { @@ -253,46 +259,47 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п ``` -Див. [Image Generation](/uk/tools/image-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover. +Див. [Генерація зображень](/uk/tools/image-generation), щоб дізнатися про спільні параметри інструмента, вибір провайдера та поведінку резервного перемикання. -`gpt-image-2` — це типове значення і для генерації OpenAI text-to-image, і для -редагування зображень. `gpt-image-1` залишається доступною як явне перевизначення моделі, але нові +`gpt-image-2` — це типове значення і для генерації зображень з тексту OpenAI, і для +редагування зображень. `gpt-image-1` залишається придатною як явне перевизначення моделі, але нові робочі процеси OpenAI для зображень мають використовувати `openai/gpt-image-2`. -Для інсталяцій із Codex OAuth зберігайте те саме посилання `openai/gpt-image-2`. Коли -налаштовано OAuth-профіль `openai-codex`, OpenClaw обчислює цей збережений OAuth-токен -доступу і надсилає запити на зображення через бекенд Codex Responses. Він -не спочатку пробує `OPENAI_API_KEY` і не виконує тихий відкат до API-ключа для цього -запиту. Явно налаштуйте `models.providers.openai` з API-ключем, -власним base URL або кінцевою точкою Azure, якщо хочете використовувати прямий маршрут OpenAI Images API. +Для інсталяцій із Codex OAuth використовуйте те саме посилання `openai/gpt-image-2`. Коли +налаштовано OAuth-профіль `openai-codex`, OpenClaw знаходить цей збережений OAuth +токен доступу й надсилає запити на зображення через бекенд Codex Responses. Він +не намагається спочатку використати `OPENAI_API_KEY` і не виконує тихого резервного переходу на API key для цього +запиту. Явно налаштуйте `models.providers.openai` з API key, +власним базовим URL або кінцевою точкою Azure, якщо ви хочете використовувати прямий маршрут OpenAI Images API +замість цього. Якщо ця власна кінцева точка зображень розташована в довіреній LAN/приватній адресі, також установіть -`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw і надалі -блокує приватні/внутрішні OpenAI-сумісні кінцеві точки зображень, якщо цей opt-in +`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw залишає +приватні/внутрішні OpenAI-сумісні кінцеві точки зображень заблокованими, якщо цей явний дозвіл не задано. -Генерувати: +Генерація: ``` -/tool image_generate model=openai/gpt-image-2 prompt="Відполірований постер запуску OpenClaw на macOS" size=3840x2160 count=1 +/tool image_generate model=openai/gpt-image-2 prompt="Відшліфований постер запуску для OpenClaw на macOS" size=3840x2160 count=1 ``` -Редагувати: +Редагування: ``` -/tool image_generate model=openai/gpt-image-2 prompt="Зберегти форму об’єкта, змінити матеріал на напівпрозоре скло" image=/path/to/reference.png size=1024x1536 +/tool image_generate model=openai/gpt-image-2 prompt="Збережіть форму об’єкта, змініть матеріал на прозоре скло" image=/path/to/reference.png size=1024x1536 ``` ## Генерація відео -Вбудований Plugin `openai` реєструє генерацію відео через інструмент `video_generate`. +Комплектний Plugin `openai` реєструє генерацію відео через інструмент `video_generate`. | Можливість | Значення | | ---------------- | --------------------------------------------------------------------------------- | -| Типова модель | `openai/sora-2` | -| Режими | Text-to-video, image-to-video, редагування одного відео | -| Вхідні еталони | 1 зображення або 1 відео | -| Перевизначення розміру | Підтримується | +| Модель за замовчуванням | `openai/sora-2` | +| Режими | Текст у відео, зображення у відео, редагування одного відео | +| Еталонні вхідні дані | 1 зображення або 1 відео | +| Перевизначення розміру | Підтримується | | Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з попередженням інструмента | ```json5 @@ -306,25 +313,25 @@ GPT-5.5 наразі доступна в OpenClaw через маршрути п ``` -Див. [Video Generation](/uk/tools/video-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover. +Див. [Генерація відео](/uk/tools/video-generation), щоб дізнатися про спільні параметри інструмента, вибір провайдера та поведінку резервного перемикання. -## Внесок у промпт GPT-5 +## Внесок у prompt для GPT-5 -OpenClaw додає спільний внесок у промпт GPT-5 для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за id моделі, тому `openai-codex/gpt-5.5`, `openai/gpt-5.4`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують той самий оверлей. Старіші моделі GPT-4.x — ні. +OpenClaw додає спільний внесок у prompt для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за ідентифікатором моделі, тому `openai-codex/gpt-5.5`, `openai/gpt-5.4`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують той самий накладений шар. Старіші моделі GPT-4.x його не отримують. -Вбудована нативна обв’язка Codex використовує таку саму поведінку GPT-5 і оверлей Heartbeat через інструкції для розробника app-server Codex, тому сесії `openai/gpt-5.x`, примусово спрямовані через `embeddedHarness.runtime: "codex"`, зберігають таке саме доведення до кінця та проактивні вказівки Heartbeat, хоча рештою промпта обв’язки керує Codex. +Комплектний нативний харнес Codex використовує ту саму поведінку GPT-5 і накладений шар Heartbeat через інструкції розробника app-server Codex, тому сесії `openai/gpt-5.x`, примусово спрямовані через `embeddedHarness.runtime: "codex"`, зберігають ті самі настанови щодо доведення справи до кінця та проактивного Heartbeat, навіть якщо рештою prompt харнеса керує Codex. -Внесок GPT-5 додає тегований контракт поведінки для збереження персони, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Специфічна для каналу поведінка відповіді та тихих повідомлень залишається у спільному системному промпті OpenClaw і політиці вихідної доставки. Вказівки GPT-5 завжди ввімкнені для відповідних моделей. Дружній шар стилю взаємодії є окремим і налаштовуваним. +Внесок GPT-5 додає тегований контракт поведінки для збереження персони, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Поведінка відповідей, специфічна для каналу, і поведінка тихих повідомлень залишаються у спільному системному prompt OpenClaw та політиці вихідної доставки. Настанови GPT-5 завжди ввімкнені для відповідних моделей. Рівень дружнього стилю взаємодії є окремим і налаштовуваним. -| Значення | Ефект | -| ---------------------- | ------------------------------------------ | -| `"friendly"` (типово) | Увімкнути дружній шар стилю взаємодії | -| `"on"` | Псевдонім для `"friendly"` | -| `"off"` | Вимкнути лише дружній шар стилю | +| Значення | Ефект | +| --------------------- | ------------------------------------------ | +| `"friendly"` (типово) | Увімкнути рівень дружнього стилю взаємодії | +| `"on"` | Псевдонім для `"friendly"` | +| `"off"` | Вимкнути лише рівень дружнього стилю | - + ```json5 { agents: { @@ -345,28 +352,28 @@ OpenClaw додає спільний внесок у промпт GPT-5 для -Значення не залежать від регістру під час виконання, тому і `"Off"`, і `"off"` вимикають дружній шар стилю. +Під час виконання значення нечутливі до регістру, тож і `"Off"`, і `"off"` вимикають рівень дружнього стилю. -Застарілий `plugins.entries.openai.config.personality` усе ще зчитується як сумісний fallback, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано. +Застаріле `plugins.entries.openai.config.personality` усе ще читається як сумісний резервний варіант, якщо спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано. ## Голос і мовлення - Вбудований Plugin `openai` реєструє синтез мовлення для поверхні `messages.tts`. + Комплектний Plugin `openai` реєструє синтез мовлення для поверхні `messages.tts`. - | Параметр | Шлях конфігурації | Типове значення | + | Параметр | Шлях конфігурації | Типово | |---------|------------|---------| | Модель | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | | Голос | `messages.tts.providers.openai.voice` | `coral` | | Швидкість | `messages.tts.providers.openai.speed` | (не задано) | | Інструкції | `messages.tts.providers.openai.instructions` | (не задано, лише `gpt-4o-mini-tts`) | | Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових нотаток, `mp3` для файлів | - | API-ключ | `messages.tts.providers.openai.apiKey` | Використовує `OPENAI_API_KEY` як fallback | - | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | + | API key | `messages.tts.providers.openai.apiKey` | Резервно використовує `OPENAI_API_KEY` | + | Базовий URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | Доступні моделі: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Доступні голоси: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`. @@ -383,20 +390,20 @@ OpenClaw додає спільний внесок у промпт GPT-5 для ``` - Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити base URL для TTS, не впливаючи на кінцеву точку chat API. + Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базовий URL для TTS, не впливаючи на кінцеву точку chat API. - Вбудований Plugin `openai` реєструє пакетне перетворення мовлення на текст через - поверхню транскрибування для розуміння медіа в OpenClaw. + Комплектний Plugin `openai` реєструє пакетне перетворення мовлення на текст через + поверхню транскрибування з розумінням медіа в OpenClaw. - - Типова модель: `gpt-4o-transcribe` - - Кінцева точка: OpenAI REST `/v1/audio/transcriptions` - - Вхідний шлях: multipart-завантаження аудіофайлу - - Підтримується в OpenClaw скрізь, де транскрибування вхідного аудіо використовує - `tools.media.audio`, включно з сегментами голосових каналів Discord і + - Модель за замовчуванням: `gpt-4o-transcribe` + - Кінцева точка: REST OpenAI `/v1/audio/transcriptions` + - Шлях вхідних даних: multipart-вивантаження аудіофайлу + - Підтримується в OpenClaw всюди, де вхідне транскрибування аудіо використовує + `tools.media.audio`, включно з сегментами голосового каналу Discord і аудіовкладеннями каналів Щоб примусово використовувати OpenAI для транскрибування вхідного аудіо: @@ -419,43 +426,43 @@ OpenClaw додає спільний внесок у промпт GPT-5 для } ``` - Підказки щодо мови та промпта передаються до OpenAI, якщо їх надає - спільна конфігурація аудіомедіа або запит транскрибування для конкретного виклику. + Підказки мови та prompt передаються до OpenAI, якщо вони задані + спільною конфігурацією аудіомедіа або запитом на транскрибування для окремого виклику. - - Вбудований Plugin `openai` реєструє транскрибування в realtime для Plugin Voice Call. + + Комплектний Plugin `openai` реєструє транскрибування в реальному часі для Plugin Voice Call. - | Параметр | Шлях конфігурації | Типове значення | + | Параметр | Шлях конфігурації | Типово | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` | | Мова | `...openai.language` | (не задано) | - | Промпт | `...openai.prompt` | (не задано) | + | Prompt | `...openai.prompt` | (не задано) | | Тривалість тиші | `...openai.silenceDurationMs` | `800` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | - | API-ключ | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як fallback | + | API key | `...openai.apiKey` | Резервно використовує `OPENAI_API_KEY` | - Використовує з’єднання WebSocket з `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей потоковий провайдер призначений для шляху транскрибування в realtime у Voice Call; голос Discord наразі натомість записує короткі сегменти і використовує пакетний шлях транскрибування `tools.media.audio`. + Використовує з’єднання WebSocket з `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей потоковий провайдер призначений для шляху транскрибування в реальному часі у Voice Call; голос у Discord зараз записує короткі сегменти й замість цього використовує пакетний шлях транскрибування `tools.media.audio`. - - Вбудований Plugin `openai` реєструє голос у realtime для Plugin Voice Call. + + Комплектний Plugin `openai` реєструє голос у реальному часі для Plugin Voice Call. - | Параметр | Шлях конфігурації | Типове значення | + | Параметр | Шлях конфігурації | Типово | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` | | Голос | `...openai.voice` | `alloy` | | Temperature | `...openai.temperature` | `0.8` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | | Тривалість тиші | `...openai.silenceDurationMs` | `500` | - | API-ключ | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як fallback | + | API key | `...openai.apiKey` | Резервно використовує `OPENAI_API_KEY` | - Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двонапрямлений виклик інструментів. Використовує аудіоформат G.711 u-law. + Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двобічний виклик інструментів. Використовує аудіоформат G.711 u-law. @@ -463,29 +470,29 @@ OpenClaw додає спільний внесок у промпт GPT-5 для ## Кінцеві точки Azure OpenAI -Вбудований провайдер `openai` може спрямовувати генерацію зображень на ресурс Azure OpenAI -шляхом перевизначення base URL. На шляху генерації зображень OpenClaw -розпізнає хости Azure у `models.providers.openai.baseUrl` і автоматично перемикається на -форму запиту Azure. +Комплектний провайдер `openai` може націлюватися на ресурс Azure OpenAI для генерації +зображень шляхом перевизначення базового URL. На шляху генерації зображень OpenClaw +визначає імена хостів Azure в `models.providers.openai.baseUrl` і автоматично перемикається на +формат запитів Azure. -Голос у realtime використовує окремий шлях конфігурації +Голос у реальному часі використовує окремий шлях конфігурації (`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`) -і не залежить від `models.providers.openai.baseUrl`. Див. акордеон **Голос у realtime** -в розділі [Голос і мовлення](#voice-and-speech) для його параметрів Azure. +і не залежить від `models.providers.openai.baseUrl`. Див. акордеон **Голос у реальному +часі** в розділі [Голос і мовлення](#voice-and-speech), щоб дізнатися про його параметри Azure. Використовуйте Azure OpenAI, коли: -- У вас уже є підписка, квота або корпоративна угода Azure OpenAI -- Вам потрібна регіональна резидентність даних або механізми відповідності, які надає Azure -- Ви хочете зберегти трафік у межах наявного tenancy Azure +- У вас уже є підписка Azure OpenAI, квота або корпоративна угода +- Вам потрібні регіональне зберігання даних або механізми відповідності, які надає Azure +- Ви хочете зберегти трафік у межах наявного тенанту Azure ### Конфігурація -Для генерації зображень через Azure за допомогою вбудованого провайдера `openai` укажіть -`models.providers.openai.baseUrl` на ваш ресурс Azure і задайте `apiKey` як -ключ Azure OpenAI (а не ключ OpenAI Platform): +Для генерації зображень через Azure за допомогою комплектного провайдера `openai` вкажіть +`models.providers.openai.baseUrl` на свій ресурс Azure і встановіть `apiKey` у значення +ключа Azure OpenAI (а не ключа OpenAI Platform): ```json5 { @@ -509,16 +516,17 @@ OpenClaw розпізнає такі суфікси хостів Azure для м Для запитів генерації зображень на розпізнаному хості Azure OpenClaw: - Надсилає заголовок `api-key` замість `Authorization: Bearer` -- Використовує шляхи в межах deployment (`/openai/deployments/{deployment}/...`) +- Використовує шляхи в межах розгортання (`/openai/deployments/{deployment}/...`) - Додає `?api-version=...` до кожного запиту -Для інших base URL (публічний OpenAI, OpenAI-сумісні проксі) зберігається стандартна -форма запиту OpenAI для зображень. +Інші базові URL (публічний OpenAI, OpenAI-сумісні проксі) зберігають стандартний +формат запитів зображень OpenAI. -Маршрутизація Azure для шляху генерації зображень у провайдера `openai` потребує +Маршрутизація Azure для шляху генерації зображень провайдера `openai` потребує OpenClaw 2026.4.22 або новішої версії. Раніші версії трактують будь-який власний -`openai.baseUrl` як публічну кінцеву точку OpenAI і завершаться помилкою при роботі з deployment зображень Azure. +`openai.baseUrl` як публічну кінцеву точку OpenAI і завершаться помилкою при роботі з розгортаннями +зображень Azure. ### Версія API @@ -530,68 +538,68 @@ OpenClaw 2026.4.22 або новішої версії. Раніші версії export AZURE_OPENAI_API_VERSION="2024-12-01-preview" ``` -Типовим значенням є `2024-12-01-preview`, коли змінну не задано. +Типове значення — `2024-12-01-preview`, якщо змінна не задана. -### Імена моделей — це імена deployment +### Назви моделей — це назви розгортань -Azure OpenAI прив’язує моделі до deployment. Для запитів генерації зображень Azure, -спрямованих через вбудований провайдер `openai`, поле `model` в OpenClaw -має бути **іменем deployment Azure**, яке ви налаштували в порталі Azure, а не -публічним id моделі OpenAI. +Azure OpenAI прив’язує моделі до розгортань. Для запитів генерації зображень Azure, +маршрутизованих через комплектний провайдер `openai`, поле `model` в OpenClaw +має бути **назвою розгортання Azure**, яку ви налаштували в порталі Azure, а не +ідентифікатором публічної моделі OpenAI. -Якщо ви створили deployment з назвою `gpt-image-2-prod`, який обслуговує `gpt-image-2`: +Якщо ви створите розгортання з назвою `gpt-image-2-prod`, яке обслуговує `gpt-image-2`: ``` /tool image_generate model=openai/gpt-image-2-prod prompt="Чистий постер" size=1024x1024 count=1 ``` -Те саме правило імен deployment застосовується до викликів генерації зображень, -спрямованих через вбудований провайдер `openai`. +Те саме правило назв розгортань застосовується до викликів генерації зображень, +маршрутизованих через комплектний провайдер `openai`. ### Регіональна доступність -Генерація зображень Azure зараз доступна лише в підмножині регіонів +Генерація зображень Azure зараз доступна лише в частині регіонів (наприклад, `eastus2`, `swedencentral`, `polandcentral`, `westus3`, -`uaenorth`). Перевіряйте актуальний список регіонів Microsoft перед створенням -deployment і підтверджуйте, що конкретна модель доступна у вашому регіоні. +`uaenorth`). Перевірте актуальний список регіонів Microsoft перед створенням +розгортання й підтвердьте, що конкретна модель доступна у вашому регіоні. ### Відмінності параметрів -Azure OpenAI та публічний OpenAI не завжди приймають однакові параметри зображень. -Azure може відхиляти параметри, які публічний OpenAI дозволяє (наприклад, певні -значення `background` у `gpt-image-2`), або відкривати їх лише в конкретних версіях +Azure OpenAI і публічний OpenAI не завжди приймають однакові параметри зображень. +Azure може відхиляти параметри, які дозволяє публічний OpenAI (наприклад, певні +значення `background` для `gpt-image-2`) або надавати їх лише для певних версій моделі. Ці відмінності походять від Azure та базової моделі, а не від OpenClaw. Якщо запит Azure завершується помилкою валідації, перевірте -набір параметрів, підтримуваний вашим конкретним deployment і версією API в +набір параметрів, який підтримує ваше конкретне розгортання та версія API, у порталі Azure. -Azure OpenAI використовує нативний транспорт і поведінку compat, але не отримує -приховані заголовки атрибуції OpenClaw — див. акордеон **Нативні vs OpenAI-сумісні -маршрути** у розділі [Розширена конфігурація](#advanced-configuration). +Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує +прихованих заголовків атрибуції OpenClaw — див. акордеон **Нативні та OpenAI-сумісні +маршрути** в розділі [Розширена конфігурація](#advanced-configuration). -Для трафіку chat або Responses на Azure (крім генерації зображень) використовуйте -потік онбордингу або окрему конфігурацію провайдера Azure — самого лише -`openai.baseUrl` недостатньо, щоб підхопити форму API/автентифікації Azure. Існує окремий -провайдер `azure-openai-responses/*`; див. -акордеон Server-side Compaction нижче. +Для трафіку chat або Responses в Azure (поза межами генерації зображень) використовуйте +потік онбордингу або окрему конфігурацію провайдера Azure — одного лише +`openai.baseUrl` недостатньо, щоб застосувати форму Azure API/автентифікації. Існує +окремий провайдер `azure-openai-responses/*`; див. +акордеон Server-side compaction нижче. ## Розширена конфігурація - - OpenClaw використовує WebSocket-first із fallback на SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`. + + OpenClaw використовує WebSocket у першу чергу з резервним переходом на SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`. У режимі `"auto"` OpenClaw: - Повторює одну ранню помилку WebSocket перед переходом на SSE - - Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час охолодження - - Прикріплює стабільні заголовки ідентичності сесії та ходу для повторних спроб і повторних підключень + - Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE протягом періоду охолодження + - Прикріплює стабільні заголовки ідентичності сесії та ходу для повторів і повторних підключень - Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами транспорту | Значення | Поведінка | |-------|----------| - | `"auto"` (типово) | Спочатку WebSocket, fallback на SSE | + | `"auto"` (типово) | Спочатку WebSocket, резервно SSE | | `"sse"` | Примусово лише SSE | | `"websocket"` | Примусово лише WebSocket | @@ -612,7 +620,7 @@ Azure OpenAI використовує нативний транспорт і п } ``` - Пов’язана документація OpenAI: + Пов’язані документи OpenAI: - [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket) - [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses) @@ -639,12 +647,12 @@ Azure OpenAI використовує нативний транспорт і п - OpenClaw відкриває спільний перемикач швидкого режиму для `openai/*` і `openai-codex/*`: + OpenClaw надає спільний перемикач швидкого режиму для `openai/*` і `openai-codex/*`: - **Chat/UI:** `/fast status|on|off` - **Конфігурація:** `agents.defaults.models["/"].params.fastMode` - Коли увімкнено, OpenClaw зіставляє швидкий режим із пріоритетною обробкою OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, а швидкий режим не переписує `reasoning` або `text.verbosity`. + Коли цей режим увімкнено, OpenClaw зіставляє швидкий режим із пріоритетною обробкою OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, а швидкий режим не переписує `reasoning` або `text.verbosity`. ```json5 { @@ -665,7 +673,7 @@ Azure OpenAI використовує нативний транспорт і п - API OpenAI відкриває пріоритетну обробку через `service_tier`. Задайте її для кожної моделі в OpenClaw: + API OpenAI надає пріоритетну обробку через `service_tier`. Установіть її для кожної моделі в OpenClaw: ```json5 { @@ -682,23 +690,23 @@ Azure OpenAI використовує нативний транспорт і п Підтримувані значення: `auto`, `default`, `flex`, `priority`. - `serviceTier` передається лише до нативних кінцевих точок OpenAI (`api.openai.com`) і нативних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви спрямовуєте будь-якого з цих провайдерів через проксі, OpenClaw залишає `service_tier` без змін. + `serviceTier` передається лише до нативних кінцевих точок OpenAI (`api.openai.com`) і нативних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого провайдера через проксі, OpenClaw залишає `service_tier` без змін. - Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) обгортка потоку Pi-harness у Plugin OpenAI автоматично вмикає server-side Compaction: + Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) обгортка потоку Pi-harness у Plugin OpenAI автоматично вмикає Server-side Compaction: - - Примусово встановлює `store: true` (якщо compat моделі не задає `supportsStore: false`) - - Впроваджує `context_management: [{ type: "compaction", compact_threshold: ... }]` - - Типовий `compact_threshold`: 70% від `contextWindow` (або `80000`, якщо значення недоступне) + - Примусово встановлює `store: true` (якщо лише сумісність моделі не задає `supportsStore: false`) + - Вставляє `context_management: [{ type: "compaction", compact_threshold: ... }]` + - Типовий `compact_threshold`: 70% від `contextWindow` (або `80000`, якщо він недоступний) - Це застосовується до вбудованого шляху Pi harness і до хуків провайдера OpenAI, які використовуються в embedded-запусках. Нативна обв’язка app-server Codex керує власним контекстом через Codex і налаштовується окремо через `agents.defaults.embeddedHarness.runtime`. + Це застосовується до вбудованого шляху Pi harness і до хуків провайдера OpenAI, які використовуються в embedded-запусках. Нативний харнес app-server Codex керує власним контекстом через Codex і налаштовується окремо через `agents.defaults.embeddedHarness.runtime`. - - Корисно для сумісних кінцевих точок, як-от Azure OpenAI Responses: + + Корисно для сумісних кінцевих точок, таких як Azure OpenAI Responses: ```json5 { @@ -750,7 +758,7 @@ Azure OpenAI використовує нативний транспорт і п - `responsesServerCompaction` керує лише впровадженням `context_management`. Прямі моделі OpenAI Responses все одно примусово встановлюють `store: true`, якщо compat не задає `supportsStore: false`. + `responsesServerCompaction` керує лише вставленням `context_management`. Прямі моделі OpenAI Responses все одно примусово встановлюють `store: true`, якщо сумісність не задає `supportsStore: false`. @@ -768,35 +776,35 @@ Azure OpenAI використовує нативний транспорт і п } ``` - Із `strict-agentic` OpenClaw: + З `strict-agentic` OpenClaw: - Більше не вважає хід лише з планом успішним прогресом, коли доступна дія інструмента - - Повторює хід із вказівкою діяти зараз + - Повторює хід із настановою діяти негайно - Автоматично вмикає `update_plan` для суттєвої роботи - Показує явний заблокований стан, якщо модель продовжує планувати без дії - Обмежується лише OpenAI та Codex-запусками сімейства GPT-5. Інші провайдери та старіші сімейства моделей зберігають типову поведінку. + Обмежено лише запусками сімейства GPT-5 OpenAI та Codex. Інші провайдери та старіші сімейства моделей зберігають типову поведінку. - - OpenClaw по-різному обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI порівняно з загальними OpenAI-сумісними проксі `/v1`: + + OpenClaw по-різному обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI та загальні OpenAI-сумісні проксі `/v1`: **Нативні маршрути** (`openai/*`, Azure OpenAI): - - Зберігають `reasoning: { effort: "none" }` лише для моделей, що підтримують OpenAI `none` effort - - Пропускають вимкнений reasoning для моделей або проксі, які відхиляють `reasoning.effort: "none"` - - Типово встановлюють строгий режим для схем інструментів + - Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують OpenAI-значення effort `none` + - Пропускають вимкнений reasoning для моделей або проксі, що відхиляють `reasoning.effort: "none"` + - Типово використовують strict mode для схем інструментів - Прикріплюють приховані заголовки атрибуції лише на перевірених нативних хостах - - Зберігають формування запитів, специфічне для OpenAI (`service_tier`, `store`, compat reasoning, підказки кешу промптів) + - Зберігають формування запитів, притаманне лише OpenAI (`service_tier`, `store`, reasoning-compat, підказки кешу prompt) **Проксі/сумісні маршрути:** - - Використовують м’якшу compat-поведінку - - Вилучають Completions `store` із ненативних payload `openai-completions` - - Приймають наскрізний JSON `params.extra_body`/`params.extraBody` для розширених OpenAI-сумісних проксі Completions - - Не примушують строгі схеми інструментів або заголовки лише для нативних маршрутів + - Використовують м’якшу поведінку сумісності + - Видаляють Completions `store` з ненативних корисних навантажень `openai-completions` + - Приймають JSON-проброс `params.extra_body`/`params.extraBody` для розширених OpenAI-сумісних проксі Completions + - Не примушують strict-схеми інструментів або заголовки, притаманні лише нативним маршрутам - Azure OpenAI використовує нативний транспорт і compat-поведінку, але не отримує приховані заголовки атрибуції. + Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує прихованих заголовків атрибуції. @@ -805,15 +813,15 @@ Azure OpenAI використовує нативний транспорт і п - Вибір провайдерів, посилань на моделі та поведінки failover. + Вибір провайдерів, посилань на моделі та поведінки резервного перемикання. Спільні параметри інструмента зображень і вибір провайдера. - Спільні параметри інструмента відео і вибір провайдера. + Спільні параметри інструмента відео й вибір провайдера. - Деталі автентифікації та правила повторного використання облікових даних. + Докладніше про автентифікацію та правила повторного використання облікових даних. diff --git a/docs/uk/providers/openrouter.md b/docs/uk/providers/openrouter.md index 4c07088e2..4cfa3dc99 100644 --- a/docs/uk/providers/openrouter.md +++ b/docs/uk/providers/openrouter.md @@ -1,21 +1,21 @@ --- read_when: - - Вам потрібен один API-ключ для багатьох LLM-ів + - Вам потрібен один API-ключ для багатьох LLM - Ви хочете запускати моделі через OpenRouter в OpenClaw - Ви хочете використовувати OpenRouter для генерації зображень summary: Використовуйте уніфікований API OpenRouter для доступу до багатьох моделей в OpenClaw title: OpenRouter x-i18n: - generated_at: "2026-04-24T00:42:40Z" + generated_at: "2026-04-25T03:44:16Z" model: gpt-5.4 provider: openai - source_hash: 7516910f67a8adfb107d07cadd73c34ddd110422ecb90278025d4d6344937aac + source_hash: f0dfbe92fbe229b3d0c22fa7997adc1906609bc3ee63c780b1f66f545d327f49 source_path: providers/openrouter.md workflow: 15 --- -OpenRouter надає **уніфікований API**, який спрямовує запити до багатьох моделей через єдину -кінцеву точку та API-ключ. Він сумісний з OpenAI, тому більшість SDK OpenAI працюють, якщо змінити базовий URL. +OpenRouter надає **уніфікований API**, який маршрутизує запити до багатьох моделей через одну +кінцеву точку та API-ключ. Він сумісний з OpenAI, тому більшість SDK OpenAI працюють після зміни базового URL. ## Початок роботи @@ -29,7 +29,7 @@ OpenRouter надає **уніфікований API**, який спрямов ``` - Під час онбордингу типовим значенням є `openrouter/auto`. Пізніше виберіть конкретну модель: + Під час онбордингу за замовчуванням використовується `openrouter/auto`. Пізніше виберіть конкретну модель: ```bash openclaw models set openrouter// @@ -51,25 +51,25 @@ OpenRouter надає **уніфікований API**, який спрямов } ``` -## Посилання моделей +## Посилання на моделі -Посилання моделей відповідають шаблону `openrouter//`. Повний список +Посилання на моделі мають шаблон `openrouter//`. Повний список доступних провайдерів і моделей дивіться в [/concepts/model-providers](/uk/concepts/model-providers). -Приклади вбудованого резервного перемикання: +Приклади вбудованих резервних варіантів: -| Model ref | Примітки | -| ------------------------------------ | --------------------------------- | +| Model ref | Примітки | +| ------------------------------------ | ---------------------------- | | `openrouter/auto` | Автоматична маршрутизація OpenRouter | -| `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 через MoonshotAI | -| `openrouter/openrouter/healer-alpha` | Маршрут OpenRouter Healer Alpha | -| `openrouter/openrouter/hunter-alpha` | Маршрут OpenRouter Hunter Alpha | +| `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 через MoonshotAI | +| `openrouter/openrouter/healer-alpha` | Маршрут OpenRouter Healer Alpha | +| `openrouter/openrouter/hunter-alpha` | Маршрут OpenRouter Hunter Alpha | ## Генерація зображень -OpenRouter також може працювати як основа для інструмента `image_generate`. Використовуйте модель зображень OpenRouter у `agents.defaults.imageGenerationModel`: +OpenRouter також може використовуватися для інструмента `image_generate`. Використовуйте модель OpenRouter для зображень у `agents.defaults.imageGenerationModel`: ```json5 { @@ -86,12 +86,38 @@ OpenRouter також може працювати як основа для ін OpenClaw надсилає запити на зображення до API зображень chat completions OpenRouter з `modalities: ["image", "text"]`. Моделі зображень Gemini отримують підтримувані підказки `aspectRatio` і `resolution` через `image_config` OpenRouter. +## Перетворення тексту на мовлення + +OpenRouter також можна використовувати як TTS-провайдера через його сумісну з OpenAI +кінцеву точку `/audio/speech`. + +```json5 +{ + messages: { + tts: { + auto: "always", + provider: "openrouter", + providers: { + openrouter: { + model: "hexgrad/kokoro-82m", + voice: "af_alloy", + responseFormat: "mp3", + }, + }, + }, + }, +} +``` + +Якщо `messages.tts.providers.openrouter.apiKey` не вказано, TTS повторно використовує +`models.providers.openrouter.apiKey`, а потім `OPENROUTER_API_KEY`. + ## Автентифікація та заголовки -OpenRouter використовує Bearer token з вашим API-ключем під капотом. +OpenRouter під капотом використовує Bearer token з вашим API-ключем. -У реальних запитах OpenRouter (`https://openrouter.ai/api/v1`) OpenClaw також додає -задокументовані заголовки атрибуції застосунку OpenRouter: +Для справжніх запитів OpenRouter (`https://openrouter.ai/api/v1`) OpenClaw також додає +задокументовані OpenRouter заголовки атрибуції застосунку: | Header | Value | | ------------------------- | --------------------- | @@ -100,39 +126,39 @@ OpenRouter використовує Bearer token з вашим API-ключем | `X-OpenRouter-Categories` | `cli-agent` | -Якщо ви перенаправите провайдер OpenRouter на якийсь інший проксі або базовий URL, OpenClaw -**не** додаватиме ці специфічні для OpenRouter заголовки або маркери кешу Anthropic. +Якщо ви перенаправите провайдера OpenRouter на якийсь інший проксі або базовий URL, OpenClaw +**не** додає ці специфічні для OpenRouter заголовки або маркери кешу Anthropic. ## Розширена конфігурація - На перевірених маршрутах OpenRouter посилання моделей Anthropic зберігають + На перевірених маршрутах OpenRouter посилання на моделі Anthropic зберігають специфічні для OpenRouter маркери Anthropic `cache_control`, які OpenClaw використовує для - кращого повторного використання кешу промптів у блоках system/developer prompt. + кращого повторного використання кешу промптів у блоках системних/розробницьких промптів. - На підтримуваних маршрутах, відмінних від `auto`, OpenClaw зіставляє вибраний рівень thinking з - payload reasoning проксі OpenRouter. Непідтримувані підказки моделей і + На підтримуваних маршрутах, відмінних від `auto`, OpenClaw зіставляє вибраний рівень thinking із + проксі-пейлоадами reasoning OpenRouter. Непідтримувані підказки моделей і `openrouter/auto` пропускають цю ін’єкцію reasoning. - OpenRouter усе ще працює через сумісний з OpenAI шлях у стилі проксі, тому - нативне формування запитів лише для OpenAI, таке як `serviceTier`, `store` у Responses, - payload сумісності reasoning OpenAI та підказки кешу промптів, не передається далі. + OpenRouter усе ще працює через сумісний із OpenAI шлях у стилі проксі, тому + власне OpenAI-специфічне формування запитів, як-от `serviceTier`, `store` у Responses, + пейлоади сумісності reasoning OpenAI та підказки кешу промптів, не пересилаються далі. - Посилання OpenRouter на базі Gemini залишаються на шляху proxy-Gemini: OpenClaw зберігає - там очищення thought-signature Gemini, але не вмикає нативну перевірку повторного відтворення Gemini - або bootstrap rewrites. + Посилання OpenRouter на базі Gemini залишаються на проксі-шляху Gemini: OpenClaw зберігає + там санітизацію thought-signature Gemini, але не вмикає нативну перевірку повторного відтворення Gemini + або bootstrap-перезаписи. - Якщо ви передаєте маршрутизацію провайдера OpenRouter через параметри моделі, OpenClaw пересилає + Якщо ви передаєте маршрутизацію провайдера OpenRouter у параметрах моделі, OpenClaw пересилає її як метадані маршрутизації OpenRouter до запуску спільних обгорток потоку. @@ -141,9 +167,9 @@ OpenRouter використовує Bearer token з вашим API-ключем - Вибір провайдерів, посилань моделей і поведінки резервного перемикання. + Вибір провайдерів, посилань на моделі та поведінки резервного перемикання. - - Повний довідник конфігурації для агентів, моделей і провайдерів. + + Повний довідник з конфігурації для агентів, моделей і провайдерів. diff --git a/docs/uk/tools/acp-agents.md b/docs/uk/tools/acp-agents.md index ef113973c..c37d7b816 100644 --- a/docs/uk/tools/acp-agents.md +++ b/docs/uk/tools/acp-agents.md @@ -1,199 +1,202 @@ --- read_when: - - Запуск coding harnesses через ACP - - Налаштування ACP-сеансів, прив’язаних до розмови, у каналах обміну повідомленнями + - Запуск harness для програмування через ACP + - Налаштування сеансів ACP, прив’язаних до розмови, у каналах обміну повідомленнями - Прив’язка розмови в каналі повідомлень до постійного сеансу ACP - - Усунення несправностей бекенду ACP і підключення Plugin-ів - - Налагодження доставки завершень ACP або циклів агент-до-агента + - Усунення несправностей бекенду ACP і підключення Plugin + - Налагодження доставки завершень ACP або циклів між агентами - Використання команд `/acp` у чаті -summary: Використовуйте сеанси виконання ACP для Claude Code, Cursor, Gemini CLI, явного резервного ACP Codex, ACP OpenClaw та інших агентів harness +summary: Використовуйте сеанси виконання ACP для Claude Code, Cursor, Gemini CLI, явного резервного ACP Codex, OpenClaw ACP та інших агентів harness title: агенти ACP x-i18n: - generated_at: "2026-04-24T15:52:30Z" + generated_at: "2026-04-25T03:44:22Z" model: gpt-5.4 provider: openai - source_hash: e453b4b1c58d0705313b6a9d39af4c4f5579575715d06b44b830bf6d001e6bfb + source_hash: 54f23bbfbd915147771b642e899ef2a660cacff2f8ae54facd6ba4cee946b2a1 source_path: tools/acp-agents.md workflow: 15 --- -Сеанси [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають OpenClaw змогу запускати зовнішні coding harnesses (наприклад Pi, Claude Code, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX harnesses) через ACP backend Plugin. +Сеанси [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають OpenClaw змогу запускати зовнішні harness для програмування (наприклад, Pi, Claude Code, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX-harness) через бекенд Plugin ACP. -Якщо ви попросите OpenClaw звичайною мовою прив’язати або керувати Codex у поточній розмові, OpenClaw має використати нативний Plugin app-server Codex (`/codex bind`, `/codex threads`, `/codex resume`). Якщо ви просите `/acp`, ACP, acpx або фоновий дочірній сеанс Codex, OpenClaw усе одно може маршрутизувати Codex через ACP. Кожен запуск сеансу ACP відстежується як [фонове завдання](/uk/automation/tasks). +Якщо ви попросите OpenClaw звичайною мовою прив’язати або керувати Codex у поточній розмові, OpenClaw має використовувати нативний Plugin app-server Codex (`/codex bind`, `/codex threads`, `/codex resume`). Якщо ви просите `/acp`, ACP, acpx або фоновий дочірній сеанс Codex, OpenClaw усе одно може маршрутизувати Codex через ACP. Кожен запуск сеансу ACP відстежується як [фонове завдання](/uk/automation/tasks). -Якщо ви попросите OpenClaw звичайною мовою «запустити Claude Code у thread» або використати інший зовнішній harness, OpenClaw має маршрутизувати цей запит до середовища виконання ACP (а не до нативного середовища виконання sub-agent). +Якщо ви попросите OpenClaw звичайною мовою «запустити Claude Code у треді» або використати інший зовнішній harness, OpenClaw має маршрутизувати цей запит до середовища виконання ACP (а не до нативного середовища виконання субагентів). -Якщо ви хочете, щоб Codex або Claude Code підключався як зовнішній клієнт MCP безпосередньо -до наявних розмов у каналах OpenClaw, використовуйте [`openclaw mcp serve`](/uk/cli/mcp) +Якщо ви хочете, щоб Codex або Claude Code підключалися як зовнішній клієнт MCP безпосередньо +до наявних розмов OpenClaw у каналах, використовуйте [`openclaw mcp serve`](/uk/cli/mcp) замість ACP. -## Яка сторінка мені потрібна? +## Яку сторінку мені потрібно? -Поруч є три поверхні, які легко сплутати: +Поруч є три схожі поверхні, які легко сплутати: | Ви хочете... | Використовуйте це | Примітки | | ----------------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Прив’язати або керувати Codex у поточній розмові | `/codex bind`, `/codex threads` | Нативний шлях app-server Codex; включає прив’язані відповіді в чаті, пересилання зображень, model/fast/permissions, stop і steer controls. ACP — явний резервний варіант | -| Запустити Claude Code, Gemini CLI, явний ACP Codex або інший зовнішній harness _через_ OpenClaw | Ця сторінка: агенти ACP | Сеанси, прив’язані до чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, керування runtime | -| Відкрити сеанс Gateway OpenClaw _як_ ACP-сервер для редактора або клієнта | [`openclaw acp`](/uk/cli/acp) | Режим моста. IDE/клієнт спілкується з OpenClaw через ACP по stdio/WebSocket | -| Повторно використати локальний AI CLI як резервну текстову модель | [CLI Backends](/uk/gateway/cli-backends) | Не ACP. Без інструментів OpenClaw, без елементів керування ACP, без runtime harness | +| Прив’язати або керувати Codex у поточній розмові | `/codex bind`, `/codex threads` | Нативний шлях app-server Codex; включає прив’язані відповіді в чаті, пересилання зображень, керування model/fast/permissions, stop і steer. ACP — явний резервний варіант | +| Запустити Claude Code, Gemini CLI, явний Codex ACP або інший зовнішній harness _через_ OpenClaw | Ця сторінка: агенти ACP | Сеанси, прив’язані до чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, керування середовищем виконання | +| Надати сеанс OpenClaw Gateway _як_ сервер ACP для редактора або клієнта | [`openclaw acp`](/uk/cli/acp) | Режим bridge. IDE/клієнт взаємодіє з OpenClaw за ACP через stdio/WebSocket | +| Повторно використовувати локальний AI CLI як резервну текстову модель | [CLI Backends](/uk/gateway/cli-backends) | Не ACP. Без інструментів OpenClaw, без керування ACP, без середовища виконання harness | -## Це працює одразу після встановлення? +## Чи працює це одразу після встановлення? -Зазвичай так. У свіжих встановленнях bundled Plugin runtime `acpx` увімкнено за замовчуванням, із закріпленим локально для Plugin бінарником `acpx`, який OpenClaw перевіряє та самостійно відновлює під час запуску. Виконайте `/acp doctor`, щоб перевірити готовність. +Зазвичай так. У нових установках увімкнено вбудований Plugin середовища виконання `acpx` за замовчуванням разом із локально закріпленим бінарним файлом `acpx`, який OpenClaw перевіряє та самостійно відновлює під час запуску. Запустіть `/acp doctor`, щоб перевірити готовність. -Поширені нюанси першого запуску: +Підводні камені першого запуску: -- Адаптери цільового harness (Codex, Claude тощо) можуть завантажуватися за потреби через `npx` під час першого використання. -- Авторизація постачальника для цього harness усе ще має бути налаштована на хості. -- Якщо на хості немає npm або доступу до мережі, завантаження адаптера під час першого запуску завершиться помилкою, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом. +- Адаптери цільових harness (Codex, Claude тощо) можуть завантажуватися за потреби через `npx` під час першого використання. +- Автентифікація постачальника все одно має бути налаштована на хості для цього harness. +- Якщо хост не має npm або доступу до мережі, завантаження адаптера при першому запуску завершиться помилкою, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом. ## Операторський runbook -Швидкий потік `/acp` із чату: +Швидкий сценарій `/acp` із чату: 1. **Запуск** — `/acp spawn claude --bind here`, `/acp spawn gemini --mode persistent --thread auto` або явний `/acp spawn codex --bind here` -2. **Працюйте** у прив’язаній розмові або thread (або явно вкажіть ключ сеансу). +2. **Працюйте** в прив’язаній розмові або треді (або явно вкажіть ключ сеансу). 3. **Перевірте стан** — `/acp status` 4. **Налаштуйте** — `/acp model `, `/acp permissions `, `/acp timeout ` -5. **Скоригуйте** без заміни контексту — `/acp steer tighten logging and continue` -6. **Зупиніть** — `/acp cancel` (поточний turn) або `/acp close` (сеанс + прив’язки) +5. **Спрямуйте** без заміни контексту — `/acp steer tighten logging and continue` +6. **Зупиніть** — `/acp cancel` (поточний хід) або `/acp close` (сеанс + прив’язки) Тригери природною мовою, які мають маршрутизуватися до нативного Plugin Codex: -- «Прив’яжи цей канал Discord до Codex.» -- «Під’єднай цей чат до thread Codex ``.» -- «Покажи threads Codex, а потім прив’яжи цей.» +- «Прив’яжи цей канал Discord до Codex». +- «Підключи цей чат до треду Codex ``». +- «Покажи треди Codex, а потім прив’яжи цей». -Нативна прив’язка розмов Codex є типовим шляхом керування чатом. Динамічні інструменти OpenClaw, як і раніше, виконуються через OpenClaw, тоді як нативні інструменти Codex, як-от -shell/apply-patch, виконуються всередині Codex. Для подій нативних інструментів Codex OpenClaw -впроваджує relay нативних hook-ів для кожного turn, щоб hook-и Plugin могли блокувати -`before_tool_call`, спостерігати за `after_tool_call` і маршрутизувати події Codex +Нативна прив’язка розмов Codex — це типовий шлях керування чатом. Динамічні +інструменти OpenClaw, як і раніше, виконуються через OpenClaw, тоді як +інструменти, нативні для Codex, такі як shell/apply-patch, виконуються всередині Codex. Для подій нативних інструментів Codex OpenClaw +впроваджує нативний relay hook на кожен хід, щоб hook-и Plugin могли блокувати +`before_tool_call`, спостерігати `after_tool_call` і маршрутизувати події Codex `PermissionRequest` через погодження OpenClaw. Relay v1 навмисно консервативний: він не змінює аргументи нативних інструментів Codex, -не переписує записи thread Codex і не контролює фінальні відповіді/Stop hook-и. Використовуйте явний -ACP лише тоді, коли вам потрібна модель runtime/сеансів ACP. +не переписує записи тредів Codex і не блокує фінальні відповіді/hook-и Stop. Використовуйте явний +ACP лише тоді, коли вам потрібна модель середовища виконання/сеансів ACP. Межі підтримки вбудованого Codex +описано в +[контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract). -Тригери природною мовою, які мають маршрутизуватися до runtime ACP: +Тригери природною мовою, які мають маршрутизуватися до середовища виконання ACP: -- «Запусти це як одноразовий сеанс Claude Code ACP і підсумуй результат.» -- «Використай Gemini CLI для цього завдання у thread, а потім зберігай подальші звернення в тому самому thread.» -- «Запусти Codex через ACP у фоновому thread.» +- «Запусти це як одноразовий сеанс Claude Code ACP і підсумуй результат». +- «Використай Gemini CLI для цього завдання в треді, а потім зберігай подальші дії в цьому ж треді». +- «Запусти Codex через ACP у фоновому треді». -OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, прив’язується до поточної розмови або thread, коли це підтримується, і маршрутизує подальші звернення до цього сеансу до його закриття або завершення строку дії. Codex переходить цим шляхом лише тоді, коли ACP запитано явно або коли для потрібного фонового runtime усе ще потрібен ACP. +OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, прив’язує до поточної розмови або треду, якщо це підтримується, і маршрутизує подальші дії до цього сеансу до його закриття/завершення. Codex використовує цей шлях лише тоді, коли ACP явно вказано або коли для запитаного фонового середовища виконання все ще потрібен ACP. -## ACP проти sub-agents +## ACP і субагенти -Використовуйте ACP, коли вам потрібен зовнішній runtime harness. Використовуйте нативний app-server Codex для прив’язки/керування розмовами Codex. Використовуйте sub-agents, коли вам потрібні делеговані запуски всередині OpenClaw. +Використовуйте ACP, коли вам потрібне зовнішнє середовище виконання harness. Використовуйте нативний app-server Codex для прив’язки/керування розмовою Codex. Використовуйте субагентів, коли вам потрібні делеговані запуски, нативні для OpenClaw. -| Область | Сеанс ACP | Запуск sub-agent | +| Область | Сеанс ACP | Запуск субагента | | ------------- | -------------------------------------- | ----------------------------------- | -| Runtime | ACP backend Plugin (наприклад acpx) | Нативний runtime sub-agent OpenClaw | +| Середовище виконання | Бекенд Plugin ACP (наприклад, acpx) | Нативне середовище виконання субагента OpenClaw | | Ключ сеансу | `agent::acp:` | `agent::subagent:` | | Основні команди | `/acp ...` | `/subagents ...` | -| Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (runtime за замовчуванням) | +| Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (середовище виконання за замовчуванням) | -Див. також [Sub-agents](/uk/tools/subagents). +Див. також [Субагенти](/uk/tools/subagents). ## Як ACP запускає Claude Code -Для Claude Code через ACP стек такий: +Для Claude Code через ACP стек виглядає так: -1. Площина керування сеансами ACP OpenClaw -2. bundled Plugin runtime `acpx` -3. ACP-адаптер Claude -4. Механізм runtime/сеансів на боці Claude +1. Контрольна площина сеансу OpenClaw ACP +2. вбудований Plugin середовища виконання `acpx` +3. адаптер Claude ACP +4. середовище виконання/механізми сеансів на боці Claude -Важливе розрізнення: +Важлива різниця: -- ACP Claude — це сеанс harness із керуванням ACP, відновленням сеансу, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/thread. -- CLI backends — це окремі локальні runtime лише для текстового резервного режиму. Див. [CLI Backends](/uk/gateway/cli-backends). +- ACP Claude — це сеанс harness із керуванням ACP, відновленням сеансу, відстеженням фонового завдання та необов’язковою прив’язкою до розмови/треду. +- CLI backends — це окремі локальні резервні середовища виконання лише для тексту. Див. [CLI Backends](/uk/gateway/cli-backends). Для операторів практичне правило таке: -- потрібні `/acp spawn`, сеанси з прив’язкою, елементи керування runtime або постійна робота harness: використовуйте ACP -- потрібен простий локальний текстовий резервний режим через сирий CLI: використовуйте CLI backends +- потрібні `/acp spawn`, сеанси з можливістю прив’язки, керування середовищем виконання або постійна робота harness: використовуйте ACP +- потрібен простий локальний текстовий резервний варіант через необроблений CLI: використовуйте CLI backends ## Прив’язані сеанси ### Прив’язки до поточної розмови -`/acp spawn --bind here` закріплює поточну розмову за створеним сеансом ACP — без дочірнього thread, у тій самій поверхні чату. OpenClaw продовжує відповідати за transport, auth, safety і доставку; подальші повідомлення в цій розмові маршрутизуються до того самого сеансу; `/new` і `/reset` скидають сеанс на місці; `/acp close` знімає прив’язку. +`/acp spawn --bind here` закріплює поточну розмову за запущеним сеансом ACP — без дочірнього треду, у тій самій поверхні чату. OpenClaw і далі керує транспортом, автентифікацією, безпекою та доставкою; подальші повідомлення в цій розмові маршрутизуються до того самого сеансу; `/new` і `/reset` скидають сеанс на місці; `/acp close` видаляє прив’язку. Ментальна модель: - **поверхня чату** — місце, де люди продовжують спілкуватися (канал Discord, тема Telegram, чат iMessage). -- **сеанс ACP** — стійкий стан runtime Codex/Claude/Gemini, до якого маршрутизує OpenClaw. -- **дочірній thread/topic** — необов’язкова додаткова поверхня обміну повідомленнями, яка створюється лише через `--thread ...`. -- **робочий простір runtime** — розташування у файловій системі (`cwd`, checkout репозиторію, робочий простір backend), де працює harness. Не залежить від поверхні чату. +- **сеанс ACP** — довготривалий стан середовища виконання Codex/Claude/Gemini, до якого маршрутизує OpenClaw. +- **дочірній тред/тема** — необов’язкова додаткова поверхня повідомлень, що створюється лише через `--thread ...`. +- **робочий простір середовища виконання** — розташування файлової системи (`cwd`, checkout репозиторію, робочий простір бекенду), де виконується harness. Воно не залежить від поверхні чату. Приклади: -- `/codex bind` — залишити цей чат, запустити або приєднати нативний app-server Codex, маршрутизувати сюди майбутні повідомлення. -- `/codex model gpt-5.4`, `/codex fast on`, `/codex permissions yolo` — налаштувати прив’язаний нативний thread Codex із чату. -- `/codex stop` або `/codex steer focus on the failing tests first` — керувати активним turn нативного Codex. +- `/codex bind` — залишити цей чат, запустити або під’єднати нативний app-server Codex, маршрутизувати майбутні повідомлення сюди. +- `/codex model gpt-5.4`, `/codex fast on`, `/codex permissions yolo` — налаштувати прив’язаний нативний тред Codex із чату. +- `/codex stop` або `/codex steer focus on the failing tests first` — керувати активним ходом нативного Codex. - `/acp spawn codex --bind here` — явний резервний варіант ACP для Codex. -- `/acp spawn codex --thread auto` — OpenClaw може створити дочірній thread/topic і прив’язати його там. -- `/acp spawn codex --bind here --cwd /workspace/repo` — та сама прив’язка чату, Codex працює в `/workspace/repo`. +- `/acp spawn codex --thread auto` — OpenClaw може створити дочірній тред/тему і прив’язати його там. +- `/acp spawn codex --bind here --cwd /workspace/repo` — та сама прив’язка до чату, Codex виконується в `/workspace/repo`. Примітки: - `--bind here` і `--thread ...` взаємовиключні. - `--bind here` працює лише в каналах, які оголошують підтримку прив’язки до поточної розмови; інакше OpenClaw повертає чітке повідомлення про відсутність підтримки. Прив’язки зберігаються після перезапусків Gateway. -- У Discord `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірній thread для `--thread auto|here`, а не для `--bind here`. -- Якщо ви запускаєте інший агент ACP без `--cwd`, OpenClaw за замовчуванням успадковує робочий простір **цільового агента**. Відсутні успадковані шляхи (`ENOENT`/`ENOTDIR`) повертаються до стандартного значення backend; інші помилки доступу (наприклад `EACCES`) відображаються як помилки запуску. +- У Discord `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірній тред для `--thread auto|here` — не для `--bind here`. +- Якщо ви запускаєте інший агент ACP без `--cwd`, OpenClaw за замовчуванням успадковує робочий простір **цільового агента**. Відсутні успадковані шляхи (`ENOENT`/`ENOTDIR`) повертаються до типового значення бекенду; інші помилки доступу (наприклад, `EACCES`) відображаються як помилки запуску. -### Сеанси, прив’язані до thread +### Сеанси, прив’язані до тредів -Коли для адаптера каналу ввімкнено прив’язки до thread, сеанси ACP можна прив’язувати до thread: +Коли для адаптера каналу ввімкнено прив’язки до тредів, сеанси ACP можна прив’язувати до тредів: -- OpenClaw прив’язує thread до цільового сеансу ACP. -- Подальші повідомлення в цьому thread маршрутизуються до прив’язаного сеансу ACP. -- Вивід ACP доставляється назад у той самий thread. -- Зняття фокуса/закриття/архівування/завершення часу очікування бездіяльності або завершення максимального строку дії знімає прив’язку. +- OpenClaw прив’язує тред до цільового сеансу ACP. +- Подальші повідомлення в цьому треді маршрутизуються до прив’язаного сеансу ACP. +- Вивід ACP доставляється назад у той самий тред. +- Втрата фокусу/закриття/архівування/неактивність за тайм-аутом або завершення за максимальним віком видаляють прив’язку. -Підтримка прив’язки до thread залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки до thread, OpenClaw повертає чітке повідомлення про відсутність підтримки/недоступність. +Підтримка прив’язки до тредів залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки до тредів, OpenClaw повертає чітке повідомлення про відсутність підтримки/недоступність. -Обов’язкові feature flags для ACP, прив’язаного до thread: +Обов’язкові feature flag-и для ACP, прив’язаного до тредів: - `acp.enabled=true` - `acp.dispatch.enabled` увімкнено за замовчуванням (встановіть `false`, щоб призупинити диспетчеризацію ACP) -- Увімкнено прапорець запуску ACP thread у адаптері каналу (залежить від адаптера) +- Увімкнено прапорець запуску ACP-тредів адаптера каналу (залежить від адаптера) - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` -### Канали з підтримкою thread +### Канали з підтримкою тредів -- Будь-який адаптер каналу, який надає можливість прив’язки сеансу/thread. +- Будь-який адаптер каналу, який надає можливість прив’язки сеансів/тредів. - Поточна вбудована підтримка: - - threads/channels Discord - - topics Telegram (теми форуму в групах/supergroups і DM topics) -- Канали Plugin можуть додати підтримку через той самий інтерфейс прив’язки. + - треди/канали Discord + - теми Telegram (теми форуму в групах/супергрупах і теми в DM) +- Канали Plugin можуть додавати підтримку через той самий інтерфейс прив’язки. -## Налаштування для конкретних каналів +## Специфічні налаштування каналів -Для неепhemeralних робочих процесів налаштовуйте постійні прив’язки ACP у записах верхнього рівня `bindings[]`. +Для неепhemeral робочих процесів налаштуйте постійні прив’язки ACP у записах верхнього рівня `bindings[]`. ### Модель прив’язки - `bindings[].type="acp"` позначає постійну прив’язку розмови ACP. - `bindings[].match` визначає цільову розмову: - - Канал або thread Discord: `match.channel="discord"` + `match.peer.id=""` - - Тема форуму Telegram: `match.channel="telegram"` + `match.peer.id=":topic:"` + - канал або тред Discord: `match.channel="discord"` + `match.peer.id=""` + - тема форуму Telegram: `match.channel="telegram"` + `match.peer.id=":topic:"` - DM/груповий чат BlueBubbles: `match.channel="bluebubbles"` + `match.peer.id=""` Для стабільних групових прив’язок віддавайте перевагу `chat_id:*` або `chat_identifier:*`. - DM/груповий чат iMessage: `match.channel="imessage"` + `match.peer.id=""` Для стабільних групових прив’язок віддавайте перевагу `chat_id:*`. -- `bindings[].agentId` — це id агента OpenClaw-власника. +- `bindings[].agentId` — це id агента-власника OpenClaw. - Необов’язкові перевизначення ACP розміщуються в `bindings[].acp`: - `mode` (`persistent` або `oneshot`) - `label` - `cwd` - `backend` -### Значення runtime за замовчуванням для кожного агента +### Типові значення середовища виконання для агента -Використовуйте `agents.list[].runtime`, щоб один раз визначити типові значення ACP для кожного агента: +Використовуйте `agents.list[].runtime`, щоб один раз визначити типові значення ACP для агента: - `agents.list[].runtime.type="acp"` - `agents.list[].runtime.acp.agent` (id harness, наприклад `codex` або `claude`) @@ -201,11 +204,11 @@ OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, п - `agents.list[].runtime.acp.mode` - `agents.list[].runtime.acp.cwd` -Порядок пріоритету перевизначень для прив’язаних сеансів ACP: +Пріоритет перевизначення для прив’язаних сеансів ACP: 1. `bindings[].acp.*` 2. `agents.list[].runtime.acp.*` -3. глобальні типові значення ACP (наприклад `acp.backend`) +3. глобальні типові значення ACP (наприклад, `acp.backend`) Приклад: @@ -289,18 +292,18 @@ OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, п Поведінка: -- OpenClaw забезпечує існування налаштованого сеансу ACP перед використанням. -- Повідомлення в цьому каналі або topic маршрутизуються до налаштованого сеансу ACP. +- OpenClaw забезпечує наявність налаштованого сеансу ACP перед використанням. +- Повідомлення в цьому каналі або темі маршрутизуються до налаштованого сеансу ACP. - У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ сеансу ACP на місці. -- Тимчасові прив’язки runtime (наприклад, створені потоками thread-focus) усе ще застосовуються там, де вони присутні. +- Тимчасові прив’язки середовища виконання (наприклад, створені потоками фокусування тредів) усе ще застосовуються, якщо вони присутні. - Для міжагентних запусків ACP без явного `cwd` OpenClaw успадковує робочий простір цільового агента з конфігурації агента. -- Відсутні успадковані шляхи робочого простору повертаються до стандартного `cwd` backend; помилки доступу за наявного шляху відображаються як помилки запуску. +- Відсутні успадковані шляхи робочого простору повертаються до типового `cwd` бекенду; збої доступу для наявних шляхів відображаються як помилки запуску. ## Запуск сеансів ACP (інтерфейси) ### Із `sessions_spawn` -Використовуйте `runtime: "acp"` для запуску сеансу ACP з turn агента або виклику інструмента. +Використовуйте `runtime: "acp"`, щоб запустити сеанс ACP із ходу агента або виклику інструмента. ```json { @@ -314,26 +317,26 @@ OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, п Примітки: -- Типовим значенням `runtime` є `subagent`, тому для сеансів ACP явно вказуйте `runtime: "acp"`. -- Якщо `agentId` пропущено, OpenClaw використовує `acp.defaultAgent`, якщо його налаштовано. -- `mode: "session"` вимагає `thread: true`, щоб зберігати постійну прив’язану розмову. +- `runtime` за замовчуванням має значення `subagent`, тому для сеансів ACP явно встановлюйте `runtime: "acp"`. +- Якщо `agentId` не вказано, OpenClaw використовує `acp.defaultAgent`, якщо його налаштовано. +- `mode: "session"` вимагає `thread: true`, щоб зберегти постійну прив’язану розмову. -Докладніше про інтерфейс: +Деталі інтерфейсу: -- `task` (обов’язково): початковий prompt, надісланий до сеансу ACP. +- `task` (обов’язково): початковий запит, надісланий до сеансу ACP. - `runtime` (обов’язково для ACP): має бути `"acp"`. -- `agentId` (необов’язково): id цільового harness ACP. Якщо задано, використовується `acp.defaultAgent`. -- `thread` (необов’язково, типово `false`): запит потоку прив’язки до thread, якщо підтримується. +- `agentId` (необов’язково): id цільового harness ACP. Якщо задано `acp.defaultAgent`, використовується він. +- `thread` (необов’язково, типове значення `false`): запитати потік прив’язки до треду, якщо це підтримується. - `mode` (необов’язково): `run` (одноразовий запуск) або `session` (постійний). - типове значення — `run` - - якщо `thread: true` і mode не вказано, OpenClaw може типово використовувати постійну поведінку залежно від шляху runtime + - якщо `thread: true`, а mode не вказано, OpenClaw може за замовчуванням вибрати постійну поведінку залежно від шляху середовища виконання - `mode: "session"` вимагає `thread: true` -- `cwd` (необов’язково): запитуваний робочий каталог runtime (перевіряється політикою backend/runtime). Якщо пропущено, запуск ACP успадковує робочий простір цільового агента, якщо його налаштовано; відсутні успадковані шляхи повертаються до типових значень backend, а реальні помилки доступу повертаються. +- `cwd` (необов’язково): запитаний робочий каталог середовища виконання (перевіряється політикою бекенду/середовища виконання). Якщо не вказано, запуск ACP успадковує робочий простір цільового агента, якщо його налаштовано; відсутні успадковані шляхи повертаються до типових значень бекенду, а реальні помилки доступу повертаються як помилки. - `label` (необов’язково): операторська мітка, що використовується в тексті сеансу/банера. - `resumeSessionId` (необов’язково): відновити наявний сеанс ACP замість створення нового. Агент відтворює історію своєї розмови через `session/load`. Вимагає `runtime: "acp"`. -- `streamTo` (необов’язково): `"parent"` транслює зведення прогресу початкового запуску ACP назад до сеансу-запитувача як системні події. - - Якщо доступно, прийняті відповіді включають `streamLogPath`, що вказує на JSONL-журнал у межах сеансу (`.acp-stream.jsonl`), який можна переглядати для повної історії relay. -- `model` (необов’язково): явне перевизначення model для дочірнього сеансу ACP. Використовується для `runtime: "acp"`, щоб дочірній сеанс використовував запитану model замість тихого повернення до типового значення цільового агента. +- `streamTo` (необов’язково): `"parent"` транслює підсумки прогресу початкового запуску ACP назад до сеансу-запитувача як системні події. + - Якщо доступно, прийняті відповіді включають `streamLogPath`, що вказує на JSONL-журнал у межах сеансу (`.acp-stream.jsonl`), який можна відстежувати для повної історії relay. +- `model` (необов’язково): явне перевизначення model для дочірнього сеансу ACP. Використовується для `runtime: "acp"`, щоб дочірній сеанс застосовував запитану model замість тихого повернення до типового значення цільового агента. ## Модель доставки @@ -341,41 +344,41 @@ OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, п ### Інтерактивні сеанси ACP -Інтерактивні сеанси призначені для продовження спілкування на видимій поверхні чату: +Інтерактивні сеанси призначені для продовження спілкування у видимій поверхні чату: - `/acp spawn ... --bind here` прив’язує поточну розмову до сеансу ACP. -- `/acp spawn ... --thread ...` прив’язує thread/topic каналу до сеансу ACP. +- `/acp spawn ... --thread ...` прив’язує тред/тему каналу до сеансу ACP. - Постійні налаштовані `bindings[].type="acp"` маршрутизують відповідні розмови до того самого сеансу ACP. -Подальші повідомлення в прив’язаній розмові маршрутизуються безпосередньо до сеансу ACP, а вивід ACP доставляється назад у той самий канал/thread/topic. +Подальші повідомлення в прив’язаній розмові маршрутизуються безпосередньо до сеансу ACP, а вивід ACP доставляється назад у той самий канал/тред/тему. ### Одноразові сеанси ACP, що належать батьківському процесу -Одноразові сеанси ACP, запущені іншим агентом, є фоновими дочірніми процесами, подібно до sub-agents: +Одноразові сеанси ACP, запущені іншим агентом, є фоновими дочірніми процесами, подібними до субагентів: - Батьківський процес запитує роботу через `sessions_spawn({ runtime: "acp", mode: "run" })`. -- Дочірній процес працює у власному сеансі harness ACP. -- Завершення повертається через внутрішній шлях оголошення завершення завдання. -- Батьківський процес переписує результат дочірнього процесу у звичайному голосі помічника, коли потрібна відповідь для користувача. +- Дочірній процес виконується у власному сеансі harness ACP. +- Про завершення повідомляється через внутрішній шлях сповіщення про завершення завдання. +- Батьківський процес переписує результат дочірнього у звичайному голосі помічника, коли потрібна відповідь для користувача. -Не розглядайте цей шлях як peer-to-peer чат між батьківським і дочірнім процесами. Дочірній процес уже має канал завершення назад до батьківського процесу. +Не розглядайте цей шлях як peer-to-peer чат між батьківським і дочірнім процесами. Дочірній процес уже має канал завершення назад до батьківського. ### `sessions_send` і доставка A2A `sessions_send` може бути націлено на інший сеанс після запуску. Для звичайних peer-сеансів OpenClaw використовує шлях подальших дій agent-to-agent (A2A) після впровадження повідомлення: -- очікує відповіді цільового сеансу -- за потреби дозволяє запитувачу та цілі обмінятися обмеженою кількістю додаткових turn-ів -- просить цільовий сеанс створити повідомлення-оголошення -- доставляє це оголошення у видимий канал або thread +- очікує на відповідь цільового сеансу +- за потреби дає змогу запитувачу й цільовому сеансу обмінятися обмеженою кількістю подальших ходів +- просить цільовий сеанс створити announce-повідомлення +- доставляє це announce у видимий канал або тред -Цей шлях A2A є резервним варіантом для peer-надсилань, коли відправнику потрібна видима подальша дія. Він залишається увімкненим, коли непов’язаний сеанс може бачити й надсилати повідомлення ACP-цілі, наприклад за широких налаштувань `tools.sessions.visibility`. +Цей шлях A2A є резервним варіантом для peer-надсилань, коли відправнику потрібна видима подальша дія. Він залишається ввімкненим, коли не пов’язаний сеанс може бачити й надсилати повідомлення цілі ACP, наприклад за широких налаштувань `tools.sessions.visibility`. -OpenClaw пропускає подальшу дію A2A лише тоді, коли запитувач є батьківським процесом власного одноразового дочірнього процесу ACP. У такому разі запуск A2A поверх завершення завдання може пробудити батьківський процес результатом дочірнього, переслати відповідь батьківського процесу назад у дочірній і створити цикл echo між батьківським і дочірнім процесами. Результат `sessions_send` повідомляє `delivery.status="skipped"` для такого випадку власного дочірнього процесу, оскільки за результат уже відповідає шлях завершення. +OpenClaw пропускає подальшу дію A2A лише тоді, коли запитувач є батьківським процесом для власного одноразового дочірнього процесу ACP, що належить цьому батьківському процесу. У такому разі запуск A2A поверх завершення завдання може пробудити батьківський процес результатом дочірнього, переслати відповідь батьківського процесу назад у дочірній і створити цикл відлуння батьківський/дочірній. Результат `sessions_send` повідомляє `delivery.status="skipped"` для такого випадку дочірнього процесу-власника, оскільки шлях завершення вже відповідає за результат. ### Відновлення наявного сеансу -Використовуйте `resumeSessionId`, щоб продовжити попередній сеанс ACP замість запуску з нуля. Агент відтворює історію своєї розмови через `session/load`, тому продовжує з повним контекстом попередньої роботи. +Використовуйте `resumeSessionId`, щоб продовжити попередній сеанс ACP замість запуску нового. Агент відтворює історію своєї розмови через `session/load`, тож він продовжує з повним контекстом попереднього. ```json { @@ -386,36 +389,36 @@ OpenClaw пропускає подальшу дію A2A лише тоді, ко } ``` -Поширені варіанти використання: +Типові сценарії використання: -- Передати сеанс Codex з ноутбука на телефон — попросіть свого агента продовжити з того місця, де ви зупинилися -- Продовжити coding session, який ви почали інтерактивно в CLI, тепер у безголовому режимі через агента -- Продовжити роботу, яку перервав перезапуск gateway або idle timeout +- Передайте сеанс Codex зі свого ноутбука на телефон — скажіть агенту продовжити з того місця, де ви зупинилися +- Продовжіть сеанс програмування, який ви почали інтерактивно в CLI, тепер у безголовому режимі через свого агента +- Відновіть роботу, яку було перервано перезапуском gateway або тайм-аутом неактивності Примітки: -- `resumeSessionId` вимагає `runtime: "acp"` — повертає помилку, якщо використовується з runtime sub-agent. -- `resumeSessionId` відновлює історію розмови upstream ACP; `thread` і `mode` усе ще звичайно застосовуються до нового сеансу OpenClaw, який ви створюєте, тому `mode: "session"` усе ще вимагає `thread: true`. +- `resumeSessionId` вимагає `runtime: "acp"` — повертає помилку, якщо використовується із середовищем виконання субагента. +- `resumeSessionId` відновлює історію розмови вищого рівня ACP; `thread` і `mode` усе одно звичайно застосовуються до нового сеансу OpenClaw, який ви створюєте, тож `mode: "session"` як і раніше вимагає `thread: true`. - Цільовий агент має підтримувати `session/load` (Codex і Claude Code підтримують). -- Якщо id сеансу не знайдено, запуск завершується з чіткою помилкою — без тихого повернення до нового сеансу. +- Якщо id сеансу не знайдено, запуск завершується з чіткою помилкою — без тихого переходу до нового сеансу. - + -Після розгортання gateway виконайте повну живу перевірку, а не покладайтеся лише на unit-тести: +Після розгортання gateway виконайте живу наскрізну перевірку замість того, щоб покладатися лише на модульні тести: -1. Перевірте версію та commit розгорнутого gateway на цільовому хості. -2. Відкрийте тимчасовий bridge-сеанс ACPX до живого агента. +1. Перевірте розгорнуту версію gateway і commit на цільовому хості. +2. Відкрийте тимчасовий сеанс bridge ACPX до живого агента. 3. Попросіть цього агента викликати `sessions_spawn` з `runtime: "acp"`, `agentId: "codex"`, `mode: "run"` і завданням `Reply with exactly LIVE-ACP-SPAWN-OK`. -4. Переконайтеся, що є `accepted=yes`, реальний `childSessionKey` і немає помилки validator. -5. Очистьте тимчасовий bridge-сеанс. +4. Переконайтеся, що є `accepted=yes`, реальний `childSessionKey` і немає помилки валідатора. +5. Очистьте тимчасовий сеанс bridge. -Для цієї перевірки використовуйте `mode: "run"` і пропускайте `streamTo: "parent"` — шляхи `mode: "session"`, прив’язані до thread, і relay потоку є окремими, багатшими інтеграційними проходами. +Залишайте перевірку на `mode: "run"` і пропускайте `streamTo: "parent"` — шляхи `mode: "session"`, прив’язані до тредів, і relay-потоки є окремими, багатшими інтеграційними перевірками. ## Сумісність із sandbox -Наразі сеанси ACP працюють у runtime хоста, а не всередині sandbox OpenClaw. +Наразі сеанси ACP виконуються в середовищі хоста, а не всередині sandbox OpenClaw. Поточні обмеження: @@ -445,9 +448,9 @@ OpenClaw пропускає подальшу дію A2A лише тоді, ко - `--cwd ` - `--label ` -Див. [Slash Commands](/uk/tools/slash-commands). +Див. [Слеш-команди](/uk/tools/slash-commands). -## Визначення цілі сеансу +## Визначення цільового сеансу Більшість дій `/acp` приймають необов’язкову ціль сеансу (`session-key`, `session-id` або `session-label`). @@ -455,12 +458,12 @@ OpenClaw пропускає подальшу дію A2A лише тоді, ко 1. Явний аргумент цілі (або `--session` для `/acp steer`) - спочатку пробує ключ - - потім session id у форматі UUID - - потім label -2. Поточна прив’язка thread (якщо ця розмова/thread прив’язана до сеансу ACP) -3. Резервний варіант із поточним сеансом запитувача + - потім id сеансу у форматі UUID + - потім мітку +2. Прив’язка поточного треду (якщо цю розмову/тред прив’язано до сеансу ACP) +3. Резервний варіант поточного сеансу-запитувача -Прив’язки до поточної розмови й прив’язки до thread беруть участь у кроці 2. +Прив’язки до поточної розмови й прив’язки до тредів беруть участь у кроці 2. Якщо ціль не вдається визначити, OpenClaw повертає чітку помилку (`Unable to resolve session target: ...`). @@ -468,101 +471,100 @@ OpenClaw пропускає подальшу дію A2A лише тоді, ко `/acp spawn` підтримує `--bind here|off`. -| Режим | Поведінка | -| ------ | --------------------------------------------------------------------- | -| `here` | Прив’язати поточну активну розмову на місці; завершитися помилкою, якщо активної немає. | -| `off` | Не створювати прив’язку до поточної розмови. | +| Режим | Поведінка | +| ----- | ----------------------------------------------------------------------- | +| `here` | Прив’язати поточну активну розмову на місці; якщо активної немає — помилка. | +| `off` | Не створювати прив’язку до поточної розмови. | Примітки: -- `--bind here` — це найпростіший шлях для оператора для сценарію «зробити цей канал або чат підключеним до Codex». -- `--bind here` не створює дочірній thread. -- `--bind here` доступний лише в каналах, що підтримують прив’язку до поточної розмови. +- `--bind here` — це найпростіший операторський шлях для «зробити цей канал або чат підключеним до Codex». +- `--bind here` не створює дочірній тред. +- `--bind here` доступний лише в каналах, які підтримують прив’язку до поточної розмови. - `--bind` і `--thread` не можна поєднувати в одному виклику `/acp spawn`. -## Режими thread під час запуску +## Режими тредів під час запуску `/acp spawn` підтримує `--thread auto|here|off`. | Режим | Поведінка | -| ------ | --------------------------------------------------------------------------------------------------- | -| `auto` | В активному thread: прив’язати цей thread. Поза thread: створити/прив’язати дочірній thread, якщо підтримується. | -| `here` | Вимагати поточний активний thread; завершитися помилкою, якщо ви не в ньому. | +| ----- | ---------------------------------------------------------------------------------------------------- | +| `auto` | У активному треді: прив’язати цей тред. Поза тредом: створити/прив’язати дочірній тред, якщо це підтримується. | +| `here` | Вимагає поточного активного треду; якщо ви не в треді — помилка. | | `off` | Без прив’язки. Сеанс запускається без прив’язки. | Примітки: -- На поверхнях без прив’язки до thread типовою поведінкою фактично є `off`. -- Запуск із прив’язкою до thread вимагає підтримки політики каналу: +- На поверхнях без прив’язки до тредів типова поведінка фактично дорівнює `off`. +- Запуск із прив’язкою до треду вимагає підтримки політики каналу: - Discord: `channels.discord.threadBindings.spawnAcpSessions=true` - Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true` -- Використовуйте `--bind here`, якщо хочете закріпити поточну розмову без створення дочірнього thread. +- Використовуйте `--bind here`, якщо хочете закріпити поточну розмову без створення дочірнього треду. ## Керування ACP -| Команда | Що вона робить | Приклад | -| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- | -| `/acp spawn` | Створює сеанс ACP; необов’язкова поточна прив’язка або прив’язка до thread. | `/acp spawn codex --bind here --cwd /repo` | -| `/acp cancel` | Скасовує turn у процесі виконання для цільового сеансу. | `/acp cancel agent:codex:acp:` | -| `/acp steer` | Надсилає інструкцію steer до запущеного сеансу. | `/acp steer --session support inbox prioritize failing tests` | -| `/acp close` | Закриває сеанс і знімає прив’язку з цільових thread. | `/acp close` | -| `/acp status` | Показує backend, режим, стан, параметри runtime, можливості. | `/acp status` | -| `/acp set-mode` | Встановлює режим runtime для цільового сеансу. | `/acp set-mode plan` | -| `/acp set` | Загальний запис параметра конфігурації runtime. | `/acp set model openai/gpt-5.4` | -| `/acp cwd` | Встановлює перевизначення робочого каталогу runtime. | `/acp cwd /Users/user/Projects/repo` | -| `/acp permissions` | Встановлює профіль політики погодження. | `/acp permissions strict` | -| `/acp timeout` | Встановлює timeout runtime (у секундах). | `/acp timeout 120` | -| `/acp model` | Встановлює перевизначення model runtime. | `/acp model anthropic/claude-opus-4-6` | -| `/acp reset-options` | Видаляє перевизначення параметрів runtime для сеансу. | `/acp reset-options` | -| `/acp sessions` | Перелічує нещодавні сеанси ACP зі сховища. | `/acp sessions` | -| `/acp doctor` | Стан backend, можливості, дієві способи виправлення. | `/acp doctor` | -| `/acp install` | Виводить детерміновані кроки встановлення й увімкнення. | `/acp install` | +| Команда | Що вона робить | Приклад | +| -------------------- | -------------------------------------------------------- | ------------------------------------------------------------- | +| `/acp spawn` | Створює сеанс ACP; необов’язкова поточна прив’язка або прив’язка до треду. | `/acp spawn codex --bind here --cwd /repo` | +| `/acp cancel` | Скасовує хід, що виконується, для цільового сеансу. | `/acp cancel agent:codex:acp:` | +| `/acp steer` | Надсилає інструкцію steer до запущеного сеансу. | `/acp steer --session support inbox prioritize failing tests` | +| `/acp close` | Закриває сеанс і відв’язує цілі тредів. | `/acp close` | +| `/acp status` | Показує бекенд, mode, state, параметри середовища виконання та можливості. | `/acp status` | +| `/acp set-mode` | Встановлює mode середовища виконання для цільового сеансу. | `/acp set-mode plan` | +| `/acp set` | Загальний запис параметра конфігурації середовища виконання. | `/acp set model openai/gpt-5.4` | +| `/acp cwd` | Встановлює перевизначення робочого каталогу середовища виконання. | `/acp cwd /Users/user/Projects/repo` | +| `/acp permissions` | Встановлює профіль політики погодження. | `/acp permissions strict` | +| `/acp timeout` | Встановлює тайм-аут середовища виконання (у секундах). | `/acp timeout 120` | +| `/acp model` | Встановлює перевизначення model середовища виконання. | `/acp model anthropic/claude-opus-4-6` | +| `/acp reset-options` | Видаляє перевизначення параметрів середовища виконання для сеансу. | `/acp reset-options` | +| `/acp sessions` | Показує список нещодавніх сеансів ACP зі сховища. | `/acp sessions` | +| `/acp doctor` | Стан бекенду, можливості, практичні виправлення. | `/acp doctor` | +| `/acp install` | Виводить детерміновані кроки встановлення та ввімкнення. | `/acp install` | -`/acp status` показує ефективні параметри runtime, а також ідентифікатори сеансу на рівні runtime і backend. Помилки непідтримуваних елементів керування відображаються чітко, якщо backend не має відповідної можливості. `/acp sessions` читає сховище для поточного прив’язаного сеансу або сеансу запитувача; цільові токени (`session-key`, `session-id` або `session-label`) визначаються через виявлення сеансів gateway, включно з користувацькими коренями `session.store` для окремих агентів. +`/acp status` показує фактичні параметри середовища виконання, а також ідентифікатори сеансу на рівні середовища виконання та бекенду. Помилки unsupported-control чітко відображаються, якщо бекенд не має певної можливості. `/acp sessions` читає сховище для поточного прив’язаного сеансу або сеансу-запитувача; цільові токени (`session-key`, `session-id` або `session-label`) визначаються через виявлення сеансів gateway, включно з користувацькими коренями `session.store` для кожного агента. -## Відображення параметрів runtime +## Відповідність параметрів середовища виконання `/acp` має зручні команди та загальний setter. Еквівалентні операції: -- `/acp model ` відображається на ключ конфігурації runtime `model`. -- `/acp permissions ` відображається на ключ конфігурації runtime `approval_policy`. -- `/acp timeout ` відображається на ключ конфігурації runtime `timeout`. -- `/acp cwd ` напряму оновлює перевизначення cwd runtime. +- `/acp model ` відповідає ключу конфігурації середовища виконання `model`. +- `/acp permissions ` відповідає ключу конфігурації середовища виконання `approval_policy`. +- `/acp timeout ` відповідає ключу конфігурації середовища виконання `timeout`. +- `/acp cwd ` безпосередньо оновлює перевизначення cwd середовища виконання. - `/acp set ` — це загальний шлях. - - Спеціальний випадок: `key=cwd` використовує шлях перевизначення cwd. -- `/acp reset-options` очищає всі перевизначення runtime для цільового сеансу. + - Особливий випадок: `key=cwd` використовує шлях перевизначення cwd. +- `/acp reset-options` очищає всі перевизначення середовища виконання для цільового сеансу. -## acpx harness, налаштування Plugin, і permissions +## Налаштування harness acpx, Plugin і дозволів -Щоб налаштувати acpx harness (аліаси Claude Code / Codex / Gemini CLI), -мости MCP plugin-tools і OpenClaw-tools, а також режими permissions ACP, див. +Щодо конфігурації harness acpx (псевдоніми Claude Code / Codex / Gemini CLI), мостів MCP plugin-tools і OpenClaw-tools, а також режимів дозволів ACP див. [Агенти ACP — налаштування](/uk/tools/acp-agents-setup). ## Усунення несправностей -| Симптом | Імовірна причина | Виправлення | -| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ACP runtime backend is not configured` | Backend Plugin відсутній або вимкнений. | Установіть і ввімкніть Plugin backend, потім виконайте `/acp doctor`. | -| `ACP is disabled by policy (acp.enabled=false)` | ACP глобально вимкнено. | Встановіть `acp.enabled=true`. | -| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Диспетчеризацію зі звичайних повідомлень thread вимкнено. | Встановіть `acp.dispatch.enabled=true`. | -| `ACP agent "" is not allowed by policy` | Агент відсутній у списку дозволених. | Використовуйте дозволений `agentId` або оновіть `acp.allowedAgents`. | -| `Unable to resolve session target: ...` | Неправильний токен key/id/label. | Виконайте `/acp sessions`, скопіюйте точний key/label і повторіть спробу. | -| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, яку можна прив’язати. | Перейдіть у цільовий чат/канал і повторіть спробу або використайте запуск без прив’язки. | -| `Conversation bindings are unavailable for .` | Адаптер не підтримує можливість ACP-прив’язки до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте верхньорівневі `bindings[]` або перейдіть до підтримуваного каналу. | -| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом thread. | Перейдіть у цільовий thread або використайте `--thread auto`/`off`. | -| `Only can rebind this channel/conversation/thread.` | Інший користувач володіє поточною ціллю прив’язки. | Повторно прив’яжіть як власник або використайте іншу розмову чи thread. | -| `Thread bindings are unavailable for .` | Адаптер не підтримує можливість прив’язки до thread. | Використовуйте `--thread off` або перейдіть до підтримуваного адаптера/каналу. | -| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP runtime працює на боці хоста; сеанс запитувача виконується в sandbox. | Використовуйте `runtime="subagent"` із сеансів у sandbox або запускайте ACP із сеансу поза sandbox. | -| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для runtime ACP запитано `sandbox="require"`. | Використовуйте `runtime="subagent"` для обов’язкового sandbox або використовуйте ACP із `sandbox="inherit"` із сеансу поза sandbox. | -| Missing ACP metadata for bound session | Застарілі/видалені метадані сеансу ACP. | Створіть заново через `/acp spawn`, потім повторно прив’яжіть/focus thread. | -| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокує запис/виконання в неінтерактивному сеансі ACP. | Встановіть `plugins.entries.acpx.config.permissionMode` у `approve-all` і перезапустіть gateway. Див. [Налаштування permissions](/uk/tools/acp-agents-setup#permission-configuration). | -| ACP session fails early with little output | Запити permissions блокуються через `permissionMode`/`nonInteractivePermissions`. | Перевірте журнали gateway на `AcpRuntimeError`. Для повних permissions встановіть `permissionMode=approve-all`; для плавної деградації встановіть `nonInteractivePermissions=deny`. | -| ACP session stalls indefinitely after completing work | Процес harness завершився, але сеанс ACP не повідомив про завершення. | Відстежуйте через `ps aux \| grep acpx`; вручну завершіть застарілі процеси. | +| Симптом | Імовірна причина | Виправлення | +| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ACP runtime backend is not configured` | Бекенд Plugin відсутній або вимкнений. | Установіть і ввімкніть бекенд Plugin, а потім запустіть `/acp doctor`. | +| `ACP is disabled by policy (acp.enabled=false)` | ACP глобально вимкнено. | Установіть `acp.enabled=true`. | +| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Диспетчеризацію зі звичайних повідомлень треду вимкнено. | Установіть `acp.dispatch.enabled=true`. | +| `ACP agent "" is not allowed by policy` | Агент відсутній у списку дозволених. | Використовуйте дозволений `agentId` або оновіть `acp.allowedAgents`. | +| `Unable to resolve session target: ...` | Неправильний токен key/id/label. | Виконайте `/acp sessions`, скопіюйте точний key/label і повторіть. | +| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, яку можна прив’язати. | Перейдіть у цільовий чат/канал і повторіть або використайте запуск без прив’язки. | +| `Conversation bindings are unavailable for .` | Адаптер не має можливості прив’язки ACP до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, якщо підтримується, налаштуйте `bindings[]` верхнього рівня або перейдіть у підтримуваний канал. | +| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом треду. | Перейдіть у цільовий тред або використайте `--thread auto`/`off`. | +| `Only can rebind this channel/conversation/thread.` | Активна ціль прив’язки належить іншому користувачеві. | Переприв’яжіть як власник або використайте іншу розмову чи тред. | +| `Thread bindings are unavailable for .` | Адаптер не має можливості прив’язки до тредів. | Використовуйте `--thread off` або перейдіть до підтримуваного адаптера/каналу. | +| `Sandboxed sessions cannot spawn ACP sessions ...` | Середовище виконання ACP працює на боці хоста; сеанс-запитувач працює в sandbox. | Використовуйте `runtime="subagent"` із сеансів у sandbox або запускайте ACP із сеансу поза sandbox. | +| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для середовища виконання ACP запитано `sandbox="require"`. | Використовуйте `runtime="subagent"` для обов’язкового sandbox або використовуйте ACP із `sandbox="inherit"` із сеансу поза sandbox. | +| Missing ACP metadata for bound session | Застарілі/видалені метадані сеансу ACP. | Створіть заново за допомогою `/acp spawn`, а потім повторно прив’яжіть/сфокусуйте тред. | +| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокує запис/виконання в неінтерактивному сеансі ACP. | Установіть `plugins.entries.acpx.config.permissionMode` у `approve-all` і перезапустіть gateway. Див. [Конфігурація дозволів](/uk/tools/acp-agents-setup#permission-configuration). | +| ACP session fails early with little output | Підказки щодо дозволів блокуються через `permissionMode`/`nonInteractivePermissions`. | Перевірте журнали gateway на `AcpRuntimeError`. Для повних дозволів установіть `permissionMode=approve-all`; для плавної деградації встановіть `nonInteractivePermissions=deny`. | +| ACP session stalls indefinitely after completing work | Процес harness завершився, але сеанс ACP не повідомив про завершення. | Відстежуйте через `ps aux \| grep acpx`; вручну завершіть застарілі процеси. | -## Пов’язані сторінки +## Пов’язане -- [Sub-agents](/uk/tools/subagents) -- [Multi-agent sandbox tools](/uk/tools/multi-agent-sandbox-tools) -- [Agent send](/uk/tools/agent-send) +- [Субагенти](/uk/tools/subagents) +- [Інструменти sandbox для багатьох агентів](/uk/tools/multi-agent-sandbox-tools) +- [Надсилання агенту](/uk/tools/agent-send) diff --git a/docs/uk/tools/plugin.md b/docs/uk/tools/plugin.md index d661d1a3b..3c3350bf1 100644 --- a/docs/uk/tools/plugin.md +++ b/docs/uk/tools/plugin.md @@ -1,58 +1,58 @@ --- read_when: - - Установлення або налаштування plugins - - Розуміння правил виявлення та завантаження pluginів - - Робота з сумісними з Codex/Claude пакунками pluginів + - Установлення або налаштування Plugin + - Розуміння правил виявлення та завантаження Plugin + - Робота з сумісними з Codex/Claude наборами Plugin sidebarTitle: Install and Configure -summary: Установлення, налаштування та керування plugins OpenClaw -title: Plugins +summary: Установлення, налаштування та керування Plugin OpenClaw +title: Plugin x-i18n: - generated_at: "2026-04-25T02:42:03Z" + generated_at: "2026-04-25T03:44:40Z" model: gpt-5.4 provider: openai - source_hash: 4e41595020c5f1702e3288eb07c88482cb820b78b33ea27154af788e8da80fa1 + source_hash: ec77f80d0f68dbb4d0ce7b53bdbce642bce933afe3f20bc1eb99eb1301f2461a source_path: tools/plugin.md workflow: 15 --- -Plugins розширюють OpenClaw новими можливостями: канали, провайдери моделей, -agent harnesses, інструменти, Skills, мовлення, транскрибування в реальному часі, голос у реальному -часі, розуміння медіа, генерація зображень, генерація відео, отримання даних із вебу, вебпошук -тощо. Деякі plugins є **core** (постачаються з OpenClaw), інші — -**external** (публікуються спільнотою в npm). +Plugin розширюють OpenClaw новими можливостями: канали, провайдери моделей, +обв’язки агентів, інструменти, Skills, мовлення, транскрипція в реальному часі, голос у реальному часі, +розуміння медіа, генерація зображень, генерація відео, отримання вебданих, вебпошук тощо. +Деякі Plugin є **core** (постачаються з OpenClaw), інші — +**external** (опубліковані спільнотою в npm). ## Швидкий старт - + ```bash openclaw plugins list ``` - + ```bash # З npm openclaw plugins install @openclaw/voice-call - # Із локального каталогу або архіву + # З локального каталогу або архіву openclaw plugins install ./my-plugin openclaw plugins install ./my-plugin.tgz ``` - + ```bash openclaw gateway restart ``` - Потім налаштуйте в `plugins.entries.\.config` у вашому файлі config. + Потім налаштуйте в `plugins.entries.\.config` у вашому файлі конфігурації. -Якщо ви надаєте перевагу керуванню безпосередньо в чаті, увімкніть `commands.plugins: true` і використовуйте: +Якщо ви віддаєте перевагу керуванню безпосередньо в чаті, увімкніть `commands.plugins: true` і використовуйте: ```text /plugin install clawhub:@openclaw/voice-call @@ -60,56 +60,56 @@ agent harnesses, інструменти, Skills, мовлення, транск /plugin enable voice-call ``` -Шлях установлення використовує той самий resolver, що й CLI: локальний -шлях/архів, явний `clawhub:` або звичайну специфікацію пакета (спочатку -ClawHub, потім резервний перехід до npm). +Шлях установлення використовує той самий механізм визначення, що й CLI: локальний +шлях/архів, явний `clawhub:` або специфікація пакета без префікса +(спочатку ClawHub, потім резервний перехід до npm). -Якщо config невалідний, установлення зазвичай безпечно завершується відмовою і -вказує вам на `openclaw doctor --fix`. Єдиний виняток для відновлення — це вузький шлях -повторного встановлення вбудованого plugin для plugins, які підтримують +Якщо конфігурація недійсна, установлення зазвичай безпечно завершується відмовою і вказує на +`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях повторного встановлення +вбудованого Plugin для Plugin, які підтримують `openclaw.install.allowInvalidConfigRecovery`. -Пакетні встановлення OpenClaw не встановлюють завчасно дерево runtime-залежностей -кожного вбудованого plugin. Коли вбудований plugin OpenClaw активний через -config plugin, застарілий config каналу або маніфест із увімкненням за замовчуванням, -startup відновлює лише оголошені runtime-залежності цього plugin перед його імпортом. +Паковані інсталяції OpenClaw не встановлюють завчасно все дерево залежностей часу виконання +для кожного вбудованого Plugin. Коли вбудований Plugin, що належить OpenClaw, є активним через +конфігурацію Plugin, застарілу конфігурацію каналу або маніфест, увімкнений типово, +під час запуску відновлюються лише оголошені залежності часу виконання цього Plugin перед його імпортом. Явне вимкнення все одно має пріоритет: `plugins.entries..enabled: false`, `plugins.deny`, `plugins.enabled: false` і `channels..enabled: false` -запобігають автоматичному відновленню runtime-залежностей вбудованого plugin/каналу. -External plugins і власні шляхи завантаження, як і раніше, потрібно встановлювати через +запобігають автоматичному відновленню вбудованих залежностей часу виконання для цього Plugin/каналу. +External Plugin і користувацькі шляхи завантаження, як і раніше, потрібно встановлювати через `openclaw plugins install`. -## Типи pluginів +## Типи Plugin -OpenClaw розпізнає два формати pluginів: +OpenClaw розпізнає два формати Plugin: | Формат | Як це працює | Приклади | | ---------- | --------------------------------------------------------------- | ------------------------------------------------------ | -| **Native** | `openclaw.plugin.json` + runtime-модуль; виконується в тому самому процесі | Офіційні plugins, пакети npm від спільноти | -| **Bundle** | Сумісне з Codex/Claude/Cursor компонування; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | +| **Native** | `openclaw.plugin.json` + модуль часу виконання; виконується в межах процесу | Офіційні Plugin, пакети npm від спільноти | +| **Bundle** | Сумісний із Codex/Claude/Cursor макет; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` | -Обидва відображаються в `openclaw plugins list`. Докладніше про bundle див. у [Plugin Bundles](/uk/plugins/bundles). +Обидва відображаються в `openclaw plugins list`. Докладніше про набори див. у [Plugin Bundles](/uk/plugins/bundles). -Якщо ви пишете native plugin, почніть із [Building Plugins](/uk/plugins/building-plugins) +Якщо ви пишете native Plugin, почніть із [Building Plugins](/uk/plugins/building-plugins) та [Plugin SDK Overview](/uk/plugins/sdk-overview). -## Офіційні plugins +## Офіційні Plugin ### Доступні для встановлення (npm) -| Plugin | Пакет | Документація | -| --------------- | --------------------- | ----------------------------------- | -| Matrix | `@openclaw/matrix` | [Matrix](/uk/channels/matrix) | -| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/uk/channels/msteams) | -| Nostr | `@openclaw/nostr` | [Nostr](/uk/channels/nostr) | -| Voice Call | `@openclaw/voice-call` | [Voice Call](/uk/plugins/voice-call) | -| Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) | -| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) | +| Plugin | Пакет | Документація | +| --------------- | ---------------------- | ------------------------------------- | +| Matrix | `@openclaw/matrix` | [Matrix](/uk/channels/matrix) | +| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/uk/channels/msteams) | +| Nostr | `@openclaw/nostr` | [Nostr](/uk/channels/nostr) | +| Voice Call | `@openclaw/voice-call` | [Voice Call](/uk/plugins/voice-call) | +| Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) | +| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) | ### Core (постачаються з OpenClaw) - + `anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`, `huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`, `moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`, @@ -117,24 +117,24 @@ OpenClaw розпізнає два формати pluginів: `vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai` - + - `memory-core` — вбудований пошук у пам’яті (типово через `plugins.slots.memory`) - `memory-lancedb` — довготривала пам’ять з установленням на вимогу з автоматичним пригадуванням/захопленням (установіть `plugins.slots.memory = "memory-lancedb"`) - + `elevenlabs`, `microsoft` - - `browser` — вбудований browser plugin для інструмента browser, CLI `openclaw browser`, gateway-методу `browser.request`, runtime browser і служби керування browser за замовчуванням (увімкнено за замовчуванням; вимкніть перед заміною) - - `copilot-proxy` — міст VS Code Copilot Proxy (типово вимкнено) + - `browser` — вбудований Plugin браузера для інструмента браузера, CLI `openclaw browser`, методу gateway `browser.request`, середовища виконання браузера та типового сервісу керування браузером (увімкнено типово; вимкніть перед його заміною) + - `copilot-proxy` — міст VS Code Copilot Proxy (типово вимкнений) -Шукаєте сторонні plugins? Див. [Community Plugins](/uk/plugins/community). +Шукаєте сторонні Plugin? Див. [Community Plugins](/uk/plugins/community). -## Config +## Конфігурація ```json5 { @@ -153,139 +153,138 @@ OpenClaw розпізнає два формати pluginів: | Поле | Опис | | ---------------- | --------------------------------------------------------- | | `enabled` | Головний перемикач (типово: `true`) | -| `allow` | Список дозволених pluginів (необов’язково) | -| `deny` | Список заборонених pluginів (необов’язково; заборона має пріоритет) | -| `load.paths` | Додаткові файли/каталоги pluginів | +| `allow` | Список дозволених Plugin (необов’язково) | +| `deny` | Список заборонених Plugin (необов’язково; `deny` має пріоритет) | +| `load.paths` | Додаткові файли/каталоги Plugin | | `slots` | Селектори ексклюзивних слотів (наприклад, `memory`, `contextEngine`) | -| `entries.\` | Перемикачі та config для кожного plugin окремо | +| `entries.\` | Перемикачі та конфігурація для окремого Plugin | -Зміни config **потребують перезапуску gateway**. Якщо Gateway працює з -відстеженням config + увімкненим перезапуском у межах процесу (типовий шлях `openclaw gateway`), -цей перезапуск зазвичай виконується автоматично невдовзі після запису config. -Підтримуваного шляху гарячого перезавантаження для native runtime-коду plugin або lifecycle -hooks немає; перезапустіть процес Gateway, який обслуговує активний канал, перш ніж -очікувати, що оновлений код `register(api)`, hooks `api.on(...)`, інструменти, служби або -hooks провайдера/runtime почнуть виконуватися. +Зміни конфігурації **потребують перезапуску Gateway**. Якщо Gateway запущено з +відстеженням конфігурації та ввімкненим перезапуском у межах процесу +(типовий шлях `openclaw gateway`), цей перезапуск зазвичай виконується +автоматично невдовзі після застосування змін конфігурації. +Підтримуваного шляху гарячого перезавантаження для native коду часу виконання Plugin або хуків +життєвого циклу немає; перезапустіть процес Gateway, який обслуговує активний канал, +перш ніж очікувати, що оновлений код `register(api)`, хуки `api.on(...)`, інструменти, сервіси або +хуки провайдера/часу виконання почнуть працювати. -`openclaw plugins list` — це локальний знімок CLI/config. Стан `loaded` -для plugin там означає, що plugin можна виявити й завантажити з config/файлів, які бачить +`openclaw plugins list` — це локальний знімок CLI/конфігурації. Plugin зі станом `loaded` +там означає, що Plugin можна виявити та завантажити з конфігурації/файлів, які бачить цей виклик CLI. Це не доводить, що вже запущений віддалений дочірній процес Gateway -перезапустився з тим самим кодом plugin. У середовищах VPS/контейнерів з процесами-обгортками -надсилайте перезапуск фактичному процесу `openclaw gateway run` або використовуйте +перезапустився з тим самим кодом Plugin. У середовищах VPS/контейнерів з процесами-обгортками +надсилайте перезапуски до фактичного процесу `openclaw gateway run`, або використовуйте `openclaw gateway restart` для запущеного Gateway. - - - **Disabled**: plugin існує, але правила ввімкнення його вимкнули. Config зберігається. - - **Missing**: config посилається на id plugin, якого не знайдено під час виявлення. - - **Invalid**: plugin існує, але його config не відповідає оголошеній schema. + + - **Вимкнений**: Plugin існує, але правила ввімкнення його вимкнули. Конфігурація зберігається. + - **Відсутній**: конфігурація посилається на ідентифікатор Plugin, який не знайдено під час виявлення. + - **Недійсний**: Plugin існує, але його конфігурація не відповідає оголошеній схемі. ## Виявлення та пріоритет -OpenClaw сканує plugins у такому порядку (перше знайдене співпадіння перемагає): +OpenClaw сканує Plugin у такому порядку (перше знайдене збігання має пріоритет): - + `plugins.load.paths` — явні шляхи до файлів або каталогів. - + `\/.openclaw//*.ts` і `\/.openclaw//*/index.ts`. - + `~/.openclaw//*.ts` і `~/.openclaw//*/index.ts`. - - Постачаються з OpenClaw. Багато з них увімкнені за замовчуванням (провайдери моделей, мовлення). + + Постачаються з OpenClaw. Багато з них увімкнені типово (провайдери моделей, мовлення). Інші потребують явного ввімкнення. ### Правила ввімкнення -- `plugins.enabled: false` вимикає всі plugins +- `plugins.enabled: false` вимикає всі Plugin - `plugins.deny` завжди має пріоритет над allow -- `plugins.entries.\.enabled: false` вимикає цей plugin -- Plugins із джерелом у робочій області **типово вимкнені** (їх треба явно ввімкнути) -- Вбудовані plugins дотримуються вбудованого набору з увімкненням за замовчуванням, якщо не перевизначено -- Ексклюзивні слоти можуть примусово вмикати plugin, вибраний для цього слота -- Деякі вбудовані opt-in plugins вмикаються автоматично, коли config називає - поверхню, якою володіє plugin, наприклад ref моделі провайдера, config каналу або - runtime harness -- Маршрути Codex сімейства OpenAI зберігають окремі межі pluginів: - `openai-codex/*` належить plugin OpenAI, тоді як вбудований plugin - сервера застосунку Codex вибирається через `embeddedHarness.runtime: "codex"` або застарілі - ref моделей `codex/*` +- `plugins.entries.\.enabled: false` вимикає цей Plugin +- Plugin із робочої області **типово вимкнені** (їх треба явно ввімкнути) +- Вбудовані Plugin дотримуються вбудованого набору типово ввімкнених, якщо це не перевизначено +- Ексклюзивні слоти можуть примусово ввімкнути вибраний Plugin для цього слота +- Деякі вбудовані Plugin з добровільним увімкненням активуються автоматично, коли конфігурація вказує поверхню, що належить Plugin, наприклад посилання на модель провайдера, конфігурацію каналу або середовище виконання harness +- Маршрути Codex сімейства OpenAI зберігають окремі межі Plugin: + `openai-codex/*` належить Plugin OpenAI, тоді як вбудований Plugin сервера застосунку Codex + вибирається через `embeddedHarness.runtime: "codex"` або застарілі + посилання на моделі `codex/*` -## Усунення проблем із runtime hooks +## Усунення проблем із хуками часу виконання -Якщо plugin з’являється в `plugins list`, але побічні ефекти `register(api)` або hooks -не виконуються в трафіку активного чату, спершу перевірте таке: +Якщо Plugin з’являється в `plugins list`, але побічні ефекти `register(api)` або хуки +не працюють у трафіку живого чату, спочатку перевірте таке: -- Виконайте `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні - URL Gateway, профіль, шлях config і процес — це саме ті, які ви редагуєте. -- Перезапустіть активний Gateway після встановлення plugin, змін config або коду. У контейнерах +- Запустіть `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні + URL Gateway, профіль, шлях до конфігурації та процес — саме ті, які ви редагуєте. +- Перезапустіть активний Gateway після змін установлення/конфігурації/коду Plugin. У контейнерах з обгортками PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому процесу `openclaw gateway run`. -- Використовуйте `openclaw plugins inspect --json`, щоб підтвердити реєстрації hooks і - діагностику. Невбудовані hooks розмов, як-от `llm_input`, - `llm_output` і `agent_end`, потребують +- Використовуйте `openclaw plugins inspect --json`, щоб підтвердити реєстрації хуків і + діагностику. Для невбудованих хуків розмови, таких як `llm_input`, + `llm_output` і `agent_end`, потрібен `plugins.entries..hooks.allowConversationAccess=true`. -- Для перемикання моделей надавайте перевагу `before_model_resolve`. Він виконується до - визначення моделі для ходів агента; `llm_output` запускається лише після того, - як спроба моделі створить вихід assistant. -- Щоб підтвердити ефективну модель сесії, використовуйте `openclaw sessions` або - поверхні сесії/статусу Gateway, а під час налагодження payload провайдера запускайте - Gateway з `--raw-stream --raw-stream-path `. +- Для перемикання моделі надавайте перевагу `before_model_resolve`. Він виконується перед + визначенням моделі для ходів агента; `llm_output` виконується лише після того, як спроба моделі + згенерує вихід асистента. +- Щоб підтвердити фактичну модель сесії, використовуйте `openclaw sessions` або + поверхні сесії/стану Gateway, а під час налагодження корисних навантажень провайдера + запускайте Gateway з `--raw-stream --raw-stream-path `. -## Слоти pluginів (ексклюзивні категорії) +## Слоти Plugin (ексклюзивні категорії) -Деякі категорії є ексклюзивними (одночасно активний лише один plugin): +Деякі категорії є ексклюзивними (одночасно активною може бути лише одна): ```json5 { plugins: { slots: { memory: "memory-core", // або "none", щоб вимкнути - contextEngine: "legacy", // або id plugin + contextEngine: "legacy", // або id Plugin }, }, } ``` -| Слот | Що він контролює | Типове значення | -| --------------- | ----------------------- | ------------------- | -| `memory` | Active Memory plugin | `memory-core` | +| Слот | Що він контролює | Типове значення | +| --------------- | ------------------------ | ------------------- | +| `memory` | Active Memory Plugin | `memory-core` | | `contextEngine` | Активний рушій контексту | `legacy` (вбудований) | ## Довідка CLI ```bash openclaw plugins list # компактний перелік -openclaw plugins list --enabled # лише завантажені plugins -openclaw plugins list --verbose # докладні рядки для кожного plugin +openclaw plugins list --enabled # лише завантажені Plugin +openclaw plugins list --verbose # докладні рядки для кожного Plugin openclaw plugins list --json # машиночитаний перелік -openclaw plugins inspect # глибока деталізація -openclaw plugins inspect --json # машиночитаний формат +openclaw plugins inspect # докладна інформація +openclaw plugins inspect --json # машиночитано openclaw plugins inspect --all # таблиця для всього набору openclaw plugins info # псевдонім inspect openclaw plugins doctor # діагностика -openclaw plugins install # установити (спочатку ClawHub, потім npm) -openclaw plugins install clawhub: # установити лише з ClawHub +openclaw plugins install # встановлення (спочатку ClawHub, потім npm) +openclaw plugins install clawhub: # встановлення лише з ClawHub openclaw plugins install --force # перезаписати наявне встановлення -openclaw plugins install # установити з локального шляху -openclaw plugins install -l # зв’язати (без копіювання) для розробки +openclaw plugins install # встановлення з локального шляху +openclaw plugins install -l # створити посилання (без копіювання) для розробки openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// -openclaw plugins install --pin # записати точну розв’язану специфікацію npm +openclaw plugins install --pin # записати точну визначену специфікацію npm openclaw plugins install --dangerously-force-unsafe-install -openclaw plugins update # оновити один plugin +openclaw plugins update # оновити один Plugin openclaw plugins update --dangerously-force-unsafe-install openclaw plugins update --all # оновити всі -openclaw plugins uninstall # видалити записи config/встановлення +openclaw plugins uninstall # видалити записи конфігурації/встановлення openclaw plugins uninstall --keep-files openclaw plugins marketplace list openclaw plugins marketplace list --json @@ -294,61 +293,60 @@ openclaw plugins enable openclaw plugins disable ``` -Вбудовані plugins постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад, -вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований browser -plugin). Інші вбудовані plugins усе ще потребують `openclaw plugins enable `. +Вбудовані Plugin постачаються разом з OpenClaw. Багато з них увімкнені типово (наприклад, +вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований Plugin +браузера). Інші вбудовані Plugin, як і раніше, потребують `openclaw plugins enable `. -`--force` перезаписує наявний встановлений plugin або пакет hook-ів на місці. Для звичайних оновлень -відстежуваних npm-plugins використовуйте `openclaw plugins update `. -Це не підтримується з `--link`, який повторно використовує шлях до джерела замість -копіювання в керовану ціль встановлення. +`--force` перезаписує наявний встановлений Plugin або набір хуків на місці. Використовуйте +`openclaw plugins update ` для звичайних оновлень відстежуваних npm +Plugin. Це не підтримується з `--link`, який повторно використовує вихідний шлях замість +копіювання до керованого цільового шляху встановлення. -Коли `plugins.allow` уже задано, `openclaw plugins install` додає id -встановленого plugin до цього allowlist перед його ввімкненням, тож установлені plugins -можна завантажувати одразу після перезапуску. +Коли `plugins.allow` уже задано, `openclaw plugins install` додає +ідентифікатор встановленого Plugin до цього списку дозволених перед його ввімкненням, тож встановлені Plugin +можна одразу завантажити після перезапуску. `openclaw plugins update ` застосовується до відстежуваних встановлень. Передавання -специфікації npm-пакета з dist-tag або точною версією розв’язує ім’я пакета -назад до відстежуваного запису plugin і записує нову специфікацію для майбутніх оновлень. -Передавання імені пакета без версії переводить точно закріплене встановлення назад на -типову лінію випуску реєстру. Якщо встановлений npm plugin уже відповідає -розв’язаній версії та записаній ідентичності артефакту, OpenClaw пропускає оновлення -без завантаження, повторного встановлення чи перезапису config. +специфікації npm-пакета з dist-tag або точною версією зіставляє назву пакета +назад із записом відстежуваного Plugin і записує нову специфікацію для майбутніх оновлень. +Передавання назви пакета без версії переводить точно закріплене встановлення назад на +типову лінійку випусків реєстру. Якщо встановлений npm Plugin уже відповідає +визначеній версії та записаній тотожності артефакту, OpenClaw пропускає оновлення +без завантаження, перевстановлення чи перезапису конфігурації. `--pin` працює лише для npm. Він не підтримується з `--marketplace`, оскільки -встановлення з marketplace зберігають метадані джерела marketplace, а не специфікацію npm. +встановлення з marketplace зберігають метадані джерела marketplace замість специфікації npm. -`--dangerously-force-unsafe-install` — це аварійний override для хибнопозитивних -спрацьовувань вбудованого сканера небезпечного коду. Він дозволяє продовжити встановлення -та оновлення pluginів попри вбудовані findings рівня `critical`, але все одно -не обходить блокування політики plugin `before_install` або блокування через помилки сканування. +`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибнопозитивних +спрацювань вбудованого сканера небезпечного коду. Воно дозволяє продовжити встановлення +та оновлення Plugin попри вбудовані критичні висновки `critical`, але +все одно не обходить блокування політики Plugin `before_install` або блокування через збій сканування. -Цей прапорець CLI застосовується лише до потоків встановлення/оновлення pluginів. Установлення -залежностей Skills через Gateway натомість використовують відповідний override запиту +Цей прапорець CLI застосовується лише до потоків встановлення/оновлення Plugin. Установлення +залежностей Skills через Gateway натомість використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills із ClawHub. -Сумісні bundle беруть участь у тих самих потоках list/inspect/enable/disable -pluginів. Поточна підтримка runtime включає bundle Skills, Claude command-skills, -типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і -оголошені в маніфесті `lspServers`, Cursor command-skills і сумісні каталоги -hook-ів Codex. +Сумісні набори беруть участь у тому самому потоці list/inspect/enable/disable для Plugin. +Поточна підтримка часу виконання включає Skills із наборів, command-skills Claude, +типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і оголошені в маніфесті +`lspServers`, command-skills Cursor і сумісні каталоги хуків Codex. -`openclaw plugins inspect ` також повідомляє про виявлені можливості bundle, а також -підтримувані або непідтримувані записи MCP і LSP server для plugins на основі bundle. +`openclaw plugins inspect ` також повідомляє про виявлені можливості набору, а також +підтримувані або непідтримувані записи серверів MCP і LSP для Plugin, що працюють на основі наборів. Джерелами marketplace можуть бути відома назва marketplace Claude з `~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або шлях до `marketplace.json`, скорочений запис GitHub на кшталт `owner/repo`, URL репозиторію GitHub -або git URL. Для віддалених marketplace записи pluginів мають залишатися всередині -клонованого репозиторію marketplace і використовувати лише відносні джерела шляхів. +або URL git. Для віддалених marketplace записи Plugin мають залишатися всередині +клонованого репозиторію marketplace і використовувати лише відносні шляхи джерел. Повні відомості див. у [довідці CLI `openclaw plugins`](/uk/cli/plugins). -## Огляд API pluginів +## Огляд API Plugin -Native plugins експортують об’єкт точки входу, який надає `register(api)`. Старіші -plugins усе ще можуть використовувати `activate(api)` як застарілий псевдонім, але нові plugins мають +Native Plugin експортують вхідний об’єкт, який надає `register(api)`. Старіші +Plugin усе ще можуть використовувати `activate(api)` як застарілий псевдонім, але нові Plugin мають використовувати `register`. ```typescript @@ -369,73 +367,75 @@ export default definePluginEntry({ }); ``` -OpenClaw завантажує об’єкт точки входу й викликає `register(api)` під час -активації plugin. Завантажувач усе ще переходить до `activate(api)` для старіших pluginів, -але вбудовані plugins і нові external plugins мають розглядати `register` як +OpenClaw завантажує вхідний об’єкт і викликає `register(api)` під час +активації Plugin. Завантажувач усе ще повертається до `activate(api)` для старіших Plugin, +але вбудовані Plugin і нові external Plugin повинні розглядати `register` як публічний контракт. -`api.registrationMode` повідомляє plugin, чому завантажується його точка входу: +`api.registrationMode` повідомляє Plugin, чому завантажується його вхідний об’єкт: | Режим | Значення | -| --------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `full` | Активація runtime. Реєструє інструменти, hooks, служби, команди, маршрути та інші побічні ефекти в активному середовищі. | -| `discovery` | Виявлення можливостей лише для читання. Реєструє провайдерів і метадані; код точки входу довіреного plugin може завантажуватися, але без побічних ефектів активного середовища. | -| `setup-only` | Завантаження метаданих setup каналу через полегшену точку входу setup. | -| `setup-runtime` | Завантаження setup каналу, якому також потрібна точка входу runtime. | +| --------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `full` | Активація часу виконання. Реєструє інструменти, хуки, сервіси, команди, маршрути та інші побічні ефекти живої роботи. | +| `discovery` | Виявлення можливостей лише для читання. Реєструє провайдери та метадані; код входу довіреного Plugin може завантажуватися, але побічні ефекти живої роботи слід пропускати. | +| `setup-only` | Завантаження метаданих налаштування каналу через спрощений запис налаштування. | +| `setup-runtime` | Завантаження налаштування каналу, яке також потребує запису часу виконання. | | `cli-metadata` | Лише збирання метаданих команд CLI. | -Точки входу pluginів, які відкривають сокети, бази даних, фонові worker-и або довготривалі -clients, мають захищати ці побічні ефекти через `api.registrationMode === "full"`. -Завантаження discovery кешуються окремо від активувальних завантажень і не замінюють -реєстр запущеного Gateway. Discovery не активує, але й не є вільним від імпорту: -OpenClaw може обчислювати довірену точку входу plugin або модуль plugin каналу, щоб побудувати -знімок. Тримайте верхні рівні модулів легкими й без побічних ефектів, а мережевих -clients, subprocesses, listeners, читання облікових даних і запуск служб -переносьте за шляхи повного runtime. +Входи Plugin, які відкривають сокети, бази даних, фонові працівники або довгоживучі +клієнти, повинні захищати ці побічні ефекти перевіркою `api.registrationMode === "full"`. +Завантаження для виявлення кешуються окремо від активаційних завантажень і не замінюють +реєстр запущеного Gateway. Виявлення не активує, але й не обходиться без імпорту: +OpenClaw може обчислювати довірений вхід Plugin або модуль Plugin каналу, щоб побудувати +знімок. Зберігайте верхній рівень модулів легким і без побічних ефектів, а мережеві клієнти, +підпроцеси, слухачі, читання облікових даних і запуск сервісів переносіть +за межі шляхів повного часу виконання. Поширені методи реєстрації: -| Метод | Що він реєструє | -| -------------------------------------- | ---------------------------- | -| `registerProvider` | Провайдер моделей (LLM) | -| `registerChannel` | Чат-канал | -| `registerTool` | Інструмент агента | -| `registerHook` / `on(...)` | Hooks життєвого циклу | -| `registerSpeechProvider` | Text-to-speech / STT | +| Метод | Що реєструє | +| --------------------------------------- | --------------------------- | +| `registerProvider` | Провайдер моделі (LLM) | +| `registerChannel` | Канал чату | +| `registerTool` | Інструмент агента | +| `registerHook` / `on(...)` | Хуки життєвого циклу | +| `registerSpeechProvider` | Синтез мовлення / STT | | `registerRealtimeTranscriptionProvider` | Потоковий STT | -| `registerRealtimeVoiceProvider` | Двобічний голос у реальному часі | -| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | -| `registerImageGenerationProvider` | Генерація зображень | -| `registerMusicGenerationProvider` | Генерація музики | -| `registerVideoGenerationProvider` | Генерація відео | -| `registerWebFetchProvider` | Провайдер отримання/скрапінгу вебданих | -| `registerWebSearchProvider` | Вебпошук | -| `registerHttpRoute` | HTTP endpoint | -| `registerCommand` / `registerCli` | Команди CLI | -| `registerContextEngine` | Рушій контексту | -| `registerService` | Фонова служба | +| `registerRealtimeVoiceProvider` | Двобічний голос у реальному часі | +| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо | +| `registerImageGenerationProvider` | Генерація зображень | +| `registerMusicGenerationProvider` | Генерація музики | +| `registerVideoGenerationProvider` | Генерація відео | +| `registerWebFetchProvider` | Провайдер отримання/скрапінгу вебданих | +| `registerWebSearchProvider` | Вебпошук | +| `registerHttpRoute` | HTTP-ендпойнт | +| `registerCommand` / `registerCli` | Команди CLI | +| `registerContextEngine` | Рушій контексту | +| `registerService` | Фоновий сервіс | -Поведінка guard для типізованих hooks життєвого циклу: +Поведінка захисту хуків для типізованих хуків життєвого циклу: -- `before_tool_call`: `{ block: true }` є термінальним; handlers із нижчим пріоритетом пропускаються. -- `before_tool_call`: `{ block: false }` нічого не змінює і не скасовує попередній block. -- `before_install`: `{ block: true }` є термінальним; handlers із нижчим пріоритетом пропускаються. -- `before_install`: `{ block: false }` нічого не змінює і не скасовує попередній block. -- `message_sending`: `{ cancel: true }` є термінальним; handlers із нижчим пріоритетом пропускаються. -- `message_sending`: `{ cancel: false }` нічого не змінює і не скасовує попередній cancel. +- `before_tool_call`: `{ block: true }` є остаточним; обробники з нижчим пріоритетом пропускаються. +- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує раніше встановлене блокування. +- `before_install`: `{ block: true }` є остаточним; обробники з нижчим пріоритетом пропускаються. +- `before_install`: `{ block: false }` нічого не робить і не скасовує раніше встановлене блокування. +- `message_sending`: `{ cancel: true }` є остаточним; обробники з нижчим пріоритетом пропускаються. +- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує раніше встановлене скасування. -Native сервер застосунку Codex повертає bridge-події native-інструментів Codex назад у цю -поверхню hook-ів. Plugins можуть блокувати native-інструменти Codex через `before_tool_call`, -спостерігати за результатами через `after_tool_call` і брати участь у підтвердженнях -Codex `PermissionRequest`. Bridge поки що не переписує аргументи native-інструментів Codex. +Native сервер застосунку Codex повертає події інструментів Codex у цей +поверхневий рівень хуків через міст. Plugin можуть блокувати native інструменти Codex через `before_tool_call`, +спостерігати результати через `after_tool_call` і брати участь у схваленнях +`PermissionRequest` Codex. Міст поки що не переписує аргументи native інструментів Codex. +Точна межа підтримки часу виконання Codex описана в +[контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract). -Повну поведінку типізованих hook-ів див. у [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics). +Докладно про типізовану поведінку хуків див. в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics). ## Пов’язане -- [Building Plugins](/uk/plugins/building-plugins) — створення власного plugin -- [Plugin Bundles](/uk/plugins/bundles) — сумісність bundle з Codex/Claude/Cursor -- [Plugin Manifest](/uk/plugins/manifest) — schema маніфесту -- [Registering Tools](/uk/plugins/building-plugins#registering-agent-tools) — додавання інструментів агента в plugin +- [Building Plugins](/uk/plugins/building-plugins) — створення власного Plugin +- [Plugin Bundles](/uk/plugins/bundles) — сумісність наборів Codex/Claude/Cursor +- [Plugin Manifest](/uk/plugins/manifest) — схема маніфесту +- [Registering Tools](/uk/plugins/building-plugins#registering-agent-tools) — додавання інструментів агента в Plugin - [Plugin Internals](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження - [Community Plugins](/uk/plugins/community) — сторонні переліки diff --git a/docs/uk/tools/tts.md b/docs/uk/tools/tts.md index 1dc49cb46..bfbfd8358 100644 --- a/docs/uk/tools/tts.md +++ b/docs/uk/tools/tts.md @@ -1,15 +1,15 @@ --- read_when: - - Увімкнення Text-to-speech для відповідей - - Налаштування provider TTS або обмежень + - Увімкнення перетворення тексту на мовлення для відповідей + - Налаштування TTS-провайдерів або обмежень - Використання команд `/tts` -summary: Text-to-speech (TTS) для вихідних відповідей -title: Text-to-speech +summary: Перетворення тексту на мовлення (TTS) для вихідних відповідей +title: Перетворення тексту на мовлення x-i18n: - generated_at: "2026-04-24T18:14:03Z" + generated_at: "2026-04-25T03:44:38Z" model: gpt-5.4 provider: openai - source_hash: 4db4e8992b866be5eee309261f45edc7b8628a815cb11c6f2f943a5bfc419e78 + source_hash: 87a52ec119f063d56ffc1182533736ab9595c1f767750886ae20bcf45520cfd0 source_path: tools/tts.md workflow: 15 --- @@ -19,26 +19,26 @@ OpenClaw може перетворювати вихідні відповіді ## Підтримувані сервіси -- **ElevenLabs** (основний або резервний provider) -- **Google Gemini** (основний або резервний provider; використовує Gemini API TTS) -- **Gradium** (основний або резервний provider; підтримує вихід voice-note і telephony) -- **Microsoft** (основний або резервний provider; поточна вбудована реалізація використовує `node-edge-tts`) -- **MiniMax** (основний або резервний provider; використовує API T2A v2) -- **OpenAI** (основний або резервний provider; також використовується для summary) -- **Vydra** (основний або резервний provider; спільний provider для зображень, відео та мовлення) -- **xAI** (основний або резервний provider; використовує xAI TTS API) +- **ElevenLabs** (основний або резервний провайдер) +- **Google Gemini** (основний або резервний провайдер; використовує Gemini API TTS) +- **Gradium** (основний або резервний провайдер; підтримує вивід голосових повідомлень і телефонії) +- **Microsoft** (основний або резервний провайдер; поточна вбудована реалізація використовує `node-edge-tts`) +- **MiniMax** (основний або резервний провайдер; використовує API T2A v2) +- **OpenAI** (основний або резервний провайдер; також використовується для підсумків) +- **Vydra** (основний або резервний провайдер; спільний провайдер зображень, відео та мовлення) +- **xAI** (основний або резервний провайдер; використовує API xAI TTS) ### Примітки щодо мовлення Microsoft -Поточний вбудований provider мовлення Microsoft використовує онлайн-сервіс -нейронного TTS Microsoft Edge через бібліотеку `node-edge-tts`. Це хостований сервіс (не +Поточний вбудований провайдер мовлення Microsoft використовує онлайн-службу +нейронного TTS Microsoft Edge через бібліотеку `node-edge-tts`. Це хостинговий сервіс (не локальний), він використовує кінцеві точки Microsoft і не потребує API-ключа. -`node-edge-tts` надає параметри конфігурації мовлення та вихідні формати, але -сервіс підтримує не всі параметри. Застаріла config і вхід директив, -що використовують `edge`, усе ще працюють і нормалізуються до `microsoft`. +`node-edge-tts` надає параметри конфігурації мовлення та формати виводу, але +сервіс підтримує не всі параметри. Застаріла конфігурація та директивний ввід +із використанням `edge` усе ще працюють і нормалізуються до `microsoft`. -Оскільки цей шлях використовує публічний вебсервіс без опублікованих SLA або квот, -сприймайте його як best-effort. Якщо вам потрібні гарантовані ліміти й підтримка, використовуйте OpenAI +Оскільки цей шлях є публічним вебсервісом без опублікованої SLA або квоти, +ставтеся до нього як до best-effort. Якщо вам потрібні гарантовані ліміти та підтримка, використовуйте OpenAI або ElevenLabs. ## Необов’язкові ключі @@ -55,9 +55,9 @@ OpenClaw може перетворювати вихідні відповіді Для мовлення Microsoft API-ключ **не** потрібен. -Якщо налаштовано кілька provider, спочатку використовується вибраний provider, а решта стають резервними варіантами. -Автоматичне summary використовує налаштований `summaryModel` (або `agents.defaults.model.primary`), -тому якщо ви вмикаєте summary, цей provider також має бути автентифікований. +Якщо налаштовано кілька провайдерів, спочатку використовується вибраний провайдер, а інші є резервними варіантами. +Автопідсумок використовує налаштований `summaryModel` (або `agents.defaults.model.primary`), +тому, якщо ви ввімкнете підсумки, цей провайдер також має бути автентифікований. ## Посилання на сервіси @@ -71,20 +71,20 @@ OpenClaw може перетворювати вихідні відповіді - [Формати виводу Microsoft Speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) - [xAI Text to Speech](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest) -## Чи ввімкнено це типово? +## Чи ввімкнено це за замовчуванням? -Ні. Автоматичний TTS типово **вимкнений**. Увімкніть його в config через -`messages.tts.auto` або локально через `/tts on`. +Ні. Auto‑TTS **вимкнено** за замовчуванням. Увімкніть його в конфігурації через +`messages.tts.auto` або локально за допомогою `/tts on`. -Коли `messages.tts.provider` не задано, OpenClaw вибирає перший налаштований -provider мовлення в порядку автовибору registry. +Коли `messages.tts.provider` не задано, OpenClaw вибирає першого налаштованого +провайдера мовлення в порядку автоматичного вибору реєстру. -## Config +## Конфігурація -Config TTS знаходиться в `messages.tts` у `openclaw.json`. -Повна схема наведена в [конфігурації Gateway](/uk/gateway/configuration). +Конфігурація TTS знаходиться в `messages.tts` у `openclaw.json`. +Повна схема наведена в [Конфігурація Gateway](/uk/gateway/configuration). -### Мінімальна config (увімкнення + provider) +### Мінімальна конфігурація (увімкнення + провайдер) ```json5 { @@ -205,9 +205,9 @@ Config TTS знаходиться в `messages.tts` у `openclaw.json`. } ``` -Google Gemini TTS використовує шлях API-ключа Gemini. Тут підходить API-ключ Google Cloud Console, -обмежений Gemini API, і це той самий тип ключа, який використовує -вбудований provider генерації зображень Google. Порядок розв’язання: +Google Gemini TTS використовує шлях API-ключа Gemini API. Тут підходить API-ключ Google Cloud Console, +обмежений Gemini API, і це той самий тип ключа, який використовується +вбудованим провайдером генерації зображень Google. Порядок визначення: `messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` -> `GEMINI_API_KEY` -> `GOOGLE_API_KEY`. @@ -233,10 +233,36 @@ Google Gemini TTS використовує шлях API-ключа Gemini. Ту } ``` -xAI TTS використовує той самий шлях `XAI_API_KEY`, що й вбудований provider моделі Grok. -Порядок розв’язання: `messages.tts.providers.xai.apiKey` -> `XAI_API_KEY`. -Поточні доступні голоси: `ara`, `eve`, `leo`, `rex`, `sal` і `una`; типово використовується `eve`. -`language` приймає тег BCP-47 або `auto`. +xAI TTS використовує той самий шлях `XAI_API_KEY`, що й вбудований +провайдер моделей Grok. Порядок визначення: `messages.tts.providers.xai.apiKey` -> `XAI_API_KEY`. +Поточні доступні голоси: `ara`, `eve`, `leo`, `rex`, `sal` і `una`; `eve` — +голос за замовчуванням. `language` приймає тег BCP-47 або `auto`. + +### OpenRouter як основний + +```json5 +{ + messages: { + tts: { + auto: "always", + provider: "openrouter", + providers: { + openrouter: { + apiKey: "openrouter_api_key", + model: "hexgrad/kokoro-82m", + voice: "af_alloy", + responseFormat: "mp3", + }, + }, + }, + }, +} +``` + +OpenRouter TTS використовує той самий шлях `OPENROUTER_API_KEY`, що й вбудований +провайдер моделей OpenRouter. Порядок визначення: +`messages.tts.providers.openrouter.apiKey` -> +`models.providers.openrouter.apiKey` -> `OPENROUTER_API_KEY`. ### Gradium як основний @@ -258,7 +284,7 @@ xAI TTS використовує той самий шлях `XAI_API_KEY`, що } ``` -### Вимкнути мовлення Microsoft +### Вимкнення мовлення Microsoft ```json5 { @@ -301,7 +327,7 @@ xAI TTS використовує той самий шлях `XAI_API_KEY`, що } ``` -### Вимкнути автоматичне summary для довгих відповідей +### Вимкнення автопідсумку для довгих відповідей ```json5 { @@ -321,35 +347,35 @@ xAI TTS використовує той самий шлях `XAI_API_KEY`, що ### Примітки щодо полів -- `auto`: режим автоматичного TTS (`off`, `always`, `inbound`, `tagged`). +- `auto`: режим auto‑TTS (`off`, `always`, `inbound`, `tagged`). - `inbound` надсилає аудіо лише після вхідного голосового повідомлення. - `tagged` надсилає аудіо лише тоді, коли відповідь містить директиви `[[tts:key=value]]` або блок `[[tts:text]]...[[/tts:text]]`. -- `enabled`: застарілий перемикач (doctor переносить його до `auto`). +- `enabled`: застарілий перемикач (doctor мігрує його до `auto`). - `mode`: `"final"` (типово) або `"all"` (включає відповіді інструментів/блоків). -- `provider`: id provider мовлення, наприклад `"elevenlabs"`, `"google"`, `"gradium"`, `"microsoft"`, `"minimax"`, `"openai"`, `"vydra"` або `"xai"` (резервний варіант вибирається автоматично). -- Якщо `provider` **не задано**, OpenClaw використовує перший налаштований provider мовлення в порядку автовибору registry. +- `provider`: ідентифікатор провайдера мовлення, наприклад `"elevenlabs"`, `"google"`, `"gradium"`, `"microsoft"`, `"minimax"`, `"openai"`, `"vydra"` або `"xai"` (резервне перемикання відбувається автоматично). +- Якщо `provider` **не задано**, OpenClaw використовує першого налаштованого провайдера мовлення в порядку автоматичного вибору реєстру. - Застарілий `provider: "edge"` усе ще працює й нормалізується до `microsoft`. -- `summaryModel`: необов’язкова дешева модель для автоматичного summary; типово `agents.defaults.model.primary`. - - Приймає `provider/model` або налаштований alias моделі. -- `modelOverrides`: дозволяє моделі видавати директиви TTS (типово увімкнено). - - `allowProvider` типово має значення `false` (перемикання provider вимагає явного дозволу). -- `providers.`: налаштування, що належать provider, з ключем за id provider мовлення. -- Застарілі прямі блоки provider (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) автоматично переносяться до `messages.tts.providers.` під час завантаження. -- `maxTextLength`: жорстке обмеження для вхідного TTS (символи). `/tts audio` завершується помилкою, якщо його перевищено. +- `summaryModel`: необов’язкова недорога модель для автопідсумку; за замовчуванням використовується `agents.defaults.model.primary`. + - Приймає `provider/model` або налаштований псевдонім моделі. +- `modelOverrides`: дозволяє моделі видавати директиви TTS (увімкнено за замовчуванням). + - `allowProvider` за замовчуванням має значення `false` (перемикання провайдера вмикається лише явно). +- `providers.`: налаштування провайдера, що належать провайдеру, з ключем за ідентифікатором провайдера мовлення. +- Застарілі прямі блоки провайдерів (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) автоматично мігруються до `messages.tts.providers.` під час завантаження. +- `maxTextLength`: жорстке обмеження для вхідного тексту TTS (символи). `/tts audio` завершується помилкою, якщо його перевищено. - `timeoutMs`: тайм-аут запиту (мс). -- `prefsPath`: перевизначає локальний шлях до JSON prefs (provider/ліміт/summary). -- Значення `apiKey` використовують резервний варіант через env vars (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `GEMINI_API_KEY`/`GOOGLE_API_KEY`, `GRADIUM_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`, `VYDRA_API_KEY`, `XAI_API_KEY`). +- `prefsPath`: перевизначає локальний шлях до JSON-файлу налаштувань (провайдер/ліміт/підсумок). +- Значення `apiKey` повертаються до змінних середовища (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `GEMINI_API_KEY`/`GOOGLE_API_KEY`, `GRADIUM_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`, `VYDRA_API_KEY`, `XAI_API_KEY`). - `providers.elevenlabs.baseUrl`: перевизначає базовий URL API ElevenLabs. -- `providers.openai.baseUrl`: перевизначає endpoint TTS OpenAI. - - Порядок розв’язання: `messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` - - Значення, відмінні від типового, трактуються як TTS endpoint, сумісні з OpenAI, тому допускаються власні назви моделей і голосів. +- `providers.openai.baseUrl`: перевизначає кінцеву точку OpenAI TTS. + - Порядок визначення: `messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` + - Нестандартні значення розглядаються як сумісні з OpenAI TTS кінцеві точки, тому дозволені власні назви моделей і голосів. - `providers.elevenlabs.voiceSettings`: - `stability`, `similarityBoost`, `style`: `0..1` - `useSpeakerBoost`: `true|false` - - `speed`: `0.5..2.0` (1.0 = звичайна швидкість) + - `speed`: `0.5..2.0` (1.0 = нормально) - `providers.elevenlabs.applyTextNormalization`: `auto|on|off` - `providers.elevenlabs.languageCode`: 2-літерний ISO 639-1 (наприклад, `en`, `de`) -- `providers.elevenlabs.seed`: ціле число `0..4294967295` (детермінованість у режимі best-effort) +- `providers.elevenlabs.seed`: ціле число `0..4294967295` (best-effort детермінізм) - `providers.minimax.baseUrl`: перевизначає базовий URL API MiniMax (типово `https://api.minimax.io`, env: `MINIMAX_API_HOST`). - `providers.minimax.model`: модель TTS (типово `speech-2.8-hd`, env: `MINIMAX_TTS_MODEL`). - `providers.minimax.voiceId`: ідентифікатор голосу (типово `English_expressive_narrator`, env: `MINIMAX_TTS_VOICE_ID`). @@ -358,56 +384,62 @@ xAI TTS використовує той самий шлях `XAI_API_KEY`, що - `providers.minimax.pitch`: зсув тону `-12..12` (типово 0). - `providers.google.model`: модель Gemini TTS (типово `gemini-3.1-flash-tts-preview`). - `providers.google.voiceName`: назва вбудованого голосу Gemini (типово `Kore`; також приймається `voice`). -- `providers.google.baseUrl`: перевизначає базовий URL API Gemini. Приймається лише `https://generativelanguage.googleapis.com`. - - Якщо `messages.tts.providers.google.apiKey` пропущено, TTS може повторно використовувати `models.providers.google.apiKey` до переходу на резервний варіант через env. +- `providers.google.baseUrl`: перевизначає базовий URL Gemini API. Дозволено лише `https://generativelanguage.googleapis.com`. + - Якщо `messages.tts.providers.google.apiKey` не вказано, TTS може повторно використовувати `models.providers.google.apiKey` перед поверненням до змінних середовища. - `providers.gradium.baseUrl`: перевизначає базовий URL API Gradium (типово `https://api.gradium.ai`). - `providers.gradium.voiceId`: ідентифікатор голосу Gradium (типово Emma, `YTpq7expH9539ERJ`). - `providers.xai.apiKey`: API-ключ xAI TTS (env: `XAI_API_KEY`). - `providers.xai.baseUrl`: перевизначає базовий URL xAI TTS (типово `https://api.x.ai/v1`, env: `XAI_BASE_URL`). -- `providers.xai.voiceId`: id голосу xAI (типово `eve`; поточні доступні голоси: `ara`, `eve`, `leo`, `rex`, `sal`, `una`). +- `providers.xai.voiceId`: ідентифікатор голосу xAI (типово `eve`; поточні доступні голоси: `ara`, `eve`, `leo`, `rex`, `sal`, `una`). - `providers.xai.language`: код мови BCP-47 або `auto` (типово `en`). - `providers.xai.responseFormat`: `mp3`, `wav`, `pcm`, `mulaw` або `alaw` (типово `mp3`). -- `providers.xai.speed`: власне перевизначення швидкості provider. +- `providers.xai.speed`: перевизначення швидкості на рівні провайдера. +- `providers.openrouter.apiKey`: API-ключ OpenRouter (env: `OPENROUTER_API_KEY`; може повторно використовувати `models.providers.openrouter.apiKey`). +- `providers.openrouter.baseUrl`: перевизначає базовий URL OpenRouter TTS (типово `https://openrouter.ai/api/v1`; застарілий `https://openrouter.ai/v1` нормалізується). +- `providers.openrouter.model`: ідентифікатор моделі OpenRouter TTS (типово `hexgrad/kokoro-82m`; також приймається `modelId`). +- `providers.openrouter.voice`: специфічний для провайдера ідентифікатор голосу (типово `af_alloy`; також приймається `voiceId`). +- `providers.openrouter.responseFormat`: `mp3` або `pcm` (типово `mp3`). +- `providers.openrouter.speed`: перевизначення швидкості на рівні провайдера. - `providers.microsoft.enabled`: дозволяє використання мовлення Microsoft (типово `true`; без API-ключа). - `providers.microsoft.voice`: назва нейронного голосу Microsoft (наприклад, `en-US-MichelleNeural`). - `providers.microsoft.lang`: код мови (наприклад, `en-US`). - `providers.microsoft.outputFormat`: формат виводу Microsoft (наприклад, `audio-24khz-48kbitrate-mono-mp3`). - - Див. формати виводу Microsoft Speech для коректних значень; не всі формати підтримуються вбудованим транспортом на базі Edge. -- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: рядки відсотків (наприклад, `+10%`, `-5%`). + - Перегляньте формати виводу Microsoft Speech для допустимих значень; не всі формати підтримуються вбудованим транспортом на основі Edge. +- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: рядки у відсотках (наприклад, `+10%`, `-5%`). - `providers.microsoft.saveSubtitles`: записує JSON-субтитри поруч з аудіофайлом. - `providers.microsoft.proxy`: URL проксі для запитів мовлення Microsoft. - `providers.microsoft.timeoutMs`: перевизначення тайм-ауту запиту (мс). -- `edge.*`: застарілий alias для тих самих налаштувань Microsoft. +- `edge.*`: застарілий псевдонім для тих самих налаштувань Microsoft. -## Перевизначення, керовані моделлю (типово увімкнено) +## Перевизначення, керовані моделлю (увімкнено за замовчуванням) -Типово модель **може** видавати директиви TTS для однієї відповіді. +За замовчуванням модель **може** видавати директиви TTS для однієї відповіді. Коли `messages.tts.auto` має значення `tagged`, ці директиви потрібні для запуску аудіо. -Коли це увімкнено, модель може видавати директиви `[[tts:...]]`, щоб перевизначити голос +Коли це ввімкнено, модель може видавати директиви `[[tts:...]]` для перевизначення голосу для однієї відповіді, а також необов’язковий блок `[[tts:text]]...[[/tts:text]]`, щоб -надати виразні теги (сміх, підказки для співу тощо), які мають з’являтися лише в +додати виразні теги (сміх, підказки для співу тощо), які мають з’являтися лише в аудіо. -Директиви `provider=...` ігноруються, якщо `modelOverrides.allowProvider: true` не увімкнено. +Директиви `provider=...` ігноруються, якщо не встановлено `modelOverrides.allowProvider: true`. -Приклад payload відповіді: +Приклад пейлоада відповіді: ``` -Here you go. +Ось, будь ласка. [[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]] -[[tts:text]](laughs) Read the song once more.[[/tts:text]] +[[tts:text]](сміється) Прочитай пісню ще раз.[[/tts:text]] ``` -Доступні ключі директив (коли увімкнено): +Доступні ключі директив (коли ввімкнено): -- `provider` (id зареєстрованого provider мовлення, наприклад `openai`, `elevenlabs`, `google`, `gradium`, `minimax`, `microsoft`, `vydra` або `xai`; потребує `allowProvider: true`) +- `provider` (ідентифікатор зареєстрованого провайдера мовлення, наприклад `openai`, `elevenlabs`, `google`, `gradium`, `minimax`, `microsoft`, `vydra` або `xai`; потребує `allowProvider: true`) - `voice` (голос OpenAI або Gradium), `voiceName` / `voice_name` / `google_voice` (голос Google) або `voiceId` (ElevenLabs / Gradium / MiniMax / xAI) -- `model` (модель TTS OpenAI, id моделі ElevenLabs або модель MiniMax) або `google_model` (модель Google TTS) +- `model` (модель OpenAI TTS, ідентифікатор моделі ElevenLabs або модель MiniMax) або `google_model` (модель Google TTS) - `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost` - `vol` / `volume` (гучність MiniMax, 0-10) -- `pitch` (висота тону MiniMax, від -12 до 12) +- `pitch` (тон MiniMax, від -12 до 12) - `applyTextNormalization` (`auto|on|off`) - `languageCode` (ISO 639-1) - `seed` @@ -426,7 +458,7 @@ Here you go. } ``` -Необов’язковий allowlist (увімкнути перемикання provider, залишаючи інші параметри доступними для налаштування): +Необов’язковий список дозволів (увімкнути перемикання провайдера, залишивши інші параметри налаштовуваними): ```json5 { @@ -442,7 +474,7 @@ Here you go. } ``` -## Налаштування для кожного користувача +## Налаштування для окремого користувача Команди зі слешем записують локальні перевизначення до `prefsPath` (типово: `~/.openclaw/settings/tts.json`, перевизначається через `OPENCLAW_TTS_PREFS` або @@ -452,7 +484,7 @@ Here you go. - `enabled` - `provider` -- `maxLength` (поріг summary; типово 1500 символів) +- `maxLength` (поріг підсумку; типово 1500 символів) - `summarize` (типово `true`) Вони перевизначають `messages.tts.*` для цього хоста. @@ -462,55 +494,55 @@ Here you go. - **Feishu / Matrix / Telegram / WhatsApp**: голосове повідомлення Opus (`opus_48000_64` від ElevenLabs, `opus` від OpenAI). - 48 кГц / 64 кбіт/с — хороший компроміс для голосових повідомлень. - **Інші канали**: MP3 (`mp3_44100_128` від ElevenLabs, `mp3` від OpenAI). - - 44.1 кГц / 128 кбіт/с — типовий баланс для чіткості мовлення. -- **MiniMax**: MP3 (модель `speech-2.8-hd`, частота дискретизації 32 кГц). Формат voice-note нативно не підтримується; використовуйте OpenAI або ElevenLabs для гарантованих голосових повідомлень Opus. -- **Google Gemini**: Gemini API TTS повертає сирий PCM 24 кГц. OpenClaw обгортає його у WAV для аудіовкладень і повертає PCM напряму для Talk/telephony. Нативний формат voice-note Opus цим шляхом не підтримується. -- **Gradium**: WAV для аудіовкладень, Opus для цілей voice-note і `ulaw_8000` на 8 кГц для telephony. -- **xAI**: типово MP3; `responseFormat` може бути `mp3`, `wav`, `pcm`, `mulaw` або `alaw`. OpenClaw використовує пакетний REST endpoint xAI TTS і повертає завершене аудіовкладення; потоковий WebSocket TTS xAI цим шляхом provider не використовується. Нативний формат voice-note Opus цим шляхом не підтримується. + - 44,1 кГц / 128 кбіт/с — типовий баланс для чіткості мовлення. +- **MiniMax**: MP3 (модель `speech-2.8-hd`, частота дискретизації 32 кГц). Формат голосових повідомлень нативно не підтримується; використовуйте OpenAI або ElevenLabs для гарантованих голосових повідомлень Opus. +- **Google Gemini**: Gemini API TTS повертає сирий PCM 24 кГц. OpenClaw обгортає його у WAV для аудіовкладень і повертає PCM напряму для Talk/телефонії. Нативний формат голосових повідомлень Opus цим шляхом не підтримується. +- **Gradium**: WAV для аудіовкладень, Opus для цілей голосових повідомлень і `ulaw_8000` на 8 кГц для телефонії. +- **xAI**: типово MP3; `responseFormat` може бути `mp3`, `wav`, `pcm`, `mulaw` або `alaw`. OpenClaw використовує пакетну REST-кінцеву точку xAI TTS і повертає повністю сформоване аудіовкладення; WebSocket потокового TTS xAI цим шляхом провайдера не використовується. Нативний формат голосових повідомлень Opus цим шляхом не підтримується. - **Microsoft**: використовує `microsoft.outputFormat` (типово `audio-24khz-48kbitrate-mono-mp3`). - Вбудований транспорт приймає `outputFormat`, але сервіс надає не всі формати. - - Значення форматів виводу відповідають форматам Microsoft Speech output formats (включно з Ogg/WebM Opus). - - `sendVoice` у Telegram приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні + - Значення формату виводу відповідають форматам виводу Microsoft Speech (включно з Ogg/WebM Opus). + - Telegram `sendVoice` приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні гарантовані голосові повідомлення Opus. - Якщо налаштований формат виводу Microsoft завершується помилкою, OpenClaw повторює спробу з MP3. -Формати виводу OpenAI/ElevenLabs є фіксованими для кожного каналу (див. вище). +Формати виводу OpenAI/ElevenLabs фіксовані для кожного каналу (див. вище). -## Поведінка автоматичного TTS +## Поведінка auto-TTS -Коли це ввімкнено, OpenClaw: +Коли ввімкнено, OpenClaw: - пропускає TTS, якщо відповідь уже містить медіа або директиву `MEDIA:`. - пропускає дуже короткі відповіді (< 10 символів). -- створює summary для довгих відповідей, якщо це ввімкнено, використовуючи `agents.defaults.model.primary` (або `summaryModel`). +- створює підсумки для довгих відповідей, якщо це ввімкнено, використовуючи `agents.defaults.model.primary` (або `summaryModel`). - додає згенероване аудіо до відповіді. -Якщо відповідь перевищує `maxLength`, а summary вимкнено (або немає API-ключа для -моделі summary), аудіо +Якщо відповідь перевищує `maxLength`, а підсумки вимкнено (або немає API-ключа для +моделі підсумків), аудіо пропускається, і надсилається звичайна текстова відповідь. ## Схема потоку ``` -Reply -> TTS enabled? - no -> send text - yes -> has media / MEDIA: / short? - yes -> send text - no -> length > limit? - no -> TTS -> attach audio - yes -> summary enabled? - no -> send text - yes -> summarize (summaryModel or agents.defaults.model.primary) - -> TTS -> attach audio +Відповідь -> TTS увімкнено? + ні -> надіслати текст + так -> є медіа / MEDIA: / коротка? + так -> надіслати текст + ні -> довжина > ліміт? + ні -> TTS -> додати аудіо + так -> підсумок увімкнено? + ні -> надіслати текст + так -> підсумувати (summaryModel або agents.defaults.model.primary) + -> TTS -> додати аудіо ``` ## Використання команд зі слешем Є одна команда: `/tts`. -Докладно про ввімкнення див. у [командах зі слешем](/uk/tools/slash-commands). +Докладніше про ввімкнення див. у [Команди зі слешем](/uk/tools/slash-commands). Примітка для Discord: `/tts` — це вбудована команда Discord, тому OpenClaw реєструє -там `/voice` як нативну команду. Текстовий `/tts ...` усе ще працює. +там `/voice` як нативну команду. Текстова команда `/tts ...` усе ще працює. ``` /tts off @@ -526,26 +558,26 @@ Reply -> TTS enabled? - Команди потребують авторизованого відправника (правила allowlist/owner усе ще застосовуються). - Має бути ввімкнено `commands.text` або реєстрацію нативних команд. -- Config `messages.tts.auto` приймає `off|always|inbound|tagged`. -- `/tts on` записує локальне налаштування TTS у `always`; `/tts off` записує його в `off`. -- Використовуйте config, коли вам потрібні типові значення `inbound` або `tagged`. -- `limit` і `summary` зберігаються в локальних prefs, а не в основній config. +- Конфігурація `messages.tts.auto` приймає `off|always|inbound|tagged`. +- `/tts on` записує локальне налаштування TTS як `always`; `/tts off` записує його як `off`. +- Використовуйте конфігурацію, якщо вам потрібні типові значення `inbound` або `tagged`. +- `limit` і `summary` зберігаються в локальних налаштуваннях, а не в основній конфігурації. - `/tts audio` генерує одноразову аудіовідповідь (не вмикає TTS). -- `/tts status` містить видимість fallback для останньої спроби: - - успішний fallback: `Fallback: -> ` плюс `Attempts: ...` +- `/tts status` включає видимість резервного перемикання для останньої спроби: + - успішне резервне перемикання: `Fallback: -> ` плюс `Attempts: ...` - помилка: `Error: ...` плюс `Attempts: ...` - детальна діагностика: `Attempt details: provider:outcome(reasonCode) latency` -- Помилки API OpenAI і ElevenLabs тепер містять розібрані деталі помилок provider і id запиту (коли provider його повертає), які відображаються в помилках/журналах TTS. +- Помилки API OpenAI і ElevenLabs тепер включають розібрані деталі помилки провайдера та id запиту (коли його повертає провайдер), що відображається в помилках/логах TTS. ## Інструмент агента -Інструмент `tts` перетворює текст на мовлення й повертає аудіовкладення для -доставки у відповіді. Коли каналом є Feishu, Matrix, Telegram або WhatsApp, +Інструмент `tts` перетворює текст на мовлення та повертає аудіовкладення для +доставки у відповіді. Якщо каналом є Feishu, Matrix, Telegram або WhatsApp, аудіо доставляється як голосове повідомлення, а не як файлове вкладення. Він приймає необов’язкові поля `channel` і `timeoutMs`; `timeoutMs` — це -тайм-аут запиту provider для кожного виклику в мілісекундах. +тайм-аут запиту до провайдера для окремого виклику в мілісекундах. -## RPC Gateway +## Gateway RPC Методи Gateway: