diff --git a/docs/uk/gateway/config-agents.md b/docs/uk/gateway/config-agents.md index b8ca0365d..ff6b88b90 100644 --- a/docs/uk/gateway/config-agents.md +++ b/docs/uk/gateway/config-agents.md @@ -1,15 +1,15 @@ --- read_when: - - Налаштування значень агента за замовчуванням (моделі, thinking, робочий простір, Heartbeat, медіа, Skills) + - Налаштування типових параметрів агента (моделі, thinking, робочий простір, Heartbeat, медіа, Skills) - Налаштування маршрутизації між кількома агентами та прив’язок - - Налаштування поведінки сесії, доставки повідомлень і режиму talk -summary: Значення агента за замовчуванням, маршрутизація між кількома агентами, сесія, повідомлення та конфігурація talk + - Налаштування сеансу, доставки повідомлень і поведінки режиму talk +summary: Типові налаштування агента, маршрутизація між кількома агентами, сесія, повідомлення та конфігурація talk title: Конфігурація — агенти x-i18n: - generated_at: "2026-04-24T18:44:26Z" + generated_at: "2026-04-24T21:43:38Z" model: gpt-5.4 provider: openai - source_hash: 85840fbc565a3d7d79a9ccaf20132225aa2a363d7ca6c6964e219b561235d183 + source_hash: 6c74f7d730fa4380acdd2af7b6dd8f3db635d901151826ce8c80993fedd70365 source_path: gateway/config-agents.md workflow: 15 --- @@ -18,11 +18,11 @@ x-i18n: `messages.*` і `talk.*`. Для каналів, інструментів, середовища виконання Gateway та інших ключів верхнього рівня див. [Довідник із конфігурації](/uk/gateway/configuration-reference). -## Значення агента за замовчуванням +## Типові параметри агента ### `agents.defaults.workspace` -За замовчуванням: `~/.openclaw/workspace`. +Типове значення: `~/.openclaw/workspace`. ```json5 { @@ -32,7 +32,7 @@ x-i18n: ### `agents.defaults.repoRoot` -Необов’язковий кореневий каталог репозиторію, який показується в рядку Runtime системного запиту. Якщо не вказано, OpenClaw автоматично визначає його, піднімаючись угору від робочого простору. +Необов’язковий корінь репозиторію, який відображається в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, підіймаючись угору від робочого простору. ```json5 { @@ -51,22 +51,22 @@ x-i18n: defaults: { skills: ["github", "weather"] }, list: [ { id: "writer" }, // успадковує github, weather - { id: "docs", skills: ["docs-search"] }, // замінює значення за замовчуванням + { id: "docs", skills: ["docs-search"] }, // замінює типові значення { id: "locked-down", skills: [] }, // без Skills ], }, } ``` -- Не вказуйте `agents.defaults.skills`, щоб Skills за замовчуванням були без обмежень. -- Не вказуйте `agents.list[].skills`, щоб успадкувати значення за замовчуванням. -- Встановіть `agents.list[].skills: []`, щоб не було Skills. +- Не вказуйте `agents.defaults.skills`, щоб типово дозволити необмежені Skills. +- Не вказуйте `agents.list[].skills`, щоб успадкувати типові значення. +- Установіть `agents.list[].skills: []`, щоб не дозволяти жодних Skills. - Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він - не об’єднується зі значеннями за замовчуванням. + не об’єднується з типовими значеннями. ### `agents.defaults.skipBootstrap` -Вимикає автоматичне створення файлів початкового налаштування робочого простору (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). +Вимикає автоматичне створення bootstrap-файлів робочого простору (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). ```json5 { @@ -76,9 +76,9 @@ x-i18n: ### `agents.defaults.contextInjection` -Керує тим, коли файли початкового налаштування робочого простору додаються до системного запиту. За замовчуванням: `"always"`. +Керує тим, коли bootstrap-файли робочого простору додаються до системного запиту. Типове значення: `"always"`. -- `"continuation-skip"`: у безпечних ходах продовження (після завершеної відповіді асистента) повторне додавання bootstrap-файлів робочого простору пропускається, що зменшує розмір запиту. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст. +- `"continuation-skip"`: у безпечних ходах продовження (після завершеної відповіді асистента) повторне додавання bootstrap-контексту робочого простору пропускається, що зменшує розмір запиту. Запуски Heartbeat і повторні спроби після Compaction все одно перебудовують контекст. ```json5 { @@ -88,7 +88,7 @@ x-i18n: ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів для кожного bootstrap-файлу робочого простору до обрізання. За замовчуванням: `12000`. +Максимальна кількість символів на один bootstrap-файл робочого простору перед обрізанням. Типове значення: `12000`. ```json5 { @@ -98,7 +98,7 @@ x-i18n: ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що додаються з усіх bootstrap-файлів робочого простору. За замовчуванням: `60000`. +Максимальна загальна кількість символів, що додаються з усіх bootstrap-файлів робочого простору. Типове значення: `60000`. ```json5 { @@ -108,12 +108,12 @@ x-i18n: ### `agents.defaults.bootstrapPromptTruncationWarning` -Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається. -За замовчуванням: `"once"`. +Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізано. +Типове значення: `"once"`. - `"off"`: ніколи не додавати текст попередження до системного запиту. -- `"once"`: додавати попередження один раз для кожного унікального сигнатурного набору обрізання (рекомендовано). -- `"always"`: додавати попередження при кожному запуску, коли є обрізання. +- `"once"`: додавати попередження один раз для кожного унікального сигнатурного випадку обрізання (рекомендовано). +- `"always"`: додавати попередження під час кожного запуску, якщо є обрізання. ```json5 { @@ -121,34 +121,34 @@ x-i18n: } ``` -### Карта володіння бюджетами контексту +### Карта володіння бюджетом контексту -OpenClaw має кілька великих бюджетів запиту/контексту, і вони -навмисно розділені між підсистемами, замість того щоб усі проходили через один -загальний параметр. +OpenClaw має кілька високонавантажених бюджетів запиту/контексту, і вони +навмисно розділені між підсистемами, а не проходять через один універсальний +параметр. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - звичайне додавання bootstrap-даних робочого простору. + звичайне додавання bootstrap-контексту робочого простору. - `agents.defaults.startupContext.*`: - одноразовий стартовий прелюд для `/new` і `/reset`, зокрема нещодавні - файли `memory/*.md` за днями. + одноразова стартова преамбула для `/new` і `/reset`, зокрема нещодавні щоденні + файли `memory/*.md`. - `skills.limits.*`: - компактний список Skills, що додається до системного запиту. + компактний список Skills, який додається до системного запиту. - `agents.defaults.contextLimits.*`: - обмежені витяги середовища виконання та додані блоки, що належать runtime. + обмежені витяги середовища виконання та додані блоки, якими керує runtime. - `memory.qmd.limits.*`: - розмір фрагментів індексованого пошуку пам’яті та додавання їх до контексту. + індексований фрагмент пошуку пам’яті та параметри додавання. -Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший -бюджет: +Використовуйте відповідне перевизначення для конкретного агента лише тоді, коли +одному агенту потрібен інший бюджет: - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -Керує стартовим прелюдом першого ходу, який додається під час порожніх запусків `/new` і `/reset`. +Керує стартовою преамбулою першого ходу, яка додається під час порожніх запусків `/new` і `/reset`. ```json5 { @@ -169,7 +169,7 @@ OpenClaw має кілька великих бюджетів запиту/кон #### `agents.defaults.contextLimits` -Спільні значення за замовчуванням для обмежених поверхонь runtime-контексту. +Спільні типові значення для обмежених поверхонь контексту середовища виконання. ```json5 { @@ -186,18 +186,16 @@ OpenClaw має кілька великих бюджетів запиту/кон } ``` -- `memoryGetMaxChars`: типовий ліміт витягу `memory_get` перед додаванням метаданих - обрізання та повідомлення про продовження. -- `memoryGetDefaultLines`: типове вікно рядків для `memory_get`, якщо `lines` +- `memoryGetMaxChars`: типове обмеження розміру витягу `memory_get` перед додаванням + метаданих обрізання та повідомлення про продовження. +- `memoryGetDefaultLines`: типове вікно рядків для `memory_get`, коли `lines` не вказано. -- `toolResultMaxChars`: поточний ліміт результату інструмента, що використовується для збережених результатів і - відновлення після переповнення. -- `postCompactionMaxChars`: ліміт витягу AGENTS.md, який використовується під час додавання - оновлення після Compaction. +- `toolResultMaxChars`: поточне обмеження розміру результату інструмента, що використовується для збережених результатів і відновлення після переповнення. +- `postCompactionMaxChars`: обмеження розміру витягу AGENTS.md, що використовується під час додавання оновлення після Compaction. #### `agents.list[].contextLimits` -Перевизначення для окремого агента для спільних параметрів `contextLimits`. Поля, які не вказано, успадковуються +Перевизначення для конкретного агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються з `agents.defaults.contextLimits`. ```json5 @@ -224,7 +222,7 @@ OpenClaw має кілька великих бюджетів запиту/кон #### `skills.limits.maxSkillsPromptChars` -Глобальний ліміт для компактного списку Skills, що додається до системного запиту. Це +Глобальне обмеження для компактного списку Skills, який додається до системного запиту. Це не впливає на читання файлів `SKILL.md` на вимогу. ```json5 @@ -239,7 +237,7 @@ OpenClaw має кілька великих бюджетів запиту/кон #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Перевизначення для окремого агента для бюджету запиту Skills. +Перевизначення бюджету запиту Skills для конкретного агента. ```json5 { @@ -258,10 +256,10 @@ OpenClaw має кілька великих бюджетів запиту/кон ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень транскрипту/інструментів перед викликами провайдера. -За замовчуванням: `1200`. +Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень стенограми/інструментів перед викликами провайдера. +Типове значення: `1200`. -Менші значення зазвичай зменшують використання vision-токенів і розмір тіла запиту для сценаріїв із великою кількістю скриншотів. +Менші значення зазвичай зменшують використання vision-токенів і розмір корисного навантаження запиту в сценаріях із великою кількістю знімків екрана. Більші значення зберігають більше візуальних деталей. ```json5 @@ -272,7 +270,7 @@ OpenClaw має кілька великих бюджетів запиту/кон ### `agents.defaults.userTimezone` -Часовий пояс для контексту системного запиту (не міток часу повідомлень). Якщо не вказано, використовується часовий пояс хоста. +Часовий пояс для контексту системного запиту (не для часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста. ```json5 { @@ -282,7 +280,7 @@ OpenClaw має кілька великих бюджетів запиту/кон ### `agents.defaults.timeFormat` -Формат часу в системному запиті. За замовчуванням: `auto` (параметри ОС). +Формат часу в системному запиті. Типове значення: `auto` (налаштування ОС). ```json5 { @@ -341,50 +339,50 @@ OpenClaw має кілька великих бюджетів запиту/кон - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Форма рядка задає лише основну модель. - - Форма об’єкта задає основну модель і впорядкований список резервних моделей. + - Форма об’єкта задає основну модель плюс впорядкований список моделей для аварійного перемикання. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується шляхом інструмента `image` як конфігурація vision-моделі. + - Використовується шляхом інструмента `image` як конфігурація його vision-моделі. - Також використовується для резервної маршрутизації, коли вибрана/типова модель не може приймати вхідні зображення. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/Plugin, що генерує зображення. - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-2` для OpenAI Images. - - Якщо ви безпосередньо вибираєте `provider/model`, також налаштуйте відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2`, `FAL_KEY` для `fal/*`). - - Якщо не вказано, `image_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів. + - Якщо ви безпосередньо вибираєте провайдера/модель, також налаштуйте відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2`, `FAL_KEY` для `fal/*`). + - Якщо не вказано, `image_generate` усе одно може визначити типовий провайдер на основі автентифікації. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`. - - Якщо не вказано, `music_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів. - - Якщо ви безпосередньо вибираєте `provider/model`, також налаштуйте відповідну автентифікацію провайдера/API-ключ. + - Якщо не вказано, `music_generate` усе одно може визначити типовий провайдер на основі автентифікації. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів. + - Якщо ви безпосередньо вибираєте провайдера/модель, також налаштуйте відповідну автентифікацію провайдера/API-ключ. - `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`. - Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`. - - Якщо не вказано, `video_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів. - - Якщо ви безпосередньо вибираєте `provider/model`, також налаштуйте відповідну автентифікацію провайдера/API-ключ. - - Вбудований провайдер генерації відео Qwen підтримує не більше ніж 1 вихідне відео, 1 вхідне зображення, 4 вхідних відео, тривалість до 10 секунд, а також параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` і `watermark`. + - Якщо не вказано, `video_generate` усе одно може визначити типовий провайдер на основі автентифікації. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів. + - Якщо ви безпосередньо вибираєте провайдера/модель, також налаштуйте відповідну автентифікацію провайдера/API-ключ. + - Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується інструментом `pdf` для маршрутизації моделі. - - Якщо не вказано, інструмент PDF використовує `imageModel`, а потім визначену модель сесії/типову модель. -- `pdfMaxBytesMb`: типовий ліміт розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. -- `pdfMaxPages`: типова максимальна кількість сторінок, яку враховує резервний режим витягування в інструменті `pdf`. -- `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. За замовчуванням: `"off"`. -- `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. За замовчуванням: `"on"`. -- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4` для доступу через API-ключ або `openai-codex/gpt-5.5` для Codex OAuth). Якщо не вказати провайдера, OpenClaw спочатку пробує alias, потім унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі і лише після цього переходить до типового налаштованого провайдера (застаріла сумісна поведінка, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення від видаленого провайдера. -- `models`: каталог налаштованих моделей і список дозволених значень для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`). - - Безпечні зміни: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додати записи. `config set` відхиляє заміни, які видалили б наявні записи зі списку дозволених значень, якщо ви не передали `--replace`. - - Потоки налаштування/онбордингу на рівні провайдера об’єднують вибрані моделі провайдера в цю мапу та зберігають уже налаштованих, не пов’язаних із цим, провайдерів. - - Для прямих моделей OpenAI Responses серверний Compaction вмикається автоматично. Використовуйте `params.responsesServerCompaction: false`, щоб припинити додавання `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Докладніше див. у [Серверний Compaction OpenAI](/uk/providers/openai#server-side-compaction-responses-api). -- `params`: глобальні типові параметри провайдера, які застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`). -- Пріоритет об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного id агента) перевизначає значення за ключами. Докладніше див. [Кешування запитів](/uk/reference/prompt-caching). -- `embeddedHarness`: типова політика низькорівневого середовища виконання вбудованого агента. Використовуйте `runtime: "auto"`, щоб дозволити зареєстрованим harness із Plugin брати на себе підтримувані моделі, `runtime: "pi"` — щоб примусово використовувати вбудований PI harness, або зареєстрований ідентифікатор harness, наприклад `runtime: "codex"`. Встановіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. Нові конфігурації Codex harness повинні зберігати посилання на моделі в канонічному форматі `openai/*` і вибирати harness тут, а не використовувати застарілі посилання на моделі `codex/*`. -- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення резервних варіантів), зберігають канонічну форму об’єкта і, коли можливо, зберігають наявні списки резервних моделей. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). За замовчуванням: 4. + - Якщо не вказано, інструмент PDF використовує `imageModel`, а потім визначену модель сеансу/типову модель. +- `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. +- `pdfMaxPages`: типова максимальна кількість сторінок, що враховується режимом резервного витягування в інструменті `pdf`. +- `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`. +- `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`. +- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4` для доступу через API-ключ або `openai-codex/gpt-5.5` для Codex OAuth). Якщо не вказати провайдера, OpenClaw спершу пробує псевдонім, потім — однозначний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише потім повертається до налаштованого типового провайдера (застаріла сумісна поведінка, тож краще вказувати явний `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення видаленого провайдера. +- `models`: налаштований каталог моделей і список дозволених значень для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`). + - Безпечні зміни: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відмовляє в замінах, які видалили б наявні записи зі списку дозволених значень, якщо не передати `--replace`. + - Потоки налаштування/онбордингу в межах провайдера об’єднують вибрані моделі провайдера в цю мапу та зберігають уже налаштованих нерелевантних провайдерів. + - Для прямих моделей OpenAI Responses компактування на стороні сервера вмикається автоматично. Використовуйте `params.responsesServerCompaction: false`, щоб припинити додавання `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Див. [Compaction на стороні сервера OpenAI](/uk/providers/openai#server-side-compaction-responses-api). +- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`). +- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного ідентифікатора агента) перевизначає за ключами. Докладніше див. у [Кешування запитів](/uk/reference/prompt-caching). +- `embeddedHarness`: типова політика низькорівневого середовища виконання вбудованого агента. Використовуйте `runtime: "auto"`, щоб дозволити зареєстрованим Plugin harness брати на себе підтримувані моделі, `runtime: "pi"`, щоб примусово використовувати вбудований harness PI, або зареєстрований ідентифікатор harness, наприклад `runtime: "codex"`. Автоматичне резервне перемикання на PI типово дорівнює `"pi"` лише в режимі `auto`. Явні середовища виконання Plugin, такі як `codex`, типово мають `"none"`, якщо ви не задасте `fallback: "pi"`. Нові конфігурації harness Codex мають зберігати посилання на моделі в канонічному вигляді `openai/*` і вибирати harness тут, а не використовувати застарілі посилання на моделі `codex/*`. +- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення резервних варіантів), зберігають канонічну форму об’єкта та, коли можливо, зберігають наявні списки резервних варіантів. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сеансами (кожен сеанс усе одно серіалізується). Типове значення: 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness` визначає, який низькорівневий виконавець запускає ходи вбудованого агента. -Для більшості розгортань слід залишати типове значення `{ runtime: "auto", fallback: "pi" }`. +`embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента. +У більшості розгортань слід залишити типове значення `{ runtime: "auto", fallback: "pi" }`. Використовуйте його, коли довірений Plugin надає нативний harness, наприклад вбудований -harness сервера застосунку Codex. +harness app-server Codex. ```json5 { @@ -400,35 +398,35 @@ harness сервера застосунку Codex. } ``` -- `runtime`: `"auto"`, `"pi"` або ідентифікатор зареєстрованого harness із Plugin. Вбудований Plugin Codex реєструє `codex`. -- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований PI harness як сумісний резервний варіант, коли не вибрано жодного harness із Plugin. `"none"` призводить до помилки, якщо вибраний harness із Plugin відсутній або не підтримується, замість тихого використання PI. Помилки вибраного harness із Plugin завжди показуються безпосередньо. -- Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає резервний перехід до PI для цього процесу. -- Для розгортань лише з Codex встановіть `model: "openai/gpt-5.5"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. -- Вибір harness закріплюється за ідентифікатором сесії після першого вбудованого запуску. Зміни конфігурації/середовища впливають на нові або скинуті сесії, але не на наявний транскрипт. Застарілі сесії з історією транскрипту, але без записаного закріплення, вважаються закріпленими за PI. `/status` показує ідентифікатори harness, відмінні від PI, наприклад `codex`, поруч із `Fast`. -- Це керує лише harness вбудованого чату. Генерація медіа, vision, PDF, музика, відео і TTS, як і раніше, використовують свої параметри провайдер/модель. +- `runtime`: `"auto"`, `"pi"` або ідентифікатор зареєстрованого Plugin harness. Вбудований Plugin Codex реєструє `codex`. +- `fallback`: `"pi"` або `"none"`. У режимі `runtime: "auto"` пропущений fallback типово дорівнює `"pi"`, щоб старі конфігурації могли й далі використовувати PI, коли жоден Plugin harness не бере запуск на себе. У режимі явного Plugin runtime, наприклад `runtime: "codex"`, пропущений fallback типово дорівнює `"none"`, щоб відсутній harness спричиняв помилку замість мовчазного використання PI. Перевизначення runtime не успадковують fallback із ширшої області; задайте `fallback: "pi"` разом із явним runtime, коли вам свідомо потрібен цей сумісний резервний варіант. Збої вибраного Plugin harness завжди відображаються безпосередньо. +- Перевизначення через змінні середовища: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` перевизначає fallback для цього процесу. +- Для розгортань лише з Codex установіть `model: "openai/gpt-5.5"` і `embeddedHarness.runtime: "codex"`. Для читабельності також можна явно задати `embeddedHarness.fallback: "none"`; це типове значення для явних Plugin runtime. +- Вибір harness фіксується для кожного ідентифікатора сеансу після першого вбудованого запуску. Зміни конфігурації/змінних середовища впливають на нові або скинуті сеанси, а не на наявну стенограму. Застарілі сеанси з історією стенограми, але без зафіксованого вибору, вважаються прив’язаними до PI. `/status` показує не-PI ідентифікатори harness, такі як `codex`, поруч із `Fast`. +- Це керує лише harness вбудованого чату. Генерація медіа, vision, PDF, музика, відео та TTS усе ще використовують свої параметри провайдера/моделі. -**Вбудовані скорочення alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): +**Вбудовані скорочення-псевдоніми** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): -| Alias | Модель | +| Псевдонім | Модель | | ------------------- | -------------------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | -| `gpt` | `openai/gpt-5.4` або налаштована Codex OAuth GPT-5.5 | +| `gpt` | `openai/gpt-5.4` або налаштований Codex OAuth GPT-5.5 | | `gpt-mini` | `openai/gpt-5.4-mini` | | `gpt-nano` | `openai/gpt-5.4-nano` | | `gemini` | `google/gemini-3.1-pro-preview` | | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Налаштовані вами alias завжди мають пріоритет над типовими. +Ваші налаштовані псевдоніми завжди мають пріоритет над типовими. -Для моделей Z.AI GLM-4.x режим thinking вмикається автоматично, якщо ви не встановите `--thinking off` або самостійно не задасте `agents.defaults.models["zai/"].params.thinking`. -Для моделей Z.AI `tool_stream` увімкнено за замовчуванням для потокової передачі викликів інструментів. Встановіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. -Для моделей Anthropic Claude 4.6 за замовчуванням використовується thinking `adaptive`, якщо не задано явний рівень thinking. +Для моделей Z.AI GLM-4.x режим thinking вмикається автоматично, якщо ви не задасте `--thinking off` або самостійно не визначите `agents.defaults.models["zai/"].params.thinking`. +Для моделей Z.AI типово вмикається `tool_stream` для потокового передавання викликів інструментів. Установіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. +Для моделей Anthropic Claude 4.6 типово використовується thinking `adaptive`, якщо явний рівень thinking не задано. ### `agents.defaults.cliBackends` -Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють. +Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери недоступні. ```json5 { @@ -457,12 +455,12 @@ harness сервера застосунку Codex. ``` - CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені. -- Сесії підтримуються, якщо задано `sessionArg`. -- Передавання зображень підтримується, якщо `imageArg` приймає шляхи до файлів. +- Сеанси підтримуються, коли задано `sessionArg`. +- Наскрізна передача зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` -Замінює весь системний запит, зібраний OpenClaw, на фіксований рядок. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для конкретного агента (`agents.list[].systemPromptOverride`). Значення для конкретного агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами. +Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для конкретного агента (`agents.list[].systemPromptOverride`). Значення для конкретного агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами. ```json5 { @@ -476,7 +474,7 @@ harness сервера застосунку Codex. ### `agents.defaults.promptOverlays` -Незалежні від провайдера накладки запитів, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки між провайдерами; `personality` керує лише шаром дружнього стилю взаємодії. +Незалежні від провайдера накладки запиту, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки між провайдерами; `personality` керує лише шаром дружнього стилю взаємодії. ```json5 { @@ -493,8 +491,8 @@ harness сервера застосунку Codex. ``` - `"friendly"` (типово) і `"on"` вмикають шар дружнього стилю взаємодії. -- `"off"` вимикає лише дружній шар; позначений контракт поведінки GPT-5 залишається увімкненим. -- Застаріле `plugins.entries.openai.config.personality` усе ще зчитується, якщо цей спільний параметр не задано. +- `"off"` вимикає лише дружній шар; позначений контракт поведінки GPT-5 залишається ввімкненим. +- Застаріле `plugins.entries.openai.config.personality` усе ще зчитується, коли цей спільний параметр не задано. ### `agents.defaults.heartbeat` @@ -508,13 +506,13 @@ harness сервера застосунку Codex. every: "30m", // 0m вимикає model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // за замовчуванням: true; false не додає розділ Heartbeat до системного запиту - lightContext: false, // за замовчуванням: false; true залишає лише HEARTBEAT.md із bootstrap-файлів робочого простору - isolatedSession: false, // за замовчуванням: false; true запускає кожен heartbeat у новій сесії (без історії розмови) + includeSystemPromptSection: true, // типово: true; false не додає розділ Heartbeat до системного запиту + lightContext: false, // типово: false; true залишає лише HEARTBEAT.md із bootstrap-файлів робочого простору + isolatedSession: false, // типово: false; true запускає кожен heartbeat у новому сеансі (без історії розмови) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (за замовчуванням) | block - target: "none", // за замовчуванням: none | варіанти: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow (типово) | block + target: "none", // типово: none | варіанти: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -525,14 +523,14 @@ harness сервера застосунку Codex. } ``` -- `every`: рядок тривалості (ms/s/m/h). За замовчуванням: `30m` (автентифікація через API-ключ) або `1h` (автентифікація через OAuth). Встановіть `0m`, щоб вимкнути. -- `includeSystemPromptSection`: якщо `false`, не додає розділ Heartbeat до системного запиту і пропускає додавання `HEARTBEAT.md` до bootstrap-контексту. За замовчуванням: `true`. -- `suppressToolErrorWarnings`: якщо `true`, пригнічує корисне навантаження попереджень про помилки інструментів під час запусків heartbeat. -- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента heartbeat, після чого його буде перервано. Якщо не вказано, використовується `agents.defaults.timeoutSeconds`. -- `directPolicy`: політика доставки напряму/в особисті повідомлення. `allow` (за замовчуванням) дозволяє доставку безпосередньо цілі. `block` пригнічує доставку безпосередньо цілі та генерує `reason=dm-blocked`. -- `lightContext`: якщо `true`, запуски heartbeat використовують полегшений bootstrap-контекст і залишають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору. -- `isolatedSession`: якщо `true`, кожен heartbeat запускається в новій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один heartbeat приблизно зі ~100K до ~2-5K токенів. -- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, **heartbeat запускаються лише для цих агентів**. +- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація API-ключем) або `1h` (автентифікація OAuth). Установіть `0m`, щоб вимкнути. +- `includeSystemPromptSection`: коли `false`, не додає розділ Heartbeat до системного запиту та пропускає додавання `HEARTBEAT.md` до bootstrap-контексту. Типове значення: `true`. +- `suppressToolErrorWarnings`: коли `true`, пригнічує корисні навантаження з попередженнями про помилки інструментів під час запусків heartbeat. +- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента heartbeat, після чого його буде перервано. Якщо не задано, використовується `agents.defaults.timeoutSeconds`. +- `directPolicy`: політика доставки напряму/в особисті повідомлення. `allow` (типово) дозволяє доставку до прямої цілі. `block` пригнічує доставку до прямої цілі та генерує `reason=dm-blocked`. +- `lightContext`: коли `true`, запуски heartbeat використовують полегшений bootstrap-контекст і залишають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору. +- `isolatedSession`: коли `true`, кожен heartbeat запускається в новому сеансі без попередньої історії розмови. Та сама схема ізоляції, що й у Cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один heartbeat приблизно зі ~100K до ~2-5K токенів. +- Для конкретного агента: задайте `agents.list[].heartbeat`. Коли будь-який агент визначає `heartbeat`, **heartbeat запускаються лише для цих агентів**. - Heartbeat виконують повноцінні ходи агента — коротші інтервали спалюють більше токенів. ### `agents.defaults.compaction` @@ -543,14 +541,14 @@ harness сервера застосунку Codex. defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id зареєстрованого Plugin провайдера compaction (необов’язково) + provider: "my-provider", // id зареєстрованого Plugin-провайдера compaction (необов’язково) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // використовується, коли identifierPolicy=custom postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне додавання model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для compaction - notifyUser: true, // надсилати короткі сповіщення користувачу, коли compaction починається і завершується (за замовчуванням: false) + notifyUser: true, // надсилати короткі сповіщення, коли compaction починається і завершується (типово: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -563,19 +561,19 @@ harness сервера застосунку Codex. } ``` -- `mode`: `default` або `safeguard` (підсумовування частинами для довгих історій). Див. [Compaction](/uk/concepts/compaction). -- `provider`: id зареєстрованого Plugin провайдера compaction. Якщо задано, замість вбудованого підсумовування LLM викликається `summarize()` цього провайдера. У разі помилки повертається до вбудованого механізму. Встановлення провайдера примусово задає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). -- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції compaction, після чого OpenClaw її перериває. За замовчуванням: `900`. -- `identifierPolicy`: `strict` (за замовчуванням), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування compaction. +- `mode`: `default` або `safeguard` (підсумовування довгої історії частинами). Див. [Compaction](/uk/concepts/compaction). +- `provider`: id зареєстрованого Plugin-провайдера compaction. Якщо задано, замість вбудованого LLM-підсумовування викликається `summarize()` провайдера. У разі збою повертається до вбудованого варіанта. Установлення провайдера примусово вмикає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). +- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції compaction, після чого OpenClaw її перериває. Типове значення: `900`. +- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані інструкції щодо збереження непрозорих ідентифікаторів під час підсумовування compaction. - `identifierInstructions`: необов’язковий власний текст щодо збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. -- `postCompactionSections`: необов’язкові назви секцій H2/H3 з AGENTS.md, які потрібно повторно додати після compaction. За замовчуванням `["Session Startup", "Red Lines"]`; встановіть `[]`, щоб вимкнути повторне додавання. Якщо значення не задано або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як резервний варіант для сумісності. -- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а підсумки compaction повинні виконуватися на іншій; якщо не задано, compaction використовує основну модель сесії. -- `notifyUser`: якщо `true`, надсилає користувачу короткі сповіщення, коли compaction починається і коли завершується (наприклад, "Compacting context..." і "Compaction complete"). За замовчуванням вимкнено, щоб compaction залишався непомітним. -- `memoryFlush`: тихий агентний хід перед автоматичним compaction для збереження довготривалої пам’яті. Пропускається, якщо робочий простір доступний лише для читання. +- `postCompactionSections`: необов’язкові назви розділів H2/H3 з AGENTS.md, які потрібно повторно додати після compaction. Типове значення — `["Session Startup", "Red Lines"]`; установіть `[]`, щоб вимкнути повторне додавання. Якщо не задано або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як застарілий резервний варіант. +- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування compaction. Використовуйте це, коли основний сеанс має залишатися на одній моделі, а підсумки compaction мають створюватися на іншій; якщо не задано, compaction використовує основну модель сеансу. +- `notifyUser`: коли `true`, надсилає користувачеві короткі сповіщення, коли compaction починається і коли завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб compaction відбувався безшумно. +- `memoryFlush`: тихий агентний хід перед автоматичним compaction для збереження тривалої пам’яті. Пропускається, коли робочий простір доступний лише для читання. ### `agents.defaults.contextPruning` -Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. +Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сеансу на диску. ```json5 { @@ -583,7 +581,7 @@ harness сервера застосунку Codex. defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // тривалість (ms/s/m/h), одиниця за замовчуванням: хвилини + ttl: "1h", // тривалість (ms/s/m/h), типова одиниця: хвилини keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -600,22 +598,22 @@ harness сервера застосунку Codex. - `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` визначає, як часто обрізання може запускатися знову (після останнього торкання кешу). +- `ttl` визначає, як часто обрізання можна запускати знову (після останнього торкання кешу). - Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім, за потреби, повністю очищає старіші результати інструментів. **М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині. -**Повне очищення** замінює весь результат інструмента на заповнювач. +**Повне очищення** замінює весь результат інструмента заповнювачем. Примітки: -- Блоки зображень ніколи не обрізаються і не очищаються. +- Блоки зображень ніколи не обрізаються й не очищаються. - Співвідношення базуються на кількості символів (приблизно), а не на точній кількості токенів. -- Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається. +- Якщо повідомлень асистента менше, ніж `keepLastAssistants`, обрізання пропускається. -Докладніше про поведінку див. у [Обрізання сесії](/uk/concepts/session-pruning). +Докладніше про поведінку див. у [Обрізання сеансу](/uk/concepts/session-pruning). ### Блокове потокове передавання @@ -633,11 +631,11 @@ harness сервера застосунку Codex. } ``` -- Канали, окрім Telegram, потребують явного `*.blockStreaming: true`, щоб увімкнути відповіді блоками. -- Перевизначення для каналів: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat за замовчуванням `minChars: 1500`. -- `humanDelay`: випадкова пауза між відповідями блоками. `natural` = 800–2500ms. Перевизначення для окремого агента: `agents.list[].humanDelay`. +- Канали, крім Telegram, потребують явного `*.blockStreaming: true`, щоб увімкнути блокові відповіді. +- Перевизначення каналу: `channels..blockStreamingCoalesce` (і варіанти для конкретних облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`. +- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500 мс. Перевизначення для конкретного агента: `agents.list[].humanDelay`. -Докладніше про поведінку та розбиття на блоки див. у [Потокове передавання](/uk/concepts/streaming). +Докладніше про поведінку й розбиття на фрагменти див. у [Потокове передавання](/uk/concepts/streaming). ### Індикатори набору тексту @@ -652,8 +650,8 @@ harness сервера застосунку Codex. } ``` -- Значення за замовчуванням: `instant` для прямих чатів/згадок, `message` для групових чатів без згадок. -- Перевизначення для сесії: `session.typingMode`, `session.typingIntervalSeconds`. +- Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. +- Перевизначення для сеансу: `session.typingMode`, `session.typingIntervalSeconds`. Див. [Індикатори набору тексту](/uk/concepts/typing-indicators). @@ -661,7 +659,7 @@ harness сервера застосунку Codex. ### `agents.defaults.sandbox` -Необов’язкова ізоляція для вбудованого агента. Повний посібник див. у [Ізоляція](/uk/gateway/sandboxing). +Необов’язкова sandbox-ізоляція для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). ```json5 { @@ -756,24 +754,24 @@ harness сервера застосунку Codex. } ``` - + -**Backend:** +**Бекенд:** -- `docker`: локальне середовище виконання Docker (за замовчуванням) -- `ssh`: загальне віддалене середовище виконання на основі SSH +- `docker`: локальне середовище виконання Docker (типово) +- `ssh`: універсальне віддалене середовище виконання на основі SSH - `openshell`: середовище виконання OpenShell -Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться до +Коли вибрано `backend: "openshell"`, налаштування, специфічні для середовища виконання, переміщуються до `plugins.entries.openshell.config`. -**Конфігурація SSH backend:** +**Конфігурація SSH-бекенда:** -- `target`: ціль SSH у форматі `user@host[:port]` -- `command`: команда SSH-клієнта (за замовчуванням: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів у межах області видимості -- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, передані до OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, який OpenClaw матеріалізує у тимчасові файли під час виконання +- `target`: SSH-ціль у форматі `user@host[:port]` +- `command`: команда SSH-клієнта (типово: `ssh`) +- `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів у межах області +- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються в OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує в тимчасові файли під час виконання - `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH **Пріоритет автентифікації SSH:** @@ -781,27 +779,27 @@ harness сервера застосунку Codex. - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data` на основі SecretRef визначаються з активного знімка середовища виконання секретів до початку сесії sandbox +- Значення `*Data`, що базуються на SecretRef, визначаються з активного знімка середовища виконання секретів до початку сеансу sandbox -**Поведінка SSH backend:** +**Поведінка SSH-бекенда:** - один раз ініціалізує віддалений робочий простір після створення або повторного створення - потім підтримує віддалений робочий простір SSH як канонічний -- маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH -- не синхронізує автоматично віддалені зміни назад на хост +- маршрутизує `exec`, файлові інструменти та шляхи до медіа через SSH +- не синхронізує віддалені зміни назад на хост автоматично - не підтримує браузерні контейнери sandbox **Доступ до робочого простору:** -- `none`: робочий простір sandbox у межах області видимості під `~/.openclaw/sandboxes` +- `none`: робочий простір sandbox у межах області під `~/.openclaw/sandboxes` - `ro`: робочий простір sandbox у `/workspace`, робочий простір агента змонтовано лише для читання в `/agent` - `rw`: робочий простір агента змонтовано для читання/запису в `/workspace` -**Область видимості:** +**Область:** -- `session`: окремий контейнер і робочий простір на сесію -- `agent`: один контейнер і робочий простір на агента (за замовчуванням) -- `shared`: спільний контейнер і робочий простір (без ізоляції між сесіями) +- `session`: окремий контейнер і робочий простір для кожного сеансу +- `agent`: один контейнер і робочий простір на агента (типово) +- `shared`: спільний контейнер і робочий простір (без ізоляції між сеансами) **Конфігурація Plugin OpenShell:** @@ -831,32 +829,32 @@ harness сервера застосунку Codex. **Режим OpenShell:** -- `mirror`: ініціалізує віддалений простір із локального перед exec, синхронізує назад після exec; локальний робочий простір залишається канонічним -- `remote`: один раз ініціалізує віддалений простір під час створення sandbox, після чого віддалений робочий простір залишається канонічним +- `mirror`: ініціалізує віддалене середовище з локального перед `exec`, синхронізує назад після `exec`; локальний робочий простір залишається канонічним +- `remote`: один раз ініціалізує віддалене середовище, коли створюється sandbox, після чого віддалений робочий простір залишається канонічним -У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються автоматично в sandbox після кроку ініціалізації. -Транспортом є SSH у sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією. +У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку ініціалізації. +Транспортом є SSH до sandbox OpenShell, але життєвим циклом sandbox і необов’язковою синхронізацією mirror керує Plugin. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного доступу до мережі, записуваного кореня та користувача root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного доступу до мережі, кореневої файлової системи з можливістю запису та користувача root. -**Для контейнерів за замовчуванням встановлено `network: "none"`** — задайте `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. -`"host"` заблоковано. `"container:"` також заблоковано за замовчуванням, якщо ви явно не встановите +**Типово контейнери мають `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. +`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не задасте `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний варіант). -**Вхідні вкладення** розміщуються в `media/inbound/*` в активному робочому просторі. +**Вхідні вкладення** розміщуються у `media/inbound/*` в активному робочому просторі. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні монтування та монтування для окремих агентів об’єднуються. +**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для конкретного агента об’єднуються. -**Ізольований браузер** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC додається до системного запиту. Не потребує `browser.enabled` в `openclaw.json`. -Доступ спостерігача через noVNC за замовчуванням використовує VNC-автентифікацію, і OpenClaw генерує URL із короткоживучим токеном (замість показу пароля в спільному URL). +**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC додається до системного запиту. Не потребує `browser.enabled` у `openclaw.json`. +Доступ спостерігача noVNC типово використовує автентифікацію VNC, а OpenClaw генерує URL із короткоживучим токеном (замість того, щоб показувати пароль у спільному URL). -- `allowHostControl: false` (за замовчуванням) блокує для ізольованих сесій націлювання на браузер хоста. -- Для `network` за замовчуванням використовується `openclaw-sandbox-browser` (окрема bridge-мережа). Встановлюйте `bridge` лише тоді, коли вам явно потрібна глобальна bridge-зв’язність. -- `cdpSourceRange` за потреби обмежує вхідний CDP-трафік на межі контейнера до діапазону CIDR (наприклад, `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер ізольованого браузера. Якщо задано (включно з `[]`), він замінює `docker.binds` для контейнера браузера. -- Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для хостів контейнерів: +- `allowHostControl: false` (типово) блокує для sandbox-сеансів націлення на браузер хоста. +- `network` типово дорівнює `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна загальна bridge-зв’язність. +- `cdpSourceRange` за потреби обмежує вхідний CDP-трафік на межі контейнера до діапазону CIDR (наприклад `172.21.0.1/32`). +- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо задано (включно з `[]`), замінює `docker.binds` для контейнера браузера. +- Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для контейнерних хостів: - `--remote-debugging-address=127.0.0.1` - - `--remote-debugging-port=<похідне від OPENCLAW_BROWSER_CDP_PORT>` + - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` - `--no-first-run` - `--no-default-browser-check` @@ -871,31 +869,31 @@ harness сервера застосунку Codex. - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (увімкнено за замовчуванням) + - `--disable-extensions` (типово ввімкнено) - `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu` - увімкнені за замовчуванням і можуть бути вимкнені через - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо для використання WebGL/3D це потрібно. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш робочий процес - залежить від них. + типово ввімкнені й можуть бути вимкнені за допомогою + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо це потрібно для WebGL/3D. + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо вони потрібні + вашому робочому процесу. - `--renderer-process-limit=2` можна змінити через - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; встановіть `0`, щоб використовувати - типовий ліміт процесів Chromium. - - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли увімкнено `noSandbox`. + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати + типове обмеження процесів Chromium. + - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. - Типові значення є базовими для образу контейнера; щоб змінити типові параметри контейнера, використовуйте власний образ браузера з власним entrypoint. -Ізоляція браузера та `sandbox.docker.binds` працюють лише з Docker. +Ізоляція браузера та `sandbox.docker.binds` доступні лише для Docker. -Зібрати образи: +Збірка образів: ```bash scripts/sandbox-setup.sh # основний образ sandbox scripts/sandbox-browser-setup.sh # необов’язковий образ браузера ``` -### `agents.list` (перевизначення для окремого агента) +### `agents.list` (перевизначення для конкретного агента) ```json5 { @@ -908,11 +906,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // або { primary, fallbacks } - thinkingDefault: "high", // перевизначення рівня thinking для окремого агента - reasoningDefault: "on", // перевизначення видимості reasoning для окремого агента - fastModeDefault: false, // перевизначення швидкого режиму для окремого агента + thinkingDefault: "high", // перевизначення рівня thinking для конкретного агента + reasoningDefault: "on", // перевизначення видимості reasoning для конкретного агента + fastModeDefault: false, // перевизначення fast mode для конкретного агента embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // перевизначає params відповідного defaults.models за ключами + params: { cacheRetention: "none" }, // перевизначає ключі у відповідних defaults.models params skills: ["docs-search"], // замінює agents.defaults.skills, якщо задано identity: { name: "Samantha", @@ -944,27 +942,27 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `id`: стабільний id агента (обов’язково). +- `id`: стабільний ідентифікатор агента (обов’язково). - `default`: якщо задано кілька, перший має пріоритет (записується попередження). Якщо не задано жодного, типовим буде перший елемент списку. -- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні резервні моделі). Завдання Cron, які перевизначають лише `primary`, усе одно успадковують типові резервні моделі, якщо ви не задасте `fallbacks: []`. -- `params`: параметри потоку для окремого агента, які об’єднуються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень, специфічних для агента, як-от `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. -- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо не задано, агент успадковує `agents.defaults.skills`, коли його задано; явний список замінює типові значення, а не об’єднується з ними, а `[]` означає відсутність Skills. -- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не задано перевизначення для повідомлення або сесії. -- `reasoningDefault`: необов’язкова типова видимість reasoning для окремого агента (`on | off | stream`). Застосовується, якщо не задано перевизначення reasoning для повідомлення або сесії. -- `fastModeDefault`: необов’язкове типове значення швидкого режиму для окремого агента (`true | false`). Застосовується, якщо не задано перевизначення швидкого режиму для повідомлення або сесії. -- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex", fallback: "none" }`, щоб зробити один агент лише Codex, а інші агенти зберігали типовий резервний PI. -- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` зі значеннями `runtime.acp` за замовчуванням (`agent`, `backend`, `mode`, `cwd`), коли агент має за замовчуванням використовувати сесії harness ACP. +- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні резервні варіанти). Cron-завдання, які перевизначають лише `primary`, усе одно успадковують типові резервні варіанти, якщо не задати `fallbacks: []`. +- `params`: параметри потоку для конкретного агента, об’єднані поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень на рівні агента, таких як `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. +- `skills`: необов’язковий список дозволених Skills для конкретного агента. Якщо не задано, агент успадковує `agents.defaults.skills`, коли він заданий; явний список замінює типові значення, а не об’єднується з ними, а `[]` означає відсутність Skills. +- `thinkingDefault`: необов’язковий типовий рівень thinking для конкретного агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення на рівні повідомлення або сеансу. +- `reasoningDefault`: необов’язкове типове значення видимості reasoning для конкретного агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning на рівні повідомлення або сеансу. +- `fastModeDefault`: необов’язкове типове значення fast mode для конкретного агента (`true | false`). Застосовується, коли не задано перевизначення fast mode на рівні повідомлення або сеансу. +- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для конкретного агента. Використовуйте `{ runtime: "codex" }`, щоб зробити одного агента лише Codex, тоді як інші агенти зберігатимуть типовий резервний варіант PI в режимі `auto`. +- `runtime`: необов’язковий дескриптор середовища виконання для конкретного агента. Використовуйте `type: "acp"` разом із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сеанси harness ACP. - `identity.avatar`: шлях відносно робочого простору, URL `http(s)` або URI `data:`. - `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. -- `subagents.allowAgents`: список дозволених id агентів для `sessions_spawn` (`["*"]` = будь-який; за замовчуванням: лише той самий агент). -- Захист успадкування sandbox: якщо сесія-запитувач працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. -- `subagents.requireAgentId`: якщо `true`, блокує виклики `sessions_spawn`, у яких не вказано `agentId` (примушує до явного вибору профілю; за замовчуванням: false). +- `subagents.allowAgents`: список дозволених ідентифікаторів агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). +- Захист успадкування sandbox: якщо сеанс-ініціатор працює в sandbox, `sessions_spawn` відхиляє цілі, які працювали б без sandbox. +- `subagents.requireAgentId`: коли `true`, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типово: false). --- ## Маршрутизація між кількома агентами -Запускайте кількох ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). +Запускайте кілька ізольованих агентів усередині одного Gateway. Див. [Багатоагентність](/uk/concepts/multi-agent). ```json5 { @@ -981,29 +979,29 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -### Поля збігу для прив’язок +### Поля зіставлення прив’язки -- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип не вказано, за замовчуванням використовується route), `acp` для постійних прив’язок розмов ACP. +- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип відсутній, типово використовується route), `acp` для постійних прив’язок розмов ACP. - `match.channel` (обов’язково) - `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо не вказано = типовий обліковий запис) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) - `match.guildId` / `match.teamId` (необов’язково; залежить від каналу) -- `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }` +- `acp` (необов’язково; лише для `type: "acp"`): `{ mode, label, cwd, backend }` -**Детермінований порядок збігів:** +**Детермінований порядок зіставлення:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (точний збіг, без peer/guild/team) -5. `match.accountId: "*"` (на весь канал) +5. `match.accountId: "*"` (на рівні всього каналу) 6. Типовий агент -У межах кожного рівня перемагає перший відповідний запис у `bindings`. +У межах кожного рівня перший відповідний запис у `bindings` має пріоритет. -Для записів `type: "acp"` OpenClaw виконує зіставлення за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує порядок рівнів прив’язки route, наведений вище. +Для записів `type: "acp"` OpenClaw виконує зіставлення за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів прив’язки route. -### Профілі доступу для окремих агентів +### Профілі доступу для конкретних агентів @@ -1098,7 +1096,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б -Докладніше про пріоритети див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). +Докладніше про пріоритети див. у [Sandbox і інструменти в багатоагентному режимі](/uk/tools/multi-agent-sandbox-tools). --- @@ -1124,22 +1122,22 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // пропускати відгалуження від батьківського потоку вище цього числа токенів (0 вимикає) + parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // тривалість або false - maxDiskBytes: "500mb", // необов’язковий жорсткий бюджет - highWaterBytes: "400mb", // необов’язкова ціль очищення + resetArchiveRetention: "30d", // duration or false + maxDiskBytes: "500mb", // optional hard budget + highWaterBytes: "400mb", // optional cleanup target }, threadBindings: { enabled: true, - idleHours: 24, // типове автоматичне зняття фокусу через неактивність у годинах (`0` вимикає) - maxAgeHours: 0, // типовий жорсткий максимальний вік у годинах (`0` вимикає) + idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) + maxAgeHours: 0, // default hard max age in hours (`0` disables) }, - mainKey: "main", // застаріле поле (runtime завжди використовує "main") + mainKey: "main", // legacy (runtime always uses "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1151,35 +1149,35 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б -- **`scope`**: базова стратегія групування сесій для контекстів групового чату. - - `per-sender` (за замовчуванням): кожен відправник отримує ізольовану сесію в межах контексту каналу. - - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли потрібен спільний контекст). +- **`scope`**: базова стратегія групування сеансів для контекстів групового чату. + - `per-sender` (типово): кожен відправник отримує ізольований сеанс у межах контексту каналу. + - `global`: усі учасники в контексті каналу спільно використовують один сеанс (використовуйте лише тоді, коли потрібен спільний контекст). - **`dmScope`**: як групуються особисті повідомлення. - - `main`: усі особисті повідомлення спільно використовують основну сесію. - - `per-peer`: ізоляція за id відправника між каналами. - - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для спільних inbox). + - `main`: усі особисті повідомлення використовують головний сеанс. + - `per-peer`: ізоляція за ідентифікатором відправника між каналами. + - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для спільних вхідних). - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для кількох облікових записів). -- **`identityLinks`**: мапа канонічних id на peer із префіксом провайдера для спільного використання сесій між каналами. -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, спрацьовує той, що настане раніше. -- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як alias для `direct`. -- **`parentForkMaxTokens`**: максимальне значення `totalTokens` у батьківській сесії, дозволене під час створення відгалуженої сесії потоку (за замовчуванням `100000`). - - Якщо `totalTokens` у батьківській сесії перевищує це значення, OpenClaw починає нову сесію потоку замість успадкування історії транскрипту батьківської сесії. - - Встановіть `0`, щоб вимкнути цей захист і завжди дозволяти відгалуження від батьківської сесії. -- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного кошика особистих чатів. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість ходів відповіді у зворотному напрямку між агентами під час обміну агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong-ланцюжок. -- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перший `deny` має пріоритет. -- **`maintenance`**: очищення сховища сесій і керування термінами зберігання. - - `mode`: `warn` лише генерує попередження; `enforce` застосовує очищення. - - `pruneAfter`: поріг віку для застарілих записів (за замовчуванням `30d`). - - `maxEntries`: максимальна кількість записів у `sessions.json` (за замовчуванням `500`). - - `rotateBytes`: ротує `sessions.json`, коли він перевищує цей розмір (за замовчуванням `10mb`). - - `resetArchiveRetention`: термін зберігання архівів транскрипту `*.reset.`. За замовчуванням дорівнює `pruneAfter`; встановіть `false`, щоб вимкнути. - - `maxDiskBytes`: необов’язковий бюджет дискового простору для каталогу сесій. У режимі `warn` лише журналює попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. - - `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. За замовчуванням `80%` від `maxDiskBytes`. -- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до потоків. +- **`identityLinks`**: мапа канонічних ідентифікаторів на peer-ідентифікатори з префіксом провайдера для спільного використання сеансів між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, спрацьовує той, що завершується раніше. +- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`. +- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківського сеансу, дозволене під час створення розгалуженого сеансу потоку (типово `100000`). + - Якщо `totalTokens` батьківського сеансу перевищує це значення, OpenClaw запускає новий сеанс потоку замість успадкування історії стенограми батьківського сеансу. + - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти розгалуження від батьківського сеансу. +- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для головного сегмента особистого чату. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість відповідей у зворотному ланцюжку між агентами під час обміну агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong-ланцюжок. +- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. +- **`maintenance`**: очищення сховища сеансів + параметри зберігання. + - `mode`: `warn` лише виводить попередження; `enforce` застосовує очищення. + - `pruneAfter`: поріг давності для застарілих записів (типово `30d`). + - `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`). + - `rotateBytes`: ротує `sessions.json`, коли його розмір перевищує це значення (типово `10mb`). + - `resetArchiveRetention`: термін зберігання архівів стенограм `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий жорсткий бюджет дискового простору для каталогу сеансів. У режимі `warn` записує попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сеанси. + - `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово `80%` від `maxDiskBytes`. +- **`threadBindings`**: глобальні типові значення для функцій сеансів, прив’язаних до потоків. - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: типове автоматичне зняття фокусу через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати) - - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати) + - `idleHours`: типове автоматичне зняття фокусу після неактивності в годинах (`0` вимикає; провайдери можуть перевизначати) + - `maxAgeHours`: типове жорстке максимальне обмеження віку в годинах (`0` вимикає; провайдери можуть перевизначати) @@ -1190,7 +1188,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ```json5 { messages: { - responsePrefix: "🦞", // або "auto" + responsePrefix: "🦞", // or "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1205,7 +1203,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б }, }, inbound: { - debounceMs: 2000, // 0 вимикає + debounceMs: 2000, // 0 disables byChannel: { whatsapp: 5000, slack: 1500, @@ -1219,36 +1217,36 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Визначення значення (найспецифічніше має пріоритет): обліковий запис → канал → глобальне. `""` вимикає й зупиняє каскад. `"auto"` формує `[{identity.name}]`. +Порядок визначення значення (найспецифічніше має пріоритет): обліковий запис → канал → глобальне. `""` вимикає та зупиняє каскад. `"auto"` формує `[{identity.name}]`. **Змінні шаблону:** -| Variable | Опис | Example | -| ----------------- | ---------------------- | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| Змінна | Опис | Приклад | +| ----------------- | ------------------------ | --------------------------- | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | | `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва провайдера | `anthropic` | +| `{provider}` | Назва провайдера | `anthropic` | | `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Назва identity агента | (те саме, що й `"auto"`) | +| `{identity.name}` | Назва identity агента | (те саме, що й `"auto"`) | -Змінні нечутливі до регістру. `{think}` — alias для `{thinkingLevel}`. +Змінні нечутливі до регістру. `{think}` — псевдонім для `{thinkingLevel}`. -### Реакція підтвердження +### Реакція-підтвердження -- За замовчуванням використовується `identity.emoji` активного агента, інакше `"👀"`. Встановіть `""`, щоб вимкнути. +- Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. - Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. - Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення з identity. -- Область: `group-mentions` (за замовчуванням), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: видаляє підтвердження після відповіді в Slack, Discord і Telegram. +- Область: `group-mentions` (типово), `group-all`, `direct`, `all`. +- `removeAckAfterReply`: видаляє підтвердження після відповіді у Slack, Discord і Telegram. - `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram. - У Slack і Discord, якщо не задано, реакції статусу залишаються увімкненими, коли активні реакції підтвердження. + У Slack і Discord, якщо значення не задано, реакції статусу залишаються ввімкненими, коли активні реакції-підтвердження. У Telegram установіть це значення явно в `true`, щоб увімкнути реакції статусу життєвого циклу. -### Debounce для вхідних повідомлень +### Inbound debounce -Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Команди керування обходять debounce. +Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди оминають debounce. -### TTS (синтез мовлення) +### TTS (перетворення тексту на мовлення) ```json5 { @@ -1289,12 +1287,12 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `auto` керує типовим режимом автоматичного TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні налаштування, а `/tts status` показує фактичний стан. -- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумовування. -- `modelOverrides` увімкнено за замовчуванням; `modelOverrides.allowProvider` за замовчуванням має значення `false` (явне ввімкнення). -- API-ключі резервно беруться з `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. +- `auto` керує типовим режимом автоматичного TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує фактичний стан. +- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку. +- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (лише за явної згоди). +- Для API-ключів резервно використовуються `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. - `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. -- Коли `openai.baseUrl` вказує на endpoint, що не належить OpenAI, OpenClaw вважає його OpenAI-сумісним TTS-сервером і послаблює перевірку моделі/голосу. +- Коли `openai.baseUrl` вказує на endpoint, що не належить OpenAI, OpenClaw розглядає його як сумісний із OpenAI TTS сервер і послаблює перевірку моделі/голосу. --- @@ -1324,17 +1322,17 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька провайдерів Talk. -- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності й автоматично мігруються до `talk.providers.`. -- Ідентифікатори голосів резервно беруться з `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. -- `providers.*.apiKey` приймає звичайні рядки або об’єкти SecretRef. -- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли API-ключ Talk не налаштовано. +- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кілька провайдерів Talk. +- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності та автоматично мігруються до `talk.providers.`. +- Для ідентифікаторів голосу резервно використовуються `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. +- `providers.*.apiKey` приймає рядки відкритого тексту або об’єкти SecretRef. +- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано API-ключ Talk. - `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви. -- `silenceTimeoutMs` визначає, скільки часу режим Talk чекає після того, як користувач замовкне, перш ніж надіслати транскрипт. Якщо не задано, зберігається типове для платформи вікно паузи (`700 ms на macOS і Android, 900 ms на iOS`). +- `silenceTimeoutMs` визначає, скільки режим Talk чекає після тиші користувача, перш ніж надсилати стенограму. Якщо не задано, зберігається типове вікно паузи для платформи (`700 ms на macOS і Android, 900 ms на iOS`). --- -## Пов’язане +## Пов’язані матеріали - [Довідник із конфігурації](/uk/gateway/configuration-reference) — усі інші ключі конфігурації - [Конфігурація](/uk/gateway/configuration) — поширені завдання та швидке налаштування diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index e05259fb4..8ffe3f081 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -1,28 +1,28 @@ --- read_when: - - Ви хочете використовувати вбудований harness app-server Codex + - Ви хочете використовувати комплектований harness app-server Codex - Вам потрібні приклади конфігурації harness Codex - - Ви хочете вимкнути резервний перехід на Pi для розгортань лише з Codex -summary: Запускайте вбудовані ходи агента OpenClaw через вбудований harness app-server Codex + - Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість переходу до Pi +summary: Запустіть вбудовані ходи агента OpenClaw через комплектований harness app-server Codex title: harness Codex x-i18n: - generated_at: "2026-04-24T19:52:02Z" + generated_at: "2026-04-24T21:43:41Z" model: gpt-5.4 provider: openai - source_hash: 1bd8f23e8c807d0c97c99ca9c8a41e39f42a35a0bfed5c7f53793a15b6d24e18 + source_hash: 674bc34552401d1a492b348ceb86fd513a894760987a0c6fef6e79fdb0b3ebfb source_path: plugins/codex-harness.md workflow: 15 --- -Вбудований Plugin `codex` дозволяє OpenClaw запускати вбудовані ходи агента через -app-server Codex замість вбудованого harness Pi. +Комплектований Plugin `codex` дає OpenClaw змогу запускати вбудовані ходи агента через +app-server Codex замість вбудованого harness PI. -Використовуйте це, коли хочете, щоб Codex керував низькорівневим сеансом агента: виявленням -моделей, нативним відновленням thread, нативним Compaction і виконанням через app-server. -OpenClaw, як і раніше, керує чат-каналами, файлами сеансів, вибором моделей, інструментами, +Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням +моделей, нативним відновленням потоку, нативною Compaction та виконанням app-server. +OpenClaw і далі керує каналами чату, файлами сесії, вибором моделі, інструментами, погодженнями, доставкою медіа та видимим дзеркалом транскрипту. -Нативні ходи Codex зберігають хуки Plugin OpenClaw як публічний шар сумісності. +Нативні ходи Codex зберігають хука Plugin OpenClaw як публічний шар сумісності. Це внутрішньопроцесні хуки OpenClaw, а не командні хуки Codex `hooks.json`: - `before_prompt_build` @@ -32,86 +32,87 @@ OpenClaw, як і раніше, керує чат-каналами, файлам - `before_message_write` для дзеркальних записів транскрипту - `agent_end` -Plugins також можуть реєструвати нейтральне до harness middleware для результатів інструментів, щоб переписувати +Plugins також можуть реєструвати нейтральне до harness middleware результатів інструментів, щоб переписувати динамічні результати інструментів OpenClaw після того, як OpenClaw виконає інструмент, і до того, -як результат буде повернуто в Codex. Це окремо від публічного -хука Plugin `tool_result_persist`, який перетворює записи результатів інструментів у транскрипті, -якими володіє OpenClaw. +як результат буде повернено до Codex. Це окремо від публічного +хука Plugin `tool_result_persist`, який трансформує записи результатів +інструментів у транскрипті, що належать OpenClaw. -harness вимкнений за замовчуванням. У нових конфігураціях слід зберігати посилання на моделі OpenAI -у канонічному вигляді `openai/gpt-*` і явно примусово вказувати -`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, якщо вони -хочуть нативне виконання через app-server. Застарілі посилання на моделі `codex/*` і далі автоматично вибирають -harness для сумісності, але вони не показуються як звичайні варіанти моделі/провайдера. +За замовчуванням harness вимкнено. У нових конфігураціях слід зберігати посилання на моделі OpenAI +канонічними як `openai/gpt-*` і явно примусово вказувати +`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли +потрібне нативне виконання app-server. Застарілі посилання на моделі `codex/*` і далі автоматично вибирають +harness для сумісності, але не показуються як звичайні варіанти моделі/провайдера. ## Виберіть правильний префікс моделі -Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, якщо вам потрібен -OAuth Codex через Pi; використовуйте `openai/*`, якщо вам потрібен прямий доступ до OpenAI API або -якщо ви примусово використовуєте нативний harness app-server Codex: +Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли хочете +Codex OAuth через PI; використовуйте `openai/*`, коли хочете прямий доступ до OpenAI API або +коли примусово використовуєте нативний harness app-server Codex: -| Посилання на модель | Шлях runtime | Використовуйте, коли | -| --------------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------- | -| `openai/gpt-5.4` | Провайдер OpenAI через OpenClaw/Pi plumbing | Вам потрібен поточний прямий доступ до 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 app-server Codex | Вам потрібне нативне виконання через app-server Codex для вбудованого ходу агента. | +| Посилання на модель | Шлях runtime | Використовуйте, коли | +| ---------------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------- | +| `openai/gpt-5.4` | Провайдер OpenAI через обв’язку OpenClaw/PI | Вам потрібен поточний прямий доступ до API платформи OpenAI з `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.5` | OpenAI Codex OAuth через OpenClaw/PI | Вам потрібна автентифікація передплати ChatGPT/Codex із runner PI за замовчуванням. | +| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | harness app-server Codex | Вам потрібне нативне виконання app-server Codex для вбудованого ходу агента. | -GPT-5.5 наразі в OpenClaw доступна лише через підписку/OAuth. Використовуйте -`openai-codex/gpt-5.5` для OAuth через Pi або `openai/gpt-5.5` з harness app-server -Codex. Прямий доступ за API-ключем для `openai/gpt-5.5` буде підтримуватися, +GPT-5.5 у OpenClaw наразі доступна лише через передплату/OAuth. Використовуйте +`openai-codex/gpt-5.5` для PI OAuth або `openai/gpt-5.5` з harness +app-server Codex. Прямий доступ через API key для `openai/gpt-5.5` підтримуватиметься, щойно OpenAI увімкне GPT-5.5 у публічному API. -Застарілі посилання `codex/gpt-*` і далі приймаються як псевдоніми для сумісності. Doctor -міграції сумісності переписує застарілі основні посилання `codex/*` на `openai/*` -і окремо записує політику harness Codex. У нових конфігураціях PI OAuth Codex -слід використовувати `openai-codex/gpt-*`; у нових конфігураціях нативного harness app-server слід -використовувати `openai/gpt-*` разом із `embeddedHarness.runtime: "codex"`. +Застарілі посилання `codex/gpt-*` і далі приймаються як псевдоніми сумісності. Doctor +міграція сумісності переписує застарілі основні посилання `codex/*` на `openai/*` +і окремо записує політику harness Codex. Нові конфігурації PI Codex OAuth +мають використовувати `openai-codex/gpt-*`; нові конфігурації нативного harness app-server +мають використовувати `openai/gpt-*` плюс `embeddedHarness.runtime: "codex"`. -`agents.defaults.imageModel` використовує той самий поділ за префіксами. Використовуйте -`openai-codex/gpt-*`, якщо розуміння зображень має виконуватися через шлях провайдера OAuth OpenAI -Codex. Використовуйте `codex/gpt-*`, якщо розуміння зображень має виконуватися -через обмежений хід app-server Codex. Модель app-server Codex повинна -підтримувати введення зображень; текстові моделі Codex завершуються з помилкою ще до початку +`agents.defaults.imageModel` дотримується такого самого поділу префіксів. Використовуйте +`openai-codex/gpt-*`, коли розуміння зображень має виконуватися через шлях провайдера OpenAI +Codex OAuth. Використовуйте `codex/gpt-*`, коли розуміння зображень має виконуватися +через обмежений хід app-server Codex. Модель app-server Codex має +оголошувати підтримку вхідних зображень; текстові моделі Codex завершуються з помилкою до початку медіа-ходу. -Використовуйте `/status`, щоб підтвердити фактичний harness для поточного сеансу. Якщо -вибір виглядає неочікуваним, увімкніть журналювання налагодження для підсистеми `agents/harness` -і перегляньте структурований запис Gateway `agent harness selected`. Він -містить ідентифікатор вибраного harness, причину вибору, політику runtime/fallback і, +Використовуйте `/status`, щоб підтвердити ефективний harness для поточної сесії. Якщо +вибір виглядає несподіваним, увімкніть журналювання налагодження для підсистеми `agents/harness` +і перегляньте структурований запис шлюзу `agent harness selected`. Він +містить ідентифікатор вибраного harness, причину вибору, політику runtime/fallback, а також, у режимі `auto`, результат підтримки для кожного кандидата Plugin. -Вибір harness не є засобом керування активним сеансом. Коли вбудований хід виконується, -OpenClaw записує ідентифікатор вибраного harness у цей сеанс і продовжує використовувати його для -наступних ходів у тому самому ідентифікаторі сеансу. Змінюйте конфігурацію `embeddedHarness` або -`OPENCLAW_AGENT_RUNTIME`, якщо хочете, щоб майбутні сеанси використовували інший harness; -використовуйте `/new` або `/reset`, щоб почати новий сеанс перед перемиканням наявної -розмови між Pi і Codex. Це дозволяє уникнути відтворення одного транскрипту через -дві несумісні нативні системи сеансів. +Вибір harness не є елементом керування живою сесією. Коли вбудований хід виконується, +OpenClaw записує ідентифікатор вибраного harness у цій сесії та продовжує використовувати його для +наступних ходів у межах того самого ідентифікатора сесії. Змінюйте конфігурацію `embeddedHarness` або +`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший harness; +використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням наявної +розмови між PI та Codex. Це запобігає повторному відтворенню одного транскрипту через +дві несумісні нативні системи сесій. -Застарілі сеанси, створені до закріплення harness, вважаються закріпленими за Pi, щойно вони -мають історію транскрипту. Використовуйте `/new` або `/reset`, щоб перевести таку розмову на +Застарілі сесії, створені до закріплення harness, вважаються закріпленими за PI, щойно в них +з’являється історія транскрипту. Використовуйте `/new` або `/reset`, щоб перевести таку розмову на Codex після зміни конфігурації. -`/status` показує фактичний не-Pi harness поруч із `Fast`, наприклад -`Fast · codex`. Типовий harness Pi і далі відображається як `Runner: pi (embedded)` і -не додає окремого бейджа harness. +`/status` показує ефективний не-PI harness поруч із `Fast`, наприклад +`Fast · codex`. Типовий harness PI і далі відображається як `Runner: pi (embedded)` і +не додає окремий бейдж harness. ## Вимоги -- OpenClaw із доступним вбудованим Plugin `codex`. -- app-server Codex версії `0.118.0` або новішої. -- Автентифікація Codex, доступна процесу app-server. +- OpenClaw із доступним комплектованим Plugin `codex`. +- Codex app-server `0.118.0` або новіший. +- Автентифікація Codex, доступна для процесу app-server. -Plugin блокує старіші або неверсіоновані handshake app-server. Це дозволяє -OpenClaw залишатися на поверхні протоколу, з якою його було протестовано. +Plugin блокує старіші або неверсіоновані handshake app-server. Це залишає +OpenClaw на поверхні протоколу, з якою його було протестовано. -Для live- і Docker smoke-тестів автентифікація зазвичай надходить з `OPENAI_API_KEY`, а також +Для live- і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також з необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і -`~/.codex/config.toml`. Використовуйте ті самі матеріали автентифікації, що й ваш локальний app-server Codex. +`~/.codex/config.toml`. Використовуйте той самий матеріал автентифікації, що й ваш локальний +app-server Codex. ## Мінімальна конфігурація -Використовуйте `openai/gpt-5.5`, увімкніть вбудований Plugin і примусово використайте harness `codex`: +Використовуйте `openai/gpt-5.5`, увімкніть комплектований Plugin і примусово вкажіть harness `codex`: ```json5 { @@ -134,7 +135,7 @@ OpenClaw залишатися на поверхні протоколу, з як } ``` -Якщо у вашій конфігурації використовується `plugins.allow`, додайте туди також `codex`: +Якщо ваша конфігурація використовує `plugins.allow`, включіть туди також `codex`: ```json5 { @@ -149,15 +150,15 @@ OpenClaw залишатися на поверхні протоколу, з як } ``` -Застарілі конфігурації, які встановлюють `agents.defaults.model` або модель агента в -`codex/`, і далі автоматично вмикають вбудований Plugin `codex`. У нових конфігураціях -слід віддавати перевагу `openai/` разом із явним записом `embeddedHarness`, наведеним вище. +Застарілі конфігурації, які встановлюють `agents.defaults.model` або модель агента на +`codex/`, усе ще автоматично вмикають комплектований Plugin `codex`. У нових конфігураціях слід +надавати перевагу `openai/` плюс явному запису `embeddedHarness`, наведеному вище. -## Додайте Codex, не замінюючи інші моделі +## Додайте Codex без заміни інших моделей -Зберігайте `runtime: "auto"`, якщо хочете, щоб застарілі посилання `codex/*` вибирали Codex, а -Pi використовувався для всього іншого. Для нових конфігурацій краще явно вказувати `runtime: "codex"` -для агентів, які мають використовувати цей harness. +Залишайте `runtime: "auto"`, якщо хочете, щоб застарілі посилання `codex/*` вибирали Codex, а +PI — для всього іншого. Для нових конфігурацій надавайте перевагу явному `runtime: "codex"` для +агентів, які мають використовувати harness. ```json5 { @@ -187,16 +188,17 @@ Pi використовувався для всього іншого. Для н } ``` -За такої структури: +За такої форми: - `/model gpt` або `/model openai/gpt-5.5` використовує harness app-server Codex для цієї конфігурації. - `/model opus` використовує шлях провайдера Anthropic. -- Якщо вибрано не-Codex модель, Pi залишається harness сумісності. +- Якщо вибрано не-Codex модель, PI залишається harness сумісності. ## Розгортання лише з Codex -Вимкніть fallback на Pi, якщо вам потрібно довести, що кожен вбудований хід агента використовує -harness Codex: +Примусово використовуйте harness Codex, коли потрібно довести, що кожен вбудований хід агента +використовує Codex. Явні runtime Plugin за замовчуванням не мають fallback до PI, тому +`fallback: "none"` необов’язковий, але часто корисний як документація: ```json5 { @@ -215,13 +217,13 @@ harness Codex: Перевизначення через середовище: ```bash -OPENCLAW_AGENT_RUNTIME=codex \ -OPENCLAW_AGENT_HARNESS_FALLBACK=none \ -openclaw gateway run +OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -Коли fallback вимкнено, OpenClaw завершується з помилкою на ранньому етапі, якщо Plugin Codex вимкнено, -app-server надто старий або app-server не може запуститися. +Коли Codex примусово увімкнено, OpenClaw завершується з помилкою на ранньому етапі, якщо Plugin Codex вимкнено, +app-server застарий або app-server не може запуститися. Встановлюйте +`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише якщо ви навмисно хочете, щоб PI обробляв +відсутній вибір harness. ## Codex для окремого агента @@ -257,15 +259,15 @@ app-server надто старий або app-server не може запуст } ``` -Використовуйте звичайні команди сеансу, щоб перемикати агентів і моделі. `/new` створює новий -сеанс OpenClaw, а harness Codex створює або відновлює свій sidecar thread app-server -за потреби. `/reset` очищає прив’язку сеансу OpenClaw для цього thread -і дозволяє наступному ходу знову визначити harness із поточної конфігурації. +Використовуйте звичайні команди сесії для перемикання агентів і моделей. `/new` створює нову +сесію OpenClaw, а harness Codex створює або відновлює свій sidecar-потік app-server +за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього потоку +і дозволяє наступному ходу знову визначити harness з поточної конфігурації. ## Виявлення моделей -За замовчуванням Plugin Codex запитує в app-server доступні моделі. Якщо -виявлення не вдається або завершується за timeout, він використовує вбудований резервний каталог для: +За замовчуванням Plugin Codex запитує app-server про доступні моделі. Якщо +виявлення не вдається або завершується за тайм-аутом, використовується комплектований резервний каталог для: - GPT-5.5 - GPT-5.4 mini @@ -291,7 +293,7 @@ app-server надто старий або app-server не може запуст } ``` -Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалося зондування Codex і використовувався +Вимкніть виявлення, якщо хочете, щоб під час запуску не відбувалося зондування Codex і використовувався резервний каталог: ```json5 @@ -311,21 +313,21 @@ app-server надто старий або app-server не може запуст } ``` -## Підключення app-server і політика +## Підключення до app-server і політика -За замовчуванням Plugin запускає Codex локально за допомогою: +За замовчуванням Plugin запускає Codex локально так: ```bash codex app-server --listen stdio:// ``` -За замовчуванням OpenClaw запускає локальні сеанси harness Codex у режимі YOLO: +За замовчуванням OpenClaw запускає локальні сесії harness Codex у режимі YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` і `sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, яка використовується -для автономних Heartbeat: Codex може використовувати shell і мережеві інструменти без -зупинки на нативних запитах погодження, на які нікому відповісти. +для автономних Heartbeat: Codex може використовувати shell- і мережеві інструменти, не +зупиняючись на нативних запитах погодження, коли нікому відповісти. -Щоб увімкнути перегляд погоджень через guardian Codex, установіть `appServer.mode: +Щоб увімкнути погодження Codex, перевірені guardian, установіть `appServer.mode: "guardian"`: ```json5 @@ -346,9 +348,9 @@ codex app-server --listen stdio:// } ``` -Guardian — це нативний рецензент погоджень Codex. Коли Codex просить вийти з пісочниці, записати за межі робочого простору або додати дозволи, наприклад доступ до мережі, Codex спрямовує цей запит на погодження до субагента-рецензента, а не до людини через підказку. Рецензент застосовує модель ризиків Codex і схвалює або відхиляє конкретний запит. Використовуйте Guardian, якщо вам потрібно більше запобіжників, ніж у режимі YOLO, але водночас необхідно, щоб агенти без нагляду могли просуватися далі. +Guardian — це нативний рецензент погоджень Codex. Коли Codex просить вийти за межі sandbox, записати поза межами workspace або додати дозволи, як-от мережевий доступ, Codex надсилає цей запит на погодження рецензенту-субагенту, а не людині через prompt. Рецензент застосовує модель ризиків Codex і погоджує або відхиляє конкретний запит. Використовуйте Guardian, коли вам потрібно більше запобіжників, ніж у режимі YOLO, але при цьому потрібно, щоб агенти без нагляду продовжували роботу. -Пресет `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля політики все одно мають пріоритет над `mode`, тож у складніших розгортаннях можна поєднувати пресет із явними виборами. +Пресет `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля політики й далі мають пріоритет над `mode`, тому розширені розгортання можуть поєднувати пресет із явними налаштуваннями. Для вже запущеного app-server використовуйте транспорт WebSocket: @@ -374,22 +376,22 @@ Guardian — це нативний рецензент погоджень Codex. Підтримувані поля `appServer`: -| Поле | Значення за замовчуванням | Значення | -| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | -| `command` | `"codex"` | Виконуваний файл для транспорту stdio. | -| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | -| `url` | не встановлено | URL WebSocket app-server. | -| `authToken` | не встановлено | Bearer-токен для транспорту WebSocket. | -| `headers` | `{}` | Додаткові заголовки WebSocket. | -| `requestTimeoutMs` | `60000` | Timeout для викликів control-plane app-server. | -| `mode` | `"yolo"` | Пресет для виконання в режимі YOLO або з перевіркою guardian. | -| `approvalPolicy` | `"never"` | Нативна політика погоджень Codex, що надсилається під час запуску/відновлення thread і під час ходу. | -| `sandbox` | `"danger-full-access"` | Нативний режим пісочниці Codex, що надсилається під час запуску/відновлення thread. | -| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб дозволити Codex Guardian перевіряти запити. | -| `serviceTier` | не встановлено | Необов’язковий рівень сервісу 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 token для транспорту WebSocket. | +| `headers` | `{}` | Додаткові заголовки WebSocket. | +| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control plane app-server. | +| `mode` | `"yolo"` | Пресет для виконання в режимі YOLO або з перевіркою guardian. | +| `approvalPolicy` | `"never"` | Нативна політика погодження Codex, що надсилається під час запуску/відновлення потоку/ходу. | +| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що надсилається під час запуску/відновлення потоку. | +| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб дозволити Codex Guardian перевіряти prompt. | +| `serviceTier` | не встановлено | Необов’язковий service tier app-server Codex: `"fast"`, `"flex"` або `null`. Неприпустимі застарілі значення ігноруються. | -Старіші змінні середовища все ще працюють як fallback для локального тестування, коли +Старіші змінні середовища й далі працюють як fallback для локального тестування, коли відповідне поле конфігурації не встановлено: - `OPENCLAW_CODEX_APP_SERVER_BIN` @@ -398,11 +400,11 @@ Guardian — це нативний рецензент погоджень Codex. - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було вилучено. Натомість використовуйте -`plugins.entries.codex.config.appServer.mode: "guardian"` або -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Конфігурація -є кращою для відтворюваних розгортань, оскільки зберігає поведінку Plugin в тому самому -перевіреному файлі, що й решта налаштувань harness Codex. +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було вилучено. Використовуйте +`plugins.entries.codex.config.appServer.mode: "guardian"` натомість або +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для одноразового локального тестування. Конфігурації +надається перевага для відтворюваних розгортань, оскільки вона зберігає поведінку Plugin в тому +самому перевіреному файлі, що й решта налаштувань harness Codex. ## Поширені рецепти @@ -420,7 +422,7 @@ Guardian — це нативний рецензент погоджень Codex. } ``` -Перевірка harness лише-Codex із вимкненим fallback на Pi: +Перевірка harness лише-Codex із вимкненим fallback до PI: ```json5 { @@ -437,7 +439,7 @@ Guardian — це нативний рецензент погоджень Codex. } ``` -Погодження Codex із перевіркою Guardian: +Погодження Codex із перевіркою guardian: ```json5 { @@ -482,115 +484,115 @@ Guardian — це нативний рецензент погоджень Codex. } ``` -Перемикання моделей і далі контролюється OpenClaw. Коли сеанс OpenClaw приєднано -до наявного thread Codex, наступний хід знову надсилає до -app-server поточну вибрану модель OpenAI, провайдера, політику погоджень, пісочницю та рівень сервісу. -Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає прив’язку до -thread, але просить Codex продовжити роботу з новою вибраною моделлю. +Перемикання моделей залишається під керуванням OpenClaw. Коли сесію OpenClaw прив’язано +до наявного потоку Codex, наступний хід знову надсилає до +app-server поточну вибрану модель OpenAI, провайдера, політику погодження, sandbox і +service tier. Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає +прив’язку до потоку, але просить Codex продовжити з новою вибраною моделлю. ## Команда Codex -Вбудований Plugin реєструє `/codex` як авторизовану slash-команду. Вона -загальна й працює в будь-якому каналі, що підтримує текстові команди OpenClaw. +Комплектований Plugin реєструє `/codex` як авторизовану slash-команду. Вона є +загальною та працює в будь-якому каналі, який підтримує текстові команди OpenClaw. Поширені форми: -- `/codex status` показує поточне підключення до app-server, моделі, обліковий запис, ліміти швидкості, сервери MCP і Skills. -- `/codex models` показує поточні моделі app-server Codex. -- `/codex threads [filter]` показує нещодавні threads Codex. -- `/codex resume ` приєднує поточний сеанс OpenClaw до наявного thread Codex. -- `/codex compact` просить app-server Codex виконати Compaction для приєднаного thread. -- `/codex review` запускає нативну перевірку Codex для приєднаного thread. +- `/codex status` показує живе підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP-сервери та skills. +- `/codex models` показує список живих моделей app-server Codex. +- `/codex threads [filter]` показує список нещодавніх потоків Codex. +- `/codex resume ` прив’язує поточну сесію OpenClaw до наявного потоку Codex. +- `/codex compact` просить app-server Codex виконати compaction для прив’язаного потоку. +- `/codex review` запускає нативну перевірку Codex для прив’язаного потоку. - `/codex account` показує стан облікового запису та лімітів швидкості. -- `/codex mcp` показує стан серверів MCP app-server Codex. -- `/codex skills` показує Skills app-server Codex. +- `/codex mcp` показує список станів MCP-серверів app-server Codex. +- `/codex skills` показує список Skills app-server Codex. `/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для -звичайних ходів. У наступному повідомленні OpenClaw відновлює цей thread Codex, передає -поточну вибрану модель OpenClaw до app-server і зберігає увімкненою -розширену історію. +звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає +поточну вибрану модель OpenClaw до app-server і зберігає розширену історію +увімкненою. -Поверхня команд вимагає app-server Codex версії `0.118.0` або новішої. Окремі +Поверхня команд вимагає Codex app-server `0.118.0` або новішої версії. Окремі методи керування позначаються як `unsupported by this Codex app-server`, якщо -майбутній або кастомний app-server не надає цей метод JSON-RPC. +майбутній або кастомний app-server не надає цей JSON-RPC метод. ## Межі хуків -harness Codex має три шари хуків: +Harness Codex має три шари хуків: | Шар | Власник | Призначення | | ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| Хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness Pi і Codex. | -| Middleware розширення app-server Codex | Вбудовані Plugins OpenClaw | Поведінка адаптера навколо динамічних інструментів OpenClaw для кожного ходу. | -| Нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і політика нативних інструментів із конфігурації Codex. | +| хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness PI і Codex. | +| middleware розширення app-server Codex | комплектовані Plugins OpenClaw | Поведінка адаптера навколо динамічних інструментів OpenClaw для кожного ходу. | +| нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і нативна політика інструментів із конфігурації Codex. | -OpenClaw не використовує файли Codex `hooks.json` проєкту або глобального рівня для маршрутизації -поведінки Plugin OpenClaw. Нативні хуки Codex корисні для операцій, якими володіє -Codex, як-от політика shell, нативна перевірка результатів інструментів, обробка зупинки та -нативний життєвий цикл Compaction/моделі, але вони не є API Plugin OpenClaw. +OpenClaw не використовує файли проєктного або глобального Codex `hooks.json` для маршрутизації +поведінки Plugin OpenClaw. Нативні хуки Codex корисні для операцій, +що належать Codex, як-от політика shell, нативна перевірка результатів інструментів, обробка зупинки та +нативна Compaction/життєвий цикл моделі, але вони не є API Plugin OpenClaw. -Для динамічних інструментів OpenClaw виконує інструмент після того, як Codex запитує +Для динамічних інструментів OpenClaw, OpenClaw виконує інструмент після того, як Codex запитує виклик, тому OpenClaw запускає поведінку Plugin і middleware, якою він володіє, у -адаптері harness. Для нативних інструментів Codex канонічним записом інструмента володіє Codex. -OpenClaw може віддзеркалювати вибрані події, але не може переписати нативний thread Codex, -якщо тільки Codex не відкриває цю операцію через app-server або колбеки -нативних хуків. +адаптері harness. Для нативних інструментів Codex саме Codex володіє канонічним записом інструмента. +OpenClaw може віддзеркалювати окремі події, але не може переписати нативний потік Codex, +якщо тільки Codex не надає цю операцію через app-server або нативні callback-хуки. -Коли новіші збірки app-server Codex відкривають нативні події хуків життєвого циклу Compaction і моделі, -OpenClaw має обмежувати підтримку цього протоколу за версією та відображати -події в наявний контракт хуків OpenClaw там, де семантика є чесною. +Коли новіші збірки app-server Codex надаватимуть події хуків нативної Compaction і життєвого циклу моделі, +OpenClaw має з урахуванням версії протоколу вмикати цю підтримку та зіставляти +події з наявним контрактом хуків OpenClaw там, де семантика є коректною. До того часу події OpenClaw `before_compaction`, `after_compaction`, `llm_input` і `llm_output` є спостереженнями на рівні адаптера, а не побайтними копіями -внутрішнього запиту або payload Compaction у Codex. +внутрішнього запиту Codex або payload Compaction. -Нативні сповіщення app-server Codex `hook/started` і `hook/completed` проєктуються як -події агента `codex_app_server.hook` для траєкторії та налагодження. +Нативні сповіщення app-server Codex `hook/started` і `hook/completed` +проєктуються як події агента `codex_app_server.hook` для траєкторії та налагодження. Вони не викликають хуки Plugin OpenClaw. ## Інструменти, медіа та Compaction -harness Codex змінює лише низькорівневий виконавець вбудованого агента. +Harness Codex змінює лише низькорівневий виконавець вбудованого агента. -OpenClaw, як і раніше, будує список інструментів і отримує динамічні результати інструментів від -harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструмента повідомлень -і далі проходять через звичайний шлях доставки OpenClaw. +OpenClaw і далі формує список інструментів і отримує результати динамічних інструментів від +harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів повідомлень +і далі проходять звичайним шляхом доставки OpenClaw. -Запити на погодження інструментів Codex MCP маршрутизуються через потік погоджень Plugin OpenClaw, коли -Codex позначає `_meta.codex_approval_kind` як -`"mcp_tool_call"`. Запити Codex `request_user_input` надсилаються назад до -початкового чату, а наступне поставлене в чергу повідомлення-відповідь відповідає на цей нативний -запит сервера замість того, щоб додаватися як додатковий контекст. Інші запити MCP на -уточнення й далі завершуються з відмовою за замовчуванням. +Запити погодження інструментів Codex MCP маршрутизуються через потік погодження Plugin +OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як +`"mcp_tool_call"`. Prompt Codex `request_user_input` надсилаються назад у +початковий чат, а наступне поставлене в чергу повідомлення-відповідь відповідає на цей нативний +запит сервера замість того, щоб спрямовуватися як додатковий контекст. Інші запити elicitation MCP +і далі завершуються за принципом fail closed. -Коли вибрана модель використовує harness Codex, нативний thread Compaction делегується +Коли вибрана модель використовує harness Codex, нативна Compaction потоку делегується app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу, пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало -включає запит користувача, фінальний текст асистента та спрощені записи міркувань або плану Codex, -коли app-server їх надсилає. Наразі OpenClaw лише записує сигнали початку й завершення -нативного Compaction. Він ще не показує зрозумілий для людини підсумок Compaction або -аудитований список того, які записи Codex зберіг після Compaction. +містить prompt користувача, фінальний текст помічника та полегшені записи міркувань або +плану Codex, коли app-server їх надсилає. Наразі OpenClaw записує лише сигнали +початку та завершення нативної Compaction. Він ще не надає зрозумілого для людини +зведення Compaction або придатного до аудиту списку того, які записи Codex +зберіг після Compaction. -Оскільки канонічним нативним thread володіє Codex, `tool_result_persist` наразі не +Оскільки Codex володіє канонічним нативним потоком, `tool_result_persist` наразі не переписує записи результатів нативних інструментів Codex. Він застосовується лише тоді, коли -OpenClaw записує результат інструмента в транскрипт сеансу, яким володіє OpenClaw. +OpenClaw записує результат інструмента в транскрипт сесії, що належить OpenClaw. -Генерація медіа не потребує Pi. Генерація зображень, відео, музики, PDF, TTS і -розуміння медіа й далі використовують відповідні налаштування провайдера/моделі, як-от +Генерація медіа не вимагає PI. Генерація зображень, відео, музики, PDF, TTS і +розуміння медіа й далі використовують відповідні налаштування провайдера/моделі, такі як `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і `messages.tts`. -## Усунення несправностей +## Усунення проблем **Codex не з’являється в `/model`:** увімкніть `plugins.entries.codex.enabled`, виберіть модель `openai/gpt-*` з `embeddedHarness.runtime: "codex"` (або застаріле посилання `codex/*`) і перевірте, чи `plugins.allow` не виключає `codex`. -**OpenClaw використовує Pi замість Codex:** якщо жоден harness Codex не бере на себе запуск, -OpenClaw може використовувати Pi як бекенд сумісності. Установіть -`embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування, або -`embeddedHarness.fallback: "none"`, щоб завершуватися з помилкою, коли жоден harness Plugin не підходить. Щойно -вибрано app-server Codex, його збої відображаються безпосередньо без додаткової -конфігурації fallback. +**OpenClaw використовує PI замість Codex:** `runtime: "auto"` усе ще може використовувати PI як +бекенд сумісності, коли жоден harness Codex не бере виконання на себе. Установіть +`embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування. Тепер +примусовий runtime Codex завершується з помилкою замість fallback до PI, якщо ви +явно не встановите `embeddedHarness.fallback: "pi"`. Щойно вибрано app-server Codex, +його збої проявляються безпосередньо без додаткової конфігурації fallback. **app-server відхиляється:** оновіть Codex, щоб handshake app-server повідомляв версію `0.118.0` або новішу. @@ -598,16 +600,16 @@ OpenClaw може використовувати Pi як бекенд суміс **Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` або вимкніть виявлення. -**Транспорт WebSocket одразу завершується з помилкою:** перевірте `appServer.url`, `authToken` +**Транспорт WebSocket відразу завершується з помилкою:** перевірте `appServer.url`, `authToken`, і що віддалений app-server використовує ту саму версію протоколу app-server Codex. -**Не-Codex модель використовує Pi:** це очікувано, якщо ви не примусово встановили +**Не-Codex модель використовує PI:** це очікувано, якщо ви не примусово встановили `embeddedHarness.runtime: "codex"` (або не вибрали застаріле посилання `codex/*`). Звичайні `openai/gpt-*` та інші посилання провайдерів залишаються на своєму звичайному шляху провайдера. ## Пов’язане -- [Agent Harness Plugins](/uk/plugins/sdk-agent-harness) +- [Plugins Harness агента](/uk/plugins/sdk-agent-harness) - [Провайдери моделей](/uk/concepts/model-providers) - [Довідник із конфігурації](/uk/gateway/configuration-reference) - [Тестування](/uk/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/uk/plugins/google-meet.md b/docs/uk/plugins/google-meet.md index cf0882fbf..f1fbd0852 100644 --- a/docs/uk/plugins/google-meet.md +++ b/docs/uk/plugins/google-meet.md @@ -6,46 +6,46 @@ read_when: summary: 'Плагін Google Meet: приєднання до явних URL-адрес Meet через Chrome або Twilio з типовими налаштуваннями голосу в реальному часі' title: Плагін Google Meet x-i18n: - generated_at: "2026-04-24T21:15:37Z" + generated_at: "2026-04-24T21:43:39Z" model: gpt-5.4 provider: openai - source_hash: 8c109e07170601a81f1802bcfb1477d82ff22d69966f73c7811d4c158a1854d7 + source_hash: 3075b803b04001a7a205215d2606087a38ce75cbde1ab0a44f61f8d5c88ccf78 source_path: plugins/google-meet.md workflow: 15 --- -Підтримка учасників Google Meet для OpenClaw — плагін навмисно зроблено явним: +Підтримка учасника Google Meet для OpenClaw — Plugin є навмисно явним за дизайном: - Він приєднується лише до явного URL `https://meet.google.com/...`. - Він може створити новий простір Meet через API Google Meet, а потім приєднатися за поверненим URL. -- `realtime` — це типовий режим голосу. +- Голос `realtime` є режимом за замовчуванням. - Голос у режимі реального часу може повертатися до повного агента OpenClaw, коли потрібні глибше міркування або інструменти. -- Агенти вибирають поведінку приєднання через `mode`: використовуйте `realtime` для живого прослуховування/відповіді голосом або `transcribe`, щоб приєднатися/керувати браузером без голосового мосту реального часу. -- Автентифікація починається як особистий Google OAuth або вже виконаний вхід у профіль Chrome. +- Агенти обирають поведінку приєднання за допомогою `mode`: використовуйте `realtime` для живого прослуховування/зворотного мовлення або `transcribe`, щоб приєднатися/керувати браузером без голосового моста режиму реального часу. +- Автентифікація починається як персональний Google OAuth або вже виконаний вхід у профіль Chrome. - Автоматичного оголошення згоди немає. - Типовий аудіобекенд Chrome — `BlackHole 2ch`. -- Chrome може працювати локально або на під’єднаному вузлі. -- Twilio приймає номер для дозвону та необов’язковий PIN або послідовність DTMF. -- Команда CLI — `googlemeet`; `meet` зарезервовано для ширших сценаріїв телеконференцій агента. +- Chrome може працювати локально або на підключеному хості Node. +- Twilio приймає номер для дозвону та необов’язкову послідовність PIN або DTMF. +- Команда CLI — `googlemeet`; `meet` зарезервовано для ширших робочих процесів телеконференцій агента. ## Швидкий старт -Установіть локальні аудіозалежності та налаштуйте постачальника голосу реального часу для бекенду. Типовим є OpenAI; Google Gemini Live також працює з `realtime.provider: "google"`: +Установіть локальні аудіозалежності та налаштуйте бекенд-провайдера голосу в режимі реального часу. OpenAI використовується за замовчуванням; Google Gemini Live також працює з `realtime.provider: "google"`: ```bash brew install blackhole-2ch sox export OPENAI_API_KEY=sk-... -# або +# or export GEMINI_API_KEY=... ``` -`blackhole-2ch` установлює віртуальний аудіопристрій `BlackHole 2ch`. Інсталятор Homebrew потребує перезавантаження, перш ніж macOS покаже цей пристрій: +`blackhole-2ch` установлює віртуальний аудіопристрій `BlackHole 2ch`. Інсталятор Homebrew вимагає перезавантаження, перш ніж macOS зробить пристрій доступним: ```bash sudo reboot ``` -Після перезавантаження перевірте обидва компоненти: +Після перезавантаження перевірте обидві складові: ```bash system_profiler SPAudioDataType | grep -i BlackHole @@ -73,9 +73,8 @@ command -v rec play openclaw googlemeet setup ``` -Вивід налаштування призначено для читання агентом. Він повідомляє про профіль Chrome, аудіоміст, закріплення вузла, відкладений вступ у режимі реального часу та, якщо налаштовано делегування Twilio, чи готові плагін `voice-call` і облікові дані Twilio. -Вважайте будь-яку перевірку `ok: false` блокером, перш ніж просити агента приєднатися. -Для скриптів або машинозчитуваного виводу використовуйте `openclaw googlemeet setup --json`. +Вивід налаштування призначений для читання агентом. Він повідомляє про профіль Chrome, аудіоміст, прив’язку до Node, відкладене вступне повідомлення режиму реального часу, а також, коли налаштовано делегування Twilio, чи готові Plugin `voice-call` і облікові дані Twilio. Вважайте будь-яку перевірку з `ok: false` блокувальною, перш ніж просити агента приєднатися. +Використовуйте `openclaw googlemeet setup --json` для скриптів або машинозчитуваного виводу. Приєднайтеся до зустрічі: @@ -101,7 +100,14 @@ openclaw googlemeet create openclaw googlemeet join https://meet.google.com/new-abcd-xyz --transport chrome-node ``` -Або скажіть агенту: «Створи Google Meet, приєднайся до нього з голосом у режимі реального часу і надішли мені посилання». Агент має викликати `google_meet` з `action: "create"`, скопіювати повернений `meetingUri`, а потім викликати `google_meet` з `action: "join"` і цим URL. +`googlemeet create` має два шляхи: + +- Створення через API: використовується, коли налаштовано облікові дані Google Meet OAuth. Це найдетермінованіший шлях, який не залежить від стану інтерфейсу браузера. +- Резервний варіант через браузер: використовується, коли облікові дані OAuth відсутні. OpenClaw використовує закріплений Chrome Node, відкриває `https://meet.google.com/new`, чекає, поки Google перенаправить на реальний URL із кодом зустрічі, а потім повертає цей URL. Цей шлях вимагає, щоб профіль OpenClaw Chrome на Node уже мав виконаний вхід у Google. + +Вивід команди містить поле `source` (`api` або `browser`), щоб агенти могли пояснити, який шлях було використано. + +Або скажіть агенту: "Створи Google Meet, приєднайся до нього з голосом у режимі реального часу та надішли мені посилання". Агент має викликати `google_meet` з `action: "create"`, скопіювати повернений `meetingUri`, а потім викликати `google_meet` з `action: "join"` і цим URL. ```json { @@ -118,19 +124,19 @@ openclaw googlemeet join https://meet.google.com/new-abcd-xyz --transport chrome } ``` -Для приєднання лише для спостереження/керування браузером установіть `"mode": "transcribe"`. Це не запускає двобічний міст моделі реального часу, тому вона не буде відповідати голосом у зустрічі. +Для приєднання лише зі спостереженням/керуванням браузером установіть `"mode": "transcribe"`. Це не запускає міст дуплексної моделі режиму реального часу, тому він не буде відповідати голосом у зустрічі. -Chrome приєднується як профіль Chrome, у якому виконано вхід. У Meet виберіть `BlackHole 2ch` для шляху мікрофона/динаміка, який використовує OpenClaw. Для чистого двобічного аудіо використовуйте окремі віртуальні пристрої або граф у стилі Loopback; одного пристрою BlackHole достатньо для першого smoke-тесту, але він може створювати відлуння. +Chrome приєднується як профіль Chrome, у якому виконано вхід. У Meet виберіть `BlackHole 2ch` для шляху мікрофона/динаміка, який використовує OpenClaw. Для чистого дуплексного аудіо використовуйте окремі віртуальні пристрої або граф на кшталт Loopback; одного пристрою BlackHole достатньо для першого smoke-тесту, але може бути луна. ### Локальний Gateway + Parallels Chrome -Вам **не** потрібен повний OpenClaw Gateway або ключ API моделі всередині macOS VM лише для того, щоб VM володіла Chrome. Запустіть Gateway і агента локально, а потім запустіть вузол у VM. Увімкніть вбудований плагін у VM один раз, щоб вузол рекламував команду Chrome: +Вам **не** потрібен повний OpenClaw Gateway або ключ API моделі всередині macOS VM лише для того, щоб VM володіла Chrome. Запустіть Gateway і агента локально, а потім запустіть хост Node у VM. Один раз увімкніть у VM вбудований Plugin, щоб Node оголошував команду Chrome: -Що де працює: +Що де запускається: -- Хост Gateway: OpenClaw Gateway, робочий простір агента, ключі моделі/API, постачальник режиму реального часу та конфігурація плагіна Google Meet. -- macOS VM у Parallels: CLI/node host OpenClaw, Google Chrome, SoX, BlackHole 2ch і профіль Chrome з виконаним входом у Google. -- Не потрібно у VM: служба Gateway, конфігурація агента, ключ OpenAI/GPT або налаштування постачальника моделі. +- Хост Gateway: OpenClaw Gateway, робочий простір агента, ключі моделі/API, провайдер режиму реального часу та конфігурація Plugin Google Meet. +- macOS VM у Parallels: OpenClaw CLI/хост Node, Google Chrome, SoX, BlackHole 2ch і профіль Chrome з виконаним входом у Google. +- Не потрібно у VM: сервіс Gateway, конфігурація агента, ключ OpenAI/GPT або налаштування провайдера моделі. Установіть залежності у VM: @@ -138,13 +144,13 @@ Chrome приєднується як профіль Chrome, у якому вик brew install blackhole-2ch sox ``` -Перезавантажте VM після встановлення BlackHole, щоб macOS показала `BlackHole 2ch`: +Перезавантажте VM після встановлення BlackHole, щоб macOS зробила `BlackHole 2ch` доступним: ```bash sudo reboot ``` -Після перезавантаження перевірте, що VM бачить аудіопристрій і команди SoX: +Після перезавантаження переконайтеся, що VM бачить аудіопристрій і команди SoX: ```bash system_profiler SPAudioDataType | grep -i BlackHole @@ -157,20 +163,20 @@ command -v rec play openclaw plugins enable google-meet ``` -Запустіть вузол у VM: +Запустіть хост Node у VM: ```bash openclaw node run --host --port 18789 --display-name parallels-macos ``` -Якщо `` — це IP-адреса LAN і ви не використовуєте TLS, вузол відхиляє незашифрований WebSocket, якщо ви явно не дозволите це для цієї довіреної приватної мережі: +Якщо `` є LAN IP і ви не використовуєте TLS, Node відхилить незашифрований WebSocket, якщо ви явно не дозволите це для цієї довіреної приватної мережі: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -Використовуйте ту саму змінну середовища, коли встановлюєте вузол як LaunchAgent: +Використовуйте ту саму змінну середовища під час установлення Node як LaunchAgent: ```bash OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ @@ -178,22 +184,22 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node restart ``` -`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` — це змінна середовища процесу, а не параметр `openclaw.json`. `openclaw node install` зберігає її в середовищі LaunchAgent, якщо вона присутня в команді встановлення. +`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` — це середовище процесу, а не параметр `openclaw.json`. `openclaw node install` зберігає його в середовищі LaunchAgent, коли воно присутнє в команді встановлення. -Підтвердьте вузол із хоста Gateway: +Схваліть Node з хоста Gateway: ```bash openclaw devices list openclaw devices approve ``` -Підтвердьте, що Gateway бачить вузол і що він рекламує як `googlemeet.chrome`, так і можливість браузера/`browser.proxy`: +Підтвердьте, що Gateway бачить Node і що він оголошує як `googlemeet.chrome`, так і можливість браузера/`browser.proxy`: ```bash openclaw nodes status ``` -Спрямуйте Meet через цей вузол на хості Gateway: +Спрямуйте Meet через цей Node на хості Gateway: ```json5 { @@ -223,7 +229,7 @@ openclaw nodes status } ``` -Тепер приєднуйтеся як зазвичай із хоста Gateway: +Тепер приєднуйтеся звичайним способом із хоста Gateway: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij @@ -231,54 +237,53 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij або попросіть агента використати інструмент `google_meet` з `transport: "chrome-node"`. -Для smoke-тесту однією командою, який створює або повторно використовує сеанс, вимовляє відому фразу та виводить стан сеансу: +Для smoke-тесту однією командою, який створює або повторно використовує сесію, промовляє відому фразу та виводить стан сесії: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij ``` -Якщо в профілі браузера не виконано вхід, Meet очікує допуску хостом або Chrome потребує дозволу на мікрофон/камеру, результат join/test-speech повідомляє `manualActionRequired: true` разом із `manualActionReason` і `manualActionMessage`. Агенти мають припинити повторні спроби приєднання, повідомити це повідомлення оператору й повторити спробу лише після завершення ручної дії в браузері. +Якщо в профілі браузера не виконано вхід, Meet очікує допуску від організатора або Chrome потребує дозволу на мікрофон/камеру, результат join/test-speech повідомляє `manualActionRequired: true` разом із `manualActionReason` і `manualActionMessage`. Агенти повинні припинити повторні спроби приєднання, повідомити оператору це повідомлення та повторити спробу лише після завершення ручної дії в браузері. -Якщо `chromeNode.node` пропущено, OpenClaw виконує автовибір лише тоді, коли рівно один підключений вузол рекламує і `googlemeet.chrome`, і керування браузером. Якщо підключено кілька придатних вузлів, установіть `chromeNode.node` на id вузла, відображуване ім’я або віддалену IP-адресу. +Якщо `chromeNode.node` пропущено, OpenClaw автоматично обирає Node лише тоді, коли рівно один підключений Node оголошує і `googlemeet.chrome`, і керування браузером. Якщо підключено кілька придатних Node, установіть `chromeNode.node` в ідентифікатор Node, відображуване ім’я або віддалену IP-адресу. -Поширені перевірки помилок: +Поширені перевірки збоїв: -- `No connected Google Meet-capable node`: запустіть `openclaw node run` у VM, підтвердьте сполучення та переконайтеся, що у VM було виконано `openclaw plugins enable google-meet` і `openclaw plugins enable browser`. Також підтвердьте, що хост Gateway дозволяє обидві команди вузла через `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]`. +- `No connected Google Meet-capable node`: запустіть `openclaw node run` у VM, схваліть сполучення та переконайтеся, що у VM було виконано `openclaw plugins enable google-meet` і `openclaw plugins enable browser`. Також підтвердьте, що хост Gateway дозволяє обидві команди Node через `gateway.nodes.allowCommands: ["googlemeet.chrome", "browser.proxy"]`. - `BlackHole 2ch audio device not found on the node`: установіть `blackhole-2ch` у VM і перезавантажте VM. -- Chrome відкривається, але не може приєднатися: увійдіть у профіль браузера всередині VM або залиште `chrome.guestName` встановленим для гостьового приєднання. Автоприєднання гостя використовує автоматизацію браузера OpenClaw через проксі браузера вузла; переконайтеся, що конфігурація браузера вузла вказує на потрібний профіль, наприклад `browser.defaultProfile: "user"` або іменований профіль наявного сеансу. -- Дубльовані вкладки Meet: залиште ввімкненим `chrome.reuseExistingTab: true`. OpenClaw активує наявну вкладку для того самого URL Meet перед відкриттям нової. -- Немає аудіо: у Meet спрямовуйте аудіо мікрофона/динаміка через шлях віртуального аудіопристрою, який використовує OpenClaw; для чистого двобічного аудіо використовуйте окремі віртуальні пристрої або маршрутизацію в стилі Loopback. +- Chrome відкривається, але не може приєднатися: увійдіть у профіль браузера всередині VM або залиште `chrome.guestName` увімкненим для гостьового приєднання. Автоприєднання гостя використовує автоматизацію браузера OpenClaw через проксі браузера Node; переконайтеся, що конфігурація браузера Node вказує на потрібний вам профіль, наприклад `browser.defaultProfile: "user"` або іменований профіль наявної сесії. +- Дубльовані вкладки Meet: залишайте `chrome.reuseExistingTab: true` увімкненим. OpenClaw активує наявну вкладку для того самого URL Meet перед відкриттям нової. +- Немає аудіо: у Meet спрямовуйте мікрофон і динамік через шлях віртуального аудіопристрою, який використовує OpenClaw; для чистого дуплексного аудіо використовуйте окремі віртуальні пристрої або маршрутизацію на кшталт Loopback. ## Примітки щодо встановлення -Типовий режим Chrome realtime використовує два зовнішні інструменти: +Типовий режим реального часу для Chrome використовує два зовнішні інструменти: -- `sox`: утиліта командного рядка для аудіо. Плагін використовує її команди `rec` і `play` для типового аудіомосту G.711 mu-law 8 кГц. -- `blackhole-2ch`: віртуальний аудіодрайвер macOS. Він створює аудіопристрій `BlackHole 2ch`, через який Chrome/Meet можуть маршрутизувати аудіо. +- `sox`: утиліта командного рядка для роботи з аудіо. Plugin використовує її команди `rec` і `play` для типового аудіомоста G.711 mu-law 8 кГц. +- `blackhole-2ch`: віртуальний аудіодрайвер macOS. Він створює аудіопристрій `BlackHole 2ch`, через який можна маршрутизувати Chrome/Meet. -OpenClaw не включає й не розповсюджує жоден із цих пакетів. У документації користувачам пропонується встановлювати їх як залежності хоста через Homebrew. SoX ліцензовано як `LGPL-2.0-only AND GPL-2.0-only`; BlackHole має ліцензію GPL-3.0. Якщо ви збираєте інсталятор або appliance, що включає BlackHole разом з OpenClaw, перегляньте умови вихідної ліцензії BlackHole або отримайте окрему ліцензію від Existential Audio. +OpenClaw не постачає й не розповсюджує жоден із цих пакетів. У документації користувачам пропонується встановлювати їх як залежності хоста через Homebrew. SoX ліцензовано як `LGPL-2.0-only AND GPL-2.0-only`; BlackHole — GPL-3.0. Якщо ви збираєте інсталятор або appliance, що постачає BlackHole разом з OpenClaw, перегляньте умови ліцензування BlackHole в джерелі або отримайте окрему ліцензію від Existential Audio. ## Транспорти ### Chrome -Транспорт Chrome відкриває URL Meet у Google Chrome і приєднується як профіль Chrome, у якому виконано вхід. На macOS плагін перед запуском перевіряє наявність `BlackHole 2ch`. -Якщо налаштовано, він також запускає команду перевірки стану аудіомосту та команду запуску перед відкриттям Chrome. Використовуйте `chrome`, коли Chrome/аудіо працюють на хості Gateway; використовуйте `chrome-node`, коли Chrome/аудіо працюють на під’єднаному вузлі, наприклад у macOS VM Parallels. +Транспорт Chrome відкриває URL Meet у Google Chrome і приєднується як профіль Chrome, у якому виконано вхід. У macOS Plugin перед запуском перевіряє наявність `BlackHole 2ch`. Якщо налаштовано, він також запускає команду перевірки стану аудіомоста та команду запуску перед відкриттям Chrome. Використовуйте `chrome`, коли Chrome/аудіо працюють на хості Gateway; використовуйте `chrome-node`, коли Chrome/аудіо працюють на підключеному Node, наприклад у macOS VM Parallels. ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome-node ``` -Спрямуйте аудіо мікрофона та динаміка Chrome через локальний аудіоміст OpenClaw. Якщо `BlackHole 2ch` не встановлено, приєднання завершується помилкою налаштування замість тихого приєднання без аудіошляху. +Спрямуйте аудіо мікрофона та динаміка Chrome через локальний аудіоміст OpenClaw. Якщо `BlackHole 2ch` не встановлено, приєднання завершиться помилкою налаштування замість тихого приєднання без аудіошляху. ### Twilio -Транспорт Twilio — це строгий план набору, делегований плагіну Voice Call. Він не аналізує сторінки Meet, щоб витягти телефонні номери. +Транспорт Twilio — це строгий план набору, делегований Plugin Voice Call. Він не аналізує сторінки Meet у пошуку телефонних номерів. -Використовуйте це, коли участь через Chrome недоступна або коли вам потрібен резервний варіант із телефонним дозвоном. Google Meet має показувати номер для телефонного дозвону та PIN для зустрічі; OpenClaw не визначає їх зі сторінки Meet. +Використовуйте це, коли участь через Chrome недоступна або коли вам потрібен резервний варіант через телефонний дозвін. Google Meet має надавати номер для телефонного підключення та PIN для зустрічі; OpenClaw не виявляє їх зі сторінки Meet. -Увімкніть плагін Voice Call на хості Gateway, а не на вузлі Chrome: +Увімкніть Plugin Voice Call на хості Gateway, а не на Node із Chrome: ```json5 { @@ -289,7 +294,7 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij --transport chrome enabled: true, config: { defaultTransport: "chrome-node", - // або встановіть "twilio", якщо Twilio має бути типовим + // or set "twilio" if Twilio should be the default }, }, "voice-call": { @@ -311,7 +316,7 @@ export TWILIO_AUTH_TOKEN=... export TWILIO_FROM_NUMBER=+15550001234 ``` -Перезапустіть або перезавантажте Gateway після ввімкнення `voice-call`; зміни конфігурації плагіна не з’являються в уже запущеному процесі Gateway, доки він не буде перезавантажений. +Перезапустіть або перезавантажте Gateway після ввімкнення `voice-call`; зміни конфігурації Plugin не з’являються у вже запущеному процесі Gateway, доки він не буде перезавантажений. Потім перевірте: @@ -321,7 +326,7 @@ openclaw plugins list | grep -E 'google-meet|voice-call' openclaw googlemeet setup ``` -Коли делегування Twilio налаштоване, `googlemeet setup` містить успішні перевірки `twilio-voice-call-plugin` і `twilio-voice-call-credentials`. +Коли делегування Twilio підключено, `googlemeet setup` містить успішні перевірки `twilio-voice-call-plugin` і `twilio-voice-call-credentials`. ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -330,7 +335,7 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --pin 123456 ``` -Використовуйте `--dtmf-sequence`, коли зустріч потребує власної послідовності: +Використовуйте `--dtmf-sequence`, коли зустріч потребує спеціальної послідовності: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -341,23 +346,21 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ ## OAuth і попередня перевірка -Доступ до Google Meet Media API спочатку використовує особистий OAuth-клієнт. Налаштуйте -`oauth.clientId` і за потреби `oauth.clientSecret`, а потім виконайте: +OAuth є необов’язковим для створення посилання Meet, оскільки `googlemeet create` може перейти до резервного варіанта з автоматизацією браузера. Налаштуйте OAuth, якщо вам потрібні офіційне створення через API, розв’язання простору або перевірки перед запуском через Meet Media API. + +Доступ до API Google Meet спочатку використовує персональний OAuth client. Налаштуйте `oauth.clientId` і, за потреби, `oauth.clientSecret`, а потім виконайте: ```bash openclaw googlemeet auth login --json ``` -Команда виводить блок конфігурації `oauth` з refresh token. Вона використовує PKCE, -локальний callback на `http://localhost:8085/oauth2callback` і ручний -потік копіювання/вставлення з `--manual`. +Команда виводить блок конфігурації `oauth` із токеном оновлення. Вона використовує PKCE, локальний callback на `http://localhost:8085/oauth2callback` і ручний сценарій копіювання/вставлення з `--manual`. -Згода OAuth включає створення просторів Meet, доступ на читання просторів Meet і -доступ на читання медіаданих конференцій Meet. Якщо ви пройшли автентифікацію до того, як з’явилася -підтримка створення зустрічей, повторно виконайте `openclaw googlemeet auth login --json`, щоб -refresh token мав область доступу `meetings.space.created`. +Згода OAuth включає створення просторів Meet, доступ на читання простору Meet і доступ на читання медіаданих конференції Meet. Якщо ви проходили автентифікацію до появи підтримки створення зустрічей, повторно виконайте `openclaw googlemeet auth login --json`, щоб токен оновлення мав область дії `meetings.space.created`. -Ці змінні середовища приймаються як резервні варіанти: +Для резервного варіанта через браузер облікові дані OAuth не потрібні. У цьому режимі автентифікація Google походить із профілю Chrome із виконаним входом на вибраному Node, а не з конфігурації OpenClaw. + +Як резервні варіанти приймаються такі змінні середовища: - `OPENCLAW_GOOGLE_MEET_CLIENT_ID` або `GOOGLE_MEET_CLIENT_ID` - `OPENCLAW_GOOGLE_MEET_CLIENT_SECRET` або `GOOGLE_MEET_CLIENT_SECRET` @@ -374,46 +377,63 @@ refresh token мав область доступу `meetings.space.created`. openclaw googlemeet resolve-space --meeting https://meet.google.com/abc-defg-hij ``` -Виконайте попередню перевірку перед роботою з медіа: +Запустіть попередню перевірку перед роботою з медіаданими: ```bash openclaw googlemeet preflight --meeting https://meet.google.com/abc-defg-hij ``` -Створіть новий простір Meet з тією самою конфігурацією OAuth: +Створіть новий простір Meet: ```bash openclaw googlemeet create ``` -Команда виводить нові `meeting uri` і `space`. Агенти можуть використовувати -інструмент `google_meet` з `action: "create"` для створення зустрічі, а потім викликати -`action: "join"` з поверненим `meetingUri`. +Команда виводить новий `meeting uri` і джерело. За наявності облікових даних OAuth вона використовує офіційний API Google Meet. Без облікових даних OAuth вона використовує профіль браузера із виконаним входом на закріпленому Chrome Node як резервний варіант. Агенти можуть використовувати інструмент `google_meet` з `action: "create"` для створення зустрічі, а потім викликати `action: "join"` з поверненим `meetingUri`. -Створення простору Meet створює лише URL зустрічі. Транспорт Chrome або Chrome-node -усе одно потребує профілю Google Chrome з виконаним входом, щоб приєднатися через -браузер. Якщо в профілі виконано вихід, OpenClaw повідомляє -`manualActionRequired: true` і просить оператора завершити вхід у Google перед -повторною спробою приєднання. +Приклад виводу JSON із резервного варіанта через браузер: -Установлюйте `preview.enrollmentAcknowledged: true` лише після підтвердження, що ваш Cloud -project, OAuth principal і учасники зустрічі зареєстровані в програмі -Google Workspace Developer Preview Program для медіа-API Meet. +```json +{ + "source": "browser", + "meetingUri": "https://meet.google.com/abc-defg-hij", + "browser": { + "nodeId": "ba0f4e4bc...", + "targetId": "tab-1" + } +} +``` + +Приклад виводу JSON зі створення через API: + +```json +{ + "source": "api", + "meetingUri": "https://meet.google.com/abc-defg-hij", + "space": { + "name": "spaces/abc-defg-hij", + "meetingCode": "abc-defg-hij", + "meetingUri": "https://meet.google.com/abc-defg-hij" + } +} +``` + +Створення Meet лише створює або виявляє URL зустрічі. Транспорт Chrome або Chrome-node усе ще потребує профілю Google Chrome із виконаним входом, щоб приєднатися через браузер. Якщо в профілі виконано вихід, OpenClaw повідомляє `manualActionRequired: true` або помилку резервного варіанта через браузер і просить оператора завершити вхід у Google перед повторною спробою. + +Установлюйте `preview.enrollmentAcknowledged: true` лише після підтвердження, що ваш проєкт Cloud, OAuth principal і учасники зустрічі зареєстровані в Google Workspace Developer Preview Program для медіа-API Meet. ## Конфігурація -Звичайному шляху Chrome realtime потрібні лише ввімкнений плагін, BlackHole, SoX -і ключ постачальника голосу реального часу для бекенду. Типовим є OpenAI; установіть -`realtime.provider: "google"`, щоб використовувати Google Gemini Live: +Для поширеного шляху Chrome у режимі реального часу потрібні лише ввімкнений Plugin, BlackHole, SoX і ключ бекенд-провайдера голосу в режимі реального часу. OpenAI використовується за замовчуванням; установіть `realtime.provider: "google"`, щоб використовувати Google Gemini Live: ```bash brew install blackhole-2ch sox export OPENAI_API_KEY=sk-... -# або +# or export GEMINI_API_KEY=... ``` -Установіть конфігурацію плагіна в `plugins.entries.google-meet.config`: +Установіть конфігурацію Plugin у `plugins.entries.google-meet.config`: ```json5 { @@ -432,26 +452,18 @@ export GEMINI_API_KEY=... - `defaultTransport: "chrome"` - `defaultMode: "realtime"` -- `chromeNode.node`: необов’язковий id/ім’я/IP вузла для `chrome-node` +- `chromeNode.node`: необов’язковий id/ім’я/IP Node для `chrome-node` - `chrome.audioBackend: "blackhole-2ch"` -- `chrome.guestName: "OpenClaw Agent"`: ім’я, яке використовується на екрані - гостя Meet без входу -- `chrome.autoJoin: true`: заповнення імені гостя та натискання Join Now у - режимі best-effort через автоматизацію браузера OpenClaw на `chrome-node` -- `chrome.reuseExistingTab: true`: активувати наявну вкладку Meet замість - відкриття дублікатів -- `chrome.waitForInCallMs: 20000`: чекати, доки вкладка Meet не повідомить про стан in-call, - перш ніж буде запущено вступ у режимі реального часу -- `chrome.audioInputCommand`: команда SoX `rec`, що записує аудіо G.711 mu-law 8 кГц - у stdout -- `chrome.audioOutputCommand`: команда SoX `play`, що читає аудіо G.711 mu-law 8 кГц - із stdin +- `chrome.guestName: "OpenClaw Agent"`: ім’я, яке використовується на екрані гостя Meet без входу +- `chrome.autoJoin: true`: найкраща можлива спроба заповнення імені гостя й натискання Join Now через автоматизацію браузера OpenClaw на `chrome-node` +- `chrome.reuseExistingTab: true`: активувати наявну вкладку Meet замість відкриття дублікатів +- `chrome.waitForInCallMs: 20000`: чекати, доки вкладка Meet не повідомить про вхід у виклик, перш ніж буде запущено вступ у режимі реального часу +- `chrome.audioInputCommand`: команда SoX `rec`, яка записує аудіо G.711 mu-law 8 кГц у stdout +- `chrome.audioOutputCommand`: команда SoX `play`, яка читає аудіо G.711 mu-law 8 кГц зі stdin - `realtime.provider: "openai"` - `realtime.toolPolicy: "safe-read-only"` -- `realtime.instructions`: короткі усні відповіді, з - `openclaw_agent_consult` для глибших відповідей -- `realtime.introMessage`: коротка усна перевірка готовності, коли міст - реального часу підключається; установіть `""`, щоб приєднуватися беззвучно +- `realtime.instructions`: короткі усні відповіді, з `openclaw_agent_consult` для глибших відповідей +- `realtime.introMessage`: коротка усна перевірка готовності, коли підключається міст режиму реального часу; установіть `""`, щоб приєднуватися беззвучно Необов’язкові перевизначення: @@ -471,7 +483,7 @@ export GEMINI_API_KEY=... realtime: { provider: "google", toolPolicy: "owner", - introMessage: "Скажи рівно: I'm here.", + introMessage: "Say exactly: I'm here.", providers: { google: { model: "gemini-2.5-flash-native-audio-preview-12-2025", @@ -497,10 +509,7 @@ export GEMINI_API_KEY=... } ``` -`voiceCall.enabled` типово має значення `true`; з транспортом Twilio він делегує -фактичний PSTN-виклик і DTMF плагіну Voice Call. Якщо `voice-call` не -ввімкнено, Google Meet усе одно може перевірити й записати план набору, але не може -виконати виклик Twilio. +`voiceCall.enabled` за замовчуванням має значення `true`; із транспортом Twilio він делегує фактичний виклик PSTN і DTMF Plugin `Voice Call`. Якщо `voice-call` не ввімкнено, Google Meet усе ще може перевіряти й записувати план набору, але не може виконати виклик Twilio. ## Інструмент @@ -515,59 +524,39 @@ export GEMINI_API_KEY=... } ``` -Використовуйте `transport: "chrome"`, коли Chrome працює на хості Gateway. Використовуйте -`transport: "chrome-node"`, коли Chrome працює на під’єднаному вузлі, наприклад у Parallels -VM. В обох випадках модель реального часу та `openclaw_agent_consult` працюють на -хості Gateway, тому облікові дані моделі залишаються там. +Використовуйте `transport: "chrome"`, коли Chrome працює на хості Gateway. Використовуйте `transport: "chrome-node"`, коли Chrome працює на підключеному Node, наприклад у Parallels VM. В обох випадках модель режиму реального часу та `openclaw_agent_consult` працюють на хості Gateway, тож облікові дані моделі залишаються там. -Використовуйте `action: "status"`, щоб перелічити активні сеанси або перевірити ID сеансу. Використовуйте -`action: "speak"` із `sessionId` і `message`, щоб змусити агента реального часу -говорити негайно. Використовуйте `action: "test_speech"`, щоб створити або повторно використати сеанс, -запустити відому фразу й повернути стан `inCall`, якщо хост Chrome може -його повідомити. Використовуйте `action: "leave"`, щоб позначити сеанс завершеним. +Використовуйте `action: "status"`, щоб перелічити активні сесії або перевірити id сесії. Використовуйте `action: "speak"` із `sessionId` і `message`, щоб агент режиму реального часу негайно заговорив. Використовуйте `action: "test_speech"`, щоб створити або повторно використати сесію, запустити відому фразу й повернути стан `inCall`, коли хост Chrome може про нього повідомити. Використовуйте `action: "leave"`, щоб позначити завершення сесії. -`status` включає стан Chrome, коли він доступний: +`status` містить стан Chrome, коли він доступний: -- `inCall`: Chrome, імовірно, перебуває всередині виклику Meet -- `micMuted`: best-effort стан мікрофона Meet -- `manualActionRequired` / `manualActionReason` / `manualActionMessage`: профіль - браузера потребує ручного входу, допуску хостом Meet, дозволів або - виправлення керування браузером, перш ніж мовлення зможе працювати -- `providerConnected` / `realtimeReady`: стан голосового мосту реального часу -- `lastInputAt` / `lastOutputAt`: час останнього аудіо, отриманого від мосту або надісланого до нього +- `inCall`: схоже, що Chrome перебуває всередині виклику Meet +- `micMuted`: найкраща можлива оцінка стану мікрофона Meet +- `manualActionRequired` / `manualActionReason` / `manualActionMessage`: профіль браузера потребує ручного входу, допуску організатора Meet, дозволів або відновлення керування браузером, перш ніж мовлення зможе працювати +- `providerConnected` / `realtimeReady`: стан голосового моста режиму реального часу +- `lastInputAt` / `lastOutputAt`: останнє аудіо, отримане мостом або надіслане до нього ```json { "action": "speak", "sessionId": "meet_...", - "message": "Скажи рівно: I'm here and listening." + "message": "Say exactly: I'm here and listening." } ``` -## Консультація агента в режимі реального часу +## Консультація агента режиму реального часу -Режим Chrome realtime оптимізовано для живого голосового циклу. Постачальник -голосу реального часу чує аудіо зустрічі та говорить через налаштований -аудіоміст. Коли моделі реального часу потрібні глибше міркування, актуальна -інформація або звичайні інструменти OpenClaw, вона може викликати `openclaw_agent_consult`. +Режим Chrome у режимі реального часу оптимізовано для живого голосового циклу. Провайдер голосу режиму реального часу чує аудіо зустрічі й говорить через налаштований аудіоміст. Коли моделі режиму реального часу потрібні глибші міркування, актуальна інформація або звичайні інструменти OpenClaw, вона може викликати `openclaw_agent_consult`. -Інструмент консультації у фоновому режимі запускає звичайного агента OpenClaw -із контекстом нещодавньої розшифровки зустрічі й повертає стислу усну відповідь -до голосового сеансу реального часу. Потім голосова модель може озвучити цю -відповідь назад у зустріч. +Інструмент консультації запускає звичайного агента OpenClaw у фоновому режимі з контекстом нещодавньої розшифровки зустрічі та повертає стислу усну відповідь до голосової сесії режиму реального часу. Потім голосова модель може озвучити цю відповідь назад у зустріч. `realtime.toolPolicy` керує запуском консультації: -- `safe-read-only`: показати інструмент консультації та обмежити звичайного агента - інструментами `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і - `memory_get`. -- `owner`: показати інструмент консультації та дозволити звичайному агенту використовувати - звичайну політику інструментів агента. -- `none`: не показувати інструмент консультації моделі голосу реального часу. +- `safe-read-only`: показувати інструмент консультації та обмежувати звичайного агента інструментами `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. +- `owner`: показувати інструмент консультації й дозволяти звичайному агенту використовувати нормальну політику інструментів агента. +- `none`: не показувати інструмент консультації моделі голосу режиму реального часу. -Ключ сеансу консультації має область дії в межах одного сеансу Meet, тому -наступні виклики консультації можуть повторно використовувати попередній контекст -консультації під час тієї самої зустрічі. +Ключ сесії консультації має область дії в межах кожної сесії Meet, тож подальші виклики консультації можуть повторно використовувати попередній контекст консультації під час тієї самої зустрічі. Щоб примусово виконати усну перевірку готовності після того, як Chrome повністю приєднався до виклику: @@ -575,7 +564,7 @@ VM. В обох випадках модель реального часу та ` openclaw googlemeet speak meet_... "Say exactly: I'm here and listening." ``` -Для повного smoke-тесту join-and-speak: +Для повного smoke-тесту приєднання й мовлення: ```bash openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ @@ -585,7 +574,7 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ ## Контрольний список live-тесту -Використовуйте цю послідовність перед передачею зустрічі агенту без нагляду: +Використовуйте цю послідовність перед передаванням зустрічі агенту без нагляду: ```bash openclaw googlemeet setup @@ -598,12 +587,11 @@ openclaw googlemeet test-speech https://meet.google.com/abc-defg-hij \ Очікуваний стан Chrome-node: - `googlemeet setup` повністю зелений. -- `nodes status` показує, що вибраний вузол підключений. -- Вибраний вузол рекламує і `googlemeet.chrome`, і `browser.proxy`. -- Вкладка Meet приєднується до виклику, а `test-speech` повертає стан Chrome з - `inCall: true`. +- `nodes status` показує, що вибраний Node підключено. +- Вибраний Node оголошує і `googlemeet.chrome`, і `browser.proxy`. +- Вкладка Meet приєднується до виклику, а `test-speech` повертає стан Chrome з `inCall: true`. -Для smoke-тесту Twilio використовуйте зустріч, яка показує деталі телефонного дозвону: +Для smoke-тесту Twilio використовуйте зустріч, яка показує дані для телефонного підключення: ```bash openclaw googlemeet setup @@ -615,17 +603,16 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ Очікуваний стан Twilio: -- `googlemeet setup` включає зелені перевірки `twilio-voice-call-plugin` і - `twilio-voice-call-credentials`. +- `googlemeet setup` містить зелені перевірки `twilio-voice-call-plugin` і `twilio-voice-call-credentials`. - `voicecall` доступний у CLI після перезавантаження Gateway. -- Повернений сеанс має `transport: "twilio"` і `twilio.voiceCallId`. +- Повернена сесія має `transport: "twilio"` і `twilio.voiceCallId`. - `googlemeet leave ` завершує делегований голосовий виклик. ## Усунення несправностей ### Агент не бачить інструмент Google Meet -Підтвердьте, що плагін увімкнено в конфігурації Gateway, і перезавантажте Gateway: +Підтвердьте, що Plugin увімкнено в конфігурації Gateway, і перезавантажте Gateway: ```bash openclaw plugins list | grep google-meet @@ -633,11 +620,11 @@ openclaw googlemeet setup ``` Якщо ви щойно відредагували `plugins.entries.google-meet`, перезапустіть або перезавантажте Gateway. -Запущений агент бачить лише інструменти плагінів, зареєстровані поточним процесом Gateway. +Запущений агент бачить лише інструменти Plugin, зареєстровані поточним процесом Gateway. -### Немає підключеного вузла з підтримкою Google Meet +### Немає підключеного Node з підтримкою Google Meet -На хості вузла виконайте: +На хості Node виконайте: ```bash openclaw plugins enable google-meet @@ -646,7 +633,7 @@ OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 \ openclaw node run --host --port 18789 --display-name parallels-macos ``` -На хості Gateway підтвердьте вузол і перевірте команди: +На хості Gateway схваліть Node і перевірте команди: ```bash openclaw devices list @@ -654,8 +641,8 @@ openclaw devices approve openclaw nodes status ``` -Вузол має бути підключений і перелічувати `googlemeet.chrome` та `browser.proxy`. -Конфігурація Gateway має дозволяти ці команди вузла: +Node має бути підключеним і містити `googlemeet.chrome` та `browser.proxy`. +Конфігурація Gateway має дозволяти ці команди Node: ```json5 { @@ -669,58 +656,48 @@ openclaw nodes status ### Браузер відкривається, але агент не може приєднатися -Запустіть `googlemeet test-speech` і перевірте повернений стан Chrome. Якщо він -повідомляє `manualActionRequired: true`, покажіть `manualActionMessage` оператору -та припиніть повторні спроби, доки дію в браузері не буде завершено. +Запустіть `googlemeet test-speech` і перевірте повернутий стан Chrome. Якщо він повідомляє `manualActionRequired: true`, покажіть `manualActionMessage` оператору й припиніть повторні спроби, доки не буде завершено дію в браузері. Поширені ручні дії: -- Увійти в профіль Chrome. -- Допустити гостя з облікового запису хоста Meet. -- Надати Chrome дозволи на мікрофон/камеру. -- Закрити або виправити завислий діалог дозволів Meet. +- Увійдіть у профіль Chrome. +- Допустіть гостя з облікового запису організатора Meet. +- Надайте Chrome дозволи на мікрофон/камеру. +- Закрийте або виправте зависле діалогове вікно дозволів Meet. ### Не вдається створити зустріч -`googlemeet create` використовує endpoint `spaces.create` API Google Meet. Підтвердьте: +`googlemeet create` спочатку використовує endpoint `spaces.create` API Google Meet, коли налаштовано облікові дані OAuth. Без облікових даних OAuth він переходить до резервного варіанта через браузер закріпленого Chrome Node. Переконайтеся в такому: -- налаштовано `oauth.clientId` і `oauth.refreshToken`, або наявні відповідні - змінні середовища `OPENCLAW_GOOGLE_MEET_*`. -- refresh token було створено після додавання підтримки create. Старі токени можуть - не мати області доступу `meetings.space.created`; повторно виконайте - `openclaw googlemeet auth login --json` і оновіть конфігурацію плагіна. -- Google Cloud project і OAuth principal мають право використовувати потрібні - області доступу API Google Meet. +- Для створення через API: налаштовано `oauth.clientId` і `oauth.refreshToken`, або присутні відповідні змінні середовища `OPENCLAW_GOOGLE_MEET_*`. +- Для створення через API: токен оновлення було видано після додавання підтримки створення. Старіші токени можуть не містити область дії `meetings.space.created`; повторно виконайте `openclaw googlemeet auth login --json` і оновіть конфігурацію Plugin. +- Для резервного варіанта через браузер: `defaultTransport: "chrome-node"` і `chromeNode.node` вказують на підключений Node з `browser.proxy` і `googlemeet.chrome`. +- Для резервного варіанта через браузер: профіль OpenClaw Chrome на цьому Node має виконаний вхід у Google і може відкрити `https://meet.google.com/new`. ### Агент приєднується, але не говорить -Перевірте шлях realtime: +Перевірте шлях режиму реального часу: ```bash openclaw googlemeet setup openclaw googlemeet status ``` -Використовуйте `mode: "realtime"` для прослуховування/відповіді голосом. `mode: "transcribe"` навмисно -не запускає двобічний голосовий міст реального часу. +Використовуйте `mode: "realtime"` для прослуховування/зворотного мовлення. `mode: "transcribe"` навмисно не запускає міст дуплексного голосу режиму реального часу. Також перевірте: -- На хості Gateway доступний ключ постачальника режиму реального часу, наприклад - `OPENAI_API_KEY` або `GEMINI_API_KEY`. +- На хості Gateway доступний ключ провайдера режиму реального часу, наприклад `OPENAI_API_KEY` або `GEMINI_API_KEY`. - `BlackHole 2ch` видимий на хості Chrome. - `rec` і `play` існують на хості Chrome. -- Мікрофон і динамік Meet маршрутизовано через віртуальний аудіошлях, який використовує - OpenClaw. +- Мікрофон і динамік Meet спрямовано через шлях віртуального аудіо, який використовує OpenClaw. ### Не проходять перевірки налаштування Twilio -`twilio-voice-call-plugin` завершується помилкою, коли `voice-call` не дозволено або не ввімкнено. -Додайте його до `plugins.allow`, увімкніть `plugins.entries.voice-call` і перезавантажте -Gateway. +`twilio-voice-call-plugin` не проходить, коли `voice-call` не дозволено або не ввімкнено. +Додайте його до `plugins.allow`, увімкніть `plugins.entries.voice-call` і перезавантажте Gateway. -`twilio-voice-call-credentials` завершується помилкою, коли в бекенді Twilio бракує account -SID, auth token або номера абонента. Установіть це на хості Gateway: +`twilio-voice-call-credentials` не проходить, коли в бекенді Twilio відсутні account SID, auth token або номер абонента. Установіть це на хості Gateway: ```bash export TWILIO_ACCOUNT_SID=AC... @@ -736,8 +713,7 @@ openclaw googlemeet setup ### Виклик Twilio починається, але ніколи не входить у зустріч -Підтвердьте, що подія Meet містить деталі телефонного дозвону. Передайте точний номер -для дозвону та PIN або власну послідовність DTMF: +Підтвердьте, що подія Meet показує дані для телефонного підключення. Передайте точний номер для дозвону та PIN або спеціальну послідовність DTMF: ```bash openclaw googlemeet join https://meet.google.com/abc-defg-hij \ @@ -746,34 +722,25 @@ openclaw googlemeet join https://meet.google.com/abc-defg-hij \ --dtmf-sequence ww123456# ``` -Використовуйте початковий `w` або коми в `--dtmf-sequence`, якщо постачальнику потрібна пауза -перед введенням PIN. +Використовуйте початковий `w` або коми в `--dtmf-sequence`, якщо провайдеру потрібна пауза перед введенням PIN. ## Примітки -Офіційний media API Google Meet орієнтований на отримання, тому для мовлення у виклику Meet -усе одно потрібен шлях учасника. Цей плагін робить цю межу видимою: -Chrome відповідає за участь через браузер і локальну маршрутизацію аудіо; Twilio відповідає за -участь через телефонний дозвін. +Офіційний медіа-API Google Meet орієнтований на отримання, тому для мовлення у виклику Meet усе ще потрібен шлях учасника. Цей Plugin зберігає цю межу видимою: +Chrome обробляє участь через браузер і локальну маршрутизацію аудіо; Twilio обробляє участь через телефонний дозвін. -Режиму Chrome realtime потрібне одне з такого: +Режим Chrome у режимі реального часу потребує одного з такого: -- `chrome.audioInputCommand` плюс `chrome.audioOutputCommand`: OpenClaw керує - мостом моделі реального часу та передає аудіо G.711 mu-law 8 кГц між цими - командами й вибраним постачальником голосу реального часу. -- `chrome.audioBridgeCommand`: зовнішня команда мосту керує всім локальним - аудіошляхом і має завершитися після запуску або перевірки свого демона. +- `chrome.audioInputCommand` плюс `chrome.audioOutputCommand`: OpenClaw керує мостом моделі режиму реального часу та передає аудіо G.711 mu-law 8 кГц між цими командами та вибраним провайдером голосу режиму реального часу. +- `chrome.audioBridgeCommand`: зовнішня команда моста керує всім локальним аудіошляхом і має завершитися після запуску або перевірки свого daemon. -Для чистого двобічного аудіо маршрутизуйте вихід Meet і мікрофон Meet через окремі -віртуальні пристрої або граф віртуальних пристроїв у стилі Loopback. Один спільний -пристрій BlackHole може повертати в дзвінок відлуння інших учасників. +Для чистого дуплексного аудіо маршрутизуйте вихід Meet і мікрофон Meet через окремі віртуальні пристрої або граф віртуальних пристроїв на кшталт Loopback. Один спільний пристрій BlackHole може повертати голоси інших учасників назад у виклик. -`googlemeet speak` запускає активний аудіоміст реального часу для сеансу -Chrome. `googlemeet leave` зупиняє цей міст. Для сеансів Twilio, делегованих -через плагін Voice Call, `leave` також завершує базовий голосовий виклик. +`googlemeet speak` запускає активний аудіоміст режиму реального часу для сесії Chrome. +`googlemeet leave` зупиняє цей міст. Для сесій Twilio, делегованих через Plugin Voice Call, `leave` також завершує базовий голосовий виклик. ## Пов’язане -- [Плагін Voice Call](/uk/plugins/voice-call) -- [Режим розмови](/uk/nodes/talk) -- [Створення плагінів](/uk/plugins/building-plugins) +- [Plugin Voice Call](/uk/plugins/voice-call) +- [Режим talk](/uk/nodes/talk) +- [Створення Plugin](/uk/plugins/building-plugins) diff --git a/docs/uk/plugins/voice-call.md b/docs/uk/plugins/voice-call.md index b7d5f9bde..00b0ba500 100644 --- a/docs/uk/plugins/voice-call.md +++ b/docs/uk/plugins/voice-call.md @@ -2,41 +2,41 @@ read_when: - Ви хочете здійснити вихідний голосовий дзвінок з OpenClaw - Ви налаштовуєте або розробляєте плагін voice-call -summary: 'Плагін Voice Call: вихідні + вхідні дзвінки через Twilio/Telnyx/Plivo (встановлення плагіна + конфігурація + CLI)' +summary: 'Плагін Voice Call: вихідні + вхідні дзвінки через Twilio/Telnyx/Plivo (встановлення Plugin + конфігурація + CLI)' title: Плагін Voice call x-i18n: - generated_at: "2026-04-24T09:19:22Z" + generated_at: "2026-04-24T21:43:34Z" model: gpt-5.4 provider: openai - source_hash: 6aed4e33ce090c86f43c71280f033e446f335c53d42456fdc93c9938250e9af6 + source_hash: a6d03153cf6ba1b4cd7cf2e4c0ffcdf96595363473b172b2d4b21b4100c20e3c source_path: plugins/voice-call.md workflow: 15 --- # Voice Call (плагін) -Голосові дзвінки для OpenClaw через плагін. Підтримує вихідні сповіщення та -багатоходові розмови з політиками для вхідних викликів. +Голосові дзвінки для OpenClaw через Plugin. Підтримує вихідні сповіщення та +багатокрокові розмови з вхідними політиками. Поточні провайдери: - `twilio` (Programmable Voice + Media Streams) - `telnyx` (Call Control v2) - `plivo` (Voice API + XML transfer + GetInput speech) -- `mock` (dev/без мережі) +- `mock` (розробка/без мережі) -Коротка ментальна модель: +Швидка ментальна модель: -- Встановіть плагін +- Встановіть Plugin - Перезапустіть Gateway - Налаштуйте в `plugins.entries.voice-call.config` - Використовуйте `openclaw voicecall ...` або інструмент `voice_call` ## Де це працює (локально чи віддалено) -Плагін Voice Call працює **всередині процесу Gateway**. +Plugin Voice Call працює **всередині процесу Gateway**. -Якщо ви використовуєте віддалений Gateway, встановіть/налаштуйте плагін на **машині, де запущено Gateway**, а потім перезапустіть Gateway, щоб завантажити його. +Якщо ви використовуєте віддалений Gateway, встановіть/налаштуйте Plugin на **машині, де запущено Gateway**, а потім перезапустіть Gateway, щоб він його завантажив. ## Встановлення @@ -48,7 +48,7 @@ openclaw plugins install @openclaw/voice-call Після цього перезапустіть Gateway. -### Варіант B: встановлення з локальної папки (dev, без копіювання) +### Варіант B: встановлення з локальної папки (розробка, без копіювання) ```bash PLUGIN_SRC=./path/to/local/voice-call-plugin @@ -81,7 +81,7 @@ cd "$PLUGIN_SRC" && pnpm install telnyx: { apiKey: "...", connectionId: "...", - // Публічний ключ Webhook Telnyx з Telnyx Mission Control Portal + // Публічний ключ webhook Telnyx з Telnyx Mission Control Portal // (рядок Base64; також можна задати через TELNYX_PUBLIC_KEY). publicKey: "...", }, @@ -103,7 +103,7 @@ cd "$PLUGIN_SRC" && pnpm install trustedProxyIPs: ["100.64.0.1"], }, - // Публічна експозиція (виберіть один варіант) + // Публічне відкриття доступу (оберіть один варіант) // publicUrl: "https://example.ngrok.app/voice/webhook", // tunnel: { provider: "ngrok" }, // tailscale: { mode: "funnel", path: "/voice/webhook" } @@ -114,7 +114,7 @@ cd "$PLUGIN_SRC" && pnpm install streaming: { enabled: true, - provider: "openai", // необов’язково; якщо не вказано, використовується перший зареєстрований провайдер транскрипції в реальному часі + provider: "openai", // необов’язково; якщо не задано — перший зареєстрований провайдер транскрипції в реальному часі streamPath: "/voice/stream", providers: { openai: { @@ -132,7 +132,7 @@ cd "$PLUGIN_SRC" && pnpm install realtime: { enabled: false, - provider: "google", // необов’язково; якщо не вказано, використовується перший зареєстрований голосовий провайдер у реальному часі + provider: "google", // необов’язково; якщо не задано — перший зареєстрований голосовий провайдер у реальному часі providers: { google: { model: "gemini-2.5-flash-native-audio-preview-12-2025", @@ -149,26 +149,26 @@ cd "$PLUGIN_SRC" && pnpm install Примітки: -- Twilio/Telnyx вимагають **публічно доступний** URL Webhook. -- Plivo вимагає **публічно доступний** URL Webhook. -- `mock` — це локальний dev-провайдер (без мережевих викликів). -- Якщо старі конфігурації досі використовують `provider: "log"`, `twilio.from` або застарілі ключі `streaming.*` для OpenAI, виконайте `openclaw doctor --fix`, щоб переписати їх. -- Для Telnyx потрібен `telnyx.publicKey` (або `TELNYX_PUBLIC_KEY`), якщо тільки `skipSignatureVerification` не має значення true. -- `skipSignatureVerification` призначений лише для локального тестування. -- Якщо ви використовуєте безкоштовний рівень ngrok, задайте `publicUrl` як точний URL ngrok; перевірка підпису завжди примусово увімкнена. -- `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє Webhook-и Twilio з невалідними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` є loopback (локальний агент ngrok). Використовуйте лише для локальної розробки. -- URL-адреси безкоштовного рівня Ngrok можуть змінюватися або додавати проміжну поведінку; якщо `publicUrl` зміниться, підписи Twilio не пройдуть перевірку. Для production віддавайте перевагу стабільному домену або Tailscale funnel. -- `realtime.enabled` запускає повноцінні голосові розмови голос-до-голосу; не вмикайте його разом із `streaming.enabled`. -- Типові параметри безпеки streaming: - - `streaming.preStartTimeoutMs` закриває сокети, які так і не надсилають валідний кадр `start`. +- Twilio/Telnyx потребують **публічно доступного** URL Webhook. +- Plivo потребує **публічно доступного** URL Webhook. +- `mock` — це локальний провайдер для розробки (без мережевих викликів). +- Якщо в старіших конфігураціях усе ще використовується `provider: "log"`, `twilio.from` або застарілі ключі OpenAI `streaming.*`, виконайте `openclaw doctor --fix`, щоб переписати їх. +- Telnyx потребує `telnyx.publicKey` (або `TELNYX_PUBLIC_KEY`), якщо тільки `skipSignatureVerification` не має значення true. +- `skipSignatureVerification` — лише для локального тестування. +- Якщо ви використовуєте безкоштовний рівень ngrok, задайте `publicUrl` точно як URL ngrok; перевірка підпису завжди примусово увімкнена. +- `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє webhook-и Twilio з недійсними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` — це local loopback (локальний агент ngrok). Використовуйте лише для локальної розробки. +- URL-адреси ngrok на безкоштовному рівні можуть змінюватися або додавати проміжну поведінку; якщо `publicUrl` зміниться, підписи Twilio не проходитимуть перевірку. Для продакшну надавайте перевагу стабільному домену або Tailscale funnel. +- `realtime.enabled` запускає повноцінні голосові розмови voice-to-voice; не вмикайте його разом із `streaming.enabled`. +- Типові налаштування безпеки для streaming: + - `streaming.preStartTimeoutMs` закриває сокети, які так і не надсилають коректний кадр `start`. - `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих сокетів до старту. -- `streaming.maxPendingConnectionsPerIp` обмежує кількість неавтентифікованих сокетів до старту з однієї IP-адреси джерела. -- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікувальні + активні). -- Під час виконання fallback наразі все ще приймає ці старі ключі voice-call, але шлях переписування — це `openclaw doctor --fix`, а шар сумісності є тимчасовим. +- `streaming.maxPendingConnectionsPerIp` обмежує кількість неавтентифікованих сокетів до старту для кожної вихідної IP-адреси. +- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоку (очікування + активні). +- На рівні виконання резервна сумісність поки що все ще приймає ці старі ключі voice-call, але шлях переписування — це `openclaw doctor --fix`, а шар сумісності є тимчасовим. ## Голосові розмови в реальному часі -`realtime` вибирає повнодуплексного голосового провайдера в реальному часі для аудіо живого дзвінка. +`realtime` вибирає повнодуплексного голосового провайдера реального часу для аудіо дзвінка вживу. Він відокремлений від `streaming`, який лише пересилає аудіо провайдерам транскрипції в реальному часі. @@ -176,18 +176,18 @@ cd "$PLUGIN_SRC" && pnpm install - `realtime.enabled` підтримується для Twilio Media Streams. - `realtime.enabled` не можна поєднувати з `streaming.enabled`. -- `realtime.provider` є необов’язковим. Якщо не вказано, Voice Call використовує першого - зареєстрованого голосового провайдера в реальному часі. -- Вбудовані голосові провайдери в реальному часі включають Google Gemini Live (`google`) та - OpenAI (`openai`), зареєстровані їхніми плагінами провайдерів. -- Сирий конфіг, що належить провайдеру, розташовано в `realtime.providers.`. -- Якщо `realtime.provider` вказує на незареєстрованого провайдера або якщо жодного голосового - провайдера в реальному часі взагалі не зареєстровано, Voice Call записує попередження в лог і пропускає - медіа в реальному часі замість того, щоб ламати весь плагін. +- `realtime.provider` — необов’язковий. Якщо не задано, Voice Call використовує першого + зареєстрованого голосового провайдера реального часу. +- Вбудовані голосові провайдери реального часу включають Google Gemini Live (`google`) і + OpenAI (`openai`), зареєстровані їхніми Plugin провайдерів. +- Власна сира конфігурація провайдера розміщується в `realtime.providers.`. +- Якщо `realtime.provider` вказує на незареєстрованого провайдера або взагалі не зареєстровано + жодного голосового провайдера реального часу, Voice Call записує попередження в журнал і пропускає + медіа реального часу замість того, щоб зламати весь Plugin. -Типові значення Google Gemini Live realtime: +Типові значення для realtime Google Gemini Live: -- API key: `realtime.providers.google.apiKey`, `GEMINI_API_KEY` або +- API-ключ: `realtime.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_GENERATIVE_AI_API_KEY` - model: `gemini-2.5-flash-native-audio-preview-12-2025` - voice: `Kore` @@ -206,7 +206,7 @@ cd "$PLUGIN_SRC" && pnpm install realtime: { enabled: true, provider: "google", - instructions: "Говоріть коротко й запитуйте перед використанням інструментів.", + instructions: "Говоріть коротко і питайте перед використанням інструментів.", providers: { google: { apiKey: "${GEMINI_API_KEY}", @@ -222,7 +222,7 @@ cd "$PLUGIN_SRC" && pnpm install } ``` -Використовуйте OpenAI натомість: +Натомість використайте OpenAI: ```json5 { @@ -246,35 +246,35 @@ cd "$PLUGIN_SRC" && pnpm install } ``` -Див. [провайдер Google](/uk/providers/google) і [провайдер OpenAI](/uk/providers/openai) -для параметрів голосу в реальному часі, специфічних для провайдера. +Див. [Google provider](/uk/providers/google) і [OpenAI provider](/uk/providers/openai) +для специфічних для провайдерів параметрів голосу в реальному часі. -## Streaming транскрипції +## Транскрипція потокового аудіо -`streaming` вибирає провайдера транскрипції в реальному часі для аудіо живого дзвінка. +`streaming` вибирає провайдера транскрипції в реальному часі для аудіо дзвінка вживу. Поточна поведінка під час виконання: -- `streaming.provider` є необов’язковим. Якщо не вказано, Voice Call використовує першого +- `streaming.provider` — необов’язковий. Якщо не задано, Voice Call використовує першого зареєстрованого провайдера транскрипції в реальному часі. - Вбудовані провайдери транскрипції в реальному часі включають Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) і xAI - (`xai`), зареєстровані їхніми плагінами провайдерів. -- Сирий конфіг, що належить провайдеру, розташовано в `streaming.providers.`. -- Якщо `streaming.provider` вказує на незареєстрованого провайдера або якщо жодного провайдера - транскрипції в реальному часі взагалі не зареєстровано, Voice Call записує попередження в лог і - пропускає streaming медіа замість того, щоб ламати весь плагін. + (`xai`), зареєстровані їхніми Plugin провайдерів. +- Власна сира конфігурація провайдера розміщується в `streaming.providers.`. +- Якщо `streaming.provider` вказує на незареєстрованого провайдера або якщо взагалі не зареєстровано + жодного провайдера транскрипції в реальному часі, Voice Call записує попередження в журнал і + пропускає потокову передачу медіа замість того, щоб зламати весь Plugin. -Типові значення транскрипції streaming OpenAI: +Типові значення для потокової транскрипції OpenAI: -- API key: `streaming.providers.openai.apiKey` або `OPENAI_API_KEY` +- API-ключ: `streaming.providers.openai.apiKey` або `OPENAI_API_KEY` - model: `gpt-4o-transcribe` - `silenceDurationMs`: `800` - `vadThreshold`: `0.5` -Типові значення транскрипції streaming xAI: +Типові значення для потокової транскрипції xAI: -- API key: `streaming.providers.xai.apiKey` або `XAI_API_KEY` +- API-ключ: `streaming.providers.xai.apiKey` або `XAI_API_KEY` - endpoint: `wss://api.x.ai/v1/stt` - `encoding`: `mulaw` - `sampleRate`: `8000` @@ -309,7 +309,7 @@ cd "$PLUGIN_SRC" && pnpm install } ``` -Використовуйте xAI натомість: +Натомість використайте xAI: ```json5 { @@ -344,17 +344,17 @@ cd "$PLUGIN_SRC" && pnpm install - `streaming.silenceDurationMs` → `streaming.providers.openai.silenceDurationMs` - `streaming.vadThreshold` → `streaming.providers.openai.vadThreshold` -## Очищувач застарілих викликів +## Очищення застарілих дзвінків -Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують фінального Webhook -(наприклад, виклики в режимі notify, які ніколи не завершуються). Типове значення — `0` +Використовуйте `staleCallReaperSeconds`, щоб завершувати дзвінки, які ніколи не отримують фінальний webhook +(наприклад, дзвінки в режимі notify, які так і не завершуються). Типове значення — `0` (вимкнено). Рекомендовані діапазони: -- **Production:** `120`–`300` секунд для потоків у стилі notify. -- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні виклики могли - завершитися. Гарна стартова точка — `maxDurationSeconds + 30–60` секунд. +- **Продакшн:** `120`–`300` секунд для сценаріїв у стилі notify. +- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні дзвінки могли + завершитися. Хороша стартова точка — `maxDurationSeconds + 30–60` секунд. Приклад: @@ -375,28 +375,28 @@ cd "$PLUGIN_SRC" && pnpm install ## Безпека Webhook -Коли перед Gateway стоїть проксі або тунель, плагін реконструює -публічний URL для перевірки підпису. Ці параметри керують тим, яким forwarded +Коли перед Gateway знаходиться проксі або тунель, Plugin відновлює +публічний URL для перевірки підпису. Ці параметри визначають, яким переспрямованим заголовкам довіряти. -`webhookSecurity.allowedHosts` задає allowlist хостів із forwarding-заголовків. +`webhookSecurity.allowedHosts` задає список дозволених хостів із переспрямованих заголовків. -`webhookSecurity.trustForwardingHeaders` довіряє forwarded-заголовкам без allowlist. +`webhookSecurity.trustForwardingHeaders` довіряє переспрямованим заголовкам без списку дозволених. -`webhookSecurity.trustedProxyIPs` довіряє forwarded-заголовкам лише тоді, коли +`webhookSecurity.trustedProxyIPs` довіряє переспрямованим заголовкам лише тоді, коли віддалена IP-адреса запиту збігається зі списком. -Захист від повторного відтворення Webhook увімкнено для Twilio та Plivo. Повторно відтворені валідні запити Webhook -підтверджуються, але пропускаються з погляду побічних ефектів. +Захист від повторного відтворення webhook увімкнено для Twilio і Plivo. Повторно відтворені коректні webhook- +запити підтверджуються, але їхні побічні ефекти пропускаються. -Ходи розмов Twilio включають токен на кожен хід у callback-ах ``, тому -застарілі/повторно відтворені callback-и мовлення не можуть задовольнити новіший очікуваний хід транскрипту. +Кроки розмови Twilio включають токен для кожного кроку в зворотних викликах ``, тому +застарілі/повторно відтворені зворотні виклики мовлення не можуть задовольнити новіший очікуваний крок транскрипції. -Неавтентифіковані запити Webhook відхиляються до читання тіла, якщо відсутні +Неавтентифіковані webhook-запити відхиляються ще до читання тіла, якщо відсутні обов’язкові заголовки підпису провайдера. -Webhook voice-call використовує спільний профіль тіла до автентифікації (64 KB / 5 секунд) -плюс обмеження кількості одночасних запитів на IP до перевірки підпису. +Webhook voice-call використовує спільний профіль тіла до автентифікації (64 КБ / 5 секунд) +плюс обмеження кількості одночасних запитів на IP перед перевіркою підпису. Приклад зі стабільним публічним хостом: @@ -419,9 +419,9 @@ Webhook voice-call використовує спільний профіль ті ## TTS для дзвінків -Voice Call використовує базову конфігурацію `messages.tts` для -потокового мовлення під час дзвінків. Ви можете перевизначити її в конфігурації плагіна з -**тією самою структурою** — вона deep-merge-иться з `messages.tts`. +Voice Call використовує основну конфігурацію `messages.tts` для +потокового мовлення в дзвінках. Ви можете перевизначити її в конфігурації Plugin з +**тією самою структурою** — вона глибоко об’єднується з `messages.tts`. ```json5 { @@ -439,15 +439,15 @@ Voice Call використовує базову конфігурацію `messa Примітки: -- Застарілі ключі `tts.` усередині конфігурації плагіна (`openai`, `elevenlabs`, `microsoft`, `edge`) автоматично мігруються до `tts.providers.` під час завантаження. У збереженій конфігурації віддавайте перевагу формі `providers`. -- **Microsoft speech ігнорується для голосових дзвінків** (телефонному аудіо потрібен PCM; поточний транспорт Microsoft не надає вихід PCM для телефонії). -- Базовий TTS використовується, коли ввімкнено потокове медіа Twilio; інакше дзвінки переходять до вбудованих голосів провайдера. -- Якщо медіапотік Twilio вже активний, Voice Call не переходить на TwiML ``. Якщо TTS для телефонії в такому стані недоступний, запит на відтворення завершується помилкою замість змішування двох шляхів відтворення. -- Коли TTS для телефонії переходить на вторинного провайдера, Voice Call записує попередження в лог із ланцюжком провайдерів (`from`, `to`, `attempts`) для налагодження. +- Застарілі ключі `tts.` у конфігурації Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) автоматично мігруються до `tts.providers.` під час завантаження. У збереженій конфігурації надавайте перевагу структурі `providers`. +- **Microsoft speech ігнорується для голосових дзвінків** (телефонне аудіо потребує PCM; поточний транспорт Microsoft не надає телефонний вихід PCM). +- Основний TTS використовується, коли увімкнено потокову передачу медіа Twilio; інакше дзвінки повертаються до нативних голосів провайдера. +- Якщо медіапотік Twilio уже активний, Voice Call не повертається до TwiML ``. Якщо телефонний TTS недоступний у цьому стані, запит на відтворення завершується помилкою замість змішування двох шляхів відтворення. +- Коли телефонний TTS повертається до вторинного провайдера, Voice Call записує попередження в журнал із ланцюгом провайдерів (`from`, `to`, `attempts`) для налагодження. ### Більше прикладів -Використовувати лише базовий TTS (без перевизначення): +Використовувати лише основний TTS (без перевизначення): ```json5 { @@ -462,7 +462,7 @@ Voice Call використовує базову конфігурацію `messa } ``` -Перевизначити на ElevenLabs лише для дзвінків (залишити базове значення в інших місцях): +Перевизначити на ElevenLabs лише для дзвінків (зберегти основне значення за замовчуванням в інших місцях): ```json5 { @@ -487,7 +487,7 @@ Voice Call використовує базову конфігурацію `messa } ``` -Перевизначити лише модель OpenAI для дзвінків (приклад deep-merge): +Перевизначити лише модель OpenAI для дзвінків (приклад глибокого об’єднання): ```json5 { @@ -512,7 +512,7 @@ Voice Call використовує базову конфігурацію `messa ## Вхідні дзвінки -Типове значення політики вхідних дзвінків — `disabled`. Щоб увімкнути вхідні дзвінки, задайте: +Політика вхідних дзвінків за замовчуванням має значення `disabled`. Щоб увімкнути вхідні дзвінки, задайте: ```json5 { @@ -522,21 +522,21 @@ Voice Call використовує базову конфігурацію `messa } ``` -`inboundPolicy: "allowlist"` — це низькорівневий фільтр caller ID. Плагін -нормалізує значення `From`, яке надає провайдер, і порівнює його з `allowFrom`. -Перевірка Webhook автентифікує доставку від провайдера та цілісність payload, але +`inboundPolicy: "allowlist"` — це низькорівнева перевірка caller ID. Plugin +нормалізує надане провайдером значення `From` і порівнює його з `allowFrom`. +Перевірка Webhook автентифікує доставку провайдером і цілісність payload, але не доводить право власності на номер абонента PSTN/VoIP. Сприймайте `allowFrom` як -фільтрацію caller ID, а не як сильне підтвердження особи абонента. +фільтрацію caller ID, а не як сильну ідентифікацію абонента. -Автовідповіді використовують систему агентів. Налаштовуйте через: +Автовідповіді використовують систему агентів. Налаштовуйте за допомогою: - `responseModel` - `responseSystemPrompt` - `responseTimeoutMs` -### Контракт озвученого виводу +### Контракт голосового виводу -Для автовідповідей Voice Call додає до системного prompt суворий контракт озвученого виводу: +Для автовідповідей Voice Call додає строгий контракт голосового виводу до системного промпту: - `{"spoken":"..."}` @@ -544,24 +544,25 @@ Voice Call використовує базову конфігурацію `messa - Ігнорує payload, позначені як reasoning/error content. - Розбирає прямий JSON, JSON у fenced-блоках або вбудовані ключі `"spoken"`. -- Переходить до plain text і видаляє ймовірні вступні абзаци з плануванням/метаданими. +- Повертається до звичайного тексту й прибирає ймовірні вступні абзаци з плануванням/метаданими. -Це дозволяє зосередити озвучення на тексті для абонента й уникнути потрапляння в аудіо тексту планування. +Це допомагає зосередити голосове відтворення на тексті для абонента й уникнути потрапляння тексту планування в аудіо. -### Поведінка під час запуску розмови +### Поведінка запуску розмови -Для вихідних дзвінків у режимі `conversation` обробка першого повідомлення пов’язана зі станом живого відтворення: +Для вихідних дзвінків у режимі `conversation` обробка першого повідомлення прив’язана до стану відтворення в реальному часі: -- Очищення черги barge-in та автовідповідь пригнічуються лише тоді, коли початкове привітання активно озвучується. -- Якщо початкове відтворення не вдається, дзвінок повертається до стану `listening`, а початкове повідомлення залишається в черзі для повторної спроби. -- Початкове відтворення для потокового Twilio починається під час підключення потоку без додаткової затримки. +- Очищення черги barge-in і автовідповідь пригнічуються лише поки активно відтворюється початкове привітання. +- Якщо початкове відтворення не вдається, дзвінок повертається в `listening`, а початкове повідомлення залишається в черзі для повторної спроби. +- Початкове відтворення для потокової передачі Twilio починається під час підключення потоку без додаткової затримки. +- Голосові розмови в реальному часі використовують власний початковий хід realtime-потоку. Voice Call не надсилає застаріле оновлення TwiML `` для цього початкового повідомлення, тому вихідні сесії `` залишаються підключеними. -### Пільговий період після відключення потоку Twilio +### Пільговий інтервал при відключенні потоку Twilio -Коли медіапотік Twilio відключається, Voice Call чекає `2000ms` перед автоматичним завершенням дзвінка: +Коли медіапотік Twilio відключається, Voice Call чекає `2000ms`, перш ніж автоматично завершити дзвінок: -- Якщо потік перепідключається протягом цього вікна, авто-завершення скасовується. -- Якщо після завершення пільгового періоду потік не реєструється знову, дзвінок завершується, щоб запобігти завислим активним дзвінкам. +- Якщо потік знову підключається протягом цього вікна, авто-завершення скасовується. +- Якщо після завершення пільгового інтервалу потік не буде повторно зареєстрований, дзвінок завершується, щоб запобігти зависанню активних дзвінків. ## CLI @@ -574,14 +575,14 @@ openclaw voicecall dtmf --call-id --digits "ww123456#" openclaw voicecall end --call-id openclaw voicecall status --call-id openclaw voicecall tail -openclaw voicecall latency # підсумувати затримку ходів за логами +openclaw voicecall latency # підсумувати затримку ходів із журналів openclaw voicecall expose --mode funnel ``` -`latency` читає `calls.jsonl` зі стандартного шляху сховища voice-call. Використовуйте -`--file `, щоб вказати інший лог, і `--last `, щоб обмежити аналіз -останніми N записами (типово 200). Вивід містить p50/p90/p99 для затримки ходу -та часу очікування прослуховування. +`latency` читає `calls.jsonl` зі стандартного шляху зберігання voice-call. Використовуйте +`--file `, щоб вказати інший журнал, і `--last `, щоб обмежити аналіз +останніми N записами (типово 200). Вивід включає p50/p90/p99 для +затримки ходів і часу очікування прослуховування. ## Інструмент агента @@ -596,7 +597,7 @@ openclaw voicecall expose --mode funnel - `end_call` (callId) - `get_status` (callId) -Цей репозиторій містить відповідний документ Skills у `skills/voice-call/SKILL.md`. +Цей репозиторій постачає відповідний документ Skills у `skills/voice-call/SKILL.md`. ## Gateway RPC