From 81479e433db8e6725c348f2e1d35c4b0cd91cec2 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 20:42:22 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/cli/mcp.md | 304 ++++++++------- docs/uk/help/testing-live.md | 418 +++++++++++---------- docs/uk/plugins/codex-harness.md | 536 ++++++++++++++------------- docs/uk/plugins/sdk-agent-harness.md | 255 ++++++------- docs/uk/providers/google.md | 202 +++++----- docs/uk/tools/tts.md | 333 ++++++++--------- 6 files changed, 1045 insertions(+), 1003 deletions(-) diff --git a/docs/uk/cli/mcp.md b/docs/uk/cli/mcp.md index e0983a10e..cbdbf81ee 100644 --- a/docs/uk/cli/mcp.md +++ b/docs/uk/cli/mcp.md @@ -2,29 +2,30 @@ read_when: - Підключення Codex, Claude Code або іншого клієнта MCP до каналів на базі OpenClaw - Запуск `openclaw mcp serve` - - Керування збереженими в OpenClaw визначеннями серверів MCP -summary: Показувати розмови каналів OpenClaw через MCP і керувати збереженими визначеннями серверів MCP + - Керування збереженими визначеннями серверів MCP в OpenClaw +summary: Відкрийте розмови каналів OpenClaw через MCP і керуйте збереженими визначеннями серверів MCP title: MCP x-i18n: - generated_at: "2026-04-25T08:04:05Z" + generated_at: "2026-04-25T20:40:02Z" model: gpt-5.4 provider: openai - source_hash: ca2a76d1dbca71b4048659c21ac7ff98a01cc6095f6baad67df5347f45cd32e6 + source_hash: 960a710fe8b35b923d8c3fd78b9904345e735ee82183e4d9b5f8d2445faa2d49 source_path: cli/mcp.md workflow: 15 --- -`openclaw mcp` має два завдання: +`openclaw mcp` має дві функції: - запускати OpenClaw як сервер MCP за допомогою `openclaw mcp serve` -- керувати визначеннями вихідних серверів MCP, що належать OpenClaw, за допомогою `list`, `show`, +- керувати визначеннями вихідних серверів MCP, якими володіє OpenClaw, за допомогою `list`, `show`, `set` і `unset` -Інакше кажучи: +Іншими словами: - `serve` — це OpenClaw, що працює як сервер MCP -- `list` / `show` / `set` / `unset` — це OpenClaw, що працює як реєстр на боці клієнта MCP - для інших серверів MCP, які його середовища виконання можуть використовувати пізніше +- `list` / `show` / `set` / `unset` — це OpenClaw, що працює як клієнтський + реєстр для інших серверів MCP, які його середовища виконання можуть + використовувати пізніше Використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має сам розміщувати сеанс coding harness і маршрутизувати це середовище виконання через ACP. @@ -37,20 +38,22 @@ x-i18n: Використовуйте `openclaw mcp serve`, коли: -- Codex, Claude Code або інший клієнт MCP має безпосередньо взаємодіяти з +- Codex, Claude Code або інший клієнт MCP має напряму взаємодіяти з розмовами каналів на базі OpenClaw -- у вас уже є локальний або віддалений Gateway OpenClaw із маршрутизованими сеансами -- вам потрібен один сервер MCP, який працює з бекендами каналів OpenClaw, +- у вас уже є локальний або віддалений Gateway OpenClaw із + маршрутизованими сеансами +- вам потрібен один сервер MCP, який працює через бекенди каналів OpenClaw, замість запуску окремих мостів для кожного каналу -Замість цього використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має сам -розміщувати середовище виконання coding і зберігати сеанс агента всередині OpenClaw. +Натомість використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має сам +розміщувати середовище виконання coding і тримати сеанс агента всередині +OpenClaw. ## Як це працює -`openclaw mcp serve` запускає stdio-сервер MCP. Клієнт MCP керує цим +`openclaw mcp serve` запускає stdio-сервер MCP. Клієнт MCP володіє цим процесом. Поки клієнт тримає сеанс stdio відкритим, міст підключається до -локального або віддаленого Gateway OpenClaw через WebSocket і показує +локального або віддаленого Gateway OpenClaw через WebSocket і відкриває маршрутизовані розмови каналів через MCP. Життєвий цикл: @@ -59,26 +62,26 @@ x-i18n: 2. міст підключається до Gateway 3. маршрутизовані сеанси стають розмовами MCP та інструментами transcript/history 4. живі події ставляться в чергу в пам’яті, поки міст підключений -5. якщо ввімкнено режим каналу Claude, той самий сеанс також може отримувати - push-сповіщення, специфічні для Claude +5. якщо увімкнено режим каналу Claude, той самий сеанс також може отримувати + специфічні для Claude push-сповіщення -Важлива поведінка: +Важливі особливості поведінки: -- стан живої черги починається, коли міст підключається -- старіша історія transcript зчитується через `messages_read` -- push-сповіщення Claude існують лише поки активний сеанс MCP -- коли клієнт відключається, міст завершує роботу, а жива черга зникає -- одноразові точки входу агента, такі як `openclaw agent` і +- стан live-черги починається, коли міст підключається +- старіша історія transcript читається через `messages_read` +- push-сповіщення Claude існують лише поки живий сеанс MCP +- коли клієнт відключається, міст завершується, і live-черга зникає +- одноразові точки входу агента, як-от `openclaw agent` і `openclaw infer model run`, прибирають усі вбудовані середовища виконання MCP, - які вони відкривають, коли відповідь завершується, тому повторні сценарні запуски - не накопичують дочірні stdio-процеси MCP -- stdio-сервери MCP, запущені OpenClaw (вбудовані або налаштовані користувачем), - зупиняються як дерево процесів під час завершення роботи, тому дочірні - підпроцеси, запущені сервером, не залишаються після завершення батьківського - stdio-клієнта -- видалення або скидання сеансу звільняє клієнтів MCP цього сеансу через - спільний шлях очищення середовища виконання, тому не залишається завислих - stdio-з’єднань, прив’язаних до видаленого сеансу + які вони відкривають, коли відповідь завершено, тож повторні скриптові + запуски не накопичують дочірні процеси stdio MCP +- stdio-сервери MCP, запущені OpenClaw (вбудовані або налаштовані + користувачем), завершуються як дерево процесів під час вимкнення, тож дочірні + підпроцеси, запущені сервером, не виживають після виходу батьківського + клієнта stdio +- видалення або скидання сеансу звільняє клієнти MCP цього сеансу через + спільний шлях очищення середовища виконання, тож не залишається завислих + stdio-з’єднань, пов’язаних із видаленим сеансом ## Виберіть режим клієнта @@ -87,30 +90,30 @@ x-i18n: - Загальні клієнти MCP: лише стандартні інструменти MCP. Використовуйте `conversations_list`, `messages_read`, `events_poll`, `events_wait`, `messages_send` та інструменти погодження. -- Claude Code: стандартні інструменти MCP плюс адаптер каналу, специфічний для Claude. +- Claude Code: стандартні інструменти MCP плюс специфічний для Claude адаптер каналу. Увімкніть `--claude-channel-mode on` або залиште значення за замовчуванням `auto`. -Наразі `auto` поводиться так само, як `on`. Визначення можливостей клієнта -ще не реалізовано. +Сьогодні `auto` поводиться так само, як `on`. Виявлення можливостей клієнта +ще немає. -## Що показує `serve` +## Що відкриває `serve` -Міст використовує наявні метадані маршрутів сеансів Gateway, щоб показувати -розмови, прив’язані до каналів. Розмова з’являється, коли OpenClaw уже має стан +Міст використовує наявні метадані маршруту сеансу Gateway, щоб відкривати +розмови на базі каналів. Розмова з’являється, коли OpenClaw уже має стан сеансу з відомим маршрутом, таким як: - `channel` -- метадані одержувача або призначення +- метадані отримувача або призначення - необов’язковий `accountId` - необов’язковий `threadId` -Це дає клієнтам MCP єдине місце, де можна: +Це дає клієнтам MCP єдине місце, щоб: - перелічувати нещодавні маршрутизовані розмови - читати нещодавню історію transcript -- очікувати нові вхідні події +- чекати на нові вхідні події - надсилати відповідь назад тим самим маршрутом -- бачити запити на погодження, що надходять, поки міст підключений +- бачити запити на погодження, які надходять, поки міст підключений ## Використання @@ -121,19 +124,19 @@ openclaw mcp serve # Віддалений Gateway openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token -# Віддалений Gateway з автентифікацією паролем +# Віддалений Gateway з автентифікацією за паролем openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password # Увімкнути докладні журнали моста openclaw mcp serve --verbose -# Вимкнути push-сповіщення, специфічні для Claude +# Вимкнути специфічні для Claude push-сповіщення openclaw mcp serve --claude-channel-mode off ``` ## Інструменти моста -Поточний міст показує такі інструменти MCP: +Поточний міст відкриває такі інструменти MCP: - `conversations_list` - `conversation_get` @@ -147,8 +150,8 @@ openclaw mcp serve --claude-channel-mode off ### `conversations_list` -Перелічує нещодавні розмови на основі сеансів, які вже мають метадані маршруту -в стані сеансу Gateway. +Перелічує нещодавні розмови на базі сеансів, які вже мають метадані маршруту в +стані сеансу Gateway. Корисні фільтри: @@ -164,24 +167,24 @@ openclaw mcp serve --claude-channel-mode off ### `messages_read` -Зчитує нещодавні повідомлення transcript для однієї розмови на основі сеансу. +Читає нещодавні повідомлення transcript для однієї розмови на базі сеансу. ### `attachments_fetch` Витягує нетекстові блоки вмісту повідомлення з одного повідомлення transcript. Це -подання метаданих вмісту transcript, а не окреме довговічне сховище blob-вкладень. +подання метаданих поверх вмісту transcript, а не окреме стале сховище blob-вкладень. ### `events_poll` -Зчитує поставлені в чергу живі події, починаючи з числового курсора. +Читає поставлені в чергу живі події, починаючи з числового курсора. ### `events_wait` -Виконує довге опитування, доки не надійде наступна відповідна подія з черги +Виконує long-poll, доки не надійде наступна відповідна поставлена в чергу подія або не спливе час очікування. -Використовуйте це, коли загальному клієнту MCP потрібна доставка, близька до -реального часу, без push-протоколу, специфічного для Claude. +Використовуйте це, коли загальному клієнту MCP потрібна майже реальна доставка +в реальному часі без специфічного для Claude push-протоколу. ### `messages_send` @@ -190,17 +193,17 @@ openclaw mcp serve --claude-channel-mode off Поточна поведінка: - потребує наявного маршруту розмови -- використовує канал сеансу, одержувача, id облікового запису та id гілки +- використовує channel, recipient, account id і thread id із сеансу - надсилає лише текст ### `permissions_list_open` -Перелічує запити на погодження exec/plugin, які міст спостерігав відтоді, як -підключився до Gateway. +Перелічує очікуючі запити на погодження exec/plugin, які міст спостерігав відтоді, +як підключився до Gateway. ### `permissions_respond` -Обробляє один очікуваний запит на погодження exec/plugin за допомогою: +Розв’язує один очікуючий запит на погодження exec/plugin за допомогою: - `allow-once` - `allow-always` @@ -208,7 +211,7 @@ openclaw mcp serve --claude-channel-mode off ## Модель подій -Міст зберігає чергу подій у пам’яті, поки він підключений. +Міст тримає чергу подій у пам’яті, поки підключений. Поточні типи подій: @@ -221,24 +224,24 @@ openclaw mcp serve --claude-channel-mode off Важливі обмеження: -- черга є лише живою; вона починається, коли запускається міст MCP +- черга лише жива; вона починається, коли запускається міст MCP - `events_poll` і `events_wait` самі по собі не відтворюють старішу історію Gateway -- довговічний backlog слід читати через `messages_read` +- сталий backlog слід читати через `messages_read` ## Сповіщення каналу Claude -Міст також може показувати сповіщення каналу, специфічні для Claude. Це +Міст також може відкривати специфічні для Claude сповіщення каналу. Це еквівалент адаптера каналу Claude Code в OpenClaw: стандартні інструменти MCP залишаються доступними, але живі вхідні повідомлення також можуть надходити як -MCP-сповіщення, специфічні для Claude. +специфічні для Claude сповіщення MCP. Прапорці: - `--claude-channel-mode off`: лише стандартні інструменти MCP - `--claude-channel-mode on`: увімкнути сповіщення каналу Claude -- `--claude-channel-mode auto`: поточне значення за замовчуванням; така сама поведінка моста, як у `on` +- `--claude-channel-mode auto`: поточне значення за замовчуванням; така сама поведінка моста, як і в `on` -Коли ввімкнено режим каналу Claude, сервер оголошує експериментальні +Коли режим каналу Claude увімкнено, сервер оголошує експериментальні можливості Claude і може надсилати: - `notifications/claude/channel` @@ -248,18 +251,18 @@ MCP-сповіщення, специфічні для Claude. - вхідні повідомлення transcript від `user` пересилаються як `notifications/claude/channel` -- запити на погодження Claude, отримані через MCP, відстежуються в пам’яті +- запити на дозволи Claude, отримані через MCP, відстежуються в пам’яті - якщо пов’язана розмова пізніше надсилає `yes abcde` або `no abcde`, міст перетворює це на `notifications/claude/channel/permission` -- ці сповіщення доступні лише в живому сеансі; якщо клієнт MCP відключається, +- ці сповіщення існують лише для живого сеансу; якщо клієнт MCP відключається, цілі для push більше немає -Це навмисно клієнтоспецифічна поведінка. Загальні клієнти MCP мають покладатися -на стандартні інструменти опитування. +Це навмисно специфічно для клієнта. Загальні клієнти MCP мають покладатися на +стандартні інструменти опитування. ## Конфігурація клієнта MCP -Приклад конфігурації клієнта stdio: +Приклад конфігурації stdio-клієнта: ```json { @@ -280,8 +283,8 @@ MCP-сповіщення, специфічні для Claude. ``` Для більшості загальних клієнтів MCP починайте зі стандартної поверхні -інструментів і ігноруйте режим Claude. Вмикайте режим Claude лише для клієнтів, -які справді розуміють методи сповіщень, специфічні для Claude. +інструментів і ігноруйте режим Claude. Увімкніть режим Claude лише для +клієнтів, які справді розуміють специфічні для Claude методи сповіщень. ## Параметри @@ -295,46 +298,45 @@ MCP-сповіщення, специфічні для Claude. - `--claude-channel-mode `: режим сповіщень Claude - `-v`, `--verbose`: докладні журнали в stderr -За можливості надавайте перевагу `--token-file` або `--password-file` замість +Коли можливо, надавайте перевагу `--token-file` або `--password-file` замість вбудованих секретів. -## Безпека та межа довіри +## Межа безпеки та довіри -Міст не вигадує маршрутизацію. Він лише показує розмови, які Gateway уже вміє -маршрутизувати. +Міст не вигадує маршрутизацію. Він лише відкриває розмови, які Gateway уже +вміє маршрутизувати. -Це означає: +Це означає, що: -- списки дозволених відправників, спарювання та довіра на рівні каналу все ще +- списки дозволених відправників, pairing і довіра на рівні каналу все ще належать базовій конфігурації каналу OpenClaw - `messages_send` може відповідати лише через наявний збережений маршрут -- стан погодження є лише живим/у пам’яті для поточного сеансу моста -- автентифікація моста має використовувати ті самі механізми контролю токена - або пароля Gateway, яким ви б довірили будь-який інший віддалений клієнт Gateway +- стан погоджень є лише живим/у пам’яті для поточного сеансу моста +- для автентифікації моста слід використовувати ті самі механізми токена або + пароля Gateway, яким ви б довіряли для будь-якого іншого віддаленого клієнта Gateway -Якщо розмова відсутня в `conversations_list`, звичайна причина полягає не в -конфігурації MCP. Причина — відсутні або неповні метадані маршруту в базовому -сеансі Gateway. +Якщо розмова відсутня в `conversations_list`, звична причина — не конфігурація +MCP. Це відсутні або неповні метадані маршруту в базовому сеансі Gateway. ## Тестування -OpenClaw постачається з детермінованою Docker smoke-перевіркою для цього моста: +OpenClaw постачає детермінований Docker smoke для цього моста: ```bash pnpm test:docker:mcp-channels ``` -Ця smoke-перевірка: +Цей smoke: -- запускає контейнер Gateway із початковими даними -- запускає другий контейнер, який запускає `openclaw mcp serve` +- запускає контейнер Gateway із попередньо підготовленими даними +- запускає другий контейнер, який виконує `openclaw mcp serve` - перевіряє виявлення розмов, читання transcript, читання метаданих вкладень, - поведінку черги живих подій і маршрутизацію вихідного надсилання -- перевіряє сповіщення у стилі Claude для каналів і дозволів через реальний - stdio-міст MCP + поведінку live-черги подій і маршрутизацію вихідних надсилань +- валідує сповіщення каналу та дозволів у стилі Claude через реальний + міст stdio MCP -Це найшвидший спосіб довести, що міст працює, не підключаючи реальний -обліковий запис Telegram, Discord або iMessage до тестового запуску. +Це найшвидший спосіб довести, що міст працює, не підключаючи реальний обліковий +запис Telegram, Discord або iMessage до тестового запуску. Для ширшого контексту тестування див. [Testing](/uk/help/testing). @@ -342,13 +344,13 @@ pnpm test:docker:mcp-channels ### Не повертаються розмови -Зазвичай це означає, що сеанс Gateway ще не придатний для маршрутизації. -Підтвердьте, що базовий сеанс має збережені channel/provider, recipient і -необов’язкові метадані маршруту account/thread. +Зазвичай це означає, що сеанс Gateway ще не маршрутизується. Підтвердьте, що +базовий сеанс має збережені метадані маршруту channel/provider, recipient і +необов’язкового account/thread. ### `events_poll` або `events_wait` пропускає старіші повідомлення -Це очікувано. Жива черга починається, коли міст підключається. Читайте старішу +Це очікувано. live-черга починається, коли міст підключається. Читайте старішу історію transcript через `messages_read`. ### Сповіщення Claude не з’являються @@ -357,46 +359,50 @@ pnpm test:docker:mcp-channels - клієнт тримав stdio-сеанс MCP відкритим - `--claude-channel-mode` має значення `on` або `auto` -- клієнт справді розуміє методи сповіщень, специфічні для Claude -- вхідне повідомлення надійшло після підключення моста +- клієнт справді розуміє специфічні для Claude методи сповіщень +- вхідне повідомлення сталося після підключення моста ### Відсутні погодження -`permissions_list_open` показує лише запити на погодження, помічені, поки міст -був підключений. Це не API довговічної історії погоджень. +`permissions_list_open` показує лише запити на погодження, які було +спостережено, поки міст був підключений. Це не API сталої історії погоджень. ## OpenClaw як реєстр клієнтів MCP Це шлях `openclaw mcp list`, `show`, `set` і `unset`. -Ці команди не показують OpenClaw через MCP. Вони керують визначеннями серверів -MCP, що належать OpenClaw, у `mcp.servers` у конфігурації OpenClaw. +Ці команди не відкривають OpenClaw через MCP. Вони керують визначеннями +серверів MCP, якими володіє OpenClaw, у `mcp.servers` у конфігурації OpenClaw. Ці збережені визначення призначені для середовищ виконання, які OpenClaw -запускає або налаштовує пізніше, наприклад для вбудованого Pi та інших -адаптерів середовища виконання. OpenClaw централізовано зберігає визначення, -щоб цим середовищам виконання не потрібно було підтримувати власні дубльовані -списки серверів MCP. +запускає або налаштовує пізніше, таких як вбудований Pi та інші адаптери +середовища виконання. OpenClaw зберігає визначення централізовано, щоб цим +середовищам виконання не доводилося тримати власні дублікати списків серверів MCP. -Важлива поведінка: +Важливі особливості поведінки: - ці команди лише читають або записують конфігурацію OpenClaw - вони не підключаються до цільового сервера MCP -- вони не перевіряють, чи команда, URL або віддалений транспорт зараз - доступні -- адаптери середовища виконання вирішують під час виконання, які форми +- вони не перевіряють, чи команда, URL або віддалений транспорт є + досяжними прямо зараз +- адаптери середовища виконання вирішують під час виконання, які саме форми транспорту вони фактично підтримують -- вбудований Pi показує налаштовані інструменти MCP у звичайних профілях +- вбудований Pi відкриває налаштовані інструменти MCP у звичайних профілях інструментів `coding` і `messaging`; `minimal` усе ще приховує їх, а `tools.deny: ["bundle-mcp"]` вимикає їх явно -- вбудовані середовища виконання MCP з областю дії сеансу прибираються після - `mcp.sessionIdleTtlMs` мілісекунд неактивності (типово 10 хвилин; встановіть `0`, +- вбудовані середовища виконання MCP на рівні сеансу прибираються після + `mcp.sessionIdleTtlMs` мілісекунд простою (типово 10 хвилин; встановіть `0`, щоб вимкнути), а одноразові вбудовані запуски очищають їх наприкінці виконання +Адаптери середовища виконання можуть нормалізувати цей спільний реєстр до форми, +яку очікує їхній downstream-клієнт. Наприклад, вбудований Pi використовує +значення OpenClaw `transport` напряму, тоді як Claude Code і Gemini отримують +власні для CLI значення `type`, такі як `http`, `sse` або `stdio`. + ## Збережені визначення серверів MCP -OpenClaw також зберігає в конфігурації легкий реєстр серверів MCP для -поверхонь, які хочуть мати визначення MCP під керуванням OpenClaw. +OpenClaw також зберігає в конфігурації легкий реєстр серверів MCP для поверхонь, +яким потрібні керовані OpenClaw визначення MCP. Команди: @@ -407,10 +413,10 @@ OpenClaw також зберігає в конфігурації легкий р Примітки: -- `list` сортує назви серверів. -- `show` без назви виводить повний налаштований об’єкт сервера MCP. +- `list` сортує імена серверів. +- `show` без імені виводить повний налаштований об’єкт сервера MCP. - `set` очікує одне значення JSON-об’єкта в командному рядку. -- `unset` завершується помилкою, якщо іменований сервер не існує. +- `unset` завершується з помилкою, якщо сервер із вказаним ім’ям не існує. Приклади: @@ -422,7 +428,7 @@ openclaw mcp set docs '{"url":"https://mcp.example.com"}' openclaw mcp unset context7 ``` -Приклад форми конфігурації: +Приклад структури конфігурації: ```json { @@ -444,28 +450,37 @@ openclaw mcp unset context7 Запускає локальний дочірній процес і взаємодіє через stdin/stdout. -| Field | Description | -| -------------------------- | ------------------------------------- | +| Field | Description | +| -------------------------- | -------------------------------- | | `command` | Виконуваний файл для запуску (обов’язково) | -| `args` | Масив аргументів командного рядка | -| `env` | Додаткові змінні середовища | -| `cwd` / `workingDirectory` | Робочий каталог для процесу | +| `args` | Масив аргументів командного рядка | +| `env` | Додаткові змінні середовища | +| `cwd` / `workingDirectory` | Робочий каталог для процесу | #### Фільтр безпеки env для Stdio -OpenClaw відхиляє ключі env запуску інтерпретатора, які можуть змінити спосіб запуску stdio-сервера MCP до першого RPC, навіть якщо вони з’являються в блоці `env` сервера. Заблоковані ключі включають `NODE_OPTIONS`, `PYTHONSTARTUP`, `PYTHONPATH`, `PERL5OPT`, `RUBYOPT`, `SHELLOPTS`, `PS4` та подібні змінні керування середовищем виконання. Запуск відхиляє їх із помилкою конфігурації, щоб вони не могли впровадити неявний prelude, підмінити інтерпретатор або ввімкнути налагоджувач для stdio-процесу. Звичайні облікові дані, проксі та змінні env, специфічні для сервера (`GITHUB_TOKEN`, `HTTP_PROXY`, власні `*_API_KEY` тощо), не зачіпаються. +OpenClaw відхиляє ключі env запуску інтерпретатора, які можуть змінити спосіб +запуску stdio-сервера MCP до першого RPC, навіть якщо вони з’являються в блоці +`env` сервера. Заблоковані ключі включають `NODE_OPTIONS`, `PYTHONSTARTUP`, +`PYTHONPATH`, `PERL5OPT`, `RUBYOPT`, `SHELLOPTS`, `PS4` та подібні змінні +керування середовищем виконання. Під час запуску вони відхиляються з помилкою +конфігурації, щоб не можна було ін’єктувати неявний prelude, підмінити +інтерпретатор або ввімкнути debugger для stdio-процесу. Звичайні змінні env для +облікових даних, proxy та специфічні для сервера (`GITHUB_TOKEN`, `HTTP_PROXY`, +власні `*_API_KEY` тощо) не зачіпаються. -Якщо вашому серверу MCP справді потрібна одна із заблокованих змінних, задайте її в процесі хоста Gateway, а не в `env` stdio-сервера. +Якщо вашому серверу MCP справді потрібна одна із заблокованих змінних, +встановіть її в процесі хоста Gateway, а не в `env` сервера stdio. ### Транспорт SSE / HTTP Підключається до віддаленого сервера MCP через HTTP Server-Sent Events. -| Field | Description | -| --------------------- | ---------------------------------------------------------------- | -| `url` | URL HTTP або HTTPS віддаленого сервера (обов’язково) | -| `headers` | Необов’язкове відображення ключ-значення HTTP-заголовків (наприклад, токенів автентифікації) | -| `connectionTimeoutMs` | Тайм-аут підключення для сервера в мс (необов’язково) | +| Field | Description | +| --------------------- | --------------------------------------------------------------- | +| `url` | URL HTTP або HTTPS віддаленого сервера (обов’язково) | +| `headers` | Необов’язкова карта HTTP-заголовків ключ-значення (наприклад, токени auth) | +| `connectionTimeoutMs` | Тайм-аут підключення для сервера в мс (необов’язково) | Приклад: @@ -489,13 +504,13 @@ OpenClaw відхиляє ключі env запуску інтерпретато ### Транспорт Streamable HTTP -`streamable-http` — це додатковий варіант транспорту поряд із `sse` і `stdio`. Він використовує HTTP-streaming для двонаправленого зв’язку з віддаленими серверами MCP. +`streamable-http` — це додатковий варіант транспорту поряд із `sse` і `stdio`. Він використовує HTTP streaming для двостороннього зв’язку з віддаленими серверами MCP. | Field | Description | | --------------------- | -------------------------------------------------------------------------------------- | | `url` | URL HTTP або HTTPS віддаленого сервера (обов’язково) | -| `transport` | Встановіть `"streamable-http"`, щоб вибрати цей транспорт; якщо його не вказано, OpenClaw використовує `sse` | -| `headers` | Необов’язкове відображення ключ-значення HTTP-заголовків (наприклад, токенів автентифікації) | +| `transport` | Встановіть `"streamable-http"` для вибору цього транспорту; якщо параметр пропущено, OpenClaw використовує `sse` | +| `headers` | Необов’язкова карта HTTP-заголовків ключ-значення (наприклад, токени auth) | | `connectionTimeoutMs` | Тайм-аут підключення для сервера в мс (необов’язково) | Приклад: @@ -517,23 +532,24 @@ OpenClaw відхиляє ключі env запуску інтерпретато } ``` -Ці команди керують лише збереженою конфігурацією. Вони не запускають міст каналу, -не відкривають живий сеанс клієнта MCP і не доводять, що цільовий сервер доступний. +Ці команди керують лише збереженою конфігурацією. Вони не запускають міст +каналу, не відкривають живий сеанс клієнта MCP і не доводять, що цільовий +сервер доступний. ## Поточні обмеження -Ця сторінка документує міст у поточному вигляді. +Ця сторінка документує міст у тому вигляді, у якому його постачають сьогодні. Поточні обмеження: -- виявлення розмов залежить від наявних метаданих маршрутів сеансів Gateway -- немає загального push-протоколу, окрім адаптера, специфічного для Claude -- інструментів редагування повідомлень або реакцій поки немає -- транспорт HTTP/SSE/streamable-http підключається до одного віддаленого сервера; мультиплексованого upstream поки немає -- `permissions_list_open` включає лише погодження, які спостерігалися, поки міст +- виявлення розмов залежить від наявних метаданих маршруту сеансу Gateway +- немає загального push-протоколу поза специфічним для Claude адаптером +- інструментів для редагування повідомлень або реакцій поки що немає +- транспорт HTTP/SSE/streamable-http підключається до одного віддаленого сервера; multiplexed upstream поки що немає +- `permissions_list_open` включає лише погодження, які спостерігалися, поки міст був підключений ## Пов’язане - [Довідник CLI](/uk/cli) -- [Plugins](/uk/cli/plugins) +- [Плагіни](/uk/cli/plugins) diff --git a/docs/uk/help/testing-live.md b/docs/uk/help/testing-live.md index 84331c94b..8b30e7cfc 100644 --- a/docs/uk/help/testing-live.md +++ b/docs/uk/help/testing-live.md @@ -1,35 +1,35 @@ --- read_when: - - Запуск перевірок smoke для живої матриці моделей / бекенду CLI / ACP / медіапровайдера + - Запуск живих smoke-тестів матриці моделей / бекенду CLI / ACP / медіапровайдера - Налагодження визначення облікових даних для живих тестів - - Додавання нового живого тесту, специфічного для провайдера + - Додавання нового живого тесту для конкретного провайдера sidebarTitle: Live tests -summary: 'Живі (із зверненням до мережі) тести: матриця моделей, бекенди CLI, ACP, медіапровайдери, облікові дані' +summary: 'Живі тести (із зверненням до мережі): матриця моделей, бекенди CLI, ACP, медіапровайдери, облікові дані' title: 'Тестування: живі набори тестів' x-i18n: - generated_at: "2026-04-25T12:43:16Z" + generated_at: "2026-04-25T20:40:00Z" model: gpt-5.4 provider: openai - source_hash: b9b2c2954eddd1b911dde5bb3a834a6f9429c91429f3fb07a509eec80183cc52 + source_hash: 72e98c2ad8a745254664e72b8ef99e617444e59f0b27785b3670bff2538970c4 source_path: help/testing-live.md workflow: 15 --- -Щоб швидко ознайомитися зі стартом, раннерами QA, наборами unit/integration тестів і Docker-потоками, див. -[Тестування](/uk/help/testing). На цій сторінці описано **живі** (із зверненням до мережі) набори тестів: -матриця моделей, бекенди CLI, ACP і живі тести медіапровайдерів, а також -обробка облікових даних. +Для швидкого старту, QA-ранерів, unit/integration наборів тестів і Docker-потоків див. +[Тестування](/uk/help/testing). Ця сторінка охоплює **живі** (із зверненням до мережі) набори тестів: +матрицю моделей, бекенди CLI, ACP і живі тести медіапровайдерів, а також +обробку облікових даних. -## Живе: локальні команди smoke для профілю +## Живі: локальні команди smoke-тестів профілю -Виконайте `source ~/.profile` перед довільними живими перевірками, щоб ключі провайдерів і локальні шляхи -до інструментів відповідали вашій оболонці: +Виконайте source для `~/.profile` перед ad hoc живими перевірками, щоб ключі провайдерів і шляхи локальних інструментів +відповідали вашій оболонці: ```bash source ~/.profile ``` -Безпечна медіа smoke-перевірка: +Безпечний медіа smoke-тест: ```bash pnpm openclaw infer tts convert --local --json \ @@ -37,131 +37,131 @@ pnpm openclaw infer tts convert --local --json \ --output /tmp/openclaw-live-smoke.mp3 ``` -Безпечна smoke-перевірка готовності голосового дзвінка: +Безпечний smoke-тест готовності голосового дзвінка: ```bash pnpm openclaw voicecall setup --json pnpm openclaw voicecall smoke --to "+15555550123" ``` -`voicecall smoke` — це сухий запуск, якщо також не вказано `--yes`. Використовуйте `--yes` лише -тоді, коли ви свідомо хочете здійснити реальний сповіщувальний дзвінок. Для Twilio, Telnyx і -Plivo успішна перевірка готовності вимагає публічної URL-адреси Webhook; локальні резервні варіанти -на основі loopback/приватної мережі навмисно відхиляються. +`voicecall smoke` — це пробний запуск, якщо також не вказано `--yes`. Використовуйте `--yes` лише тоді, +коли ви навмисно хочете здійснити справжній дзвінок-сповіщення. Для Twilio, Telnyx і +Plivo успішна перевірка готовності вимагає публічного URL Webhook; резервні варіанти лише для локального +loopback/приватного доступу навмисно відхиляються. -## Живе: повний перегляд можливостей Android Node +## Живі: огляд можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яку наразі оголошує** підключений Android Node, і перевірити поведінку контракту команди. +- Мета: викликати **кожну команду, що зараз оголошена** підключеним Android Node, і перевірити поведінку контракту команд. - Обсяг: - - Попередньо підготовлене/ручне налаштування (набір тестів не встановлює/не запускає/не спарює застосунок). - - Перевірка `node.invoke` у Gateway для вибраного Android Node, команда за командою. -- Потрібне попереднє налаштування: - - Застосунок Android уже підключено та спарено з Gateway. + - Попередньо підготовлене/ручне налаштування (набір тестів не встановлює/не запускає/не з’єднує застосунок). + - Перевірка `node.invoke` шлюзу команда за командою для вибраного Android Node. +- Обов’язкове попереднє налаштування: + - Android-застосунок уже підключений і з’єднаний із Gateway. - Застосунок утримується на передньому плані. - - Для можливостей, які мають пройти перевірку, надано дозволи/згоду на захоплення. + - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте пройти. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Повні подробиці налаштування Android: [Android App](/uk/platforms/android) +- Повні відомості про налаштування Android: [Android App](/uk/platforms/android) -## Живе: smoke моделей (ключі профілю) +## Живі: smoke-тест моделей (ключі профілю) -Живі тести поділено на два шари, щоб ми могли ізолювати збої: +Живі тести поділено на два рівні, щоб ми могли ізолювати збої: -- «Пряма модель» показує, чи провайдер/модель взагалі може відповісти з наданим ключем. -- «Smoke Gateway» показує, чи працює для цієї моделі повний конвеєр Gateway+агента (сесії, історія, інструменти, політика sandbox тощо). +- «Direct model» показує, чи провайдер/модель взагалі можуть відповісти з наданим ключем. +- «Gateway smoke» показує, чи повністю працює конвеєр Gateway+агента для цієї моделі (сеанси, історія, інструменти, політика sandbox тощо). -### Шар 1: пряме завершення моделі (без Gateway) +### Рівень 1: пряме завершення моделі (без Gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані - - Виконати невелике завершення для кожної моделі (і цільові регресійні перевірки, де потрібно) + - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані + - Виконати невелике завершення для кожної моделі (і цільові регресійні перевірки, де це потрібно) - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви викликаєте Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб дійсно запустити цей набір тестів; інакше його буде пропущено, щоб `pnpm test:live` залишався зосередженим на smoke Gateway -- Як вибирати моделі: + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) +- Встановіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запустити цей набір тестів; інакше він пропускається, щоб `pnpm test:live` залишався зосередженим на smoke-тестах Gateway +- Як вибрати моделі: - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для сучасного allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Для переглядів modern/all за замовчуванням використовується підібране обмеження з високою інформативністю; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного перегляду modern або додатне число для меншого обмеження. - - Для вичерпних переглядів використовується `OPENCLAW_LIVE_TEST_TIMEOUT_MS` як тайм-аут усього тесту прямої моделі. За замовчуванням: 60 хвилин. - - За замовчуванням перевірки прямої моделі виконуються з паралелізмом 20; щоб перевизначити це, установіть `OPENCLAW_LIVE_MODEL_CONCURRENCY`. -- Як вибирати провайдерів: + - Для проходів modern/all за замовчуванням використовується підібране обмеження з високим сигналом; встановіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного сучасного проходу або додатне число для меншого обмеження. + - Для вичерпних проходів використовується `OPENCLAW_LIVE_TEST_TIMEOUT_MS` як тайм-аут усього тесту direct-model. За замовчуванням: 60 хвилин. + - Проби direct-model за замовчуванням виконуються з паралелізмом 20; щоб перевизначити, встановіть `OPENCLAW_LIVE_MODEL_CONCURRENCY`. +- Як вибрати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: сховище профілів і резервні значення env - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** + - За замовчуванням: сховище профілів і резервні варіанти з env + - Встановіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - - Відокремлює «API провайдера зламане / ключ недійсний» від «конвеєр агента Gateway зламаний» - - Містить невеликі ізольовані регресії (приклад: повторне відтворення міркувань OpenAI Responses/Codex Responses + потоки виклику інструментів) + - Відокремлює «API провайдера зламаний / ключ недійсний» від «конвеєр агента Gateway зламаний» + - Містить невеликі, ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки викликів інструментів) -### Шар 2: smoke Gateway + dev-агента (що насправді робить "@openclaw") +### Рівень 2: smoke-тест Gateway + dev-агента (те, що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Підняти внутрішньопроцесний Gateway - - Створити/змінити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) + - Підняти Gateway in-process + - Створити/оновити сеанс `agent:dev:*` (перевизначення моделі для кожного запуску) - Перебрати моделі з ключами й перевірити: - «змістовну» відповідь (без інструментів) - - що працює реальний виклик інструмента (`read` probe) - - необов’язкові додаткові перевірки інструментів (`exec+read` probe) - - що регресійні шляхи OpenAI (лише виклик інструмента → подальший крок) продовжують працювати -- Подробиці probe (щоб ви могли швидко пояснювати збої): - - `read` probe: тест записує файл із nonce у робочому просторі й просить агента `read` прочитати його та повернути nonce у відповіді. - - `exec+read` probe: тест просить агента `exec` записати nonce у тимчасовий файл, а потім `read` прочитати його назад. - - image probe: тест додає згенерований PNG (cat + випадковий код) й очікує, що модель поверне `cat `. + - що працює реальний виклик інструмента (проба читання) + - необов’язкові додаткові проби інструментів (проба exec+read) + - що регресійні шляхи OpenAI (лише tool-call → наступний виклик) продовжують працювати +- Відомості про проби (щоб ви могли швидко пояснювати збої): + - проба `read`: тест записує файл із nonce у робочий простір і просить агента `read` його та повернути nonce у відповіді. + - проба `exec+read`: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. + - проба зображення: тест додає згенерований PNG (кіт + випадковий код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви викликаєте Vitest напряму) -- Як вибирати моделі: + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) +- Як вибрати моделі: - За замовчуванням: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для сучасного allowlist - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір - - Для переглядів modern/all у Gateway за замовчуванням використовується підібране обмеження з високою інформативністю; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного перегляду modern або додатне число для меншого обмеження. -- Як вибирати провайдерів (уникнути сценарію «усе OpenRouter»): + - Для проходів modern/all Gateway за замовчуванням використовується підібране обмеження з високим сигналом; встановіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного сучасного проходу або додатне число для меншого обмеження. +- Як вибрати провайдерів (уникати «все з OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Перевірки інструментів і зображень у цьому живому тесті завжди ввімкнені: - - `read` probe + `exec+read` probe (навантажувальна перевірка інструментів) - - image probe виконується, коли модель оголошує підтримку вхідних зображень - - Потік (на високому рівні): - - Тест генерує крихітний PNG із “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) +- Проби інструментів і зображень у цьому живому тесті завжди увімкнені: + - проба `read` + проба `exec+read` (навантажувальна перевірка інструментів) + - проба зображення виконується, коли модель оголошує підтримку введення зображень + - Потік (високорівнево): + - Тест генерує крихітний PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - Gateway розбирає вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Вбудований агент передає мультимодальне повідомлення користувача моделі - - Перевірка: відповідь містить `cat` + код (стійкість до OCR: незначні помилки допускаються) + - Вбудований агент пересилає мультимодальне повідомлення користувача моделі + - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) -Порада: щоб побачити, що ви можете тестувати на своїй машині (і точні ідентифікатори `provider/model`), виконайте: +Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Живе: smoke бекенду CLI (Claude, Codex, Gemini або інші локальні CLI) +## Живі: smoke-тест бекенду CLI (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + агента з використанням локального бекенду CLI, не торкаючись вашої типової конфігурації. -- Типові параметри smoke для конкретного бекенду містяться у визначенні `cli-backend.ts` розширення-власника. +- Мета: перевірити конвеєр Gateway + агента з використанням локального бекенду CLI, не торкаючись вашої стандартної конфігурації. +- Типові параметри smoke-тестів для конкретного бекенду зберігаються у визначенні `cli-backend.ts` у відповідному extension. - Увімкнення: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо ви викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Типові значення: - - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image походить із метаданих plugin бекенду CLI-власника. +- За замовчуванням: + - Провайдер/модель за замовчуванням: `claude-cli/claude-sonnet-4-6` + - Поведінка команди/аргументів/зображень береться з метаданих plugin відповідного бекенду CLI. - Перевизначення (необов’язково): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальне вкладення зображення (шляхи інжектуються в prompt). У рецептах Docker це типово вимкнено, якщо явно не запитано. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість інжекції в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати справжнє вкладення-зображення (шляхи впроваджуються в prompt). У рецептах Docker це типово вимкнено, якщо явно не запитано. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість впровадження в prompt. - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати тим, як передаються аргументи зображень, коли встановлено `IMAGE_ARG`. - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити потік відновлення. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1`, щоб увімкнути перевірку безперервності тієї самої сесії Claude Sonnet -> Opus, коли вибрана модель підтримує ціль перемикання. У рецептах Docker це типово вимкнено для загальної надійності. - - `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1`, щоб увімкнути loopback-перевірку MCP/інструментів. У рецептах Docker це типово вимкнено, якщо явно не запитано. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1`, щоб увімкнути пробу безперервності того самого сеансу Claude Sonnet -> Opus, коли вибрана модель підтримує ціль перемикання. У рецептах Docker це типово вимкнено для загальної надійності. + - `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1`, щоб увімкнути loopback-пробу MCP/інструментів. У рецептах Docker це типово вимкнено, якщо явно не запитано. Приклад: @@ -171,13 +171,25 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:live src/gateway/gateway-cli-backend.live.test.ts ``` +Недорогий smoke-тест конфігурації Gemini MCP: + +```bash +OPENCLAW_LIVE_TEST=1 \ + pnpm test:live src/agents/cli-runner/bundle-mcp.gemini.live.test.ts +``` + +Це не просить Gemini згенерувати відповідь. Тест записує ті самі системні +налаштування, які OpenClaw надає Gemini, а потім запускає `gemini --debug mcp list`, щоб довести, +що збережений сервер `transport: "streamable-http"` нормалізується до HTTP-форми Gemini MCP +і може підключатися. + Рецепт Docker: ```bash pnpm test:docker:live-cli-backend ``` -Docker-рецепти для одного провайдера: +Рецепти Docker для окремих провайдерів: ```bash pnpm test:docker:live-cli-backend:claude @@ -188,29 +200,29 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker runner розташовано в `scripts/test-live-cli-backend-docker.sh`. -- Він запускає живу smoke-перевірку CLI-бекенду всередині Docker-образу репозиторію від імені непривілейованого користувача `node`. -- Він визначає метадані CLI smoke з розширення-власника, а потім встановлює відповідний Linux-пакет CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований доступний для запису префікс за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` вимагає переносиму OAuth-підписку Claude Code через `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він доводить прямий `claude -p` у Docker, а потім виконує два ходи Gateway CLI-backend без збереження env-змінних ключів Anthropic API. Ця гілка підписки типово вимикає перевірки Claude MCP/інструментів і зображень, тому що Claude наразі маршрутизує використання сторонніх застосунків через тарифікацію за додаткове використання замість звичайних лімітів плану підписки. -- Жива smoke-перевірка CLI-бекенду тепер виконує однаковий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик інструмента MCP `cron`, перевірений через Gateway CLI. -- Типова smoke-перевірка Claude також змінює сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає раніше зроблену нотатку. +- Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. +- Він запускає живий smoke-тест CLI-бекенду всередині Docker-образу репозиторію від імені непривілейованого користувача `node`. +- Він визначає метадані CLI smoke-тесту з відповідного extension, а потім установлює відповідний пакет Linux CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований доступний для запису префікс у `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` вимагає переносимого OAuth підписки Claude Code через або `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він підтверджує прямий `claude -p` у Docker, а потім запускає два ходи CLI-бекенду Gateway без збереження змінних середовища ключів Anthropic API. Ця доріжка підписки типово вимикає проби Claude MCP/інструментів і зображень, оскільки Claude зараз маршрутизує використання сторонніх застосунків через оплату додаткового використання, а не звичайні ліміти тарифного плану підписки. +- Живий smoke-тест CLI-бекенду тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображень, а потім виклик інструмента MCP `cron`, перевірений через шлюзовий CLI. +- Типовий smoke-тест Claude також оновлює сеанс із Sonnet до Opus і перевіряє, що відновлений сеанс усе ще пам’ятає попередню нотатку. -## Живе: smoke прив’язки ACP (`/acp spawn ... --bind here`) +## Живі: smoke-тест ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік прив’язки розмови ACP з живим ACP-агентом: +- Мета: перевірити реальний потік ACP conversation-bind із живим ACP-агентом: - надіслати `/acp spawn --bind here` - прив’язати синтетичну розмову каналу повідомлень на місці - - надіслати звичайний подальший крок у цій самій розмові - - перевірити, що подальший крок потрапив у транскрипт прив’язаної сесії ACP + - надіслати звичайне наступне повідомлення в тій самій розмові + - перевірити, що наступне повідомлення потрапляє до транскрипту прив’язаного сеансу ACP - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Типові значення: +- За замовчуванням: - ACP-агенти в Docker: `claude,codex,gemini` - ACP-агент для прямого `pnpm test:live ...`: `claude` - - Синтетичний канал: контекст розмови в стилі Slack DM - - Бекенд ACP: `acpx` + - Синтетичний канал: контекст розмови у стилі Slack DM + - ACP-бекенд: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -223,8 +235,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_REQUIRE_TRANSCRIPT=1` - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.2` - Примітки: - - Ця гілка використовує поверхню gateway `chat.send` з адміністративними полями synthetic originating-route, щоб тести могли додавати контекст каналу повідомлень без імітації зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного ACP harness-агента. + - Ця доріжка використовує поверхню gateway `chat.send` з синтетичними полями originating-route лише для адміністратора, щоб тести могли додавати контекст каналу повідомлень без удавання зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного ACP harness-агента. Приклад: @@ -234,13 +246,13 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:live src/gateway/gateway-acp-bind.live.test.ts ``` -Docker-рецепт: +Рецепт Docker: ```bash pnpm test:docker:live-acp-bind ``` -Docker-рецепти для одного агента: +Рецепти Docker для окремих агентів: ```bash pnpm test:docker:live-acp-bind:claude @@ -251,37 +263,37 @@ pnpm test:docker:live-acp-bind:opencode Примітки щодо Docker: -- Docker runner розташовано в `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він запускає smoke-перевірку ACP bind для сукупних живих CLI-агентів послідовно: `claude`, `codex`, потім `gemini`. +- Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він запускає ACP bind smoke-тест послідовно для сукупних живих CLI-агентів: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode`, щоб звузити матрицю. -- Він виконує `source ~/.profile`, готує відповідні матеріали автентифікації CLI в контейнері, а потім встановлює запитаний живий CLI (`@anthropic-ai/claude-code`, `@openai/codex`, `@google/gemini-cli` або `opencode-ai`), якщо його немає. Сам бекенд ACP — це вбудований пакет `acpx/runtime` з plugin `acpx`. -- Варіант Docker для OpenCode — це сувора регресійна гілка для одного агента. Після виконання `source ~/.profile` він записує тимчасову типову модель `OPENCODE_CONFIG_CONTENT` з `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL` (типово `opencode/kimi-k2.6`), а `pnpm test:docker:live-acp-bind:opencode` вимагає прив’язаного транскрипту асистента замість прийняття загального пропуску після bind. -- Прямі виклики CLI `acpx` — це лише ручний/обхідний шлях для порівняння поведінки поза Gateway. Docker smoke-перевірка ACP bind перевіряє вбудований бекенд runtime `acpx` в OpenClaw. +- Він виконує source для `~/.profile`, переносить відповідні автентифікаційні дані CLI до контейнера, а потім установлює запитаний живий CLI (`@anthropic-ai/claude-code`, `@openai/codex`, `@google/gemini-cli` або `opencode-ai`), якщо його немає. Сам ACP-бекенд — це вбудований пакет середовища виконання `acpx/runtime` із plugin `acpx`. +- Варіант Docker для OpenCode — це сувора регресійна доріжка для одного агента. Після виконання source для `~/.profile` він записує тимчасову типову модель `OPENCODE_CONFIG_CONTENT` із `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL` (типово `opencode/kimi-k2.6`), а `pnpm test:docker:live-acp-bind:opencode` вимагає транскрипт прив’язаного помічника замість прийняття загального пропуску після bind. +- Прямі виклики CLI `acpx` — це лише ручний/обхідний шлях для порівняння поведінки поза Gateway. Docker ACP bind smoke-тест перевіряє вбудований бекенд середовища виконання `acpx` OpenClaw. -## Живе: smoke Codex app-server harness +## Живі: smoke-тест Codex app-server harness -- Мета: перевірити harness Codex, що належить plugin, через звичайний +- Мета: перевірити harness Codex, яким володіє plugin, через звичайний метод gateway `agent`: - завантажити вбудований plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - - надіслати перший хід gateway agent до `openai/gpt-5.2` із примусово вибраним harness Codex - - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що потік + - надіслати перший хід gateway agent до `openai/gpt-5.2` із примусовим Codex harness + - надіслати другий хід у той самий сеанс OpenClaw і перевірити, що потік app-server може відновитися - - виконати `/codex status` і `/codex models` через той самий командний - шлях gateway - - за потреби виконати дві перевірки оболонки з підвищеними правами, схвалені Guardian: одну безпечну - команду, яку слід дозволити, і одне фіктивне вивантаження секрету, яке має бути + - виконати `/codex status` і `/codex models` через той самий шлях + команд gateway + - за потреби виконати дві ескальовані shell-проби, перевірені Guardian: одну нешкідливу + команду, яку слід схвалити, і одне фальшиве вивантаження секрету, яке має бути відхилене, щоб агент перепитав - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `openai/gpt-5.2` -- Необов’язкова image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Необов’язкова MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Необов’язкова Guardian probe: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- Для smoke встановлюється `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex - harness не міг пройти, непомітно переключившись на резервний PI. +- Необов’язкова проба зображення: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Необов’язкова проба MCP/інструментів: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Необов’язкова проба Guardian: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` +- Smoke-тест установлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex + harness не міг пройти, непомітно переключившись на Pi. - Автентифікація: автентифікація Codex app-server із локального входу до підписки Codex. Docker - smoke-перевірки також можуть надавати `OPENAI_API_KEY` для не-Codex перевірок, де це застосовно, + smoke-тести також можуть надавати `OPENAI_API_KEY` для проб не-Codex, де це доречно, а також за потреби скопійовані `~/.codex/auth.json` і `~/.codex/config.toml`. Локальний рецепт: @@ -296,7 +308,7 @@ OPENCLAW_LIVE_CODEX_HARNESS=1 \ pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts ``` -Docker-рецепт: +Рецепт Docker: ```bash source ~/.profile @@ -305,73 +317,73 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker runner розташовано в `scripts/test-live-codex-harness-docker.sh`. -- Він виконує `source` для змонтованого `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - автентифікації CLI Codex за наявності, встановлює `@openai/codex` у доступний для запису змонтований npm - префікс, готує дерево вихідного коду, а потім запускає лише живий тест Codex-harness. -- Docker типово вмикає image, MCP/tool і Guardian probe. Установіть - `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або +- Docker-ранер розташований у `scripts/test-live-codex-harness-docker.sh`. +- Він виконує source для змонтованого `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + автентифікації CLI Codex, якщо вони є, установлює `@openai/codex` у доступний для запису змонтований npm + prefix, готує дерево вихідного коду, а потім запускає лише живий тест Codex-harness. +- Docker типово вмикає проби зображень, MCP/інструментів і Guardian. Установіть + `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0`, `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` або `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий налагоджувальний запуск. - Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, що відповідає конфігурації живого - тесту, тож застарілі псевдоніми або резервний PI не можуть приховати регресію + тесту, тому застарілі псевдоніми або резервний перехід на Pi не можуть приховати регресію Codex harness. ### Рекомендовані живі рецепти -Вузькі, явні allowlist — найшвидші й найменш схильні до збоїв: +Вузькі, явні allowlist — найшвидші та найменш нестабільні: - Одна модель, напряму (без Gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts` -- Одна модель, smoke Gateway: +- Одна модель, Gateway smoke-тест: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Виклик інструментів через кількох провайдерів: +- Виклики інструментів для кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,deepseek/deepseek-v4-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Фокус на Google (ключ API Gemini + Antigravity): - Gemini (ключ API): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Жива smoke-перевірка адаптивного мислення Google: - - Якщо локальні ключі містяться в профілі оболонки: `source ~/.profile` - - Динамічний типовий Gemini 3: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000` - - Динамічний бюджет Gemini 2.5: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000` +- Smoke-тест adaptive thinking для Google: + - Якщо локальні ключі зберігаються в профілі оболонки: `source ~/.profile` + - Динамічний режим за замовчуванням для Gemini 3: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000` + - Динамічний бюджет для Gemini 2.5: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000` Примітки: -- `google/...` використовує API Gemini (ключ API). -- `google-antigravity/...` використовує OAuth-міст Antigravity (кінцева точка агента в стилі Cloud Code Assist). +- `google/...` використовує Gemini API (ключ API). +- `google-antigravity/...` використовує міст Antigravity OAuth (кінцева точка агента у стилі Cloud Code Assist). - `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості інструментів). -- API Gemini проти Gemini CLI: - - API: OpenClaw викликає розміщений Google API Gemini через HTTP (автентифікація ключем API / профілем); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw викликає локальний двійковий файл `gemini`; він має власну автентифікацію і може поводитися інакше (streaming/підтримка інструментів/розходження версій). +- Gemini API проти Gemini CLI: + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (ключ API / автентифікація профілю); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw викликає локальний двійковий файл `gemini`; він має власну автентифікацію та може поводитися інакше (streaming/підтримка інструментів/розбіжність версій). -## Живе: матриця моделей (що ми покриваємо) +## Живі: матриця моделей (що ми покриваємо) -Фіксованого «списку моделей CI» немає (живі тести — opt-in), але це **рекомендовані** моделі, які слід регулярно покривати на машині розробника з ключами. +Фіксованого «списку моделей CI» немає (живі тести запускаються за бажанням), але це **рекомендовані** моделі, які варто регулярно покривати на машині розробника з ключами. -### Сучасний набір smoke (виклик інструментів + зображення) +### Сучасний набір smoke-тестів (виклики інструментів + зображення) -Це запуск «поширених моделей», який ми очікуємо зберігати працездатним: +Це запуск «поширених моделей», який, як ми очікуємо, має й надалі працювати: -- OpenAI (не Codex): `openai/gpt-5.2` -- OpenAI Codex OAuth: `openai-codex/gpt-5.2` +- OpenAI (не-Codex): `openai/gpt-5.2` +- OAuth OpenAI Codex: `openai-codex/gpt-5.2` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) -- Google (API Gemini): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) +- Google (Gemini API): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` і `google-antigravity/gemini-3-flash` - DeepSeek: `deepseek/deepseek-v4-flash` і `deepseek/deepseek-v4-pro` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запустіть smoke Gateway з інструментами + зображенням: +Запустити Gateway smoke-тест з інструментами + зображенням: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,deepseek/deepseek-v4-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) +### Базовий рівень: виклики інструментів (Read + необов’язковий Exec) -Виберіть щонайменше одну модель для кожного сімейства провайдерів: +Виберіть щонайменше одну модель на сімейство провайдерів: - OpenAI: `openai/gpt-5.2` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -382,77 +394,77 @@ pnpm test:docker:live-codex-harness Необов’язкове додаткове покриття (було б добре мати): -- xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яку у вас ввімкнено) +- xAI: `xai/grok-4` (або найновіша доступна версія) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою «tools», яку у вас увімкнено) - Cerebras: `cerebras/`… (якщо маєте доступ) -- LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) +- LM Studio: `lmstudio/`… (локально; виклики інструментів залежать від режиму API) ### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) -Додайте щонайменше одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (варіанти Claude/Gemini/OpenAI із підтримкою vision тощо), щоб перевірити image probe. +Додайте щонайменше одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (варіанти Claude/Gemini/OpenAI із підтримкою vision тощо), щоб перевірити пробу зображення. ### Агрегатори / альтернативні Gateway -Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: +Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою інструментів і зображень) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити до живої матриці (якщо у вас є облікові дані/конфігурація): +Інші провайдери, яких можна додати до живої матриці (якщо у вас є облікові дані/конфігурація): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (власні кінцеві точки): `minimax` (хмара/API), а також будь-який OpenAI/Anthropic-сумісний проксі (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (власні кінцеві точки): `minimax` (хмара/API), а також будь-який проксі, сумісний з OpenAI/Anthropic (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко фіксувати в документації «усі моделі». Авторитетний список — це все, що повертає `discoverModels(...)` на вашій машині, плюс усі доступні ключі. +Порада: не намагайтеся жорстко закодувати в документації «всі моделі». Авторитетний список — це те, що `discoverModels(...)` повертає на вашій машині, разом із ключами, які доступні. ## Облікові дані (ніколи не комітьте) Живі тести виявляють облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, живі тести повинні знаходити ті самі ключі. +- Якщо CLI працює, живі тести мають знаходити ті самі ключі. - Якщо живий тест каже «немає облікових даних», налагоджуйте це так само, як ви налагоджували б `openclaw models list` / вибір моделі. -- Профілі автентифікації для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це у живих тестах означає «ключі профілю») +- Профілі автентифікації для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це в живих тестах означає «ключі профілю») - Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Застарілий каталог стану: `~/.openclaw/credentials/` (копіюється до staged live home за наявності, але це не основне сховище ключів профілю) -- Локальні живі запуски типово копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасового test home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` прибираються, щоб перевірки не торкалися вашого реального робочого простору хоста. +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staging live home, якщо присутній, але не є основним сховищем ключів профілю) +- Локальні живі запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасового тестового home; staging live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб проби не працювали у вашому реальному робочому просторі хоста. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте наведені нижче Docker runner-и (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на ключі env (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). -## Живе: Deepgram (транскрибування аудіо) +## Живі тести Deepgram (транскрибування аудіо) - Тест: `extensions/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` -## Живе: план кодування BytePlus +## Живий тест BytePlus coding plan - Тест: `extensions/byteplus/live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Живе: медіа workflow ComfyUI +## Живі медіатести workflow ComfyUI - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє вбудовані шляхи comfy для зображень, відео і `music_generate` + - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` - Пропускає кожну можливість, якщо не налаштовано `plugins.entries.comfy.config.` - Корисно після змін у надсиланні workflow comfy, опитуванні, завантаженнях або реєстрації plugin -## Живе: генерація зображень +## Живі тести генерації зображень - Тест: `test/image-generation.runtime.live.test.ts` - Команда: `pnpm test:live test/image-generation.runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Обсяг: - Перелічує кожен зареєстрований plugin провайдера генерації зображень - - Завантажує відсутні env-змінні провайдерів із вашої login shell (`~/.profile`) перед перевіркою + - Завантажує відсутні env-змінні провайдерів із вашої оболонки входу (`~/.profile`) перед пробами - За замовчуванням використовує живі/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Запускає кожного налаштованого провайдера через спільний runtime генерації зображень: + - Запускає кожного налаштованого провайдера через спільне середовище виконання генерації зображень: - `:generate` - `:edit`, коли провайдер оголошує підтримку редагування -- Поточні вбудовані провайдери, які покриваються: +- Поточні вбудовані провайдери, що покриваються: - `fal` - `google` - `minimax` @@ -465,10 +477,10 @@ pnpm test:docker:live-codex-harness - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише з env -Для шляху shipped CLI додайте smoke-перевірку `infer` після того, як живий тест -провайдера/runtime пройде: +Для шляху CLI, що постачається, додайте smoke-тест `infer` після того, як живий +тест провайдера/середовища виконання пройде: ```bash OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_INFER_CLI_TEST=1 pnpm test:live -- test/image-generation.infer-cli.live.test.ts @@ -480,77 +492,77 @@ openclaw infer image generate \ --json ``` -Це покриває розбір аргументів CLI, визначення config/default-agent, активацію вбудованого -plugin, відновлення залежностей bundled runtime на вимогу, спільний -runtime генерації зображень і живий запит до провайдера. +Це покриває розбір аргументів CLI, визначення конфігурації/типового агента, активацію вбудованих +plugin, відновлення вбудованих залежностей середовища виконання на вимогу, спільне +середовище виконання генерації зображень і живий запит до провайдера. -## Живе: генерація музики +## Живі тести генерації музики - Тест: `extensions/music-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Обсяг: - - Перевіряє спільний шлях bundled-провайдера генерації музики - - Наразі покриває Google і MiniMax - - Завантажує env-змінні провайдерів із вашої login shell (`~/.profile`) перед перевіркою + - Перевіряє спільний вбудований шлях провайдера генерації музики + - Наразі охоплює Google і MiniMax + - Завантажує env-змінні провайдерів із вашої оболонки входу (`~/.profile`) перед пробами - За замовчуванням використовує живі/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Запускає обидва оголошені режими runtime, коли вони доступні: + - Запускає обидва оголошені режими середовища виконання, коли вони доступні: - `generate` з вхідними даними лише у вигляді prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття у спільній гілці: + - Поточне покриття спільної доріжки: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий живий файл Comfy, не цей спільний перегляд + - `comfy`: окремий живий файл Comfy, а не цей спільний прохід - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.6"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише з env -## Живе: генерація відео +## Живі тести генерації відео - Тест: `extensions/video-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Обсяг: - - Перевіряє спільний шлях bundled-провайдера генерації відео - - За замовчуванням використовує безпечний для релізу шлях smoke: провайдери не-FAL, один запит text-to-video на провайдера, односекундний prompt із лобстером і обмеження операції для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) - - За замовчуванням пропускає FAL, оскільки затримка черги на боці провайдера може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно - - Завантажує env-змінні провайдерів із вашої login shell (`~/.profile`) перед перевіркою + - Перевіряє спільний вбудований шлях провайдера генерації відео + - За замовчуванням використовує безпечний для релізу шлях smoke-тесту: провайдери не-FAL, один запит text-to-video на провайдера, односекундний prompt про омара та обмеження операції для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) + - За замовчуванням пропускає FAL, оскільки затримка черги на стороні провайдера може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно + - Завантажує env-змінні провайдерів із вашої оболонки входу (`~/.profile`) перед пробами - За замовчуванням використовує живі/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки - Пропускає провайдерів без придатної автентифікації/профілю/моделі - За замовчуванням запускає лише `generate` - - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими transform, коли вони доступні: - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід зображення на основі buffer у спільному перегляді - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід відео на основі buffer у спільному перегляді - - Поточні провайдери `imageToVideo`, оголошені, але пропущені у спільному перегляді: - - `vydra`, тому що вбудований `veo3` підтримує лише text-to-video, а вбудований `kling` вимагає віддалену URL-адресу зображення - - Специфічне для провайдера покриття Vydra: + - Встановіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими перетворення, коли вони доступні: + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальне введення зображень із backing buffer у спільному проході + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальне введення відео із backing buffer у спільному проході + - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільному проході: + - `vydra`, оскільки вбудований `veo3` підтримує лише text, а вбудований `kling` вимагає віддалений URL зображення + - Покриття Vydra, специфічне для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс гілку `kling`, яка за замовчуванням використовує fixture віддаленої URL-адреси зображення + - цей файл запускає `veo3` text-to-video, а також доріжку `kling`, яка за замовчуванням використовує fixture із віддаленим URL зображення - Поточне живе покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні провайдери `videoToVideo`, оголошені, але пропущені у спільному перегляді: - - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають віддалені URL-адреси посилань `http(s)` / MP4 - - `google`, тому що поточна спільна гілка Gemini/Veo використовує локальний вхід на основі buffer, і цей шлях не приймається у спільному перегляді - - `openai`, тому що поточна спільна гілка не має гарантій доступу до video inpaint/remix, специфічних для org + - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільному проході: + - `alibaba`, `qwen`, `xai`, оскільки ці шляхи зараз вимагають віддалені URL-посилання `http(s)` / MP4 + - `google`, оскільки поточна спільна доріжка Gemini/Veo використовує локальне введення з backing buffer, а цей шлях не приймається у спільному проході + - `openai`, оскільки поточна спільна доріжка не гарантує доступ до video inpaint/remix, специфічний для org - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типового перегляду, зокрема FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити обмеження операції для кожного провайдера в агресивному smoke-запуску + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типового проходу, включно з FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції кожного провайдера для агресивного smoke-запуску - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише з env ## Harness для живих медіатестів - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні живі набори тестів для зображень, музики й відео через одну вбудовану точку входу репозиторію + - Запускає спільні живі набори тестів для зображень, музики й відео через один нативний для репозиторію entrypoint - Автоматично завантажує відсутні env-змінні провайдерів із `~/.profile` - - За замовчуванням автоматично звужує кожен набір тестів до провайдерів, для яких наразі є придатна автентифікація - - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і тихого режиму залишається узгодженою + - За замовчуванням автоматично звужує кожен набір тестів до провайдерів, які зараз мають придатну автентифікацію + - Повторно використовує `scripts/test-live.mjs`, тому поведінка Heartbeat і тихого режиму лишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -559,4 +571,4 @@ runtime генерації зображень і живий запит до пр ## Пов’язане -- [Тестування](/uk/help/testing) — набори unit, integration, QA і Docker тестів +- [Тестування](/uk/help/testing) — набори unit, integration, QA і Docker diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index 44203f267..0e8a1887b 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -1,122 +1,125 @@ --- read_when: - - Ви хочете використовувати комплектний app-server harness Codex - - Вам потрібні приклади конфігурації Codex harness - - Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість fallback до PI -summary: Запускайте вбудовані цикли агентів OpenClaw через комплектний app-server harness Codex -title: Codex harness + - Ви хочете використовувати комплектний harness app-server Codex + - Вам потрібні приклади конфігурації harness Codex + - Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість переходу до PI +summary: Запустіть вбудовані ходи агента OpenClaw через комплектний harness app-server Codex +title: harness Codex x-i18n: - generated_at: "2026-04-25T05:57:09Z" + generated_at: "2026-04-25T20:40:02Z" model: gpt-5.4 provider: openai - source_hash: 5458c8501338361a001c3457235d2a9abfc7e24709f2e50185bc31b92bbadb3b + source_hash: a5d14d2482b0c5eed5481c42db70e881f88e590dd109244fbb131a2e0d8ec239 source_path: plugins/codex-harness.md workflow: 15 --- -Комплектний Plugin `codex` дає змогу OpenClaw запускати вбудовані цикли агента через -app-server Codex замість вбудованого harness PI. +Комплектний Plugin `codex` дає OpenClaw змогу запускати вбудовані ходи агента через +Codex app-server замість вбудованого harness Pi. -Використовуйте це, якщо хочете, щоб Codex керував низькорівневою сесією агента: виявленням -model, нативним відновленням thread, нативною Compaction і виконанням app-server. -OpenClaw усе ще керує каналами чату, файлами сесій, вибором model, tools, -approvals, доставкою медіа та видимим дзеркалом transcript. +Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням +моделей, нативним відновленням потоків, нативною Compaction і виконанням через app-server. +OpenClaw, як і раніше, керує каналами чату, файлами сесій, вибором моделей, інструментами, +погодженнями, доставкою медіа та видимим дзеркалом транскрипту. -Якщо ви лише орієнтуєтеся, почніть із -[Agent runtimes](/uk/concepts/agent-runtimes). Коротка версія така: -`openai/gpt-5.5` — це посилання на model, `codex` — це runtime, а Telegram, +Якщо ви намагаєтеся зорієнтуватися, почніть із +[середовищ виконання агентів](/uk/concepts/agent-runtimes). Коротка версія така: +`openai/gpt-5.5` — це посилання на модель, `codex` — це середовище виконання, а Telegram, Discord, Slack або інший канал залишається поверхнею комунікації. -Нативні цикли Codex зберігають hooks Plugin OpenClaw як публічний рівень сумісності. -Це внутрішньопроцесні hooks OpenClaw, а не командні hooks Codex `hooks.json`: +Нативні ходи Codex зберігають хуки Plugin OpenClaw як публічний шар сумісності. +Це внутрішньопроцесні хуки OpenClaw, а не командні хуки Codex `hooks.json`: - `before_prompt_build` - `before_compaction`, `after_compaction` - `llm_input`, `llm_output` - `before_tool_call`, `after_tool_call` -- `before_message_write` для дзеркальних записів transcript +- `before_message_write` для дзеркальних записів транскрипту - `agent_end` -Plugins також можуть реєструвати runtime-neutral middleware результатів tools, щоб переписувати -динамічні результати tools OpenClaw після того, як OpenClaw виконає tool, і перед тим, -як результат буде повернено до Codex. Це окремо від публічного -hook Plugin `tool_result_persist`, який перетворює записи результатів tools у transcript, що належать OpenClaw. +Plugins також можуть реєструвати нейтральне до середовища виконання middleware результатів інструментів, щоб переписувати +результати динамічних інструментів OpenClaw після того, як OpenClaw виконає інструмент, і до того, +як результат буде повернуто до Codex. Це окремо від публічного +хука Plugin `tool_result_persist`, який трансформує записи результатів інструментів +у транскрипті, що належать OpenClaw. -Про саму семантику hooks Plugin див. [Plugin hooks](/uk/plugins/hooks) -і [Plugin guard behavior](/uk/tools/plugin). +Щодо семантики самих хуків Plugin дивіться [хуки Plugin](/uk/plugins/hooks) +і [поведінку guard Plugin](/uk/tools/plugin). -Harness за замовчуванням вимкнено. Нові конфігурації мають зберігати посилання на model OpenAI +harness вимкнений за замовчуванням. Нові конфігурації мають зберігати посилання на моделі OpenAI у канонічному вигляді `openai/gpt-*` і явно примусово задавати -`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли вони -хочуть нативне виконання через app-server. Застарілі посилання на model `codex/*` усе ще автоматично вибирають -harness для сумісності, але застарілі префікси provider, підкріплені runtime, -не показуються як звичайні варіанти model/provider. +`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли +потрібне нативне виконання через app-server. Застарілі посилання на моделі `codex/*` і далі автоматично вибирають +harness для сумісності, але застарілі префікси провайдерів, підкріплені середовищем виконання, не +показуються як звичайні варіанти моделі/провайдера. -## Виберіть правильний префікс model +## Виберіть правильний префікс моделі -Маршрути сімейства OpenAI чутливі до префікса. Використовуйте `openai-codex/*`, якщо хочете -Codex OAuth через PI; використовуйте `openai/*`, якщо хочете прямий доступ до OpenAI API або -коли примусово використовуєте нативний app-server harness Codex: +Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли вам потрібен +OAuth Codex через Pi; використовуйте `openai/*`, коли вам потрібен прямий доступ до OpenAI API або +коли ви примусово використовуєте нативний harness Codex app-server: -| Посилання на model | Шлях runtime | Використовуйте, коли | -| --------------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------- | -| `openai/gpt-5.4` | provider OpenAI через plumbing OpenClaw/PI | Вам потрібен поточний прямий доступ до API OpenAI Platform з `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.5` | OAuth OpenAI Codex через OpenClaw/PI | Вам потрібна автентифікація підписки ChatGPT/Codex із типовим runner PI. | -| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | app-server 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 для вбудованого ходу агента. | -GPT-5.5 у OpenClaw зараз доступна лише через subscription/OAuth. Використовуйте -`openai-codex/gpt-5.5` для OAuth через PI або `openai/gpt-5.5` з harness app-server -Codex. Прямий доступ за API key для `openai/gpt-5.5` підтримуватиметься, +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. -Застарілі посилання `codex/gpt-*` досі приймаються як псевдоніми сумісності. Doctor -міграція сумісності переписує застарілі основні посилання runtime на канонічні посилання model -і записує політику runtime окремо, тоді як застарілі посилання лише для fallback залишаються без змін, -оскільки runtime налаштовується для всього контейнера агента. -Нові конфігурації PI Codex OAuth мають використовувати `openai-codex/gpt-*`; нові конфігурації нативного -app-server harness мають використовувати `openai/gpt-*` плюс +Застарілі посилання `codex/gpt-*` і далі приймаються як псевдоніми сумісності. Міграція сумісності +doctor переписує застарілі первинні посилання середовища виконання в канонічні посилання на моделі +й окремо записує політику середовища виконання, тоді як застарілі посилання лише для fallback +залишаються без змін, оскільки середовище виконання налаштовується для всього контейнера агента. +Нові конфігурації OAuth Codex для Pi мають використовувати `openai-codex/gpt-*`; нові конфігурації +нативного harness app-server мають використовувати `openai/gpt-*` плюс `embeddedHarness.runtime: "codex"`. `agents.defaults.imageModel` дотримується того самого розділення префіксів. Використовуйте -`openai-codex/gpt-*`, коли розуміння зображень має йти через шлях provider OpenAI -Codex OAuth. Використовуйте `codex/gpt-*`, коли розуміння зображень має виконуватися -через обмежений цикл app-server Codex. Model app-server Codex має -оголошувати підтримку вхідних зображень; текстові model Codex завершуються помилкою до того, як почнеться цикл медіа. +`openai-codex/gpt-*`, коли розуміння зображень має працювати через шлях провайдера OAuth OpenAI +Codex. Використовуйте `codex/gpt-*`, коли розуміння зображень має працювати +через обмежений хід Codex app-server. Модель Codex app-server має +заявляти підтримку введення зображень; текстові моделі Codex завершуються помилкою ще до +початку медіа-ходу. -Використовуйте `/status`, щоб підтвердити ефективний harness для поточної сесії. Якщо -вибір виглядає несподіваним, увімкніть debug-логування для підсистеми `agents/harness` -і перевірте структурований запис gateway `agent harness selected`. Він -містить id вибраного harness, причину вибору, політику runtime/fallback і, +Використовуйте `/status`, щоб підтвердити фактичний harness для поточної сесії. Якщо вибір +несподіваний, увімкніть debug-логування для підсистеми `agents/harness` +і перегляньте структурований запис gateway `agent harness selected`. Він +містить ідентифікатор вибраного harness, причину вибору, політику runtime/fallback та, у режимі `auto`, результат підтримки для кожного кандидата Plugin. -Вибір harness не є елементом керування живою сесією. Коли вбудований цикл виконується, -OpenClaw записує id вибраного harness для цієї сесії й продовжує використовувати його -для наступних циклів у межах того самого id сесії. Змініть конфігурацію `embeddedHarness` або +Вибір harness не є засобом керування живою сесією. Коли виконується вбудований хід, +OpenClaw записує ідентифікатор вибраного harness у цю сесію та продовжує використовувати його +для наступних ходів у межах того самого ідентифікатора сесії. Змінюйте конфігурацію `embeddedHarness` або `OPENCLAW_AGENT_RUNTIME`, якщо хочете, щоб майбутні сесії використовували інший harness; -використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням -наявної розмови між PI і Codex. Це дає змогу уникнути повторного програвання -одного transcript через дві несумісні нативні системи сесій. +використовуйте `/new` або `/reset`, щоб почати нову сесію, перш ніж перемикати наявну +розмову між Pi і Codex. Це запобігає повторному програванню одного транскрипту через +дві несумісні нативні системи сесій. -Застарілі сесії, створені до появи прив’язок harness, трактуються як прив’язані до PI, -щойно вони мають історію transcript. Використовуйте `/new` або `/reset`, щоб перевести -цю розмову на Codex після зміни конфігурації. +Застарілі сесії, створені до закріплення harness, розглядаються як закріплені за Pi, щойно вони +мають історію транскрипту. Використовуйте `/new` або `/reset`, щоб перевести цю розмову на +Codex після зміни конфігурації. -`/status` показує ефективний runtime model. Типовий harness PI відображається як -`Runtime: OpenClaw Pi Default`, а app-server harness Codex — як +`/status` показує фактичне середовище виконання моделі. Типовий harness Pi відображається як +`Runtime: OpenClaw Pi Default`, а harness Codex app-server — як `Runtime: OpenAI Codex`. ## Вимоги - OpenClaw із доступним комплектним Plugin `codex`. -- app-server Codex версії `0.118.0` або новішої. -- Доступна автентифікація Codex для процесу app-server. +- Codex app-server `0.125.0` або новіший. Нативні payload хуків MCP з’явилися в Codex + `0.124.0`; OpenClaw використовує `0.125.0` як перевірену нижню межу підтримки. +- Автентифікація Codex, доступна для процесу app-server. -Plugin блокує старіші або неверсіоновані handshakes app-server. Це зберігає -OpenClaw у межах поверхні протоколу, з якою його було протестовано. +Plugin блокує старіші або неверсіоновані handshakes app-server. Це гарантує, що +OpenClaw працює лише з поверхнею протоколу, з якою його було протестовано. Для live- і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також -необов’язкових файлів Codex CLI, як-от `~/.codex/auth.json` і -`~/.codex/config.toml`. Використовуйте ті самі матеріали автентифікації, що й ваш локальний app-server Codex. +із необов’язкових файлів CLI Codex, таких як `~/.codex/auth.json` і +`~/.codex/config.toml`. Використовуйте ті самі дані автентифікації, які використовує ваш локальний Codex app-server. ## Мінімальна конфігурація @@ -142,7 +145,7 @@ OpenClaw у межах поверхні протоколу, з якою його } ``` -Якщо у вашій конфігурації використовується `plugins.allow`, додайте туди й `codex`: +Якщо ваша конфігурація використовує `plugins.allow`, додайте туди й `codex`: ```json5 { @@ -157,28 +160,28 @@ OpenClaw у межах поверхні протоколу, з якою його } ``` -Застарілі конфігурації, які задають `agents.defaults.model` або model агента як -`codex/`, усе ще автоматично вмикають комплектний Plugin `codex`. Нові конфігурації мають -надавати перевагу `openai/` плюс явний запис `embeddedHarness`, наведений вище. +Застарілі конфігурації, які задають `agents.defaults.model` або модель агента як +`codex/`, і далі автоматично вмикають комплектний Plugin `codex`. Нові конфігурації мають +надавати перевагу `openai/` плюс явному запису `embeddedHarness` вище. -## Додайте Codex поряд з іншими model +## Додайте Codex поруч з іншими моделями Не задавайте `runtime: "codex"` глобально, якщо той самий агент має вільно перемикатися -між Codex і model інших provider. Примусовий runtime застосовується до кожного -вбудованого циклу для цього агента або сесії. Якщо ви виберете model Anthropic, поки -такий runtime примусово задано, OpenClaw все одно спробує harness Codex і завершиться помилкою, -замість того щоб мовчки маршрутизувати цей цикл через PI. +між Codex і моделями інших провайдерів. Примусове середовище виконання застосовується до кожного +вбудованого ходу для цього агента або сесії. Якщо ви виберете модель Anthropic, поки +це середовище виконання примусово задане, OpenClaw усе одно спробує harness Codex і завершиться помилкою +безшумно не перенаправляючи цей хід через Pi. Натомість використовуйте одну з таких форм: - Розмістіть Codex на окремому агенті з `embeddedHarness.runtime: "codex"`. -- Залиште типовому агенту `runtime: "auto"` і fallback до PI для звичайного змішаного - використання provider. -- Використовуйте застарілі посилання `codex/*` лише для сумісності. Нові конфігурації мають надавати перевагу - `openai/*` плюс явна політика runtime Codex. +- Залиште типовий агент із `runtime: "auto"` і fallback на Pi для звичайного змішаного + використання провайдерів. +- Використовуйте застарілі посилання `codex/*` лише для сумісності. Нові конфігурації мають віддавати перевагу + `openai/*` плюс явній політиці середовища виконання Codex. -Наприклад, така конфігурація зберігає для типового агента звичайний автоматичний вибір -і додає окремого агента Codex: +Наприклад, така конфігурація залишає типовий агент зі звичайним автоматичним вибором і +додає окремого агента Codex: ```json5 { @@ -215,18 +218,18 @@ OpenClaw у межах поверхні протоколу, з якою його } ``` -За такої форми: +З такою формою: -- Типовий агент `main` використовує звичайний шлях provider і fallback сумісності з PI. -- Агент `codex` використовує app-server harness Codex. -- Якщо Codex відсутній або не підтримується для агента `codex`, цикл - завершується помилкою замість тихого використання PI. +- Типовий агент `main` використовує звичайний шлях провайдера та fallback сумісності Pi. +- Агент `codex` використовує harness Codex app-server. +- Якщо для агента `codex` Codex відсутній або не підтримується, хід + завершується помилкою замість тихого використання Pi. ## Розгортання лише з Codex -Примусово використовуйте harness Codex, коли потрібно гарантувати, що кожен вбудований цикл агента -використовує Codex. Явні runtime Plugin за замовчуванням не мають fallback до PI, тому -`fallback: "none"` є необов’язковим, але часто корисним як документація: +Примусово задайте harness Codex, коли потрібно гарантувати, що кожен вбудований хід агента +використовує Codex. Явні runtimes Plugin за замовчуванням не мають fallback на Pi, тому +`fallback: "none"` необов’язковий, але часто корисний як документація: ```json5 { @@ -249,14 +252,14 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` Коли Codex примусово задано, OpenClaw завершується помилкою на ранньому етапі, якщо Plugin Codex вимкнено, -app-server надто старий або app-server не може запуститися. Установлюйте -`OPENCLAW_AGENT_HARNESS_FALLBACK=pi`, лише якщо ви навмисно хочете, щоб PI обробляв +app-server надто старий або app-server не вдається запустити. Установлюйте +`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише якщо ви свідомо хочете, щоб Pi обробляв відсутній вибір harness. ## Codex для окремого агента -Ви можете зробити одного агента лише для Codex, тоді як типовий агент збереже звичайний -автовибір: +Ви можете зробити одного агента лише для Codex, тоді як типовий агент зберігатиме звичайний +автоматичний вибір: ```json5 { @@ -287,15 +290,15 @@ app-server надто старий або app-server не може запуст } ``` -Використовуйте звичайні команди сесії, щоб перемикати агентів і model. `/new` створює нову -сесію OpenClaw, а harness Codex створює або відновлює свій sidecar thread app-server -за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього thread -і дає змогу наступному циклу знову визначити harness із поточної конфігурації. +Використовуйте звичайні команди сесії, щоб перемикати агентів і моделі. `/new` створює нову +сесію OpenClaw, а harness Codex за потреби створює або відновлює свій sidecar app-server +thread. `/reset` очищує прив’язку сесії OpenClaw для цього thread +і дає змогу наступному ходу знову визначити harness із поточної конфігурації. -## Виявлення model +## Виявлення моделей -За замовчуванням Plugin Codex запитує app-server про доступні model. Якщо -виявлення не вдається або завершується за timeout, він використовує комплектний fallback-каталог для: +За замовчуванням Plugin Codex запитує app-server про доступні моделі. Якщо +виявлення завершується помилкою або перевищує час очікування, він використовує комплектний резервний каталог для: - GPT-5.5 - GPT-5.4 mini @@ -321,8 +324,8 @@ app-server надто старий або app-server не може запуст } ``` -Вимкніть виявлення, якщо хочете, щоб під час запуску не було перевірки Codex і використовувався -fallback-каталог: +Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалася перевірка Codex і використовувався +резервний каталог: ```json5 { @@ -341,7 +344,7 @@ fallback-каталог: } ``` -## Підключення app-server і політика +## З’єднання app-server і політика За замовчуванням Plugin запускає Codex локально так: @@ -351,11 +354,11 @@ codex app-server --listen stdio:// За замовчуванням OpenClaw запускає локальні сесії harness Codex у режимі YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` і -`sandbox: "danger-full-access"`. Це поза довіри локального оператора, що використовується -для автономних Heartbeat: Codex може використовувати shell і мережеві tools без -зупинки на нативних prompt approval, на які нікому відповісти. +`sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, яка використовується +для автономних Heartbeat: Codex може використовувати shell і мережеві інструменти без +зупинок на нативних запитах підтвердження, на які нікому відповісти. -Щоб увімкнути approvals Codex, які перевіряє guardian, задайте `appServer.mode: +Щоб увімкнути підтвердження Codex, переглянуті guardian, задайте `appServer.mode: "guardian"`: ```json5 @@ -376,20 +379,21 @@ codex app-server --listen stdio:// } ``` -Режим Guardian використовує нативний шлях auto-review approval у Codex. Коли Codex просить -вийти із sandbox, писати поза workspace або додати дозволи, як-от доступ до мережі, -Codex маршрутизує цей запит approval до нативного reviewer, а не до prompt для людини. -Reviewer застосовує модель ризику Codex і схвалює або відхиляє конкретний запит. Використовуйте Guardian, якщо хочете більше запобіжників, ніж у режимі YOLO, -але все одно потребуєте, щоб unattended agents могли просуватися далі. +Режим Guardian використовує нативний шлях автоперевірки погоджень Codex. Коли Codex просить +вийти із sandbox, писати за межами workspace або додати дозволи на кшталт мережевого +доступу, Codex спрямовує цей запит на погодження до нативного рецензента замість +людського запиту. Рецензент застосовує модель ризиків Codex і схвалює або відхиляє +конкретний запит. Використовуйте Guardian, коли вам потрібні жорсткіші запобіжники, ніж у режимі YOLO, +але при цьому потрібно, щоб агенти без нагляду могли просуватися далі. -Preset `guardian` розгортається в `approvalPolicy: "on-request"`, +preset `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"` і `sandbox: "workspace-write"`. -Окремі поля політики все одно перевизначають `mode`, тож розширені розгортання можуть поєднувати -preset із явними параметрами. Старіше значення reviewer `guardian_subagent` -усе ще приймається як псевдонім сумісності, але нові конфігурації мають використовувати +Окремі поля політики, як і раніше, перевизначають `mode`, тому розширені розгортання можуть поєднувати +цей preset із явними виборами. Старе значення рецензента `guardian_subagent` +досі приймається як псевдонім сумісності, але нові конфігурації мають використовувати `auto_review`. -Для app-server, який уже працює, використовуйте транспорт WebSocket: +Для вже запущеного app-server використовуйте транспорт WebSocket: ```json5 { @@ -413,23 +417,23 @@ preset із явними параметрами. Старіше значення Підтримувані поля `appServer`: -| Поле | Типове значення | Значення | -| ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -| `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` | Timeout для викликів control plane app-server. | -| `mode` | `"yolo"` | Preset для виконання в режимі YOLO або з approvals, перевіреними guardian. | -| `approvalPolicy` | `"never"` | Нативна політика approval Codex, яка надсилається під час start/resume/turn thread. | -| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, який надсилається під час start/resume thread. | -| `approvalsReviewer` | `"user"` | Використовуйте `"auto_review"`, щоб дозволити Codex перевіряти нативні prompt approval. `guardian_subagent` лишається застарілим псевдонімом. | -| `serviceTier` | не задано | Необов’язковий service tier app-server Codex: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. | +| Поле | Типове значення | Значення | +| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `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"` | preset для виконання в режимі YOLO або з погодженнями, перевіреними Guardian. | +| `approvalPolicy` | `"never"` | Нативна політика погоджень Codex, що надсилається під час start/resume/turn thread. | +| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що надсилається під час start/resume 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` @@ -437,11 +441,11 @@ preset із явними параметрами. Старіше значення - `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. +відтворюваних розгортань перевага надається конфігурації, оскільки вона зберігає поведінку Plugin +у тому самому перевіреному файлі, що й решта налаштувань harness Codex. ## Поширені рецепти @@ -459,7 +463,7 @@ preset із явними параметрами. Старіше значення } ``` -Перевірка harness лише для Codex: +Перевірка harness лише з Codex: ```json5 { @@ -481,7 +485,7 @@ preset із явними параметрами. Старіше значення } ``` -Approvals Codex, перевірені Guardian: +Погодження Codex, перевірені Guardian: ```json5 { @@ -503,7 +507,7 @@ Approvals Codex, перевірені Guardian: } ``` -Віддалений app-server з явними заголовками: +Віддалений app-server із явними заголовками: ```json5 { @@ -526,181 +530,187 @@ Approvals Codex, перевірені Guardian: } ``` -Перемикання model залишається під контролем OpenClaw. Коли сесію OpenClaw приєднано -до наявного thread Codex, наступний цикл знову надсилає поточну вибрану -model OpenAI, provider, політику approval, sandbox і service tier до -app-server. Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає -прив’язку thread, але просить Codex продовжити з новою вибраною model. +Перемикання моделей залишається під контролем OpenClaw. Коли сесію OpenClaw приєднано +до наявного thread Codex, наступний хід знову надсилає до +app-server поточну вибрану модель OpenAI, провайдера, політику погоджень, sandbox і +рівень сервісу. Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає +прив’язку до thread, але просить Codex продовжити з новою вибраною моделлю. ## Команда Codex -Комплектний Plugin реєструє `/codex` як авторизовану slash-команду. Вона -загальна й працює в будь-якому каналі, який підтримує текстові команди OpenClaw. +Комплектний Plugin реєструє `/codex` як авторизовану slash-команду. Вона є +загальною і працює в будь-якому каналі, що підтримує текстові команди OpenClaw. Поширені форми: -- `/codex status` показує живе підключення app-server, model, обліковий запис, ліміти rate, сервери MCP і Skills. -- `/codex models` показує список живих model app-server Codex. -- `/codex threads [filter]` показує список нещодавніх thread Codex. +- `/codex status` показує живе підключення до app-server, моделі, обліковий запис, ліміти швидкості, сервери MCP і Skills. +- `/codex models` перелічує живі моделі Codex app-server. +- `/codex threads [filter]` перелічує нещодавні threads Codex. - `/codex resume ` приєднує поточну сесію OpenClaw до наявного thread Codex. -- `/codex compact` просить app-server Codex виконати Compaction приєднаного thread. +- `/codex compact` просить Codex app-server виконати Compaction приєднаного thread. - `/codex review` запускає нативну перевірку Codex для приєднаного thread. -- `/codex account` показує стан облікового запису та лімітів rate. -- `/codex mcp` показує список станів серверів MCP app-server Codex. -- `/codex skills` показує список Skills app-server Codex. +- `/codex account` показує стан облікового запису та лімітів швидкості. +- `/codex mcp` перелічує стан серверів MCP у Codex app-server. +- `/codex skills` перелічує Skills у Codex app-server. `/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для -звичайних циклів. На наступному повідомленні OpenClaw відновлює цей thread Codex, передає -поточну вибрану model OpenClaw до app-server і зберігає розширену історію -увімкненою. +звичайних ходів. Під час наступного повідомлення OpenClaw відновлює цей thread Codex, передає +поточну вибрану модель OpenClaw до app-server і зберігає увімкнену +розширену історію. -Поверхня команд вимагає app-server Codex версії `0.118.0` або новішої. Окремі +Поверхня команд вимагає Codex app-server `0.125.0` або новішого. Окремі методи керування позначаються як `unsupported by this Codex app-server`, якщо -майбутній або кастомний app-server не надає цей метод JSON-RPC. +майбутній або кастомний app-server не надає цей JSON-RPC-метод. -## Межі hooks +## Межі хуків -Harness Codex має три шари hooks: +harness Codex має три шари хуків: -| Шар | Власник | Призначення | -| ------------------------------------- | ------------------------ | ------------------------------------------------------------------ | -| hooks Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness PI та Codex. | -| middleware розширення app-server Codex | комплектні plugins OpenClaw | Адаптерна поведінка для кожного циклу навколо динамічних tools OpenClaw. | -| нативні hooks Codex | Codex | Низькорівневий життєвий цикл Codex і нативна політика tools із конфігурації Codex. | +| Шар | Власник | Призначення | +| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | +| Хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness Pi і Codex. | +| Middleware розширення Codex app-server | Комплектні plugins OpenClaw | Поведінка адаптера для кожного ходу навколо динамічних інструментів OpenClaw. | +| Нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і політика нативних інструментів із конфігурації Codex. | -OpenClaw не використовує проєктні або глобальні файли Codex `hooks.json` для маршрутизації -поведінки Plugin OpenClaw. Для підтримуваного мосту нативних tools і дозволів -OpenClaw ін’єктує конфігурацію Codex для конкретного thread для `PreToolUse`, `PostToolUse` і -`PermissionRequest`. Інші hooks Codex, як-от `SessionStart`, -`UserPromptSubmit` і `Stop`, залишаються елементами керування на рівні Codex; у контракті v1 вони не відкриті -як hooks Plugin OpenClaw. +OpenClaw не використовує файлові `hooks.json` Codex на рівні проєкту або глобальному рівні для маршрутизації +поведінки Plugin OpenClaw. Для підтримуваного мосту нативних інструментів і дозволів +OpenClaw впроваджує для кожного thread конфігурацію Codex для `PreToolUse`, `PostToolUse` і +`PermissionRequest`. Інші хуки Codex, такі як `SessionStart`, +`UserPromptSubmit` і `Stop`, залишаються елементами керування на рівні Codex; вони не +експонуються як хуки Plugin OpenClaw у контракті v1. -Для динамічних tools OpenClaw виконує tool після того, як Codex запитує -виклик, тож OpenClaw запускає поведінку Plugin і middleware, якою він володіє, у -адаптері harness. Для нативних tools Codex канонічним записом tool володіє Codex. -OpenClaw може віддзеркалювати окремі події, але не може переписувати нативний thread Codex, -якщо Codex не надає цю операцію через app-server або callbacks нативних -hooks. +Для динамічних інструментів OpenClaw сам OpenClaw виконує інструмент після того, як Codex запитує +виклик, тому OpenClaw запускає поведінку Plugin і middleware, якою він володіє, в +адаптері harness. Для нативних інструментів Codex канонічний запис інструмента належить Codex. +OpenClaw може віддзеркалювати вибрані події, але не може переписувати нативний thread Codex, +якщо Codex не надає цю операцію через app-server або callbacks нативних хуків. -Проєкції Compaction і життєвого циклу LLM надходять зі сповіщень app-server Codex -і стану адаптера OpenClaw, а не з команд нативних hooks Codex. +Проєкції Compaction і життєвого циклу LLM надходять зі сповіщень Codex app-server +та стану адаптера OpenClaw, а не з команд нативних хуків Codex. Події OpenClaw `before_compaction`, `after_compaction`, `llm_input` і -`llm_output` є спостереженнями на рівні адаптера, а не побайтовими копіями +`llm_output` — це спостереження на рівні адаптера, а не побайтові захоплення внутрішнього запиту Codex або payload Compaction. -Нативні сповіщення app-server Codex `hook/started` і `hook/completed` -проєктуються як події агента `codex_app_server.hook` для trajectory і налагодження. -Вони не викликають hooks Plugin OpenClaw. +Нативні сповіщення Codex app-server `hook/started` і `hook/completed` +проєктуються як події агента `codex_app_server.hook` для траєкторії та налагодження. +Вони не викликають хуки Plugin OpenClaw. ## Контракт підтримки V1 -Режим Codex — це не PI з іншим викликом model під капотом. Codex володіє більшою частиною -нативного циклу model, а OpenClaw адаптує свої поверхні Plugin і сесії -навколо цієї межі. +Режим Codex — це не Pi з іншим викликом моделі в основі. Codex керує більшою частиною +нативного циклу моделі, а OpenClaw адаптує свої поверхні Plugin і сесій +навколо цього кордону. Підтримується в runtime Codex v1: -| Поверхня | Підтримка | Чому | -| --------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -| Цикл model OpenAI через Codex | Підтримується | app-server Codex володіє циклом OpenAI, нативним відновленням thread і нативним продовженням tools. | -| Маршрутизація та доставка каналів OpenClaw | Підтримується | Telegram, Discord, Slack, WhatsApp, iMessage та інші канали залишаються поза runtime model. | -| Динамічні tools OpenClaw | Підтримується | Codex просить OpenClaw виконувати ці tools, тож OpenClaw залишається на шляху виконання. | -| Plugins prompt і контексту | Підтримується | OpenClaw будує накладки prompt і проєктує контекст у цикл Codex перед запуском або відновленням thread. | -| Життєвий цикл контекстного рушія | Підтримується | Assemble, ingest або обслуговування after-turn і координація Compaction контекстного рушія виконуються для циклів Codex. | -| Hooks динамічних tools | Підтримується | `before_tool_call`, `after_tool_call` і middleware результатів tools виконуються навколо динамічних tools, якими володіє OpenClaw. | -| Hooks життєвого циклу | Підтримуються як спостереження адаптера | `llm_input`, `llm_output`, `agent_end`, `before_compaction` і `after_compaction` спрацьовують із чесними payload для режиму Codex. | -| Нативний shell і блокування або спостереження patch | Підтримується через relay нативних hooks | `PreToolUse` і `PostToolUse` Codex ретранслюються для підтримуваних поверхонь нативних tools. Блокування підтримується; переписування аргументів — ні. | -| Нативна політика дозволів | Підтримується через relay нативних hooks | `PermissionRequest` Codex можна маршрутизувати через політику OpenClaw там, де runtime це дозволяє. | -| Захоплення trajectory app-server | Підтримується | OpenClaw записує запит, який він надіслав до app-server, і сповіщення, які отримує від app-server. | +| Поверхня | Підтримка | Чому | +| --------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Цикл моделі OpenAI через Codex | Підтримується | Codex app-server керує ходом OpenAI, нативним відновленням thread і нативним продовженням інструментів. | +| Маршрутизація і доставка каналів OpenClaw | Підтримується | Telegram, Discord, Slack, WhatsApp, iMessage та інші канали залишаються поза runtime моделі. | +| Динамічні інструменти OpenClaw | Підтримується | Codex просить OpenClaw виконати ці інструменти, тому OpenClaw залишається в шляху виконання. | +| Plugins підказок і контексту | Підтримується | OpenClaw будує накладки підказок і проєктує контекст у хід Codex перед запуском або відновленням thread. | +| Життєвий цикл рушія контексту | Підтримується | Збирання, поглинання або обслуговування після ходу, а також координація Compaction рушія контексту виконуються для ходів Codex. | +| Хуки динамічних інструментів | Підтримується | `before_tool_call`, `after_tool_call` і middleware результатів інструментів виконуються навколо динамічних інструментів, якими володіє OpenClaw. | +| Хуки життєвого циклу | Підтримуються як спостереження адаптера | `llm_input`, `llm_output`, `agent_end`, `before_compaction` і `after_compaction` спрацьовують із коректними payload для режиму Codex. | +| Нативне блокування або спостереження shell, patch і MCP | Підтримується через relay нативних хуків | `PreToolUse` і `PostToolUse` Codex передаються далі для зафіксованих поверхонь нативних інструментів, включно з payload MCP у Codex app-server `0.125.0` або новішому. Блокування підтримується; переписування аргументів — ні. | +| Нативна політика дозволів | Підтримується через relay нативних хуків | `PermissionRequest` Codex може маршрутизуватися через політику OpenClaw там, де runtime це надає. Якщо OpenClaw не повертає рішення, Codex продовжує своїм звичайним шляхом погодження guardian або користувача. | +| Захоплення траєкторії app-server | Підтримується | OpenClaw записує запит, який він надіслав до app-server, і сповіщення, які він отримує від app-server. | Не підтримується в runtime Codex v1: -| Поверхня | Межа V1 | Майбутній шлях | -| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -| Мутація аргументів нативних tools | Нативні pre-tool hooks Codex можуть блокувати, але OpenClaw не переписує аргументи нативних tools Codex. | Потребує підтримки hook/schema у Codex для заміни вхідних даних tool. | -| Редагована історія нативного transcript Codex | Codex володіє канонічною історією нативного thread. OpenClaw володіє дзеркалом і може проєктувати майбутній контекст, але не має змінювати непідтримувані внутрішні механізми. | Додати явні API app-server Codex, якщо потрібна нативна хірургія thread. | -| `tool_result_persist` для записів нативних tools Codex | Цей hook перетворює записи transcript, якими володіє OpenClaw, а не записи нативних tools Codex. | Може віддзеркалювати перетворені записи, але канонічне переписування потребує підтримки Codex. | -| Розширені нативні метадані Compaction | OpenClaw спостерігає початок і завершення Compaction, але не отримує стабільний список збережених/відкинутих елементів, дельту токенів або payload підсумку. | Потребує багатших подій Compaction у Codex. | -| Втручання в Compaction | Поточні hooks Compaction в OpenClaw у режимі Codex працюють на рівні сповіщень. | Додати hooks pre/post Compaction у Codex, якщо Plugins мають забороняти або переписувати нативну Compaction. | -| Stop або gate для фінальної відповіді | Codex має нативні hooks stop, але OpenClaw не надає gate для фінальної відповіді як контракт Plugin v1. | Майбутній opt-in primitive із захистом від циклів і timeout. | -| Паритет нативних hooks MCP як зафіксована поверхня v1 | Relay є загальним, але OpenClaw ще не version-gated і не протестував наскрізну поведінку нативних hooks MCP pre/post. | Додати тести relay MCP у OpenClaw і документацію, щойно підтримуваний нижній поріг протоколу app-server покриє ці payload. | -| Побайтове захоплення запиту до API model | OpenClaw може захоплювати запити й сповіщення app-server, але ядро Codex внутрішньо будує фінальний запит до OpenAI API. | Потребує події трасування запиту model Codex або debug API. | +| Поверхня | Межа v1 | Майбутній шлях | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | +| Мутація аргументів нативних інструментів | Нативні pre-tool хуки Codex можуть блокувати, але OpenClaw не переписує аргументи нативних інструментів Codex. | Потребує підтримки хуків/схеми Codex для заміни вхідних даних інструмента. | +| Редагована історія нативного транскрипту Codex | 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 хуки Compaction у Codex, якщо plugins потрібно забороняти або переписувати нативну Compaction. | +| Керування зупинкою або фінальною відповіддю | Codex має нативні stop-хуки, але OpenClaw не експонує керування фінальною відповіддю як контракт Plugin v1. | Майбутній opt-in primitive із захистом циклів і тайм-аутів. | +| Побайтове захоплення запиту до API моделі | OpenClaw може захоплювати запити і сповіщення app-server, але ядро Codex будує фінальний запит до OpenAI API внутрішньо. | Потрібна подія трасування запиту моделі Codex або debug API. | -## Tools, медіа і Compaction +## Інструменти, медіа та Compaction -Harness Codex змінює лише низькорівневий виконавець вбудованого агента. +harness Codex змінює лише низькорівневий виконавець вбудованого агента. -OpenClaw, як і раніше, формує список tools і отримує результати динамічних tools від -harness. Текст, зображення, відео, музика, TTS, approvals і вивід tool для повідомлень +OpenClaw, як і раніше, формує список інструментів і отримує результати динамічних інструментів від +harness. Текст, зображення, відео, музика, TTS, погодження і вихідні дані інструментів обміну повідомленнями продовжують проходити звичайним шляхом доставки OpenClaw. -Relay нативних hooks навмисно є загальним, але контракт підтримки v1 -обмежено нативними шляхами tools і дозволів Codex, які OpenClaw тестує. Не -припускайте, що кожна майбутня подія hook Codex є поверхнею Plugin OpenClaw, доки -контракт runtime прямо цього не визначить. +relay нативних хуків навмисно зроблений узагальненим, але контракт підтримки v1 +обмежений нативними шляхами інструментів і дозволів Codex, які тестує OpenClaw. У +runtime Codex це включає payload `PreToolUse`, +`PostToolUse` і `PermissionRequest` для shell, patch і MCP. Не припускайте, що кожна майбутня +подія хуків Codex є поверхнею Plugin OpenClaw, доки контракт runtime +не назве її. -Запити на approval для tools MCP Codex маршрутизуються через потік approval +Для `PermissionRequest` OpenClaw повертає явні рішення allow або deny +лише коли це визначає політика. Результат без рішення — це не allow. Codex +трактує це як відсутність рішення hook і переходить до власного шляху погодження guardian або користувача. + +Запити на погодження інструментів MCP Codex маршрутизуються через потік погодження Plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як -`"mcp_tool_call"`. Prompt-и Codex `request_user_input` надсилаються назад до -чату походження, а наступне повідомлення у черзі відповідає на цей нативний -запит сервера замість того, щоб бути спрямованим як додатковий контекст. Інші -запити elicitation MCP, як і раніше, завершуються помилкою за принципом fail closed. +`"mcp_tool_call"`. Запити `request_user_input` Codex надсилаються назад до +початкового чату, а наступне поставлене в чергу повідомлення-відповідь відповідає на цей нативний +запит сервера замість того, щоб спрямовуватися як додатковий контекст. Інші запити MCP +на elicitation як і раніше завершуються помилкою. -Коли вибрана model використовує harness Codex, нативну Compaction thread делеговано -app-server Codex. OpenClaw зберігає дзеркало transcript для історії каналів, -пошуку, `/new`, `/reset` і майбутнього перемикання model або harness. Дзеркало -включає prompt користувача, фінальний текст асистента і полегшені записи -reasoning або plan Codex, коли їх видає app-server. Наразі OpenClaw лише -записує сигнали початку й завершення нативної Compaction. Він ще не надає -людинозрозумілого підсумку Compaction або придатного для аудиту списку того, які записи Codex +Коли вибрана модель використовує harness Codex, нативна Compaction thread делегується +Codex app-server. OpenClaw зберігає дзеркало транскрипту для історії каналу, +пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало +включає підказку користувача, фінальний текст асистента та полегшені записи міркувань або плану Codex, +коли їх випромінює app-server. Наразі OpenClaw записує лише сигнали +початку й завершення нативної Compaction. Він поки не надає +людинозрозуміле зведення Compaction або придатний до аудиту список того, які записи Codex зберіг після Compaction. Оскільки Codex володіє канонічним нативним thread, `tool_result_persist` наразі -не переписує записи результатів нативних tools Codex. Він застосовується лише тоді, -коли OpenClaw записує результат tool у transcript сесії, яким володіє OpenClaw. +не переписує записи результатів нативних інструментів Codex. Він застосовується лише тоді, +коли OpenClaw записує результат інструмента в транскрипт сесії, яким володіє OpenClaw. -Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і -розуміння медіа, як і раніше, використовують відповідні налаштування provider/model, як-от +Генерація медіа не потребує Pi. Генерація зображень, відео, музики, PDF, TTS і +розуміння медіа й далі використовують відповідні налаштування провайдера/моделі, такі як `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і `messages.tts`. ## Усунення несправностей -**Codex не з’являється як звичайний provider у `/model`:** це очікувана поведінка для -нових конфігурацій. Виберіть model `openai/gpt-*` з -`embeddedHarness.runtime: "codex"` (або застаріле посилання `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 під час тестування. Примусовий -runtime Codex тепер завершується помилкою замість fallback до PI, якщо ви -явно не встановите `embeddedHarness.fallback: "pi"`. Щойно буде вибрано app-server Codex, -його збої проявлятимуться напряму без додаткової конфігурації fallback. +**OpenClaw використовує Pi замість Codex:** `runtime: "auto"` усе ще може використовувати Pi як +backend сумісності, коли жоден harness Codex не бере виконання на себе. Установіть +`embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування. Тепер +примусовий runtime Codex завершується помилкою замість fallback на Pi, якщо ви +явно не задасте `embeddedHarness.fallback: "pi"`. Щойно вибрано Codex app-server, +його збої проявляються безпосередньо без додаткової конфігурації fallback. **app-server відхиляється:** оновіть Codex, щоб handshake app-server -повідомляв версію `0.118.0` або новішу. +повідомляв версію `0.125.0` або новішу. Пререлізи тієї самої версії або версії +із суфіксами збірки, такі як `0.125.0-alpha.2` або `0.125.0+custom`, відхиляються, оскільки +стабільний поріг протоколу `0.125.0` — це те, що тестує OpenClaw. -**Виявлення model повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` +**Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` або вимкніть виявлення. **Транспорт WebSocket одразу завершується помилкою:** перевірте `appServer.url`, `authToken` -і чи віддалений app-server використовує ту саму версію протоколу app-server Codex. +і що віддалений app-server використовує ту саму версію протоколу Codex app-server. -**Модель не-Codex використовує PI:** це очікувано, якщо тільки ви не примусово задали +**Модель не Codex використовує Pi:** це очікувана поведінка, якщо ви не примусово задали `embeddedHarness.runtime: "codex"` для цього агента або не вибрали застаріле -посилання `codex/*`. Звичайні посилання `openai/gpt-*` та посилання інших provider залишаються на своєму звичайному -шляху provider в режимі `auto`. Якщо ви примусово задаєте `runtime: "codex"`, кожен вбудований -цикл для цього агента має бути model OpenAI, яку підтримує Codex. +посилання `codex/*`. Звичайні `openai/gpt-*` та інші посилання провайдерів залишаються на своєму нормальному +шляху провайдера в режимі `auto`. Якщо ви примусово задасте `runtime: "codex"`, кожен вбудований +хід для цього агента має бути моделлю OpenAI, яку підтримує Codex. ## Пов’язане -- [Agent harness plugins](/uk/plugins/sdk-agent-harness) -- [Agent runtimes](/uk/concepts/agent-runtimes) -- [Model providers](/uk/concepts/model-providers) -- [OpenAI provider](/uk/providers/openai) -- [Status](/uk/cli/status) -- [Plugin hooks](/uk/plugins/hooks) -- [Configuration reference](/uk/gateway/configuration-reference) -- [Testing](/uk/help/testing-live#live-codex-app-server-harness-smoke) +- [Plugins harness агента](/uk/plugins/sdk-agent-harness) +- [Середовища виконання агентів](/uk/concepts/agent-runtimes) +- [Провайдери моделей](/uk/concepts/model-providers) +- [Провайдер OpenAI](/uk/providers/openai) +- [Стан](/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/plugins/sdk-agent-harness.md b/docs/uk/plugins/sdk-agent-harness.md index f09030023..5364ebcbe 100644 --- a/docs/uk/plugins/sdk-agent-harness.md +++ b/docs/uk/plugins/sdk-agent-harness.md @@ -1,58 +1,58 @@ --- read_when: - - Ви змінюєте вбудоване середовище виконання агента або реєстр каркаса - - Ви реєструєте каркас агента з комплектного або довіреного плагіна - - Вам потрібно зрозуміти, як плагін Codex пов’язаний із постачальниками моделей + - Ви змінюєте вбудоване середовище виконання агента або реєстр обв’язок агента + - Ви реєструєте обв’язку агента з вбудованого або довіреного Plugin + - Вам потрібно зрозуміти, як Plugin Codex пов’язаний із постачальниками моделей sidebarTitle: Agent Harness -summary: Експериментальна поверхня SDK для плагінів, які замінюють низькорівневий вбудований виконавець агента -title: Плагіни каркаса агента +summary: Експериментальна поверхня SDK для Plugin, які замінюють низькорівневий вбудований виконавець агента +title: Plugin для обв’язки агента x-i18n: - generated_at: "2026-04-25T01:53:12Z" + generated_at: "2026-04-25T20:40:01Z" model: gpt-5.4 provider: openai - source_hash: bceb0ccf51431918aec2dfca047af6ed916aa1a8a7c34ca38cb64a14655e4d50 + source_hash: 9742e8a1e5df64da939452b36767ccb01f25a388fd1307e9d75aeb73f5699947 source_path: plugins/sdk-agent-harness.md workflow: 15 --- -**Каркас агента** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів. -Щоб зрозуміти модель для користувача, див. [Середовища виконання агентів](/uk/concepts/agent-runtimes). +**Обв’язка агента** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів. +Щоб зрозуміти користувацьку ментальну модель, див. [Середовища виконання агента](/uk/concepts/agent-runtimes). -Використовуйте цю поверхню лише для комплектних або довірених нативних плагінів. Контракт -досі експериментальний, оскільки типи параметрів навмисно віддзеркалюють поточний +Використовуйте цю поверхню лише для вбудованих або довірених нативних Plugin. Контракт +досі є експериментальним, оскільки типи параметрів навмисно віддзеркалюють поточний вбудований виконавець. -## Коли використовувати каркас +## Коли використовувати обв’язку -Реєструйте каркас агента, коли сімейство моделей має власне нативне середовище +Реєструйте обв’язку агента, коли сімейство моделей має власне нативне середовище виконання сесії, а звичайний транспорт постачальника OpenClaw є хибною абстракцією. Приклади: -- нативний сервер агента для кодування, який володіє потоками та Compaction -- локальний CLI або демон, який має потоково передавати нативні події плану/міркування/інструментів -- середовище виконання моделі, якому потрібен власний ідентифікатор відновлення на додачу до +- нативний сервер агента для кодування, який керує потоками та Compaction +- локальний CLI або демон, який має передавати нативні події плану/міркування/інструментів у потоці +- середовище виконання моделі, якому потрібен власний resume id на додачу до стенограми сесії OpenClaw -**Не** реєструйте каркас лише для того, щоб додати новий API LLM. Для звичайних HTTP або -WebSocket API моделей створіть [плагін постачальника](/uk/plugins/sdk-provider-plugins). +**Не** реєструйте обв’язку лише для того, щоб додати новий API LLM. Для звичайних HTTP або +WebSocket API моделей створіть [Plugin постачальника](/uk/plugins/sdk-provider-plugins). -## Що ядро все ще контролює +## Що все ще належить core -До вибору каркаса OpenClaw уже визначив: +Перш ніж обв’язку буде вибрано, OpenClaw уже визначив: - постачальника та модель - стан автентифікації середовища виконання - рівень міркування та бюджет контексту -- стенограму/файл сесії OpenClaw +- файл стенограми/сесії OpenClaw - робочий простір, пісочницю та політику інструментів -- зворотні виклики відповіді каналу та потокові зворотні виклики -- політику резервного перемикання моделі та перемикання live-моделі +- зворотні виклики відповіді каналу та зворотні виклики потокової передачі +- політику резервного перемикання моделі та перемикання live-моделей -Цей поділ навмисний. Каркас виконує підготовлену спробу; він не обирає -постачальників, не замінює доставку каналу і не перемикає моделі непомітно. +Цей поділ є навмисним. Обв’язка виконує підготовлену спробу; вона не вибирає +постачальників, не замінює доставку каналу й не перемикає моделі непомітно. -## Зареєструйте каркас +## Зареєструйте обв’язку **Імпорт:** `openclaw/plugin-sdk/agent-harness` @@ -90,111 +90,112 @@ export default definePluginEntry({ ## Політика вибору -OpenClaw обирає каркас після визначення постачальника/моделі: +OpenClaw вибирає обв’язку після визначення постачальника/моделі: -1. Записаний ідентифікатор каркаса наявної сесії має пріоритет, тому зміни config/env не - перемикають цю стенограму на інше середовище виконання «на гарячу». -2. `OPENCLAW_AGENT_RUNTIME=` примусово задає зареєстрований каркас із цим ідентифікатором для +1. Якщо для наявної сесії вже записано id обв’язки, він має пріоритет, тому зміни config/env не + перемикають цю стенограму «на гарячу» на інше середовище виконання. +2. `OPENCLAW_AGENT_RUNTIME=` примусово задає зареєстровану обв’язку з цим id для сесій, які ще не закріплені. -3. `OPENCLAW_AGENT_RUNTIME=pi` примусово задає вбудований каркас PI. -4. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані каркаси, чи підтримують вони +3. `OPENCLAW_AGENT_RUNTIME=pi` примусово задає вбудовану обв’язку PI. +4. `OPENCLAW_AGENT_RUNTIME=auto` просить зареєстровані обв’язки перевірити, чи підтримують вони визначеного постачальника/модель. -5. Якщо жоден зареєстрований каркас не підходить, OpenClaw використовує PI, якщо резервне - повернення до PI не вимкнене. +5. Якщо жодна зареєстрована обв’язка не підходить, OpenClaw використовує PI, якщо резервний перехід на PI не вимкнено. -Збої каркаса плагіна відображаються як збої виконання. У режимі `auto` резервне повернення до PI -використовується лише тоді, коли жоден зареєстрований каркас плагіна не підтримує визначеного -постачальника/модель. Щойно каркас плагіна взяв на себе виконання, OpenClaw не -переграє той самий хід через PI, оскільки це може змінити семантику автентифікації/середовища виконання -або дублювати побічні ефекти. +Збої Plugin-обв’язок відображаються як збої виконання. У режимі `auto` резервний перехід на PI +використовується лише тоді, коли жодна зареєстрована Plugin-обв’язка не підтримує визначеного +постачальника/модель. Щойно Plugin-обв’язка заявила про запуск, OpenClaw не +повторює той самий хід через PI, оскільки це може змінити семантику auth/runtime +або продублювати побічні ефекти. -Після вбудованого запуску вибраний ідентифікатор каркаса зберігається разом з ідентифікатором сесії. -Застарілі сесії, створені до закріплення каркасів, вважаються закріпленими за PI, щойно вони +Вибраний id обв’язки зберігається разом з id сесії після вбудованого запуску. +Застарілі сесії, створені до появи закріплення обв’язок, вважаються закріпленими за PI, щойно вони мають історію стенограми. Використовуйте нову/скинуту сесію під час перемикання між PI та -нативним каркасом плагіна. `/status` показує нестандартні ідентифікатори каркасів, як-от `codex`, -поруч із `Fast`; PI приховано, оскільки це типовий шлях сумісності. -Якщо вибраний каркас виглядає несподівано, увімкніть журналювання налагодження `agents/harness` і +нативною Plugin-обв’язкою. `/status` показує id обв’язок, що не є типовими, наприклад `codex`, +поруч із `Fast`; PI залишається прихованою, оскільки це типовий сумісний шлях. +Якщо вибрана обв’язка видається несподіваною, увімкніть налагоджувальне логування `agents/harness` і перевірте структурований запис Gateway `agent harness selected`. Він містить -ідентифікатор вибраного каркаса, причину вибору, політику середовища виконання/резервного повернення, а в -режимі `auto` — результат підтримки для кожного кандидата плагіна. +вибраний id обв’язки, причину вибору, політику runtime/fallback, а в режимі +`auto` — також результат підтримки для кожного кандидата Plugin. -Комплектний плагін Codex реєструє `codex` як свій ідентифікатор каркаса. Ядро трактує це -як звичайний ідентифікатор каркаса плагіна; специфічні для Codex псевдоніми мають належати плагіну +Вбудований Plugin Codex реєструє `codex` як id своєї обв’язки. Core розглядає це +як звичайний id Plugin-обв’язки; псевдоніми, специфічні для Codex, мають належати Plugin або config оператора, а не спільному селектору середовища виконання. -## Пара постачальник плюс каркас +## Поєднання постачальника та обв’язки -Більшість каркасів також мають реєструвати постачальника. Постачальник робить посилання на моделі, -стан автентифікації, метадані моделей і вибір `/model` видимими для решти -OpenClaw. Потім каркас заявляє про підтримку цього постачальника в `supports(...)`. +Більшість обв’язок також мають реєструвати постачальника. Постачальник робить посилання на моделі, +стан auth, метадані моделей і вибір `/model` видимими для решти +OpenClaw. Потім обв’язка заявляє цей постачальник у `supports(...)`. -Комплектний плагін Codex дотримується цього шаблону: +Вбудований Plugin Codex дотримується цього шаблону: -- бажані посилання на моделі для користувача: `openai/gpt-5.5` плюс +- бажані користувацькі посилання на моделі: `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"` -- посилання сумісності: застарілі посилання `codex/gpt-*` залишаються прийнятними, але нові - config не повинні використовувати їх як звичайні посилання постачальника/моделі -- ідентифікатор каркаса: `codex` -- автентифікація: синтетична доступність постачальника, оскільки каркас Codex володіє +- посилання для сумісності: застарілі посилання `codex/gpt-*` залишаються підтримуваними, але нові + config не повинні використовувати їх як звичайні посилання provider/model +- id обв’язки: `codex` +- auth: синтетична доступність постачальника, оскільки обв’язка Codex володіє нативним входом/сесією Codex -- запит app-server: OpenClaw надсилає до Codex «голий» ідентифікатор моделі та дозволяє - каркасу працювати з нативним протоколом app-server +- запит до app-server: OpenClaw надсилає до Codex лише id моделі й дозволяє + обв’язці взаємодіяти з нативним протоколом app-server -Плагін Codex є адитивним. Звичайні посилання `openai/gpt-*` і далі використовують -стандартний шлях постачальника OpenClaw, якщо ви примусово не задасте каркас Codex через +Plugin Codex є адитивним. Звичайні посилання `openai/gpt-*` і надалі використовують +звичайний шлях постачальника OpenClaw, якщо ви не примусово задасте обв’язку Codex через `embeddedHarness.runtime: "codex"`. Старіші посилання `codex/gpt-*` і далі вибирають -постачальника Codex і каркас задля сумісності. +постачальника та обв’язку Codex для сумісності. -Налаштування для оператора, приклади префіксів моделей і config лише для Codex див. у -[Каркас Codex](/uk/plugins/codex-harness). +Щодо налаштування оператором, прикладів префіксів моделей і конфігурацій лише для Codex див. +[Обв’язка Codex](/uk/plugins/codex-harness). -OpenClaw вимагає Codex app-server `0.118.0` або новішої версії. Плагін Codex перевіряє -ініціалізаційне рукостискання app-server і блокує старіші або безверсійні сервери, щоб +OpenClaw вимагає Codex app-server `0.125.0` або новіший. Plugin Codex перевіряє +ініціалізаційний handshake app-server і блокує старіші або неверсіоновані сервери, щоб OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано. +Поріг `0.125.0` включає підтримку payload нативного гачка MCP, що з’явилася в +Codex `0.124.0`, водночас прив’язуючи OpenClaw до новішої протестованої стабільної лінійки. ### Проміжне ПЗ результатів інструментів -Комплектні плагіни можуть підключати незалежне від середовища виконання проміжне ПЗ результатів інструментів через +Вбудовані Plugin можуть підключати нейтральне до середовища виконання проміжне ПЗ результатів інструментів через `api.registerAgentToolResultMiddleware(...)`, коли їхній маніфест оголошує -цільові ідентифікатори середовищ виконання в `contracts.agentToolResultMiddleware`. Цей довірений -шов призначений для асинхронних перетворень результатів інструментів, які мають виконуватися до того, як PI або Codex подасть -вивід інструмента назад у модель. +цільові id середовищ виконання в `contracts.agentToolResultMiddleware`. Цей довірений +механізм призначено для асинхронних перетворень результатів інструментів, які мають виконуватися +до того, як PI або Codex повернуть вихід інструмента назад у модель. -Застарілі комплектні плагіни все ще можуть використовувати +Застарілі вбудовані Plugin усе ще можуть використовувати `api.registerCodexAppServerExtensionFactory(...)` для проміжного ПЗ лише для Codex app-server, -але нові перетворення результатів мають використовувати нейтральний до середовища виконання API. -Хук лише для Pi `api.registerEmbeddedExtensionFactory(...)` було вилучено; -перетворення результатів інструментів Pi мають використовувати нейтральне до середовища виконання проміжне ПЗ. +але нові перетворення результатів мають використовувати API, нейтральний до середовища виконання. +Гачок лише для Pi `api.registerEmbeddedExtensionFactory(...)` було вилучено; +перетворення результатів інструментів Pi мають використовувати проміжне ПЗ, нейтральне до середовища виконання. -### Режим нативного каркаса Codex +### Режим нативної обв’язки Codex -Комплектний каркас `codex` — це нативний режим Codex для вбудованих ходів -агента OpenClaw. Спочатку увімкніть комплектний плагін `codex` і додайте `codex` до -`plugins.allow`, якщо у вашому config використовується обмежувальний список дозволених. Нативні config app-server -мають використовувати `openai/gpt-*` із `embeddedHarness.runtime: "codex"`. -Натомість використовуйте `openai-codex/*` для Codex OAuth через PI. Застарілі посилання на моделі `codex/*` -залишаються псевдонімами сумісності для нативного каркаса. +Вбудована обв’язка `codex` — це нативний режим Codex для вбудованих ходів +агента OpenClaw. Спочатку ввімкніть вбудований Plugin `codex` і додайте `codex` до +`plugins.allow`, якщо ваш config використовує обмежувальний список дозволених значень. Конфігурації нативного app-server +мають використовувати `openai/gpt-*` з `embeddedHarness.runtime: "codex"`. +Натомість використовуйте `openai-codex/*` для OAuth Codex через PI. Застарілі посилання на моделі `codex/*` +залишаються сумісними псевдонімами для нативної обв’язки. -Коли цей режим працює, Codex володіє нативним ідентифікатором потоку, поведінкою відновлення, -Compaction і виконанням app-server. OpenClaw і далі контролює канал чату, -видиме дзеркало стенограми, політику інструментів, погодження, доставку медіа та вибір сесії. -Використовуйте `embeddedHarness.runtime: "codex"` без перевизначення `fallback`, -коли вам потрібно довести, що виконання може взяти на себе лише шлях Codex app-server. -Явні середовища виконання плагіна вже типово завершуються із закритим контуром. Задавайте `fallback: "pi"` -лише тоді, коли ви свідомо хочете, щоб відсутній вибір каркаса оброблявся PI. Збої Codex -app-server уже завершуються напряму, а не з повторною спробою через PI. +Коли цей режим працює, Codex керує нативним id потоку, поведінкою відновлення, +Compaction і виконанням app-server. OpenClaw, як і раніше, керує каналом чату, +видимим дзеркалом стенограми, політикою інструментів, схваленнями, доставкою медіа та +вибором сесії. Використовуйте `embeddedHarness.runtime: "codex"` без перевизначення `fallback`, +коли потрібно довести, що лише шлях app-server Codex може заявити про цей запуск. +Явно задані Plugin runtime уже за замовчуванням завершуються з помилкою в закритому режимі. Встановлюйте `fallback: "pi"` +лише тоді, коли ви свідомо хочете, щоб PI обробляла відсутній вибір обв’язки. Збої Codex +app-server уже напряму завершуються помилкою замість повторної спроби через PI. -## Вимкнути резервне повернення до PI +## Вимкнення резервного переходу на PI -Типово OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, -встановленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані каркаси плагінів -можуть взяти на себе пару постачальник/модель. Якщо жоден не підходить, OpenClaw повертається до PI. +За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, +встановленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані Plugin-обв’язки +можуть заявити про пару постачальник/модель. Якщо жодна не підходить, OpenClaw повертається до PI. -У режимі `auto` задайте `fallback: "none"`, коли вам потрібно, щоб відсутність вибору каркаса плагіна -призводила до збою замість використання PI. Явні середовища виконання плагіна, як-от -`runtime: "codex"`, уже типово завершуються із закритим контуром, якщо лише `fallback: "pi"` не -встановлено в тій самій області перевизначення config або середовища. Збої вибраного каркаса плагіна -завжди завершуються жорстким збоєм. Це не блокує явний `runtime: "pi"` або +У режимі `auto` встановіть `fallback: "none"`, коли вам потрібно, щоб відсутність вибору Plugin-обв’язки +призводила до помилки замість використання PI. Явно задані Plugin runtime, такі як +`runtime: "codex"`, уже за замовчуванням завершуються з помилкою в закритому режимі, якщо лише `fallback: "pi"` не +задано в тій самій області перевизначення config або середовища. Збої вибраних Plugin-обв’язок +завжди завершуються жорсткою помилкою. Це не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. Для вбудованих запусків лише з Codex: @@ -212,9 +213,9 @@ app-server уже завершуються напряму, а не з повто } ``` -Якщо ви хочете, щоб будь-який зареєстрований каркас плагіна міг брати на себе відповідні моделі, але ніколи +Якщо ви хочете, щоб будь-яка зареєстрована Plugin-обв’язка могла заявити про відповідні моделі, але ніколи не хочете, щоб OpenClaw непомітно повертався до PI, залиште `runtime: "auto"` і вимкніть -резервне повернення: +резервний перехід: ```json { @@ -255,8 +256,8 @@ app-server уже завершуються напряму, а не з повто ``` `OPENCLAW_AGENT_RUNTIME` і далі перевизначає налаштоване середовище виконання. Використовуйте -`OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути резервне повернення до PI через -середовище. +`OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути резервний перехід на PI з +середовища. ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -264,53 +265,53 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Якщо резервне повернення вимкнене, сесія завершується збоєм на ранньому етапі, коли запитаний каркас не -зареєстрований, не підтримує визначеного постачальника/модель або завершується збоєм до +Коли резервний перехід вимкнено, сесія завершується помилкою на ранньому етапі, якщо запитана обв’язка не +зареєстрована, не підтримує визначеного постачальника/модель або завершується помилкою до створення побічних ефектів ходу. Це зроблено навмисно для розгортань лише з Codex і -для live-тестів, які мають довести, що шлях Codex app-server справді використовується. +для live-тестів, які мають довести, що шлях app-server Codex справді використовується. -Це налаштування керує лише каркасом вбудованого агента. Воно не вимикає -маршрутизацію моделей для зображень, відео, музики, TTS, PDF або інших специфічних для постачальника моделей. +Це налаштування керує лише обв’язкою вбудованого агента. Воно не вимикає маршрутизацію +зображень, відео, музики, TTS, PDF або інших моделей, специфічних для постачальника. ## Нативні сесії та дзеркало стенограми -Каркас може зберігати нативний ідентифікатор сесії, ідентифікатор потоку або маркер відновлення на боці демона. -Тримайте цей зв’язок явно асоційованим із сесією OpenClaw і продовжуйте -віддзеркалювати видимий користувачу вивід помічника/інструмента в стенограму OpenClaw. +Обв’язка може зберігати нативний id сесії, id потоку або токен відновлення на боці демона. +Явно пов’язуйте цю прив’язку із сесією OpenClaw і продовжуйте +віддзеркалювати видимий користувачеві вихід асистента/інструментів у стенограму OpenClaw. Стенограма OpenClaw залишається шаром сумісності для: - видимої в каналі історії сесії - пошуку та індексації стенограми -- перемикання назад на вбудований каркас PI на пізнішому ході -- узагальненої поведінки `/new`, `/reset` і видалення сесії +- повернення до вбудованої обв’язки PI на наступному ході +- загальної поведінки `/new`, `/reset` і видалення сесії -Якщо ваш каркас зберігає побічне прив’язування, реалізуйте `reset(...)`, щоб OpenClaw міг -очистити його, коли пов’язану сесію OpenClaw буде скинуто. +Якщо ваша обв’язка зберігає побічну прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг +очистити її, коли пов’язану сесію OpenClaw скинуто. ## Результати інструментів і медіа -Ядро формує список інструментів OpenClaw і передає його в підготовлену спробу. -Коли каркас виконує динамічний виклик інструмента, повертайте результат інструмента назад через -форму результату каркаса замість того, щоб самостійно надсилати медіа в канал. +Core формує список інструментів OpenClaw і передає його в підготовлену спробу. +Коли обв’язка виконує динамічний виклик інструмента, повертайте результат інструмента через +форму результату обв’язки замість того, щоб самостійно надсилати медіа в канал. -Це зберігає текст, зображення, відео, музику, TTS, погодження та виводи -інструментів обміну повідомленнями на тому самому шляху доставки, що й під час запусків на базі PI. +Це зберігає текст, зображення, відео, музику, TTS, схвалення та вихід інструментів обміну повідомленнями +в тому самому шляху доставки, що й для запусків на основі PI. ## Поточні обмеження -- Публічний шлях імпорту є узагальненим, але деякі псевдоніми типів спроби/результату все ще - мають назви `Pi` задля сумісності. -- Встановлення сторонніх каркасів є експериментальним. Віддавайте перевагу плагінам постачальників, +- Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроб/результатів усе ще + мають назви `Pi` для сумісності. +- Установлення сторонніх обв’язок є експериментальним. Віддавайте перевагу Plugin постачальника, доки вам не знадобиться нативне середовище виконання сесії. -- Перемикання каркасів між ходами підтримується. Не перемикайте каркаси посеред - ходу після того, як почалися нативні інструменти, погодження, текст помічника або +- Перемикання обв’язок між ходами підтримується. Не перемикайте обв’язки посеред + ходу після того, як уже почалися нативні інструменти, схвалення, текст асистента або надсилання повідомлень. ## Пов’язане - [Огляд SDK](/uk/plugins/sdk-overview) - [Допоміжні засоби середовища виконання](/uk/plugins/sdk-runtime) -- [Плагіни постачальників](/uk/plugins/sdk-provider-plugins) -- [Каркас Codex](/uk/plugins/codex-harness) +- [Plugin постачальника](/uk/plugins/sdk-provider-plugins) +- [Обв’язка Codex](/uk/plugins/codex-harness) - [Постачальники моделей](/uk/concepts/model-providers) diff --git a/docs/uk/providers/google.md b/docs/uk/providers/google.md index 3c4d87af5..37e6f5b7f 100644 --- a/docs/uk/providers/google.md +++ b/docs/uk/providers/google.md @@ -1,34 +1,34 @@ --- read_when: - Ви хочете використовувати моделі Google Gemini з OpenClaw - - Вам потрібен API-ключ або сценарій автентифікації OAuth -summary: Налаштування Google Gemini (API-ключ + OAuth, генерація зображень, розуміння медіа, TTS, вебпошук) + - Вам потрібен ключ API або потік автентифікації OAuth +summary: Налаштування Google Gemini (ключ API + OAuth, генерація зображень, розуміння медіа, TTS, вебпошук) title: Google (Gemini) x-i18n: - generated_at: "2026-04-25T05:58:00Z" + generated_at: "2026-04-25T20:39:58Z" model: gpt-5.4 provider: openai - source_hash: de0d6563d1c7a25fe26aa7ce255b1d3ed80e950b7761039e6d0a76f23a14e6f3 + source_hash: 990a2567790673261f7b018816ee3fb81fe03e662a78769248ee91311ff5d2fc source_path: providers/google.md workflow: 15 --- -Plugin `google` надає доступ до моделей Gemini через Google AI Studio, а також -генерацію зображень, розуміння медіа (зображення/аудіо/відео), перетворення тексту на мовлення та вебпошук через +Плагін Google надає доступ до моделей Gemini через Google AI Studio, а також до +генерації зображень, розуміння медіа (зображення/аудіо/відео), перетворення тексту на мовлення та вебпошуку через Gemini Grounding. -- Постачальник: `google` +- Провайдер: `google` - Автентифікація: `GEMINI_API_KEY` або `GOOGLE_API_KEY` - API: Google Gemini API -- Параметр середовища виконання: `agents.defaults.embeddedHarness.runtime: "google-gemini-cli"` +- Опція середовища виконання: `agents.defaults.embeddedHarness.runtime: "google-gemini-cli"` повторно використовує OAuth Gemini CLI, зберігаючи канонічні посилання на моделі як `google/*`. ## Початок роботи -Виберіть бажаний метод автентифікації та виконайте кроки налаштування. +Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування. - + **Найкраще для:** стандартного доступу до Gemini API через Google AI Studio. @@ -37,7 +37,7 @@ Gemini Grounding. openclaw onboard --auth-choice gemini-api-key ``` - Або передайте ключ безпосередньо: + Або передайте ключ напряму: ```bash openclaw onboard --non-interactive \ @@ -46,7 +46,7 @@ Gemini Grounding. --gemini-api-key "$GEMINI_API_KEY" ``` - + ```json5 { agents: { @@ -65,33 +65,33 @@ Gemini Grounding. - Обидві змінні середовища `GEMINI_API_KEY` і `GOOGLE_API_KEY` підтримуються. Використовуйте ту, яку вже налаштовано у вас. + Змінні середовища `GEMINI_API_KEY` і `GOOGLE_API_KEY` обидві підтримуються. Використовуйте ту, яка у вас уже налаштована. - **Найкраще для:** повторного використання наявного входу Gemini CLI через PKCE OAuth замість окремого API-ключа. + **Найкраще для:** повторного використання наявного входу Gemini CLI через PKCE OAuth замість окремого ключа API. - Постачальник `google-gemini-cli` є неофіційною інтеграцією. Деякі користувачі - повідомляють про обмеження облікового запису при такому використанні OAuth. Використовуйте на власний ризик. + Провайдер `google-gemini-cli` є неофіційною інтеграцією. Деякі користувачі + повідомляють про обмеження акаунта при такому використанні OAuth. Використовуйте на власний ризик. - Локальна команда `gemini` має бути доступною в `PATH`. + Локальна команда `gemini` має бути доступна в `PATH`. ```bash # Homebrew brew install gemini-cli - # або npm + # or npm npm install -g @google/gemini-cli ``` - OpenClaw підтримує як встановлення через Homebrew, так і глобальні встановлення npm, включно з - поширеними схемами Windows/npm. + OpenClaw підтримує як встановлення через Homebrew, так і глобальні встановлення через npm, включно з + поширеними Windows/npm-макетами. ```bash @@ -117,17 +117,17 @@ Gemini Grounding. (Або варіанти `GEMINI_CLI_*`.) - Якщо запити Gemini CLI OAuth не вдаються після входу, задайте `GOOGLE_CLOUD_PROJECT` або - `GOOGLE_CLOUD_PROJECT_ID` на хості gateway і повторіть спробу. + Якщо запити OAuth Gemini CLI не вдаються після входу, встановіть `GOOGLE_CLOUD_PROJECT` або + `GOOGLE_CLOUD_PROJECT_ID` на хості Gateway і повторіть спробу. - Якщо вхід не вдається ще до запуску сценарію браузера, переконайтеся, що локальну команду `gemini` - встановлено і вона є в `PATH`. + Якщо вхід завершується невдачею ще до запуску потоку в браузері, переконайтеся, що локальна команда `gemini` + встановлена та доступна в `PATH`. - Посилання на моделі `google-gemini-cli/*` — це застарілі псевдоніми сумісності. Нові - конфігурації мають використовувати посилання на моделі `google/*` плюс середовище виконання `google-gemini-cli`, + Посилання на моделі `google-gemini-cli/*` є застарілими псевдонімами сумісності. У нових + конфігураціях слід використовувати посилання на моделі `google/*` плюс середовище виконання `google-gemini-cli`, коли потрібне локальне виконання Gemini CLI. @@ -135,40 +135,40 @@ Gemini Grounding. ## Можливості -| Можливість | Підтримується | -| --------------------- | ---------------------------- | -| Завершення чату | Так | -| Генерація зображень | Так | -| Генерація музики | Так | -| Перетворення тексту на мовлення | Так | -| Голос у реальному часі | Так (Google Live API) | -| Розуміння зображень | Так | -| Транскрипція аудіо | Так | -| Розуміння відео | Так | -| Вебпошук (Grounding) | Так | -| Thinking/reasoning | Так (Gemini 2.5+ / Gemini 3+) | -| Моделі Gemma 4 | Так | +| Можливість | Підтримка | +| --------------------- | ------------------------------ | +| Завершення чату | Так | +| Генерація зображень | Так | +| Генерація музики | Так | +| Перетворення тексту на мовлення | Так | +| Голос у реальному часі | Так (Google Live API) | +| Розуміння зображень | Так | +| Транскрипція аудіо | Так | +| Розуміння відео | Так | +| Вебпошук (Grounding) | Так | +| Мислення/міркування | Так (Gemini 2.5+ / Gemini 3+) | +| Моделі Gemma 4 | Так | -Моделі Gemini 3 використовують `thinkingLevel`, а не `thinkingBudget`. OpenClaw зіставляє -керування reasoning для Gemini 3, Gemini 3.1 і псевдонімів `gemini-*-latest` із -`thinkingLevel`, щоб запуск за замовчуванням/із низькою затримкою не надсилав вимкнені +Моделі Gemini 3 використовують `thinkingLevel` замість `thinkingBudget`. OpenClaw зіставляє +керування міркуванням для Gemini 3, Gemini 3.1 і псевдонімів `gemini-*-latest` з +`thinkingLevel`, щоб типові запуски та запуски з низькою затримкою не надсилали вимкнені значення `thinkingBudget`. -`/think adaptive` зберігає динамічну семантику thinking від Google замість вибору +`/think adaptive` зберігає семантику динамічного мислення Google замість вибору фіксованого рівня OpenClaw. Gemini 3 і Gemini 3.1 не задають фіксований `thinkingLevel`, тому Google може вибрати рівень; Gemini 2.5 надсилає динамічний sentinel Google `thinkingBudget: -1`. -Моделі Gemma 4 (наприклад, `gemma-4-26b-a4b-it`) підтримують режим thinking. OpenClaw -переписує `thinkingBudget` у підтримуваний Google `thinkingLevel` для Gemma 4. -Якщо встановити thinking у `off`, thinking залишиться вимкненим замість зіставлення з +Моделі Gemma 4 (наприклад, `gemma-4-26b-a4b-it`) підтримують режим мислення. OpenClaw +перезаписує `thinkingBudget` у підтримуваний Google `thinkingLevel` для Gemma 4. +Установлення мислення в `off` зберігає вимкнений стан мислення замість зіставлення з `MINIMAL`. ## Генерація зображень -Вбудований постачальник генерації зображень `google` за замовчуванням використовує +Вбудований провайдер генерації зображень `google` за замовчуванням використовує `google/gemini-3.1-flash-image-preview`. - Також підтримує `google/gemini-3-pro-image-preview` @@ -176,7 +176,7 @@ Google може вибрати рівень; Gemini 2.5 надсилає дин - Режим редагування: увімкнено, до 5 вхідних зображень - Керування геометрією: `size`, `aspectRatio` і `resolution` -Щоб використовувати Google як постачальника зображень за замовчуванням: +Щоб використовувати Google як провайдера зображень за замовчуванням: ```json5 { @@ -191,7 +191,7 @@ Google може вибрати рівень; Gemini 2.5 надсилає дин ``` -Спільні параметри інструмента, вибір постачальника й поведінку failover див. у [Image Generation](/uk/tools/image-generation). +Див. [Генерація зображень](/uk/tools/image-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover. ## Генерація відео @@ -200,11 +200,11 @@ Google може вибрати рівень; Gemini 2.5 надсилає дин інструмент `video_generate`. - Модель відео за замовчуванням: `google/veo-3.1-fast-generate-preview` -- Режими: text-to-video, image-to-video і сценарії з одним еталонним відео +- Режими: text-to-video, image-to-video та потоки з посиланням на одне відео - Підтримує `aspectRatio`, `resolution` і `audio` - Поточне обмеження тривалості: **від 4 до 8 секунд** -Щоб використовувати Google як постачальника відео за замовчуванням: +Щоб використовувати Google як провайдера відео за замовчуванням: ```json5 { @@ -219,7 +219,7 @@ Google може вибрати рівень; Gemini 2.5 надсилає дин ``` -Спільні параметри інструмента, вибір постачальника й поведінку failover див. у [Video Generation](/uk/tools/video-generation). +Див. [Генерація відео](/uk/tools/video-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover. ## Генерація музики @@ -231,10 +231,10 @@ Google може вибрати рівень; Gemini 2.5 надсилає дин - Також підтримує `google/lyria-3-pro-preview` - Керування промптом: `lyrics` і `instrumental` - Формат виводу: `mp3` за замовчуванням, а також `wav` для `google/lyria-3-pro-preview` -- Еталонні входи: до 10 зображень -- Запуски з опорою на сесію відокремлюються через спільний потік task/status, включно з `action: "status"` +- Вхідні дані-посилання: до 10 зображень +- Запуски з підтримкою сесій від’єднуються через спільний потік завдань/статусу, включно з `action: "status"` -Щоб використовувати Google як постачальника музики за замовчуванням: +Щоб використовувати Google як провайдера музики за замовчуванням: ```json5 { @@ -249,20 +249,20 @@ Google може вибрати рівень; Gemini 2.5 надсилає дин ``` -Спільні параметри інструмента, вибір постачальника й поведінку failover див. у [Music Generation](/uk/tools/music-generation). +Див. [Генерація музики](/uk/tools/music-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover. ## Перетворення тексту на мовлення -Вбудований постачальник мовлення `google` використовує шлях Gemini API TTS з +Вбудований мовленнєвий провайдер `google` використовує шлях Gemini API TTS з `gemini-3.1-flash-tts-preview`. - Голос за замовчуванням: `Kore` - Автентифікація: `messages.tts.providers.google.apiKey`, `models.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_API_KEY` -- Вивід: WAV для звичайних вкладень TTS, PCM для Talk/телефонії -- Нативний вивід голосових нотаток: не підтримується на цьому шляху Gemini API, оскільки API повертає PCM, а не Opus +- Вивід: WAV для звичайних TTS-вкладень, Opus для цілей голосових нотаток, PCM для Talk/телефонії +- Вивід голосових нотаток: Google PCM обгортається у WAV і транскодується в 48 кГц Opus за допомогою `ffmpeg` -Щоб використовувати Google як постачальника TTS за замовчуванням: +Щоб використовувати Google як TTS-провайдера за замовчуванням: ```json5 { @@ -282,39 +282,39 @@ Google може вибрати рівень; Gemini 2.5 надсилає дин } ``` -Gemini API TTS використовує промпти природною мовою для керування стилем. Задайте -`audioProfile`, щоб додати повторно використовуваний стильовий промпт перед озвучуваним текстом. Задайте -`speakerName`, якщо текст вашого промпту посилається на іменованого мовця. +Gemini API TTS використовує промпти природною мовою для керування стилем. Установіть +`audioProfile`, щоб додавати багаторазовий стильовий промпт перед озвученим текстом. Установіть +`speakerName`, якщо текст вашого промпта посилається на іменованого мовця. Gemini API TTS також приймає виразні квадратні аудіотеги в тексті, -такі як `[whispers]` або `[laughs]`. Щоб теги не потрапляли у видиму відповідь чату, -але надсилалися в TTS, помістіть їх у блок `[[tts:text]]...[[/tts:text]]`: +наприклад `[whispers]` або `[laughs]`. Щоб не показувати теги у видимій відповіді чату, +але надсилати їх у TTS, помістіть їх у блок `[[tts:text]]...[[/tts:text]]`: ```text -Here is the clean reply text. +Ось чистий текст відповіді. -[[tts:text]][whispers] Here is the spoken version.[[/tts:text]] +[[tts:text]][whispers] Ось озвучена версія.[[/tts:text]] ``` -API-ключ Google Cloud Console, обмежений Gemini API, є дійсним для цього -постачальника. Це не окремий шлях Cloud Text-to-Speech API. +Ключ API Google Cloud Console, обмежений Gemini API, є дійсним для цього +провайдера. Це не окремий шлях Cloud Text-to-Speech API. ## Голос у реальному часі -Вбудований Plugin `google` реєструє постачальника голосу в реальному часі на основі -Gemini Live API для серверних аудіомостів, таких як Voice Call і Google Meet. +Вбудований Plugin `google` реєструє провайдера голосу в реальному часі на базі +Gemini Live API для бекендових аудіомостів, таких як Voice Call і Google Meet. -| Налаштування | Шлях конфігурації | За замовчуванням | -| --------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | -| Модель | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` | -| Голос | `...google.voice` | `Kore` | -| Temperature | `...google.temperature` | (не задано) | -| Чутливість початку VAD | `...google.startSensitivity` | (не задано) | -| Чутливість завершення VAD | `...google.endSensitivity` | (не задано) | -| Тривалість тиші | `...google.silenceDurationMs` | (не задано) | -| API-ключ | `...google.apiKey` | Резервно береться з `models.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_API_KEY` | +| Параметр | Шлях конфігурації | Значення за замовчуванням | +| --------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| Модель | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` | +| Голос | `...google.voice` | `Kore` | +| Temperature | `...google.temperature` | (не встановлено) | +| Чутливість початку VAD | `...google.startSensitivity` | (не встановлено) | +| Чутливість завершення VAD | `...google.endSensitivity` | (не встановлено) | +| Тривалість тиші | `...google.silenceDurationMs` | (не встановлено) | +| Ключ API | `...google.apiKey` | Використовує `models.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_API_KEY` як резервне значення | Приклад конфігурації Voice Call у реальному часі: @@ -343,33 +343,33 @@ Gemini Live API для серверних аудіомостів, таких я ``` -Google Live API використовує двоспрямоване аудіо та виклики функцій через WebSocket. -OpenClaw адаптує аудіо мостів телефонії/Meet до PCM-потоку Live API Gemini і -зберігає виклики інструментів у межах спільного контракту голосу в реальному часі. Залишайте `temperature` -не заданим, якщо вам не потрібні зміни семплування; OpenClaw не надсилає непозитивні значення, -оскільки Google Live може повертати транскрипти без аудіо при `temperature: 0`. -Транскрипція Gemini API вмикається без `languageCodes`; поточний SDK Google -відхиляє підказки з кодами мов на цьому шляху API. +Google Live API використовує двобічне аудіо та виклик функцій через WebSocket. +OpenClaw адаптує аудіо телефонії/мосту Meet до PCM-потоку Gemini Live API і +зберігає виклики інструментів у спільному контракті голосу в реальному часі. Залишайте `temperature` +не встановленим, якщо вам не потрібні зміни семплювання; OpenClaw пропускає недодатні значення, +оскільки Google Live може повертати транскрипти без аудіо для `temperature: 0`. +Транскрипцію Gemini API увімкнено без `languageCodes`; поточний SDK Google +відхиляє підказки кодів мов на цьому шляху API. -Сеанси браузера Talk у Control UI все ще потребують постачальника голосу в реальному часі з -реалізацією браузерної сесії WebRTC. Наразі цим шляхом є OpenAI Realtime; постачальник -Google призначений для серверних мостів реального часу. +Сеанси браузера Talk у Control UI, як і раніше, потребують провайдера голосу в реальному часі з +реалізацією браузерного сеансу WebRTC. Наразі цей шлях — OpenAI Realtime; провайдер +Google призначений для бекендових мостів реального часу. ## Розширена конфігурація - + Для прямих запусків Gemini API (`api: "google-generative-ai"`) OpenClaw - передає налаштований дескриптор `cachedContent` безпосередньо в запити Gemini. + передає налаштований дескриптор `cachedContent` у запити Gemini. - - Налаштуйте параметри для окремої моделі або глобально за допомогою + - Налаштовуйте параметри для окремих моделей або глобально за допомогою `cachedContent` або застарілого `cached_content` - Якщо присутні обидва, пріоритет має `cachedContent` - Приклад значення: `cachedContents/prebuilt-context` - - Використання кеш-влучань Gemini нормалізується в OpenClaw `cacheRead` з + - Використання Gemini cache-hit нормалізується в OpenClaw як `cacheRead` з вихідного `cachedContentTokenCount` ```json5 @@ -391,12 +391,12 @@ Google призначений для серверних мостів реаль - При використанні постачальника OAuth `google-gemini-cli` OpenClaw нормалізує + Під час використання OAuth-провайдера `google-gemini-cli` OpenClaw нормалізує JSON-вивід CLI таким чином: - Текст відповіді береться з поля CLI JSON `response`. - - Використання резервно береться з `stats`, коли CLI залишає `usage` порожнім. - - `stats.cached` нормалізується в OpenClaw `cacheRead`. + - Використання бере `stats` як резервне значення, якщо CLI залишає `usage` порожнім. + - `stats.cached` нормалізується в OpenClaw як `cacheRead`. - Якщо `stats.input` відсутній, OpenClaw виводить вхідні токени з `stats.input_tokens - stats.cached`. @@ -413,15 +413,15 @@ Google призначений для серверних мостів реаль - Вибір постачальників, посилань на моделі та поведінки failover. + Вибір провайдерів, посилань на моделі та поведінки failover. - Спільні параметри інструмента зображень і вибір постачальника. + Спільні параметри інструмента зображень і вибір провайдера. - Спільні параметри інструмента відео і вибір постачальника. + Спільні параметри відеоінструмента та вибір провайдера. - Спільні параметри інструмента музики і вибір постачальника. + Спільні параметри музичного інструмента та вибір провайдера. diff --git a/docs/uk/tools/tts.md b/docs/uk/tools/tts.md index b3312b24e..18ef62c53 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-25T18:15:09Z" + generated_at: "2026-04-25T20:39:59Z" model: gpt-5.4 provider: openai - source_hash: 2c56c42f201139a7277153a6a1409ef9a288264e0702d2940b74b08ece385718 + source_hash: b780ad48492ebc91a28d252bec53116a265eabde7ff658b031d9785fba8df34e source_path: tools/tts.md workflow: 15 --- @@ -19,29 +19,30 @@ OpenClaw може перетворювати вихідні відповіді ## Підтримувані сервіси -- **ElevenLabs** (основний або резервний provider) -- **Google Gemini** (основний або резервний provider; використовує Gemini API TTS) -- **Gradium** (основний або резервний provider; підтримує вихід voice-note і telephony) -- **Local CLI** (основний або резервний provider; запускає налаштовану локальну команду TTS) -- **Microsoft** (основний або резервний provider; поточна вбудована реалізація використовує `node-edge-tts`) -- **MiniMax** (основний або резервний provider; використовує API T2A v2) -- **OpenAI** (основний або резервний provider; також використовується для підсумків) -- **Vydra** (основний або резервний provider; спільний provider зображень, відео та мовлення) -- **xAI** (основний або резервний provider; використовує xAI TTS API) -- **Xiaomi MiMo** (основний або резервний provider; використовує MiMo TTS через Xiaomi chat completions) +- **ElevenLabs** (основний або резервний провайдер) +- **Google Gemini** (основний або резервний провайдер; використовує Gemini API TTS) +- **Gradium** (основний або резервний провайдер; підтримує вихід у форматі голосових повідомлень і телефонії) +- **Local CLI** (основний або резервний провайдер; запускає налаштовану локальну команду TTS) +- **Microsoft** (основний або резервний провайдер; поточна вбудована реалізація використовує `node-edge-tts`) +- **MiniMax** (основний або резервний провайдер; використовує API T2A v2) +- **OpenAI** (основний або резервний провайдер; також використовується для зведень) +- **Vydra** (основний або резервний провайдер; спільний провайдер для зображень, відео та мовлення) +- **xAI** (основний або резервний провайдер; використовує xAI TTS API) +- **Xiaomi MiMo** (основний або резервний провайдер; використовує MiMo TTS через Xiaomi chat completions) -### Примітки щодо Microsoft speech +### Примітки щодо мовлення Microsoft -Поточний вбудований provider Microsoft speech зараз використовує онлайн-сервіс -нейронного TTS від Microsoft Edge через бібліотеку `node-edge-tts`. Це хостований сервіс (не -локальний), він використовує endpoint-и Microsoft і не потребує API-ключа. -`node-edge-tts` надає параметри налаштування мовлення та формати виводу, але -сервіс підтримує не всі параметри. Застаріла конфігурація та введення директив -із використанням `edge` усе ще працюють і нормалізуються до `microsoft`. +Поточний вбудований провайдер мовлення Microsoft використовує онлайновий +нейронний сервіс TTS Microsoft Edge через бібліотеку `node-edge-tts`. Це +хостований сервіс (не локальний), він використовує кінцеві точки Microsoft і +не потребує API-ключа. +`node-edge-tts` надає параметри конфігурації мовлення та формати виводу, але +не всі параметри підтримуються сервісом. Застаріла конфігурація та введення +директив із використанням `edge` усе ще працюють і нормалізуються до `microsoft`. Оскільки цей шлях використовує публічний вебсервіс без опублікованого SLA або квоти, -розглядайте його як best-effort. Якщо вам потрібні гарантовані ліміти й підтримка, використовуйте OpenAI -або ElevenLabs. +сприймайте його як best-effort. Якщо вам потрібні гарантовані ліміти та підтримка, +використовуйте OpenAI або ElevenLabs. ## Необов’язкові ключі @@ -58,11 +59,11 @@ OpenClaw може перетворювати вихідні відповіді - `XAI_API_KEY` - `XIAOMI_API_KEY` -Local CLI і Microsoft speech **не** потребують API-ключа. +Local CLI і мовлення Microsoft **не** потребують API-ключа. -Якщо налаштовано кілька provider, спочатку використовується вибраний provider, а інші стають резервними варіантами. -Автопідсумок використовує налаштований `summaryModel` (або `agents.defaults.model.primary`), -тому якщо ви вмикаєте підсумки, цей provider також має бути автентифікований. +Якщо налаштовано кілька провайдерів, спочатку використовується вибраний провайдер, а решта слугують резервними варіантами. +Автоматичне зведення використовує налаштований `summaryModel` (або `agents.defaults.model.primary`), +тому цей провайдер також має бути автентифікований, якщо ви вмикаєте зведення. ## Посилання на сервіси @@ -71,7 +72,7 @@ Local CLI і Microsoft speech **не** потребують API-ключа. - [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech) - [Автентифікація ElevenLabs](https://elevenlabs.io/docs/api-reference/authentication) - [Gradium](/uk/providers/gradium) -- [MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2) +- [API MiniMax T2A v2](https://platform.minimaxi.com/document/T2A%20V2) - [Синтез мовлення Xiaomi MiMo](/uk/providers/xiaomi#text-to-speech) - [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts) - [Формати виводу Microsoft Speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) @@ -79,18 +80,18 @@ Local CLI і Microsoft speech **не** потребують API-ключа. ## Чи ввімкнено це за замовчуванням? -Ні. Авто‑TTS **вимкнено** за замовчуванням. Увімкніть його в конфігурації через +Ні. Auto‑TTS **вимкнено** за замовчуванням. Увімкніть його в конфігурації через `messages.tts.auto` або локально через `/tts on`. Коли `messages.tts.provider` не задано, OpenClaw вибирає перший налаштований -provider speech у порядку автоматичного вибору реєстру. +провайдер мовлення в порядку автовибору реєстру. ## Конфігурація -Конфігурація TTS розміщена в `messages.tts` у `openclaw.json`. -Повна схема наведена в [Конфігурація Gateway](/uk/gateway/configuration). +Конфігурація TTS знаходиться в `messages.tts` у `openclaw.json`. +Повну схему наведено в [Конфігурація Gateway](/uk/gateway/configuration). -### Мінімальна конфігурація (увімкнення + provider) +### Мінімальна конфігурація (увімкнення + провайдер) ```json5 { @@ -191,12 +192,12 @@ provider speech у порядку автоматичного вибору реє } ``` -Порядок визначення автентифікації MiniMax TTS: `messages.tts.providers.minimax.apiKey`, далі -збережені профілі OAuth/token `minimax-portal`, далі ключі середовища Token Plan +Порядок визначення автентифікації MiniMax TTS такий: `messages.tts.providers.minimax.apiKey`, потім +збережені профілі OAuth/token `minimax-portal`, потім ключі середовища Token Plan (`MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY`, -`MINIMAX_CODING_API_KEY`), далі `MINIMAX_API_KEY`. Якщо явний TTS -`baseUrl` не задано, OpenClaw може повторно використати налаштований OAuth-хост `minimax-portal` -для Token Plan speech. +`MINIMAX_CODING_API_KEY`), потім `MINIMAX_API_KEY`. Якщо явний TTS +`baseUrl` не задано, OpenClaw може повторно використати налаштований OAuth-хост +`minimax-portal` для мовлення Token Plan. ### Google Gemini як основний @@ -220,7 +221,7 @@ provider speech у порядку автоматичного вибору реє Google Gemini TTS використовує шлях API-ключа Gemini. API-ключ Google Cloud Console, обмежений Gemini API, тут є дійсним, і це той самий тип ключа, який використовується -вбудованим provider генерації зображень Google. Порядок визначення: +вбудованим провайдером генерації зображень Google. Порядок визначення: `messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` -> `GEMINI_API_KEY` -> `GOOGLE_API_KEY`. @@ -246,10 +247,10 @@ Google Gemini TTS використовує шлях API-ключа Gemini. API- } ``` -xAI TTS використовує той самий шлях `XAI_API_KEY`, що й вбудований provider моделі Grok. +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`. +Поточні доступні голоси: `ara`, `eve`, `leo`, `rex`, `sal` і `una`; типовим є +`eve`. `language` приймає тег BCP-47 або `auto`. ### Xiaomi MiMo як основний @@ -274,10 +275,10 @@ xAI TTS використовує той самий шлях `XAI_API_KEY`, що } ``` -Xiaomi MiMo TTS використовує той самий шлях `XIAOMI_API_KEY`, що й вбудований provider моделі Xiaomi. -Ідентифікатор provider speech — `xiaomi`; `mimo` також приймається як псевдонім. -Цільовий текст надсилається як повідомлення асистента, що відповідає контракту TTS Xiaomi. -Необов’язковий `style` надсилається як інструкція користувача і не озвучується. +Xiaomi MiMo TTS використовує той самий шлях `XIAOMI_API_KEY`, що й вбудований провайдер моделі Xiaomi. +Ідентифікатор провайдера мовлення — `xiaomi`; `mimo` також приймається як псевдонім. +Цільовий текст надсилається як повідомлення помічника, що відповідає контракту TTS +Xiaomi. Необов’язковий `style` надсилається як інструкція користувача і не озвучується. ### OpenRouter як основний @@ -301,7 +302,7 @@ Xiaomi MiMo TTS використовує той самий шлях `XIAOMI_API_ ``` OpenRouter TTS використовує той самий шлях `OPENROUTER_API_KEY`, що й вбудований -provider моделі OpenRouter. Порядок визначення: +провайдер моделі OpenRouter. Порядок визначення: `messages.tts.providers.openrouter.apiKey` -> `models.providers.openrouter.apiKey` -> `OPENROUTER_API_KEY`. @@ -326,12 +327,13 @@ provider моделі OpenRouter. Порядок визначення: } ``` -Local CLI TTS запускає налаштовану команду на хості gateway. Заповнювачі `{{Text}}`, +Local CLI TTS запускає налаштовану команду на хості Gateway. Заповнювачі `{{Text}}`, `{{OutputPath}}`, `{{OutputDir}}` і `{{OutputBase}}` розгортаються в `args`; якщо заповнювач `{{Text}}` відсутній, OpenClaw записує -озвучуваний текст у stdin. `outputFormat` приймає `mp3`, `opus` або `wav`. -Цілі voice-note транскодуються в Ogg/Opus, а вихід telephony транскодується в raw 16 kHz mono PCM за допомогою `ffmpeg`. Застарілий псевдонім provider -`cli` усе ще працює, але нова конфігурація повинна використовувати `tts-local-cli`. +текст для озвучення у stdin. `outputFormat` приймає `mp3`, `opus` або `wav`. +Цілі для голосових повідомлень перекодовуються в Ogg/Opus, а вихід для телефонії +перекодовується в raw 16 kHz mono PCM за допомогою `ffmpeg`. Застарілий псевдонім провайдера +`cli` усе ще працює, але в новій конфігурації слід використовувати `tts-local-cli`. ### Gradium як основний @@ -353,7 +355,7 @@ Local CLI TTS запускає налаштовану команду на хос } ``` -### Вимкнути Microsoft speech +### Вимкнути мовлення Microsoft ```json5 { @@ -396,7 +398,7 @@ Local CLI TTS запускає налаштовану команду на хос } ``` -### Вимкнути автопідсумок для довгих відповідей +### Вимкнути автоматичне зведення для довгих відповідей ```json5 { @@ -416,100 +418,100 @@ Local CLI TTS запускає налаштовану команду на хос ### Примітки щодо полів -- `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`). -- `mode`: `"final"` (за замовчуванням) або `"all"` (включно з відповідями інструментів/блокувань). -- `provider`: ідентифікатор provider speech, наприклад `"elevenlabs"`, `"google"`, `"gradium"`, `"microsoft"`, `"minimax"`, `"openai"`, `"vydra"`, `"xai"` або `"xiaomi"` (резервний варіант вибирається автоматично). -- Якщо `provider` **не задано**, OpenClaw використовує перший налаштований provider speech у порядку автоматичного вибору реєстру. -- Застарілу конфігурацію `provider: "edge"` виправляє `openclaw doctor --fix`, переписуючи її на - `provider: "microsoft"`. -- `summaryModel`: необов’язкова дешева модель для автопідсумку; за замовчуванням використовується `agents.defaults.model.primary`. +- `mode`: `"final"` (типово) або `"all"` (включає відповіді інструментів/блоків). +- `provider`: ідентифікатор провайдера мовлення, наприклад `"elevenlabs"`, `"google"`, `"gradium"`, `"microsoft"`, `"minimax"`, `"openai"`, `"vydra"`, `"xai"` або `"xiaomi"` (резервний перехід відбувається автоматично). +- Якщо `provider` **не задано**, OpenClaw використовує перший налаштований провайдер мовлення в порядку автовибору реєстру. +- Застаріла конфігурація `provider: "edge"` виправляється командою `openclaw doctor --fix` і + переписується на `provider: "microsoft"`. +- `summaryModel`: необов’язкова недорога модель для автоматичного зведення; типово використовується `agents.defaults.model.primary`. - Приймає `provider/model` або псевдонім налаштованої моделі. -- `modelOverrides`: дозволяє моделі генерувати директиви TTS (увімкнено за замовчуванням). - - `allowProvider` за замовчуванням має значення `false` (перемикання provider вмикається окремо). -- `providers.`: налаштування, що належать provider, з ключем за ідентифікатором provider speech. -- Застарілі прямі блоки provider (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) виправляються через `openclaw doctor --fix`; у збереженій конфігурації слід використовувати `messages.tts.providers.`. -- Застарілий `messages.tts.providers.edge` також виправляється через `openclaw doctor --fix`; у збереженій конфігурації слід використовувати `messages.tts.providers.microsoft`. +- `modelOverrides`: дозволяє моделі виводити директиви TTS (увімкнено за замовчуванням). + - `allowProvider` типово має значення `false` (перемикання провайдера потребує явного дозволу). +- `providers.`: налаштування, що належать провайдеру, із ключем за ідентифікатором провайдера мовлення. +- Застарілі прямі блоки провайдерів (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) виправляються командою `openclaw doctor --fix`; у збереженій конфігурації слід використовувати `messages.tts.providers.`. +- Застарілий `messages.tts.providers.edge` також виправляється командою `openclaw doctor --fix`; у збереженій конфігурації слід використовувати `messages.tts.providers.microsoft`. - `maxTextLength`: жорстке обмеження для вхідного тексту TTS (символи). `/tts audio` завершується помилкою, якщо його перевищено. - `timeoutMs`: тайм-аут запиту (мс). -- `prefsPath`: перевизначає локальний шлях до JSON-файлу prefs (provider/ліміт/підсумок). +- `prefsPath`: перевизначає локальний шлях до JSON-файлу налаштувань (провайдер/ліміт/зведення). - Значення `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`, `XIAOMI_API_KEY`). - `providers.elevenlabs.baseUrl`: перевизначає базову URL-адресу API ElevenLabs. -- `providers.openai.baseUrl`: перевизначає endpoint OpenAI TTS. +- `providers.openai.baseUrl`: перевизначає кінцеву точку OpenAI TTS. - Порядок визначення: `messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` - - Значення, відмінні від стандартного, трактуються як OpenAI-сумісні endpoint-и TTS, тому приймаються користувацькі назви моделей і голосів. + - Нетипові значення трактуються як OpenAI-сумісні кінцеві точки TTS, тому дозволені власні назви моделей і голосів. - `providers.elevenlabs.voiceSettings`: - `stability`, `similarityBoost`, `style`: `0..1` - `useSpeakerBoost`: `true|false` - `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.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`). -- `providers.minimax.speed`: швидкість відтворення `0.5..2.0` (за замовчуванням 1.0). -- `providers.minimax.vol`: гучність `(0, 10]` (за замовчуванням 1.0; має бути більшою за 0). -- `providers.minimax.pitch`: цілий зсув тону `-12..12` (за замовчуванням 0). Дробові значення усікаються перед викликом MiniMax T2A, оскільки API відхиляє нецілі значення `pitch`. +- `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`). +- `providers.minimax.speed`: швидкість відтворення `0.5..2.0` (типово 1.0). +- `providers.minimax.vol`: гучність `(0, 10]` (типово 1.0; має бути більшою за 0). +- `providers.minimax.pitch`: цілочисельне зміщення тону `-12..12` (типово 0). Дробові значення відкидаються перед викликом MiniMax T2A, оскільки API відхиляє нецілі значення тону. - `providers.tts-local-cli.command`: локальний виконуваний файл або рядок команди для CLI TTS. -- `providers.tts-local-cli.args`: аргументи команди; підтримує заповнювачі `{{Text}}`, `{{OutputPath}}`, `{{OutputDir}}` і `{{OutputBase}}`. -- `providers.tts-local-cli.outputFormat`: очікуваний формат виводу CLI (`mp3`, `opus` або `wav`; за замовчуванням `mp3` для аудіовкладень). -- `providers.tts-local-cli.timeoutMs`: тайм-аут команди в мілісекундах (за замовчуванням `120000`). +- `providers.tts-local-cli.args`: аргументи команди; підтримуються заповнювачі `{{Text}}`, `{{OutputPath}}`, `{{OutputDir}}` і `{{OutputBase}}`. +- `providers.tts-local-cli.outputFormat`: очікуваний формат виводу CLI (`mp3`, `opus` або `wav`; типово `mp3` для аудіовкладень). +- `providers.tts-local-cli.timeoutMs`: тайм-аут команди в мілісекундах (типово `120000`). - `providers.tts-local-cli.cwd`: необов’язковий робочий каталог команди. -- `providers.tts-local-cli.env`: необов’язкові строкові перевизначення середовища для команди. -- `providers.google.model`: модель Gemini TTS (за замовчуванням `gemini-3.1-flash-tts-preview`). -- `providers.google.voiceName`: назва вбудованого голосу Gemini (за замовчуванням `Kore`; також приймається `voice`). -- `providers.google.audioProfile`: промпт у природній мові для стилю, що додається перед озвучуваним текстом. -- `providers.google.speakerName`: необов’язкова мітка мовця, що додається перед озвучуваним текстом, коли ваш TTS-промпт використовує іменованого мовця. -- `providers.google.baseUrl`: перевизначає базову URL-адресу Gemini API. Приймається лише `https://generativelanguage.googleapis.com`. - - Якщо `messages.tts.providers.google.apiKey` не вказано, TTS може повторно використати `models.providers.google.apiKey` до переходу на резервний env. -- `providers.gradium.baseUrl`: перевизначає базову URL-адресу API Gradium (за замовчуванням `https://api.gradium.ai`). -- `providers.gradium.voiceId`: ідентифікатор голосу Gradium (за замовчуванням Emma, `YTpq7expH9539ERJ`). +- `providers.tts-local-cli.env`: необов’язкові рядкові перевизначення змінних середовища для команди. +- `providers.google.model`: модель Gemini TTS (типово `gemini-3.1-flash-tts-preview`). +- `providers.google.voiceName`: назва вбудованого голосу Gemini (типово `Kore`; також приймається `voice`). +- `providers.google.audioProfile`: підказка природною мовою щодо стилю, яка додається перед текстом для озвучення. +- `providers.google.speakerName`: необов’язкова мітка мовця, яка додається перед текстом для озвучення, коли ваш TTS-запит використовує іменованого мовця. +- `providers.google.baseUrl`: перевизначає базову URL-адресу Gemini API. Дозволено лише `https://generativelanguage.googleapis.com`. + - Якщо `messages.tts.providers.google.apiKey` пропущено, TTS може повторно використати `models.providers.google.apiKey` перед переходом до значення з env. +- `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`: ідентифікатор голосу 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.baseUrl`: перевизначає базову URL-адресу xAI TTS (типово `https://api.x.ai/v1`, env: `XAI_BASE_URL`). +- `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`: перевизначення швидкості на рівні провайдера. - `providers.xiaomi.apiKey`: API-ключ Xiaomi MiMo (env: `XIAOMI_API_KEY`). -- `providers.xiaomi.baseUrl`: перевизначає базову URL-адресу API Xiaomi MiMo (за замовчуванням `https://api.xiaomimimo.com/v1`, env: `XIAOMI_BASE_URL`). -- `providers.xiaomi.model`: модель TTS (за замовчуванням `mimo-v2.5-tts`, env: `XIAOMI_TTS_MODEL`; також підтримується `mimo-v2-tts`). -- `providers.xiaomi.voice`: ідентифікатор голосу MiMo (за замовчуванням `mimo_default`, env: `XIAOMI_TTS_VOICE`). -- `providers.xiaomi.format`: `mp3` або `wav` (за замовчуванням `mp3`, env: `XIAOMI_TTS_FORMAT`). -- `providers.xiaomi.style`: необов’язкова стильова інструкція природною мовою, яка надсилається як повідомлення користувача; вона не озвучується. +- `providers.xiaomi.baseUrl`: перевизначає базову URL-адресу API Xiaomi MiMo (типово `https://api.xiaomimimo.com/v1`, env: `XIAOMI_BASE_URL`). +- `providers.xiaomi.model`: модель TTS (типово `mimo-v2.5-tts`, env: `XIAOMI_TTS_MODEL`; також підтримується `mimo-v2-tts`). +- `providers.xiaomi.voice`: ідентифікатор голосу MiMo (типово `mimo_default`, env: `XIAOMI_TTS_VOICE`). +- `providers.xiaomi.format`: `mp3` або `wav` (типово `mp3`, env: `XIAOMI_TTS_FORMAT`). +- `providers.xiaomi.style`: необов’язкова інструкція стилю природною мовою, що надсилається як повідомлення користувача; вона не озвучується. - `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`: ідентифікатор голосу, специфічний для provider (за замовчуванням `af_alloy`; також приймається `voiceId`). -- `providers.openrouter.responseFormat`: `mp3` або `pcm` (за замовчуванням `mp3`). -- `providers.openrouter.speed`: перевизначення швидкості на рівні provider. -- `providers.microsoft.enabled`: дозволяє використання Microsoft speech (за замовчуванням `true`; без API-ключа). +- `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; не всі формати підтримуються вбудованим transport на основі Edge. + - Дійсні значення див. у Microsoft Speech output formats; не всі формати підтримуються вбудованим транспортом на базі Edge. - `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: рядки з відсотками (наприклад, `+10%`, `-5%`). - `providers.microsoft.saveSubtitles`: записує JSON-субтитри поруч з аудіофайлом. -- `providers.microsoft.proxy`: URL-адреса проксі для запитів Microsoft speech. +- `providers.microsoft.proxy`: URL-адреса проксі для запитів мовлення Microsoft. - `providers.microsoft.timeoutMs`: перевизначення тайм-ауту запиту (мс). -- `edge.*`: застарілий псевдонім для тих самих налаштувань Microsoft. Запустіть +- `edge.*`: застарілий псевдонім для тих самих налаштувань Microsoft. Виконайте `openclaw doctor --fix`, щоб переписати збережену конфігурацію на `providers.microsoft`. ## Перевизначення, керовані моделлю (увімкнено за замовчуванням) -За замовчуванням модель **може** генерувати директиви TTS для однієї відповіді. -Коли `messages.tts.auto` має значення `tagged`, ці директиви обов’язкові для запуску аудіо. +За замовчуванням модель **може** виводити директиви TTS для однієї відповіді. +Коли `messages.tts.auto` має значення `tagged`, ці директиви потрібні для запуску аудіо. -Коли це ввімкнено, модель може генерувати директиви `[[tts:...]]`, щоб перевизначити голос -для однієї відповіді, а також необов’язковий блок `[[tts:text]]...[[/tts:text]]`, -щоб додати виразні теги (сміх, підказки для співу тощо), які мають з’являтися лише в -аудіо. +Коли цю можливість увімкнено, модель може виводити директиви `[[tts:...]]`, щоб перевизначити голос +для однієї відповіді, а також необов’язковий блок `[[tts:text]]...[[/tts:text]]`, щоб +надати експресивні теги (сміх, підказки для співу тощо), які мають з’являтися лише +в аудіо. Директиви `provider=...` ігноруються, якщо не встановлено `modelOverrides.allowProvider: true`. -Приклад payload відповіді: +Приклад корисного навантаження відповіді: ``` Here you go. @@ -518,14 +520,14 @@ Here you go. [[tts:text]](laughs) Read the song once more.[[/tts:text]] ``` -Доступні ключі директив (коли ввімкнено): +Доступні ключі директив (коли можливість увімкнено): -- `provider` (ідентифікатор зареєстрованого provider speech, наприклад `openai`, `elevenlabs`, `google`, `gradium`, `minimax`, `microsoft`, `vydra`, `xai` або `xiaomi`; потребує `allowProvider: true`) +- `provider` (ідентифікатор зареєстрованого провайдера мовлення, наприклад `openai`, `elevenlabs`, `google`, `gradium`, `minimax`, `microsoft`, `vydra`, `xai` або `xiaomi`; потребує `allowProvider: true`) - `voice` (голос OpenAI, Gradium або Xiaomi), `voiceName` / `voice_name` / `google_voice` (голос Google) або `voiceId` (ElevenLabs / Gradium / MiniMax / xAI) - `model` (модель OpenAI TTS, ідентифікатор моделі ElevenLabs, модель MiniMax або модель Xiaomi MiMo TTS) або `google_model` (модель Google TTS) - `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost` - `vol` / `volume` (гучність MiniMax, 0-10) -- `pitch` (цілий `pitch` MiniMax, від -12 до 12; дробові значення усікаються перед запитом до MiniMax) +- `pitch` (цілочисельний тон MiniMax, від -12 до 12; дробові значення відкидаються перед запитом до MiniMax) - `applyTextNormalization` (`auto|on|off`) - `languageCode` (ISO 639-1) - `seed` @@ -544,7 +546,7 @@ Here you go. } ``` -Необов’язковий allowlist (увімкнути перемикання provider, залишивши інші параметри налаштовуваними): +Необов’язковий список дозволів (увімкнути перемикання провайдера, залишивши інші параметри налаштовуваними): ```json5 { @@ -562,7 +564,7 @@ Here you go. ## Налаштування для окремого користувача -Команди slash записують локальні перевизначення в `prefsPath` (за замовчуванням: +Команди зі слешем записують локальні перевизначення в `prefsPath` (типово: `~/.openclaw/settings/tts.json`, можна перевизначити через `OPENCLAW_TTS_PREFS` або `messages.tts.prefsPath`). @@ -570,52 +572,52 @@ Here you go. - `enabled` - `provider` -- `maxLength` (поріг для підсумку; за замовчуванням 1500 символів) -- `summarize` (за замовчуванням `true`) +- `maxLength` (поріг зведення; типово 1500 символів) +- `summarize` (типово `true`) Вони перевизначають `messages.tts.*` для цього хоста. ## Формати виводу (фіксовані) -- **Feishu / Matrix / Telegram / WhatsApp**: відповіді у форматі voice-note віддають перевагу Opus (`opus_48000_64` від ElevenLabs, `opus` від OpenAI). - - 48kHz / 64kbps — це вдалий компроміс для голосових повідомлень. -- **Feishu**: коли відповідь у форматі voice-note створюється як MP3/WAV/M4A або інший - імовірний аудіофайл, plugin Feishu транскодує її в 48kHz Ogg/Opus за допомогою - `ffmpeg` перед надсиланням нативної бульбашки `audio`. Якщо конвертація не вдається, Feishu +- **Feishu / Matrix / Telegram / WhatsApp**: відповіді у форматі голосових повідомлень переважно використовують Opus (`opus_48000_64` від ElevenLabs, `opus` від OpenAI). + - 48 кГц / 64 кбіт/с — це вдалий компроміс для голосових повідомлень. +- **Feishu**: коли відповідь-голосове повідомлення створюється як MP3/WAV/M4A або в іншому + імовірному форматі аудіофайлу, Plugin Feishu перекодовує її в 48 кГц Ogg/Opus за допомогою + `ffmpeg` перед надсиланням нативної бульбашки `audio`. Якщо конвертація завершується помилкою, Feishu отримує оригінальний файл як вкладення. - **Інші канали**: MP3 (`mp3_44100_128` від ElevenLabs, `mp3` від OpenAI). - - 44.1kHz / 128kbps — це стандартний баланс для чіткості мовлення. -- **MiniMax**: MP3 (модель `speech-2.8-hd`, частота дискретизації 32kHz) для звичайних аудіовкладень. Для цілей voice-note, таких як Feishu і Telegram, OpenClaw транскодує MP3 від MiniMax у 48kHz Opus за допомогою `ffmpeg` перед доставкою. -- **Xiaomi MiMo**: за замовчуванням MP3 або WAV, якщо це налаштовано. Для цілей voice-note, таких як Feishu і Telegram, OpenClaw транскодує вихід Xiaomi у 48kHz Opus за допомогою `ffmpeg` перед доставкою. -- **Local CLI**: використовує налаштований `outputFormat`. Цілі voice-note - конвертуються в Ogg/Opus, а вихід telephony конвертується в raw 16 kHz mono PCM + - 44,1 кГц / 128 кбіт/с — типовий баланс для чіткості мовлення. +- **MiniMax**: MP3 (модель `speech-2.8-hd`, частота дискретизації 32 кГц) для звичайних аудіовкладень. Для цілей голосових повідомлень, таких як Feishu і Telegram, OpenClaw перекодовує MP3 MiniMax у 48 кГц Opus за допомогою `ffmpeg` перед доставленням. +- **Xiaomi MiMo**: типово MP3 або WAV, якщо це налаштовано. Для цілей голосових повідомлень, таких як Feishu і Telegram, OpenClaw перекодовує вихід Xiaomi у 48 кГц Opus за допомогою `ffmpeg` перед доставленням. +- **Local CLI**: використовує налаштований `outputFormat`. Цілі голосових повідомлень + конвертуються в Ogg/Opus, а вихід для телефонії конвертується в raw 16 кГц mono PCM за допомогою `ffmpeg`. -- **Google Gemini**: Gemini API TTS повертає raw 24kHz PCM. OpenClaw обгортає його у WAV для аудіовкладень і повертає PCM напряму для Talk/telephony. Нативний формат voice-note Opus цим шляхом не підтримується. -- **Gradium**: WAV для аудіовкладень, Opus для цілей voice-note і `ulaw_8000` на 8 kHz для telephony. -- **xAI**: за замовчуванням MP3; `responseFormat` може бути `mp3`, `wav`, `pcm`, `mulaw` або `alaw`. OpenClaw використовує batch REST endpoint TTS від xAI і повертає повне аудіовкладення; потоковий TTS WebSocket від xAI не використовується цим шляхом provider. Нативний формат voice-note Opus цим шляхом не підтримується. -- **Microsoft**: використовує `microsoft.outputFormat` (за замовчуванням `audio-24khz-48kbitrate-mono-mp3`). - - Вбудований transport приймає `outputFormat`, але сервіс підтримує не всі формати. - - Значення формату виводу відповідають форматам виводу Microsoft Speech (включно з Ogg/WebM Opus). - - `sendVoice` у Telegram приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні - гарантовані голосові повідомлення в Opus. +- **Google Gemini**: Gemini API TTS повертає raw 24 кГц PCM. OpenClaw обгортає його у WAV для аудіовкладень, перекодовує у 48 кГц Opus для цілей голосових повідомлень і повертає PCM напряму для Talk/телефонії. +- **Gradium**: WAV для аудіовкладень, Opus для цілей голосових повідомлень і `ulaw_8000` на 8 кГц для телефонії. +- **xAI**: типово MP3; `responseFormat` може бути `mp3`, `wav`, `pcm`, `mulaw` або `alaw`. OpenClaw використовує пакетну REST-кінцеву точку xAI TTS і повертає завершене аудіовкладення; потоковий TTS WebSocket xAI не використовується в цьому шляху провайдера. Нативний формат голосових повідомлень Opus у цьому шляху не підтримується. +- **Microsoft**: використовує `microsoft.outputFormat` (типово `audio-24khz-48kbitrate-mono-mp3`). + - Вбудований транспорт приймає `outputFormat`, але не всі формати доступні в сервісі. + - Значення формату виводу відповідають Microsoft Speech output formats (включно з 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 символів). -- підсумовує довгі відповіді, якщо це ввімкнено, використовуючи `agents.defaults.model.primary` (або `summaryModel`). +- робить зведення довгих відповідей, коли це ввімкнено, за допомогою `agents.defaults.model.primary` (або `summaryModel`). - додає згенероване аудіо до відповіді. -Якщо відповідь перевищує `maxLength`, а підсумок вимкнено (або немає API-ключа для -моделі підсумку), аудіо -пропускається, і надсилається звичайна текстова відповідь. +Якщо відповідь перевищує `maxLength`, а зведення вимкнено (або немає API-ключа для +моделі зведення), аудіо +пропускається і надсилається звичайна текстова відповідь. -## Діаграма потоку +## Схема потоку ``` Reply -> TTS enabled? @@ -630,13 +632,13 @@ Reply -> TTS enabled? -> TTS -> attach audio ``` -## Використання slash-команди +## Використання слеш-команди Є одна команда: `/tts`. -Деталі ввімкнення див. у [Slash commands](/uk/tools/slash-commands). +Докладніше про ввімкнення див. у [Слеш-команди](/uk/tools/slash-commands). -Примітка для Discord: `/tts` — це вбудована команда Discord, тому OpenClaw реєструє -там `/voice` як нативну команду. Текстова команда `/tts ...` усе одно працює. +Примітка щодо Discord: `/tts` — це вбудована команда Discord, тому OpenClaw реєструє +там `/voice` як нативну команду. Текстова команда `/tts ...` усе ще працює. ``` /tts off @@ -654,25 +656,26 @@ Reply -> TTS enabled? - Має бути ввімкнено `commands.text` або реєстрацію нативних команд. - Конфігурація `messages.tts.auto` приймає `off|always|inbound|tagged`. - `/tts on` записує локальне налаштування TTS як `always`; `/tts off` записує його як `off`. -- Використовуйте конфігурацію, якщо вам потрібні типові значення `inbound` або `tagged`. -- `limit` і `summary` зберігаються в локальних prefs, а не в основній конфігурації. +- Використовуйте конфігурацію, якщо хочете типові значення `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 і request id (коли provider його повертає), які відображаються в помилках/логах TTS. + - докладна діагностика: `Attempt details: provider:outcome(reasonCode) latency` +- Збої API OpenAI та ElevenLabs тепер включають розібрані деталі помилки провайдера та request id (коли їх повертає провайдер), що відображається в помилках/журналах TTS. ## Інструмент агента Інструмент `tts` перетворює текст на мовлення і повертає аудіовкладення для -доставки відповіді. Коли каналом є Feishu, Matrix, Telegram або WhatsApp, -аудіо доставляється як голосове повідомлення, а не як файлове вкладення. -Feishu може транскодувати не-Opus вихід TTS на цьому шляху, якщо доступний `ffmpeg`. -WhatsApp надсилає видимий текст окремо від PTT-аудіо voice-note, оскільки клієнти -не завжди коректно відображають підписи на voice notes. -Він приймає необов’язкові поля `channel` і `timeoutMs`; `timeoutMs` — -це тайм-аут запиту provider для окремого виклику в мілісекундах. +доставлення відповіді. Коли каналом є Feishu, Matrix, Telegram або WhatsApp, +аудіо доставляється як голосове повідомлення, а не як вкладення файлу. +Feishu може перекодовувати вихід TTS не у форматі Opus у цьому шляху, якщо `ffmpeg` +доступний. +WhatsApp надсилає видимий текст окремо від PTT-аудіо голосового повідомлення, оскільки клієнти +не завжди коректно відображають підписи до голосових повідомлень. +Він приймає необов’язкові поля `channel` і `timeoutMs`; `timeoutMs` — це +тайм-аут запиту до провайдера для одного виклику в мілісекундах. ## Gateway RPC