From 237560254bdaa530949be81efa4dcecdd4351d36 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 22 Apr 2026 05:44:25 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/gateway/configuration-reference.md | 1451 ++++++++++---------- docs/uk/plugins/codex-harness.md | 170 +-- docs/uk/plugins/sdk-agent-harness.md | 136 +- 3 files changed, 853 insertions(+), 904 deletions(-) diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index f54dd3794..60caac149 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -1,70 +1,70 @@ --- read_when: - - Вам потрібні точні семантики полів конфігурації або значення за замовчуванням + - Потрібні точні семантики полів конфігурації або значення за замовчуванням - Ви перевіряєте блоки конфігурації каналу, моделі, Gateway або інструмента summary: Довідник із конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем title: Довідник із конфігурації x-i18n: - generated_at: "2026-04-21T21:40:52Z" + generated_at: "2026-04-22T05:34:59Z" model: gpt-5.4 provider: openai - source_hash: 0313f47079536b93385b4e9c7680a896098ac05dce4e368d389a33e31b4649ac + source_hash: f0d6fc076f54e84bef5beefbcc42d8f172cc79792c716f76103894303e3042ac source_path: gateway/configuration-reference.md workflow: 15 --- # Довідник із конфігурації -Довідник із базової конфігурації для `~/.openclaw/openclaw.json`. Для огляду за сценаріями див. [Configuration](/uk/gateway/configuration). +Основний довідник із конфігурації для `~/.openclaw/openclaw.json`. Огляд, орієнтований на завдання, див. у [Configuration](/uk/gateway/configuration). -Ця сторінка охоплює основні поверхні конфігурації OpenClaw і дає посилання назовні, якщо підсистема має власний, глибший довідник. Вона **не** намагається вбудувати на одній сторінці кожен каталог команд, що належить каналу/Plugin, або кожен глибокий параметр пам’яті/QMD. +Ця сторінка охоплює основні поверхні конфігурації OpenClaw і дає посилання назовні, коли підсистема має власний докладніший довідник. Вона **не** намагається вбудувати на одній сторінці кожен каталог команд, що належить каналу/Plugin, або кожен глибокий параметр пам’яті/QMD. Джерело істини в коді: -- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, із вбудованими метаданими plugin/каналів, об’єднаними за наявності -- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів детального перегляду -- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий геш документації конфігурації щодо поточної поверхні схеми +- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, з об’єднаними метаданими bundled/Plugin/channel, коли вони доступні +- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів поглибленого перегляду +- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш документації конфігурації щодо поточної поверхні схеми -Окремі детальні довідники: +Окремі докладні довідники: - [Довідник із конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації Dreaming у `plugins.entries.memory-core.config.dreaming` -- [Слеш-команди](/uk/tools/slash-commands) для поточного вбудованого + комплектного каталогу команд +- [Слеш-команди](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд - сторінки відповідного каналу/Plugin для поверхонь команд, специфічних для каналу -Формат конфігурації — **JSON5** (дозволені коментарі + коми в кінці). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено. +Формат конфігурації — **JSON5** (дозволені коментарі й кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено. --- ## Канали -Кожен канал запускається автоматично, коли існує його секція конфігурації (якщо не вказано `enabled: false`). +Кожен канал запускається автоматично, коли існує його секція конфігурації (якщо тільки не вказано `enabled: false`). ### Доступ до DM і груп -Усі канали підтримують політики DM і групові політики: +Усі канали підтримують політики DM і політики груп: -| Політика DM | Поведінка | -| ------------------- | ---------------------------------------------------------------- | +| Політика DM | Поведінка | +| ------------------- | --------------------------------------------------------------- | | `pairing` (типово) | Невідомі відправники отримують одноразовий код сполучення; власник має підтвердити | -| `allowlist` | Лише відправники в `allowFrom` (або у спареному сховищі дозволів) | -| `open` | Дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) | -| `disabled` | Ігнорувати всі вхідні DM | +| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволених сполучених контактів) | +| `open` | Дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) | +| `disabled` | Ігнорувати всі вхідні DM | -| Групова політика | Поведінка | +| Політика груп | Поведінка | | --------------------- | ------------------------------------------------------ | | `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволених | -| `open` | Обійти списки дозволених груп (фільтрація за згадуванням усе ще застосовується) | +| `open` | Обійти списки дозволених груп (обмеження за згадуванням усе ще застосовується) | | `disabled` | Блокувати всі повідомлення груп/кімнат | -`channels.defaults.groupPolicy` задає типове значення, якщо `groupPolicy` провайдера не встановлено. -Коди сполучення спливають через 1 годину. Кількість очікуваних запитів на сполучення DM обмежена **3 на канал**. -Якщо блок провайдера відсутній повністю (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (fail-closed) із попередженням під час запуску. +`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` провайдера не встановлено. +Коди сполучення діють 1 годину. Незавершені запити на сполучення DM обмежені **3 на канал**. +Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (fail-closed) із попередженням під час запуску. -### Перевизначення моделі для каналу +### Перевизначення моделі для каналів -Використовуйте `channels.modelByChannel`, щоб закріпити певні ID каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналу застосовується, якщо для сесії вже не встановлено перевизначення моделі (наприклад, через `/model`). +Використовуйте `channels.modelByChannel`, щоб закріпити конкретні ідентифікатори каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Це зіставлення каналу застосовується, коли сесія ще не має перевизначення моделі (наприклад, установленого через `/model`). ```json5 { @@ -87,7 +87,7 @@ x-i18n: ### Типові значення каналів і Heartbeat -Використовуйте `channels.defaults` для спільної групової політики та поведінки Heartbeat для всіх провайдерів: +Використовуйте `channels.defaults` для спільної поведінки політики груп і Heartbeat у різних провайдерів: ```json5 { @@ -105,15 +105,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`: резервна групова політика, якщо `groupPolicy` на рівні провайдера не встановлено. -- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь контекст цитат/гілок/історії), `allowlist` (включати контекст лише від відправників зі списку дозволених), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення на рівні каналу: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: включати статуси справних каналів у вивід Heartbeat. +- `channels.defaults.groupPolicy`: резервна політика груп, коли `groupPolicy` на рівні провайдера не встановлено. +- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь контекст цитат/гілок/історії), `allowlist` (включати контекст лише від відправників зі списку дозволених), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення для каналу: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: включати здорові статуси каналів у вивід Heartbeat. - `channels.defaults.heartbeat.showAlerts`: включати деградовані/помилкові статуси у вивід Heartbeat. - `channels.defaults.heartbeat.useIndicator`: відображати компактний вивід Heartbeat у стилі індикатора. ### WhatsApp -WhatsApp працює через web-канал Gateway (Baileys Web). Він запускається автоматично, коли існує прив’язана сесія. +WhatsApp працює через вебканал Gateway (Baileys Web). Він запускається автоматично, коли існує прив’язана сесія. ```json5 { @@ -124,7 +124,7 @@ WhatsApp працює через web-канал Gateway (Baileys Web). Він з textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // сині галочки (false у режимі self-chat) + sendReadReceipts: true, // blue ticks (false in self-chat mode) groups: { "*": { requireMention: true }, }, @@ -146,7 +146,7 @@ WhatsApp працює через web-канал Gateway (Baileys Web). Він з } ``` - + ```json5 { @@ -164,10 +164,10 @@ WhatsApp працює через web-канал Gateway (Baileys Web). Він з } ``` -- Вихідні команди типово використовують обліковий запис `default`, якщо він є; інакше — перший налаштований ID облікового запису (після сортування). -- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. -- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується `openclaw doctor` у `whatsapp/default`. -- Перевизначення на рівні облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. +- Вихідні команди типово використовують обліковий запис `default`, якщо він є; інакше — перший налаштований ідентифікатор облікового запису (після сортування). +- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується командою `openclaw doctor` до `whatsapp/default`. +- Перевизначення для окремого облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -202,7 +202,7 @@ WhatsApp працює через web-канал Gateway (Baileys Web). Він з historyLimit: 50, replyToMode: "first", // off | first | all | batched linkPreview: true, - streaming: "partial", // off | partial | block | progress (типово: off; вмикайте явно, щоб уникнути обмежень rate limit для редагування прев’ю) + streaming: "partial", // off | partial | block | progress (default: off; opt in explicitly to avoid preview-edit rate limits) actions: { reactions: true, sendMessage: true }, reactionNotifications: "own", // off | own | all mediaMaxMb: 100, @@ -226,11 +226,11 @@ WhatsApp працює через web-канал Gateway (Baileys Web). Він з ``` - Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; символічні посилання відхиляються), з `TELEGRAM_BOT_TOKEN` як резервним варіантом для типового облікового запису. -- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. -- У багатооблікових конфігураціях (2+ ID облікових записів) установіть явний типовий обліковий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо він відсутній або некоректний. -- `configWrites: false` блокує ініційовані з Telegram записи конфігурації (міграції ID супергруп, `/config set|unset`). -- Елементи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив’язки ACP для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- Прев’ю потоку в Telegram використовують `sendMessage` + `editMessageText` (працює в прямих і групових чатах). +- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- У конфігураціях із кількома обліковими записами (2+ ідентифікатори облікових записів) установіть явний типовий обліковий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього немає або значення некоректне. +- `configWrites: false` блокує ініційовані через Telegram записи конфігурації (міграції ID супергруп, `/config set|unset`). +- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Попередній перегляд потоків у Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах). - Політика повторних спроб: див. [Політика повторних спроб](/uk/concepts/retry). ### Discord @@ -286,7 +286,7 @@ WhatsApp працює через web-канал Gateway (Baileys Web). Він з historyLimit: 20, textChunkLimit: 2000, chunkMode: "length", // length | newline - streaming: "off", // off | partial | block | progress (progress відповідає partial у Discord) + streaming: "off", // off | partial | block | progress (progress maps to partial on Discord) maxLinesPerMessage: 17, ui: { components: { @@ -297,7 +297,7 @@ WhatsApp працює через web-канал Gateway (Baileys Web). Він з enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // opt-in для sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -334,35 +334,35 @@ WhatsApp працює через web-канал Gateway (Baileys Web). Він з ``` - Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервним варіантом для типового облікового запису. -- Прямі вихідні виклики, які явно передають Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime. -- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. -- Використовуйте `user:` (DM) або `channel:` (канал guild) для цілей доставки; прості числові ID відхиляються. -- Slug-и guild мають нижній регістр, а пробіли замінюються на `-`; ключі каналів використовують slug-ім’я (без `#`). Надавайте перевагу ID guild. -- Повідомлення, створені ботом, типово ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно фільтруються). -- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення на рівні каналу) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (крім @everyone/@here). -- `maxLinesPerMessage` (типово 17) розбиває високі повідомлення, навіть якщо вони не перевищують 2000 символів. +- Прямі вихідні виклики, що явно передають Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime. +- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- Використовуйте `user:` (DM) або `channel:` (канал guild) для цілей доставки; прості числові ідентифікатори відхиляються. +- Слаги guild мають нижній регістр, а пробіли в них замінюються на `-`; ключі каналів використовують назву у вигляді слага (без `#`). Надавайте перевагу ID guild. +- Повідомлення, створені ботом, типово ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно відфільтровуються). +- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення на рівні каналу) відкидає повідомлення, у яких згадується інший користувач або роль, але не бот (крім @everyone/@here). +- `maxLinesPerMessage` (типово 17) розбиває довгі за висотою повідомлення, навіть якщо вони коротші за 2000 символів. - `channels.discord.threadBindings` керує маршрутизацією з прив’язкою до гілок Discord: - - `enabled`: перевизначення Discord для функцій сесій із прив’язкою до гілки (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і доставка/маршрутизація з прив’язкою) - - `idleHours`: перевизначення Discord для авто-зняття фокуса через неактивність у годинах (`0` вимикає) + - `enabled`: перевизначення Discord для функцій сесій із прив’язкою до гілок (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і доставка/маршрутизація з прив’язкою) + - `idleHours`: перевизначення Discord для автоматичного зняття фокуса через неактивність у годинах (`0` вимикає) - `maxAgeHours`: перевизначення Discord для жорсткого максимального віку в годинах (`0` вимикає) - `spawnSubagentSessions`: перемикач opt-in для автоматичного створення/прив’язки гілок через `sessions_spawn({ thread: true })` -- Елементи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і гілок (використовуйте id каналу/гілки в `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` задає колір акценту для контейнерів Discord components v2. +- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і гілок (використовуйте id каналу/гілки в `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- `channels.discord.ui.components.accentColor` задає колір акценту для контейнерів компонентів Discord v2. - `channels.discord.voice` вмикає розмови в голосових каналах Discord і необов’язкові перевизначення auto-join + TTS. -- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` наскрізно передаються в параметри DAVE `@discordjs/voice` (`true` і `24` типово). -- OpenClaw також намагається відновити прийом голосу, виходячи та повторно входячи в голосову сесію після повторних збоїв дешифрування. -- `channels.discord.streaming` — це канонічний ключ режиму потоку. Застарілі значення `streamMode` і булеві `streaming` мігруються автоматично. -- `channels.discord.autoPresence` відображає доступність runtime у присутність бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. -- `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваними ім’ям/тегом (режим сумісності break-glass). -- `channels.discord.execApprovals`: нативна для Discord доставка підтверджень exec і авторизація тих, хто підтверджує. - - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto підтвердження exec активуються, коли список тих, хто підтверджує, можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Discord, яким дозволено підтверджувати exec-запити. Якщо не вказано, використовується `commands.ownerAllowFrom`. - - `agentFilter`: необов’язковий список дозволених ID агентів. Пропустіть, щоб пересилати підтвердження для всіх агентів. - - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). - - `target`: куди надсилати запити на підтвердження. `"dm"` (типово) надсилає в DM тим, хто підтверджує, `"channel"` надсилає у вихідний канал, `"both"` надсилає в обидва місця. Коли target включає `"channel"`, кнопки можуть використовувати лише визначені особи, що підтверджують. - - `cleanupAfterResolve`: якщо `true`, видаляє DM із запитом на підтвердження після підтвердження, відхилення або тайм-ауту. +- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` напряму передаються в параметри DAVE `@discordjs/voice` (типово `true` і `24`). +- OpenClaw додатково намагається відновити прийом голосу, виходячи з голосової сесії та приєднуючись знову після повторних збоїв дешифрування. +- `channels.discord.streaming` — канонічний ключ режиму потокової передачі. Застарілі `streamMode` і булеві значення `streaming` мігруються автоматично. +- `channels.discord.autoPresence` зіставляє доступність runtime зі статусом присутності бота (healthy => online, degraded => idle, exhausted => dnd) і дає змогу необов’язково перевизначати текст статусу. +- `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваним ім’ям/тегом (аварійний режим сумісності). +- `channels.discord.execApprovals`: власна доставка погоджень exec для Discord і авторизація погоджувачів. + - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі погодження exec активуються, коли погоджувачів можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ID користувачів Discord, яким дозволено погоджувати запити exec. Якщо не вказано, використовується `commands.ownerAllowFrom`. + - `agentFilter`: необов’язковий список дозволених ID агентів. Якщо пропустити, погодження пересилатимуться для всіх агентів. + - `sessionFilter`: необов’язкові шаблони ключів сесії (підрядок або regex). + - `target`: куди надсилати запити на погодження. `"dm"` (типово) надсилає в DM погоджувачам, `"channel"` надсилає у вихідний канал, `"both"` надсилає в обидва місця. Коли ціль містить `"channel"`, кнопками можуть користуватися лише визначені погоджувачі. + - `cleanupAfterResolve`: якщо `true`, видаляє DM із погодженням після схвалення, відхилення або тайм-ауту. -**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (від `guilds..users` для всіх повідомлень). +**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (із `guilds..users` для всіх повідомлень). ### Google Chat @@ -393,11 +393,11 @@ WhatsApp працює через web-канал Gateway (Baileys Web). Він з } ``` -- JSON облікового запису служби: вбудований (`serviceAccount`) або на основі файла (`serviceAccountFile`). -- Також підтримується SecretRef облікового запису служби (`serviceAccountRef`). +- JSON облікового запису сервісу: вбудований (`serviceAccount`) або на основі файлу (`serviceAccountFile`). +- Також підтримується SecretRef облікового запису сервісу (`serviceAccountRef`). - Резервні змінні середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Використовуйте `spaces/` або `users/` для цілей доставки. -- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваним email principal (режим сумісності break-glass). +- Для цілей доставки використовуйте `spaces/` або `users/`. +- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваним email principal (аварійний режим сумісності). ### Slack @@ -449,7 +449,7 @@ WhatsApp працює через web-канал Gateway (Baileys Web). Він з chunkMode: "length", streaming: { mode: "partial", // off | partial | block | progress - nativeTransport: true, // використовувати нативний API потокової передачі Slack, коли mode=partial + nativeTransport: true, // use Slack native streaming API when mode=partial }, mediaMaxMb: 20, execApprovals: { @@ -464,35 +464,35 @@ WhatsApp працює через web-канал Gateway (Baileys Web). Він з } ``` -- **Socket mode** потребує і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для резервного варіанта змінних середовища типового облікового запису). -- **HTTP mode** потребує `botToken` плюс `signingSecret` (у корені або для кожного облікового запису). -- `botToken`, `appToken`, `signingSecret` і `userToken` приймають текстові +- **Socket mode** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як резервні змінні середовища для типового облікового запису). +- **HTTP mode** вимагає `botToken` плюс `signingSecret` (у корені або для окремого облікового запису). +- `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті рядки або об’єкти SecretRef. -- Знімки облікових записів Slack показують поля джерела/статусу для кожного облікового запису, такі як - `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у режимі HTTP, +- Знімки облікових записів Slack показують поля джерела/статусу для окремих + облікових даних, такі як `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у HTTP mode, `signingSecretStatus`. `configured_unavailable` означає, що обліковий запис - налаштовано через SecretRef, але поточний шлях команди/runtime не зміг + налаштований через SecretRef, але поточний шлях команди/runtime не зміг визначити значення секрету. -- `configWrites: false` блокує записи конфігурації, ініційовані зі Slack. -- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. -- `channels.slack.streaming.mode` — це канонічний ключ режиму потоку Slack. `channels.slack.streaming.nativeTransport` керує нативним транспортом потокової передачі Slack. Застарілі значення `streamMode`, булеві `streaming` і `nativeStreaming` мігруються автоматично. -- Використовуйте `user:` (DM) або `channel:` для цілей доставки. +- `configWrites: false` блокує ініційовані через Slack записи конфігурації. +- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- `channels.slack.streaming.mode` — канонічний ключ режиму потокової передачі Slack. `channels.slack.streaming.nativeTransport` керує власним транспортом потокової передачі Slack. Застарілі `streamMode`, булеві значення `streaming` і `nativeStreaming` мігруються автоматично. +- Для цілей доставки використовуйте `user:` (DM) або `channel:`. **Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). -**Ізоляція сесій гілок:** `thread.historyScope` є для кожної гілки окремо (типово) або спільним для каналу. `thread.inheritParent` копіює стенограму батьківського каналу в нові гілки. +**Ізоляція сесій гілок:** `thread.historyScope` — окремо для кожної гілки (типово) або спільно для каналу. `thread.inheritParent` копіює стенограму батьківського каналу в нові гілки. -- Нативна потокова передача Slack разом зі статусом гілки Slack у стилі помічника «is typing...» вимагають ціль відповіді у гілці. DM верхнього рівня типово залишаються поза гілкою, тому вони використовують `typingReaction` або звичайну доставку замість прев’ю у стилі гілки. -- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте shortcode емодзі Slack, наприклад `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: нативна для Slack доставка підтверджень exec і авторизація тих, хто підтверджує. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). +- Власна потокова передача Slack разом зі статусом гілки Slack у стилі асистента "is typing..." вимагають ціль у вигляді гілки відповіді. DM верхнього рівня типово залишаються поза гілками, тому вони використовують `typingReaction` або звичайну доставку замість попереднього перегляду у стилі гілки. +- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: власна доставка погоджень exec для Slack і авторизація погоджувачів. Та сама схема, що й для Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). -| Група дій | Типово | Примітки | -| ----------- | ------- | ----------------------- | -| reactions | увімкнено | Реагування + список реакцій | -| messages | увімкнено | Читання/надсилання/редагування/видалення | -| pins | увімкнено | Закріпити/відкріпити/список | -| memberInfo | увімкнено | Інформація про учасника | -| emojiList | увімкнено | Список власних емодзі | +| Група дій | Типово | Примітки | +| ------------ | -------- | ------------------------ | +| reactions | увімкнено | Реакції + список реакцій | +| messages | увімкнено | Читання/надсилання/редагування/видалення | +| pins | увімкнено | Закріплення/відкріплення/список | +| memberInfo | увімкнено | Інформація про учасника | +| emojiList | увімкнено | Список користувацьких emoji | ### Mattermost @@ -516,7 +516,7 @@ Mattermost постачається як Plugin: `openclaw plugins install @open native: true, // opt-in nativeSkills: true, callbackPath: "/api/channels/mattermost/command", - // Необов’язкова явна URL-адреса для розгортань із reverse proxy/публічним доступом + // Optional explicit URL for reverse-proxy/public deployments callbackUrl: "https://gateway.example.com/api/channels/mattermost/command", }, textChunkLimit: 4000, @@ -528,21 +528,21 @@ Mattermost постачається як Plugin: `openclaw plugins install @open Режими чату: `oncall` (відповідати на @-згадування, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса тригера). -Коли нативні команди Mattermost увімкнено: +Коли власні команди Mattermost увімкнено: -- `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повною URL-адресою. -- `commands.callbackUrl` має вказувати на endpoint Gateway OpenClaw і бути досяжним із сервера Mattermost. -- Нативні зворотні виклики slash-команд автентифікуються токенами для кожної команди, які Mattermost повертає - під час реєстрації slash-команд. Якщо реєстрація не вдається або жодні - команди не активовані, OpenClaw відхиляє зворотні виклики з помилкою +- `commands.callbackPath` має бути шляхом (наприклад, `/api/channels/mattermost/command`), а не повним URL. +- `commands.callbackUrl` має вказувати на endpoint Gateway OpenClaw і бути доступним із сервера Mattermost. +- Власні виклики слеш-команд автентифікуються за токенами для окремих команд, які Mattermost повертає + під час реєстрації слеш-команд. Якщо реєстрація не вдається або жодної + команди не активовано, OpenClaw відхиляє виклики з повідомленням `Unauthorized: invalid command token.` - Для приватних/tailnet/internal хостів зворотних викликів Mattermost може вимагати, - щоб `ServiceSettings.AllowedUntrustedInternalConnections` включав хост/домен зворотного виклику. - Використовуйте значення хоста/домену, а не повні URL-адреси. -- `channels.mattermost.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Mattermost. + щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен зворотного виклику. + Використовуйте значення хоста/домену, а не повні URL. +- `channels.mattermost.configWrites`: дозволити або заборонити ініційовані через Mattermost записи конфігурації. - `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в каналах. -- `channels.mattermost.groups..requireMention`: перевизначення фільтрації за згадуванням для конкретного каналу (`"*"` для типового значення). -- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. +- `channels.mattermost.groups..requireMention`: перевизначення обмеження за згадуванням для окремого каналу (`"*"` для типового значення). +- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. ### Signal @@ -551,7 +551,7 @@ Mattermost постачається як Plugin: `openclaw plugins install @open channels: { signal: { enabled: true, - account: "+15555550123", // необов’язкова прив’язка облікового запису + account: "+15555550123", // optional account binding dmPolicy: "pairing", allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"], configWrites: true, @@ -566,8 +566,8 @@ Mattermost постачається як Plugin: `openclaw plugins install @open **Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). - `channels.signal.account`: прив’язати запуск каналу до конкретної ідентичності облікового запису Signal. -- `channels.signal.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Signal. -- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. +- `channels.signal.configWrites`: дозволити або заборонити ініційовані через Signal записи конфігурації. +- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. ### BlueBubbles @@ -580,20 +580,20 @@ BlueBubbles — рекомендований шлях для iMessage (на ос enabled: true, dmPolicy: "pairing", // serverUrl, password, webhookPath, group controls, and advanced actions: - // див. /channels/bluebubbles + // see /channels/bluebubbles }, }, } ``` - Основні шляхи ключів, охоплені тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. -- Елементи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних сесій ACP. Використовуйте handle BlueBubbles або цільовий рядок (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних ACP-сесій. Використовуйте handle або цільовий рядок BlueBubbles (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). - Повну конфігурацію каналу BlueBubbles задокументовано в [BlueBubbles](/uk/channels/bluebubbles). ### iMessage -OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон або порт не потрібні. +OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Daemon або порт не потрібні. ```json5 { @@ -617,15 +617,15 @@ OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон а } ``` -- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. +- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. -- Потрібен Full Disk Access до БД Messages. +- Потребує Full Disk Access до БД Messages. - Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів. - `cliPath` може вказувати на SSH-обгортку; установіть `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. - `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (типово: `/Users/*/Library/Messages/Attachments`). -- SCP використовує сувору перевірку host key, тому переконайтеся, що ключ relay-host уже існує в `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з iMessage. -- Елементи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних сесій ACP. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- SCP використовує сувору перевірку ключа хоста, тож переконайтеся, що ключ хоста relay уже існує в `~/.ssh/known_hosts`. +- `channels.imessage.configWrites`: дозволити або заборонити ініційовані через iMessage записи конфігурації. +- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних ACP-сесій. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). @@ -638,7 +638,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix працює через Plugin і налаштовується в `channels.matrix`. +Matrix працює на основі Plugin і налаштовується в `channels.matrix`. ```json5 { @@ -669,24 +669,24 @@ Matrix працює через Plugin і налаштовується в `channe ``` - Автентифікація за токеном використовує `accessToken`; автентифікація за паролем використовує `userId` + `password`. -- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначити його через `channels.matrix.accounts..proxy`. +- `channels.matrix.proxy` спрямовує HTTP-трафік Matrix через явний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначати його через `channels.matrix.accounts..proxy`. - `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/internal homeserver. `proxy` і цей opt-in для мережі — незалежні елементи керування. -- `channels.matrix.defaultAccount` вибирає пріоритетний обліковий запис у багатооблікових конфігураціях. -- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати та нові запрошення в стилі DM ігноруються, доки ви не встановите `autoJoin: "allowlist"` разом із `autoJoinAllowlist` або `autoJoin: "always"`. -- `channels.matrix.execApprovals`: нативна для Matrix доставка підтверджень exec і авторизація тих, хто підтверджує. - - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto підтвердження exec активуються, коли список тих, хто підтверджує, можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Matrix (наприклад `@owner:example.org`), яким дозволено підтверджувати exec-запити. - - `agentFilter`: необов’язковий список дозволених ID агентів. Пропустіть, щоб пересилати підтвердження для всіх агентів. - - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). - - `target`: куди надсилати запити на підтвердження. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`. - - Перевизначення на рівні облікового запису: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` керує тим, як DM Matrix групуються в сесії: `per-user` (типово) спільне за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату. -- Перевірки статусу Matrix і живі запити до каталогу використовують ту саму політику проксі, що й runtime-трафік. +- `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у конфігураціях із кількома обліковими записами. +- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати й нові запрошення у стилі DM ігноруються, доки ви не встановите `autoJoin: "allowlist"` із `autoJoinAllowlist` або `autoJoin: "always"`. +- `channels.matrix.execApprovals`: власна доставка погоджень exec для Matrix і авторизація погоджувачів. + - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі погодження exec активуються, коли погоджувачів можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ID користувачів Matrix (наприклад, `@owner:example.org`), яким дозволено погоджувати запити exec. + - `agentFilter`: необов’язковий список дозволених ID агентів. Якщо пропустити, погодження пересилатимуться для всіх агентів. + - `sessionFilter`: необов’язкові шаблони ключів сесії (підрядок або regex). + - `target`: куди надсилати запити на погодження. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`. + - Перевизначення для окремого облікового запису: `channels.matrix.accounts..execApprovals`. +- `channels.matrix.dm.sessionScope` керує тим, як DM у Matrix групуються в сесії: `per-user` (типово) спільно використовує сесію за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату. +- Перевірки статусу Matrix і живі пошуки в каталозі використовують ту саму політику проксі, що й runtime-трафік. - Повну конфігурацію Matrix, правила націлювання й приклади налаштування задокументовано в [Matrix](/uk/channels/matrix). ### Microsoft Teams -Microsoft Teams працює через Plugin і налаштовується в `channels.msteams`. +Microsoft Teams працює на основі Plugin і налаштовується в `channels.msteams`. ```json5 { @@ -695,18 +695,18 @@ Microsoft Teams працює через Plugin і налаштовується enabled: true, configWrites: true, // appId, appPassword, tenantId, webhook, team/channel policies: - // див. /channels/msteams + // see /channels/msteams }, }, } ``` - Основні шляхи ключів, охоплені тут: `channels.msteams`, `channels.msteams.configWrites`. -- Повну конфігурацію Teams (облікові дані, Webhook, політика DM/груп, перевизначення для окремих team/каналів) задокументовано в [Microsoft Teams](/uk/channels/msteams). +- Повну конфігурацію Teams (облікові дані, Webhook, політика DM/груп, перевизначення для окремих team/channel) задокументовано в [Microsoft Teams](/uk/channels/msteams). ### IRC -IRC працює через Plugin і налаштовується в `channels.irc`. +IRC працює на основі Plugin і налаштовується в `channels.irc`. ```json5 { @@ -728,12 +728,12 @@ IRC працює через Plugin і налаштовується в `channels. ``` - Основні шляхи ключів, охоплені тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з ID налаштованого облікового запису. -- Повну конфігурацію IRC-каналу (host/port/TLS/канали/списки дозволених/фільтрація за згадуванням) задокументовано в [IRC](/uk/channels/irc). +- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/обмеження за згадуванням) задокументовано в [IRC](/uk/channels/irc). -### Багатообліковість (усі канали) +### Кілька облікових записів (усі канали) -Запускайте кілька облікових записів на канал (кожен зі своїм `accountId`): +Запускайте кілька облікових записів на канал (кожен із власним `accountId`): ```json5 { @@ -755,27 +755,27 @@ IRC працює через Plugin і налаштовується в `channels. ``` - `default` використовується, коли `accountId` пропущено (CLI + маршрутизація). -- Токени змінних середовища застосовуються лише до облікового запису **default**. -- Базові налаштування каналу застосовуються до всіх облікових записів, якщо їх не перевизначено для конкретного облікового запису. +- Токени середовища застосовуються лише до облікового запису **default**. +- Базові налаштування каналу застосовуються до всіх облікових записів, якщо не перевизначені для окремого облікового запису. - Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен обліковий запис до іншого агента. -- Якщо ви додаєте не-типовий обліковий запис через `openclaw channels add` (або onboarding каналу), залишаючись у конфігурації каналу верхнього рівня для одного облікового запису, OpenClaw спочатку переносить значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у карту облікових записів каналу, щоб початковий обліковий запис продовжив працювати. Більшість каналів переносить їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. -- Наявні прив’язки лише до каналу (без `accountId`) і далі зіставляються з типовим обліковим записом; прив’язки з прив’язкою до облікового запису залишаються необов’язковими. -- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи верхньорівневі значення для одного облікового запису, прив’язані до облікового запису, у підвищений обліковий запис, вибраний для цього каналу. Більшість каналів використовує `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. +- Якщо ви додаєте не-типовий обліковий запис через `openclaw channels add` (або онбординг каналу), коли все ще перебуваєте в однокористувацькій конфігурації каналу верхнього рівня, OpenClaw спочатку піднімає значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у карту облікових записів каналу, щоб початковий обліковий запис продовжував працювати. Більшість каналів переміщують їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. +- Наявні прив’язки лише до каналу (без `accountId`) і далі зіставляються з типовим обліковим записом; прив’язки з областю окремого облікового запису залишаються необов’язковими. +- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у піднятий обліковий запис, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. ### Інші канали Plugin -Багато каналів Plugin налаштовуються як `channels.` і задокументовані на їхніх окремих сторінках каналів (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). +Багато каналів Plugin налаштовуються як `channels.` і задокументовані на їхніх окремих сторінках каналів (наприклад, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). Див. повний індекс каналів: [Channels](/uk/channels). -### Фільтрація за згадуванням у групових чатах +### Обмеження за згадуванням у групових чатах -Повідомлення в групах типово **вимагають згадування** (метадані згадування або безпечні шаблони regex). Застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. +Для групових повідомлень типово **потрібне згадування** (метадані згадування або безпечні regex-шаблони). Застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. **Типи згадувань:** -- **Згадування в метаданих**: нативні @-згадування платформи. Ігноруються в режимі self-chat WhatsApp. -- **Текстові шаблони**: безпечні шаблони regex у `agents.list[].groupChat.mentionPatterns`. Некоректні шаблони та небезпечне вкладене повторення ігноруються. -- Фільтрація за згадуванням застосовується лише тоді, коли виявлення можливе (нативні згадування або принаймні один шаблон). +- **Згадування в метаданих**: рідні @-згадування платформи. Ігноруються в режимі self-chat WhatsApp. +- **Текстові шаблони**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Некоректні шаблони та небезпечне вкладене повторення ігноруються. +- Обмеження за згадуванням застосовується лише тоді, коли виявлення можливе (рідні згадування або принаймні один шаблон). ```json5 { @@ -788,9 +788,9 @@ IRC працює через Plugin і налаштовується в `channels. } ``` -`messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначити його через `channels..historyLimit` (або на рівні облікового запису). Установіть `0`, щоб вимкнути. +`messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначати його через `channels..historyLimit` (або для окремого облікового запису). Установіть `0`, щоб вимкнути. -#### Обмеження історії DM +#### Ліміти історії DM ```json5 { @@ -805,13 +805,13 @@ IRC працює через Plugin і налаштовується в `channels. } ``` -Розв’язання: перевизначення для конкретного DM → типове значення провайдера → без обмеження (зберігається все). +Розв’язання: перевизначення для окремого DM → типове значення провайдера → без ліміту (зберігається все). Підтримуються: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. #### Режим self-chat -Додайте свій власний номер до `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадування, відповідає лише на текстові шаблони): +Додайте власний номер у `allowFrom`, щоб увімкнути режим self-chat (ігнорує рідні @-згадування, відповідає лише на текстові шаблони): ```json5 { @@ -832,21 +832,21 @@ IRC працює через Plugin і налаштовується в `channels. } ``` -### Команди (обробка команд чату) +### Команди (обробка команд у чаті) ```json5 { commands: { - native: "auto", // реєструвати нативні команди, коли це підтримується - nativeSkills: "auto", // реєструвати нативні команди Skills, коли це підтримується - text: true, // розбирати /commands у повідомленнях чату - bash: false, // дозволити ! (псевдонім: /bash) + native: "auto", // register native commands when supported + nativeSkills: "auto", // register native skill commands when supported + text: true, // parse /commands in chat messages + bash: false, // allow ! (alias: /bash) bashForegroundMs: 2000, - config: false, // дозволити /config - mcp: false, // дозволити /mcp - plugins: false, // дозволити /plugins - debug: false, // дозволити /debug - restart: true, // дозволити /restart + інструмент перезапуску gateway + config: false, // allow /config + mcp: false, // allow /mcp + plugins: false, // allow /plugins + debug: false, // allow /debug + restart: true, // allow /restart + gateway restart tool ownerAllowFrom: ["discord:123456789012345678"], ownerDisplay: "raw", // raw | hash ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}", @@ -859,40 +859,40 @@ IRC працює через Plugin і налаштовується в `channels. } ``` - + -- Цей блок налаштовує поверхні команд. Для поточного каталогу вбудованих + комплектних команд див. [Слеш-команди](/uk/tools/slash-commands). -- Ця сторінка — це **довідник ключів конфігурації**, а не повний каталог команд. Команди, що належать каналу/Plugin, такі як QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, задокументовані на сторінках їхніх каналів/Plugin, а також у [Слеш-команди](/uk/tools/slash-commands). +- Цей блок налаштовує поверхні команд. Поточний каталог вбудованих + bundled команд див. у [Slash Commands](/uk/tools/slash-commands). +- Ця сторінка — **довідник за ключами конфігурації**, а не повний каталог команд. Команди, що належать каналам/Plugin, такі як QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, задокументовані на сторінках відповідних каналів/Plugin, а також у [Slash Commands](/uk/tools/slash-commands). - Текстові команди мають бути **окремими** повідомленнями з початковим `/`. -- `native: "auto"` вмикає нативні команди для Discord/Telegram, залишає Slack вимкненим. -- `nativeSkills: "auto"` вмикає нативні команди Skills для Discord/Telegram, залишає Slack вимкненим. +- `native: "auto"` вмикає рідні команди для Discord/Telegram, але залишає Slack вимкненим. +- `nativeSkills: "auto"` вмикає рідні команди Skills для Discord/Telegram, але залишає Slack вимкненим. - Перевизначення для каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди. -- Перевизначуйте реєстрацію нативних команд Skills для каналу через `channels..commands.nativeSkills`. -- `channels.telegram.customCommands` додає додаткові пункти меню бота Telegram. -- `bash: true` вмикає `! ` для shell хоста. Потребує `tools.elevated.enabled` і щоб відправник був у `tools.elevated.allowFrom.`. -- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів gateway `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; лише для читання `/config show` лишається доступним для звичайних клієнтів operator із правами запису. -- `mcp: true` вмикає `/mcp` для конфігурації MCP-серверів, якими керує OpenClaw, у `mcp.servers`. -- `plugins: true` вмикає `/plugins` для пошуку Plugin, встановлення та керування ввімкненням/вимкненням. -- `channels..configWrites` керує змінами конфігурації для кожного каналу (типово: true). -- Для багатооблікових каналів `channels..accounts..configWrites` також керує записами, націленими на цей обліковий запис (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`). -- `restart: false` вимикає `/restart` і дії інструмента перезапуску gateway. Типово: `true`. -- `ownerAllowFrom` — це явний список дозволених власників для команд/інструментів лише для власника. Він окремий від `allowFrom`. -- `ownerDisplay: "hash"` гешує ID власників у системному prompt. Установіть `ownerDisplaySecret`, щоб керувати гешуванням. -- `allowFrom` задається для кожного провайдера. Якщо встановлено, це **єдине** джерело авторизації (списки дозволених каналу/сполучення і `useAccessGroups` ігноруються). -- `useAccessGroups: false` дозволяє командам обходити політики груп доступу, коли `allowFrom` не встановлено. -- Карта документації команд: - - вбудований + комплектний каталог: [Слеш-команди](/uk/tools/slash-commands) - - поверхні команд, специфічні для каналу: [Channels](/uk/channels) +- Перевизначуйте реєстрацію рідних команд Skills для каналу через `channels..commands.nativeSkills`. +- `channels.telegram.customCommands` додає додаткові записи меню бота Telegram. +- `bash: true` вмикає `! ` для shell хоста. Потрібні `tools.elevated.enabled` і відправник у `tools.elevated.allowFrom.`. +- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів gateway `chat.send` постійні записи `/config set|unset` також вимагають `operator.admin`; режим лише читання `/config show` залишається доступним для звичайних клієнтів оператора з правом запису. +- `mcp: true` вмикає `/mcp` для конфігурації MCP-сервера під керуванням OpenClaw у `mcp.servers`. +- `plugins: true` вмикає `/plugins` для виявлення, встановлення та керування вмиканням/вимиканням Plugin. +- `channels..configWrites` керує мутаціями конфігурації для кожного каналу (типово: true). +- Для каналів із кількома обліковими записами `channels..accounts..configWrites` також керує записами, націленими на цей обліковий запис (наприклад, `/allowlist --config --account ` або `/config set channels..accounts....`). +- `restart: false` вимикає `/restart` і дії інструмента перезапуску gateway. Типове значення: `true`. +- `ownerAllowFrom` — це явний список дозволених власників для команд/інструментів лише для власника. Він відокремлений від `allowFrom`. +- `ownerDisplay: "hash"` хешує ідентифікатори власників у системному запиті. Установіть `ownerDisplaySecret`, щоб керувати хешуванням. +- `allowFrom` задається для кожного провайдера. Якщо його встановлено, це **єдине** джерело авторизації (списки дозволених каналу/сполучення та `useAccessGroups` ігноруються). +- `useAccessGroups: false` дає змогу командам обходити політики груп доступу, коли `allowFrom` не встановлено. +- Відображення документації команд: + - каталог вбудованих + bundled команд: [Slash Commands](/uk/tools/slash-commands) + - поверхні команд, специфічні для каналів: [Channels](/uk/channels) - команди QQ Bot: [QQ Bot](/uk/channels/qqbot) - команди сполучення: [Pairing](/uk/channels/pairing) - команда картки LINE: [LINE](/uk/channels/line) - - Dreaming для memory: [Dreaming](/uk/concepts/dreaming) + - dreaming для пам’яті: [Dreaming](/uk/concepts/dreaming) --- -## Типові значення агентів +## Типові значення агента ### `agents.defaults.workspace` @@ -906,7 +906,7 @@ IRC працює через Plugin і налаштовується в `channels. ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, що показується в рядку Runtime системного prompt. Якщо не встановлено, OpenClaw автоматично визначає його, піднімаючись вгору від workspace. +Необов’язковий корінь репозиторію, що показується в рядку Runtime системного запиту. Якщо не встановлено, OpenClaw автоматично визначає його, піднімаючись угору від workspace. ```json5 { @@ -924,17 +924,17 @@ IRC працює через Plugin і налаштовується в `channels. agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // успадковує github, weather - { id: "docs", skills: ["docs-search"] }, // замінює типові значення - { id: "locked-down", skills: [] }, // без Skills + { id: "writer" }, // inherits github, weather + { id: "docs", skills: ["docs-search"] }, // replaces defaults + { id: "locked-down", skills: [] }, // no skills ], }, } ``` -- Пропустіть `agents.defaults.skills`, щоб типово дозволити необмежені Skills. +- Пропустіть `agents.defaults.skills`, щоб типово не обмежувати Skills. - Пропустіть `agents.list[].skills`, щоб успадкувати типові значення. -- Установіть `agents.list[].skills: []`, щоб не використовувати Skills. +- Установіть `agents.list[].skills: []`, щоб не мати Skills. - Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він не об’єднується з типовими значеннями. @@ -950,9 +950,9 @@ IRC працює через Plugin і налаштовується в `channels. ### `agents.defaults.contextInjection` -Керує тим, коли bootstrap-файли workspace вставляються в системний prompt. Типово: `"always"`. +Керує тим, коли bootstrap-файли workspace вбудовуються в системний запит. Типове значення: `"always"`. -- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді помічника) пропускають повторну вставку bootstrap workspace, зменшуючи розмір prompt. Запуски Heartbeat і повторні спроби після Compaction все одно перебудовують контекст. +- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне вбудовування bootstrap workspace, зменшуючи розмір запиту. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст. ```json5 { @@ -962,7 +962,7 @@ IRC працює через Plugin і налаштовується в `channels. ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів на bootstrap-файл workspace перед обрізанням. Типово: `12000`. +Максимальна кількість символів на один bootstrap-файл workspace перед обрізанням. Типове значення: `12000`. ```json5 { @@ -972,7 +972,7 @@ IRC працює через Plugin і налаштовується в `channels. ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що вставляються з усіх bootstrap-файлів workspace. Типово: `60000`. +Максимальна загальна кількість символів, що вбудовуються через всі bootstrap-файли workspace. Типове значення: `60000`. ```json5 { @@ -982,12 +982,12 @@ IRC працює через Plugin і налаштовується в `channels. ### `agents.defaults.bootstrapPromptTruncationWarning` -Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається. -Типово: `"once"`. +Керує видимим агенту текстом попередження, коли bootstrap-контекст обрізається. +Типове значення: `"once"`. -- `"off"`: ніколи не вставляти текст попередження в системний prompt. -- `"once"`: вставляти попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано). -- `"always"`: вставляти попередження на кожному запуску, коли є обрізання. +- `"off"`: ніколи не вбудовувати текст попередження в системний запит. +- `"once"`: вбудовувати попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано). +- `"always"`: вбудовувати попередження під час кожного запуску, коли є обрізання. ```json5 { @@ -997,24 +997,24 @@ IRC працює через Plugin і налаштовується в `channels. ### Карта відповідальності за бюджет контексту -OpenClaw має кілька високонавантажених бюджетів prompt/контексту, і вони -навмисно розділені за підсистемами, а не проходять через один універсальний -перемикач. +OpenClaw має кілька високонавантажених бюджетів запиту/контексту, і вони +навмисно розділені за підсистемами замість того, щоб усі проходили через один +загальний параметр. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - звичайна вставка bootstrap workspace. + звичайне вбудовування bootstrap workspace. - `agents.defaults.startupContext.*`: - одноразова стартова преамбула для `/new` і `/reset`, включно з останніми щоденними - файлами `memory/*.md`. + одноразовий початковий пролог для `/new` і `/reset`, включно з недавніми + файлами `memory/*.md` за днями. - `skills.limits.*`: - компактний список Skills, що вставляється в системний prompt. + компактний список Skills, вбудований у системний запит. - `agents.defaults.contextLimits.*`: - обмежені витяги runtime та вставлені блоки, що належать runtime. + обмежені фрагменти runtime і вбудовані блоки, що належать runtime. - `memory.qmd.limits.*`: - розмір фрагментів індексованого пошуку пам’яті та їх вставки. + розмір фрагментів і вбудовування для індексованого пошуку в пам’яті. -Використовуйте відповідне перевизначення для конкретного агента лише тоді, коли одному агенту потрібен інший +Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший бюджет: - `agents.list[].skillsLimits.maxSkillsPromptChars` @@ -1022,7 +1022,8 @@ OpenClaw має кілька високонавантажених бюджеті #### `agents.defaults.startupContext` -Керує стартовою преамбулою першого ходу, що вставляється в запусках із порожнім `/new` і `/reset`. +Керує початковим прологом першого ходу, що вбудовується в запуски `/new` і `/reset` +без додаткового контексту. ```json5 { @@ -1060,18 +1061,18 @@ OpenClaw має кілька високонавантажених бюджеті } ``` -- `memoryGetMaxChars`: типове обмеження витягу `memory_get` перед додаванням - метаданих обрізання і повідомлення про продовження. +- `memoryGetMaxChars`: типовий ліміт фрагмента `memory_get` перед додаванням + метаданих обрізання та повідомлення про продовження. - `memoryGetDefaultLines`: типове вікно рядків `memory_get`, коли `lines` пропущено. -- `toolResultMaxChars`: поточне обмеження результатів інструментів, що використовується для збережених результатів і - відновлення при переповненні. -- `postCompactionMaxChars`: обмеження витягу AGENTS.md, що використовується під час вставки +- `toolResultMaxChars`: актуальний ліміт результату інструмента, що використовується для збережених результатів і + відновлення переповнення. +- `postCompactionMaxChars`: ліміт фрагмента AGENTS.md, що використовується під час вбудовування оновлення після Compaction. #### `agents.list[].contextLimits` -Перевизначення для конкретного агента для спільних перемикачів `contextLimits`. Пропущені поля успадковуються +Перевизначення для окремого агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються з `agents.defaults.contextLimits`. ```json5 @@ -1098,8 +1099,8 @@ OpenClaw має кілька високонавантажених бюджеті #### `skills.limits.maxSkillsPromptChars` -Глобальне обмеження для компактного списку Skills, що вставляється в системний prompt. Це -не впливає на читання файлів `SKILL.md` на вимогу. +Глобальний ліміт для компактного списку Skills, вбудованого в системний запит. Це +не впливає на читання файлів `SKILL.md` за потреби. ```json5 { @@ -1113,7 +1114,7 @@ OpenClaw має кілька високонавантажених бюджеті #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Перевизначення для конкретного агента для бюджету prompt Skills. +Перевизначення для окремого агента для бюджету запиту Skills. ```json5 { @@ -1132,10 +1133,10 @@ OpenClaw має кілька високонавантажених бюджеті ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для найдовшої сторони зображення в блоках зображень transcript/tool перед викликами провайдера. -Типово: `1200`. +Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень transcript/tool перед викликами провайдера. +Типове значення: `1200`. -Менші значення зазвичай зменшують використання vision-token і розмір payload запиту в сценаріях із великою кількістю скриншотів. +Менші значення зазвичай зменшують використання vision-token і розмір payload запиту для запусків із великою кількістю скриншотів. Більші значення зберігають більше візуальних деталей. ```json5 @@ -1146,7 +1147,7 @@ OpenClaw має кілька високонавантажених бюджеті ### `agents.defaults.userTimezone` -Часовий пояс для контексту системного prompt (не для часових позначок повідомлень). Якщо не встановлено, використовується часовий пояс хоста. +Часовий пояс для контексту системного запиту (не для часових позначок повідомлень). Якщо не задано, використовується часовий пояс хоста. ```json5 { @@ -1156,7 +1157,7 @@ OpenClaw має кілька високонавантажених бюджеті ### `agents.defaults.timeFormat` -Формат часу в системному prompt. Типово: `auto` (налаштування ОС). +Формат часу в системному запиті. Типове значення: `auto` (налаштування ОС). ```json5 { @@ -1194,7 +1195,7 @@ OpenClaw має кілька високонавантажених бюджеті primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // глобальні типові параметри провайдера + params: { cacheRetention: "long" }, // global default provider params embeddedHarness: { runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none @@ -1214,47 +1215,47 @@ OpenClaw має кілька високонавантажених бюджеті ``` - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Рядкова форма задає лише основну модель. - - Форма об’єкта задає основну модель плюс упорядковані резервні моделі для failover. + - Форма рядка задає лише основну модель. + - Форма об’єкта задає основну модель плюс упорядковані моделі для failover. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується шляхом інструмента `image` як його конфігурація vision-моделі. - Також використовується як резервна маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/Plugin, що генерує зображення. + - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею tool/Plugin, що генерує зображення. - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-2` для OpenAI Images. - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію/API key провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). - - Якщо поле пропущено, `image_generate` усе одно може визначити типове значення провайдера з доступною автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. + - Якщо поле пропущено, `image_generate` усе одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`. - - Якщо поле пропущено, `music_generate` усе одно може визначити типове значення провайдера з доступною автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку provider-id. + - Якщо поле пропущено, `music_generate` усе одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку provider-id. - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію/API key провайдера. - `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-id. + - Якщо поле пропущено, `video_generate` усе одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку provider-id. - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію/API key провайдера. - - Комплектний провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд, а також параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` і `watermark`. + - Bundled провайдер генерації відео Qwen підтримує не більше 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується інструментом `pdf` для маршрутизації моделей. + - Використовується інструментом `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`). Якщо ви пропускаєте провайдера, OpenClaw спочатку пробує псевдонім, потім — унікальний збіг серед налаштованих провайдерів для точного id моделі, і лише потім повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому надавайте перевагу явному `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повертається до першого налаштованого provider/model замість того, щоб показувати застаріле типове значення видаленого провайдера. -- `models`: налаштований каталог моделей і список дозволених значень для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад `{ cacheRetention: "long" }`). -- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається через `agents.defaults.models["provider/model"].params` (для моделі), а потім `agents.list[].params` (для відповідного id агента) перевизначає за ключем. Докладніше див. [Prompt Caching](/uk/reference/prompt-caching). -- `embeddedHarness`: типова політика низькорівневого runtime вбудованого агента. Використовуйте `runtime: "auto"`, щоб дозволити зареєстрованим harness Plugin перехоплювати підтримувані моделі, `runtime: "pi"`, щоб примусово використовувати вбудований harness PI, або зареєстрований id harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. -- Засоби запису конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення резервних моделей), зберігають канонічну форму об’єкта та, коли можливо, зберігають наявні списки резервних моделей. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). Типово: 4. +- `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`). Якщо пропустити провайдера, OpenClaw спочатку пробує alias, потім унікальний збіг exact model id серед налаштованих провайдерів, і лише потім повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому надавайте перевагу явному `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари provider/model замість того, щоб показувати застаріле типове значення видаленого провайдера. +- `models`: налаштований каталог моделей і список дозволених для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`). +- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), після чого `agents.list[].params` (для відповідного id агента) перевизначає за ключем. Докладніше див. у [Prompt Caching](/uk/reference/prompt-caching). +- `embeddedHarness`: типова політика низькорівневого runtime вбудованого агента. Використовуйте `runtime: "auto"`, щоб зареєстровані harness Plugin могли перехоплювати підтримувані моделі, `runtime: "pi"` — щоб примусово використовувати вбудований harness PI, або зареєстрований id harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. +- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта й за можливості зберігають наявні списки fallback. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). Типове значення: 4. ### `agents.defaults.embeddedHarness` `embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента. -У більшості розгортань варто залишити типове значення `{ runtime: "auto", fallback: "pi" }`. -Використовуйте його, коли довірений Plugin надає нативний harness, наприклад комплектний +У більшості розгортань слід залишити типове значення `{ runtime: "auto", fallback: "pi" }`. +Використовуйте це, коли довірений Plugin надає нативний harness, наприклад bundled harness app-server Codex. ```json5 @@ -1271,15 +1272,15 @@ harness app-server Codex. } ``` -- `runtime`: `"auto"`, `"pi"` або id зареєстрованого harness Plugin. Комплектний Plugin Codex реєструє `codex`. -- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований harness PI як сумісний резервний варіант. `"none"` змушує помилково завершувати вибір відсутнього або непідтримуваного harness Plugin замість тихого використання PI. +- `runtime`: `"auto"`, `"pi"` або id зареєстрованого harness Plugin. Bundled Plugin Codex реєструє `codex`. +- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований harness PI як резервний варіант сумісності, коли harness Plugin не вибрано. `"none"` призводить до помилки, якщо вибраний harness Plugin відсутній або не підтримується, замість тихого використання PI. Помилки вибраного harness Plugin завжди показуються напряму. - Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає резервний перехід до PI для цього процесу. -- Для розгортань лише з Codex встановіть `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. -- Це керує лише вбудованим harness чату. Генерація медіа, vision, PDF, музика, відео і TTS все одно використовують свої налаштування provider/model. +- Для розгортань лише з Codex установіть `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. +- Це керує лише вбудованим harness чату. Генерація медіа, vision, PDF, музика, відео й TTS усе ще використовують свої налаштування provider/model. -**Вбудовані скорочення псевдонімів** (застосовуються лише коли модель є в `agents.defaults.models`): +**Скорочені вбудовані alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): -| Псевдонім | Модель | +| Alias | Модель | | ------------------- | -------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -1290,15 +1291,15 @@ harness app-server Codex. | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Ваші налаштовані псевдоніми завжди мають пріоритет над типовими. +Ваші налаштовані alias завжди мають пріоритет над типовими. -Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не встановите `--thinking off` або не визначите `agents.defaults.models["zai/"].params.thinking` самостійно. +Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не встановите `--thinking off` або самі не визначите `agents.defaults.models["zai/"].params.thinking`. Моделі Z.AI типово вмикають `tool_stream` для потокової передачі викликів інструментів. Установіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. -Моделі Anthropic Claude 4.6 типово використовують `adaptive` thinking, коли явний рівень thinking не задано. +Для моделей Anthropic Claude 4.6 типовим є thinking `adaptive`, якщо явно не задано рівень thinking. ### `agents.defaults.cliBackends` -Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють. +Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли збоять API-провайдери. ```json5 { @@ -1328,11 +1329,11 @@ harness app-server Codex. - CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені. - Сесії підтримуються, коли встановлено `sessionArg`. -- Передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів. +- Пряме передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` -Замінює весь системний prompt, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для конкретного агента (`agents.list[].systemPromptOverride`). Значення для конкретного агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із prompt. +Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілами ігнорується. Корисно для контрольованих експериментів із запитами. ```json5 { @@ -1353,16 +1354,16 @@ harness app-server Codex. agents: { defaults: { heartbeat: { - every: "30m", // 0m вимикає + every: "30m", // 0m disables model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // типово: true; false прибирає секцію Heartbeat із системного prompt - lightContext: false, // типово: false; true залишає лише HEARTBEAT.md із bootstrap-файлів workspace - isolatedSession: false, // типово: false; true запускає кожен Heartbeat у свіжій сесії (без історії розмови) + includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt + lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files + isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (типово) | block - target: "none", // типово: none | варіанти: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow (default) | block + target: "none", // default: none | options: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -1373,15 +1374,15 @@ harness app-server Codex. } ``` -- `every`: рядок тривалості (ms/s/m/h). Типово: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути. -- `includeSystemPromptSection`: якщо false, прибирає секцію Heartbeat із системного prompt і пропускає вставку `HEARTBEAT.md` у bootstrap-контекст. Типово: `true`. -- `suppressToolErrorWarnings`: якщо true, пригнічує payload попереджень про помилки інструментів під час запусків Heartbeat. -- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента Heartbeat, після чого його буде перервано. Якщо не задано, використовується `agents.defaults.timeoutSeconds`. -- `directPolicy`: політика прямої доставки/DM. `allow` (типово) дозволяє доставку на пряму ціль. `block` пригнічує доставку на пряму ціль і повертає `reason=dm-blocked`. -- `lightContext`: якщо true, запуски Heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів workspace. -- `isolatedSession`: якщо true, кожен запуск Heartbeat виконується у свіжій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує вартість токенів на один Heartbeat приблизно зі ~100K до ~2-5K токенів. -- Для конкретного агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, Heartbeat запускається **лише для цих агентів**. -- Heartbeat виконує повні ходи агента — коротші інтервали спалюють більше токенів. +- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути. +- `includeSystemPromptSection`: якщо `false`, прибирає секцію Heartbeat із системного запиту та пропускає вбудовування `HEARTBEAT.md` у bootstrap-контекст. Типове значення: `true`. +- `suppressToolErrorWarnings`: якщо `true`, пригнічує payload попереджень про помилки інструментів під час запусків Heartbeat. +- `timeoutSeconds`: максимальний час у секундах, дозволений для ходу агента Heartbeat, після чого він переривається. Якщо не встановлено, використовується `agents.defaults.timeoutSeconds`. +- `directPolicy`: політика прямої доставки/DM. `allow` (типово) дозволяє доставку до прямої цілі. `block` пригнічує доставку до прямої цілі та повертає `reason=dm-blocked`. +- `lightContext`: якщо `true`, запуски Heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів workspace. +- `isolatedSession`: якщо `true`, кожен запуск Heartbeat виконується в новій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один Heartbeat приблизно зі ~100K до ~2–5K токенів. +- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, Heartbeat запускаються **лише для цих агентів**. +- Heartbeat запускає повні ходи агента — коротші інтервали витрачають більше токенів. ### `agents.defaults.compaction` @@ -1411,19 +1412,19 @@ harness app-server 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. -- `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 для збереження тривалих спогадів. Пропускається, коли workspace доступний лише для читання. +- `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 для збереження довготривалих спогадів. Пропускається, коли workspace доступний лише для читання. ### `agents.defaults.contextPruning` -Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням у LLM. **Не** змінює історію сесії на диску. +Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. ```json5 { @@ -1448,22 +1449,22 @@ harness app-server Codex. - `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього торкання кешу). -- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім, за потреби, повністю очищає старіші результати інструментів. +- `ttl` визначає, як часто обрізання може запускатися знову (після останнього торкання кешу). +- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім за потреби повністю очищає старіші результати. **М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині. -**Повне очищення** замінює весь результат інструмента плейсхолдером. +**Повне очищення** замінює весь результат інструмента заповнювачем. Примітки: - Блоки зображень ніколи не обрізаються й не очищаються. -- Співвідношення базуються на символах (приблизно), а не на точній кількості токенів. -- Якщо є менше ніж `keepLastAssistants` повідомлень помічника, обрізання пропускається. +- Співвідношення базуються на кількості символів (приблизно), а не на точних кількостях токенів. +- Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається. -Деталі поведінки див. у [Session Pruning](/uk/concepts/session-pruning). +Докладніше про поведінку див. у [Session Pruning](/uk/concepts/session-pruning). ### Блокова потокова передача @@ -1481,13 +1482,13 @@ harness app-server 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`. -Деталі поведінки та розбиття на частини див. у [Streaming](/uk/concepts/streaming). +Докладніше про поведінку й нарізання блоків див. у [Streaming](/uk/concepts/streaming). -### Індикатори набору тексту +### Індикатори набору ```json5 { @@ -1604,51 +1605,51 @@ harness app-server Codex. } ``` - + -**Бекенд:** +**Backend:** - `docker`: локальний runtime Docker (типово) - `ssh`: загальний віддалений runtime на основі SSH - `openshell`: runtime OpenShell -Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться в +Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться до `plugins.entries.openshell.config`. -**Конфігурація SSH-бекенда:** +**Конфігурація backend SSH:** -- `target`: SSH-ціль у формі `user@host[:port]` -- `command`: команда SSH-клієнта (типово: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace за кожною областю -- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються в OpenSSH +- `target`: ціль SSH у форматі `user@host[:port]` +- `command`: команда клієнта SSH (типово: `ssh`) +- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace на кожну область +- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються до OpenSSH - `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує в тимчасові файли під час runtime -- `strictHostKeyChecking` / `updateHostKeys`: перемикачі політики host key в OpenSSH +- `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH -**Пріоритет SSH-автентифікації:** +**Пріоритет автентифікації SSH:** - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data` на основі SecretRef визначаються з активного знімка runtime секретів перед запуском sandbox-сесії +- Значення `*Data` на основі SecretRef визначаються з активного знімка runtime секретів до запуску сесії sandbox -**Поведінка SSH-бекенда:** +**Поведінка backend SSH:** -- один раз ініціалізує віддалений workspace після створення або перевідтворення -- потім зберігає віддалений SSH-workspace як канонічний -- маршрутизує `exec`, файлові інструменти та медіашляхи через SSH +- один раз засіває віддалений workspace після створення або повторного створення +- далі тримає віддалений SSH workspace канонічним +- маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH - не синхронізує віддалені зміни назад на хост автоматично -- не підтримує browser-контейнери sandbox +- не підтримує контейнерів браузера sandbox **Доступ до workspace:** -- `none`: workspace sandbox за кожною областю в `~/.openclaw/sandboxes` -- `ro`: workspace sandbox у `/workspace`, workspace агента монтується тільки для читання в `/agent` +- `none`: workspace sandbox на кожну область у `~/.openclaw/sandboxes` +- `ro`: workspace sandbox у `/workspace`, workspace агента монтується лише для читання в `/agent` - `rw`: workspace агента монтується для читання/запису в `/workspace` **Область:** -- `session`: контейнер + workspace для кожної сесії -- `agent`: один контейнер + workspace для кожного агента (типово) +- `session`: контейнер + workspace на кожну сесію +- `agent`: один контейнер + workspace на агента (типово) - `shared`: спільний контейнер і workspace (без ізоляції між сесіями) **Конфігурація Plugin OpenShell:** @@ -1679,29 +1680,29 @@ harness app-server Codex. **Режим OpenShell:** -- `mirror`: ініціалізує віддалене середовище з локального перед exec, синхронізує назад після exec; локальний workspace лишається канонічним -- `remote`: ініціалізує віддалене середовище один раз під час створення sandbox, після чого канонічним лишається віддалений workspace +- `mirror`: засіяти віддалений простір із локального перед exec, синхронізувати назад після exec; локальний workspace залишається канонічним +- `remote`: засіяти віддалений простір один раз при створенні sandbox, далі тримати віддалений workspace канонічним -У режимі `remote` локальні редагування на хості, зроблені поза OpenClaw, автоматично не синхронізуються в sandbox після кроку ініціалізації. -Транспортом є SSH до sandbox OpenShell, але Plugin володіє життєвим циклом sandbox і необов’язковою синхронізацією mirror. +У режимі `remote` локальні редагування на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку засівання. +Транспортом є SSH до sandbox OpenShell, але життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією керує Plugin. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, кореня з можливістю запису та користувача root. +**`setupCommand`** запускається один раз після створення контейнера (через `sh -lc`). Потребує вихідного доступу до мережі, кореня з правом запису, користувача root. -**Контейнери типово мають `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. +**Для контейнерів типово встановлено `network: "none"`** — задайте `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. `"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (режим break-glass). +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний режим). **Вхідні вкладення** розміщуються в `media/inbound/*` в активному workspace. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для конкретного агента об’єднуються. +**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремого агента об’єднуються. -**Browser у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. noVNC URL вставляється в системний prompt. Не потребує `browser.enabled` у `openclaw.json`. -Доступ спостерігача noVNC типово використовує VNC-автентифікацію, а OpenClaw видає URL із короткоживучим токеном (замість того, щоб показувати пароль у спільному URL). +**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в системний запит. Не потребує `browser.enabled` в `openclaw.json`. +Доступ спостерігача через noVNC типово використовує автентифікацію VNC, і OpenClaw видає короткоживучий URL із токеном (замість розкриття пароля у спільному URL). -- `allowHostControl: false` (типово) блокує націлювання сесій у sandbox на browser хоста. -- `network` типово має значення `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна bridge-зв’язність. -- `cdpSourceRange` необов’язково обмежує вхідний CDP-трафік на межі контейнера до діапазону CIDR (наприклад `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер browser у sandbox. Якщо задано (включно з `[]`), воно замінює `docker.binds` для контейнера browser. +- `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=` @@ -1721,26 +1722,26 @@ harness app-server Codex. - `--metrics-recording-only` - `--disable-extensions` (типово увімкнено) - `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu` - типово ввімкнені та можуть бути вимкнені через + типово увімкнені; їх можна вимкнути за допомогою `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо цього вимагає використання WebGL/3D. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш workflow + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш робочий процес залежить від них. - - `--renderer-process-limit=2` можна змінити через + - `--renderer-process-limit=2` можна змінити за допомогою `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати типове обмеження процесів Chromium. - - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. - - Типові значення є базовими для образу контейнера; використовуйте власний образ browser із власною - entrypoint, щоб змінити типові значення контейнера. + - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли увімкнено `noSandbox`. + - Типові значення є базовими для образу контейнера; щоб змінити типові параметри контейнера, використовуйте власний + образ браузера з власним entrypoint. -Ізоляція browser і `sandbox.docker.binds` підтримуються лише для Docker. +Ізоляція браузера й `sandbox.docker.binds` доступні лише для Docker. -Зберіть образи: +Створення образів: ```bash -scripts/sandbox-setup.sh # основний образ sandbox -scripts/sandbox-browser-setup.sh # необов’язковий образ browser +scripts/sandbox-setup.sh # main sandbox image +scripts/sandbox-browser-setup.sh # optional browser image ``` ### `agents.list` (перевизначення для окремого агента) @@ -1793,20 +1794,20 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ``` - `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`: необов’язкове типове значення fast mode для конкретного агента (`true | false`). Застосовується, якщо не встановлено перевизначення fast mode для повідомлення або сесії. -- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для конкретного агента. Використовуйте `{ runtime: "codex", fallback: "none" }`, щоб зробити один агент лише для Codex, тоді як інші агенти зберігатимуть типовий резервний PI. -- `runtime`: необов’язковий дескриптор runtime для конкретного агента. Використовуйте `type: "acp"` з типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сесії harness ACP. -- `identity.avatar`: шлях відносно workspace, `http(s)` URL або `data:` URI. -- `identity` виводить типові значення: `ackReaction` із `emoji`, `mentionPatterns` з `name`/`emoji`. +- `default`: коли встановлено кілька значень, перше має пріоритет (записується попередження). Якщо не встановлено жодного, типовим стає перший запис у списку. +- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback). Cron-завдання, які перевизначають лише `primary`, усе одно успадковують типові fallback, якщо ви не встановите `fallbacks: []`. +- `params`: параметри потоку для окремого агента, які зливаються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень, специфічних для агента, таких як `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. +- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо пропущено, агент успадковує `agents.defaults.skills`, коли це значення задано; явний список замінює типові значення замість злиття, а `[]` означає відсутність Skills. +- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не задано перевизначення для окремого повідомлення чи сесії. +- `reasoningDefault`: необов’язкове типове значення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, якщо не задано перевизначення reasoning для окремого повідомлення чи сесії. +- `fastModeDefault`: необов’язкове типове значення швидкого режиму для окремого агента (`true | false`). Застосовується, якщо не задано перевизначення швидкого режиму для окремого повідомлення чи сесії. +- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex", fallback: "none" }`, щоб зробити один агент лише для Codex, тоді як інші агенти зберігатимуть типовий fallback PI. +- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` з типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сесії harness ACP. +- `identity.avatar`: шлях відносно workspace, URL `http(s)` або URI `data:`. +- `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. - `subagents.allowAgents`: список дозволених id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). -- Захист успадкування sandbox: якщо сесія запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. -- `subagents.requireAgentId`: якщо true, блокує виклики `sessions_spawn`, які не вказують `agentId` (примушує до явного вибору профілю; типово: false). +- Захист успадкування sandbox: якщо сесія-запитувач працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. +- `subagents.requireAgentId`: коли `true`, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типово: false). --- @@ -1831,12 +1832,12 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ### Поля зіставлення прив’язок -- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній `type` типово означає route), `acp` для постійних ACP-прив’язок розмов. +- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній `type` типово означає route), `acp` для постійних прив’язок розмов ACP. - `match.channel` (обов’язково) -- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; пропущено = типовий обліковий запис) +- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо пропущено = типовий обліковий запис) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (необов’язково; специфічно для каналу) -- `acp` (необов’язково; лише для елементів `type: "acp"`): `{ mode, label, cwd, backend }` +- `match.guildId` / `match.teamId` (необов’язково; залежить від каналу) +- `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }` **Детермінований порядок зіставлення:** @@ -1844,14 +1845,14 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (точний збіг, без peer/guild/team) -5. `match.accountId: "*"` (на рівні всього каналу) +5. `match.accountId: "*"` (на весь канал) 6. Типовий агент У межах кожного рівня перемагає перший відповідний запис `bindings`. -Для елементів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів route-прив’язок. +Для записів `type: "acp"` OpenClaw виконує зіставлення за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує порядок рівнів route-прив’язок, наведений вище. -### Профілі доступу для окремого агента +### Профілі доступу для окремих агентів @@ -1871,7 +1872,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br - + ```json5 { @@ -1946,7 +1947,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br -Докладно про пріоритетність див. [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). +Докладніше про пріоритети див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). --- @@ -1997,7 +1998,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br } ``` - + - **`scope`**: базова стратегія групування сесій для контекстів групового чату. - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу. @@ -2005,29 +2006,29 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br - **`dmScope`**: як групуються DM. - `main`: усі DM спільно використовують основну сесію. - `per-peer`: ізоляція за id відправника між каналами. - - `per-channel-peer`: ізоляція для кожної пари канал + відправник (рекомендовано для вхідних скриньок із кількома користувачами). - - `per-account-channel-peer`: ізоляція для кожної пари обліковий запис + канал + відправник (рекомендовано для багатообліковості). -- **`identityLinks`**: зіставляє канонічні id з peer-ідентифікаторами з префіксом провайдера для спільного використання сесій між каналами. -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, перемагає той, що спливає раніше. -- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`. + - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для inbox із кількома користувачами). + - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для кількох облікових записів). +- **`identityLinks`**: зіставляє канонічні id з peer із префіксом провайдера для спільного використання сесій між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, спрацьовує той, чий строк настає раніше. +- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як alias для `direct`. - **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківської сесії, дозволене під час створення розгалуженої сесії гілки (типово `100000`). - - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw запускає нову сесію гілки замість успадкування історії стенограми батьківської сесії. + - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw починає нову сесію гілки замість успадкування історії стенограми батьківської сесії. - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти розгалуження від батьківської сесії. -- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного кошика прямих чатів. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість ходів відповіді назад між агентами під час обмінів агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжки ping-pong. -- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. -- **`maintenance`**: очищення сховища сесій + параметри зберігання. +- **`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`). + - `pruneAfter`: граничний вік для застарілих записів (типово `30d`). - `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`). - - `rotateBytes`: ротація `sessions.json`, коли він перевищує цей розмір (типово `10mb`). - - `resetArchiveRetention`: строк зберігання архівів стенограм `*.reset.`. Типово збігається з `pruneAfter`; установіть `false`, щоб вимкнути. - - `maxDiskBytes`: необов’язковий жорсткий бюджет для каталогу сесій на диску. У режимі `warn` записує попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. - - `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово `80%` від `maxDiskBytes`. + - `rotateBytes`: ротує `sessions.json`, коли його розмір перевищує це значення (типово `10mb`). + - `resetArchiveRetention`: строк зберігання архівів стенограм `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий жорсткий бюджет диска для каталогу сесій. У режимі `warn` лише пише попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. + - `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово дорівнює `80%` від `maxDiskBytes`. - **`threadBindings`**: глобальні типові значення для функцій сесій із прив’язкою до гілок. - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - `idleHours`: типове автоматичне зняття фокуса через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати) - - `maxAgeHours`: типове жорстке обмеження максимального віку в годинах (`0` вимикає; провайдери можуть перевизначати) + - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати) @@ -2067,34 +2068,34 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Порядок визначення (перемагає найспецифічніше): обліковий запис → канал → глобальне значення. `""` вимикає й зупиняє каскад. `"auto"` виводить `[{identity.name}]`. +Розв’язання (перемагає найспецифічніше): обліковий запис → канал → глобальне значення. `""` вимикає і зупиняє каскад. `"auto"` виводить `[{identity.name}]`. **Змінні шаблону:** -| Змінна | Опис | Приклад | -| ----------------- | ---------------------- | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | -| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва провайдера | `anthropic` | +| Змінна | Опис | Приклад | +| ---------------- | ------------------------ | --------------------------- | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | +| `{provider}` | Назва провайдера | `anthropic` | | `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Ім’я ідентичності агента | (те саме, що `"auto"`) | +| `{identity.name}` | Назва identity агента | (те саме, що `"auto"`) | -Змінні нечутливі до регістру. `{think}` — псевдонім для `{thinkingLevel}`. +Змінні нечутливі до регістру. `{think}` — alias для `{thinkingLevel}`. -### Реакція підтвердження +### Реакція-підтвердження - Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. - Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення ідентичності. +- Порядок розв’язання: обліковий запис → канал → `messages.ackReaction` → резервне значення identity. - Область: `group-mentions` (типово), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: прибирає підтвердження після відповіді в Slack, Discord і Telegram. -- `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram. - У Slack і Discord, якщо не задано, реакції статусу лишаються ввімкненими, коли активні реакції підтвердження. - У Telegram установіть це поле явно в `true`, щоб увімкнути реакції статусу життєвого циклу. +- `removeAckAfterReply`: видаляє підтвердження після відповіді у Slack, Discord і Telegram. +- `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу у Slack, Discord і Telegram. + У Slack і Discord, якщо значення не встановлено, реакції статусу залишаються ввімкненими, коли активні реакції-підтвердження. + У Telegram для ввімкнення реакцій статусу життєвого циклу потрібно явно встановити `true`. -### Дебаунс вхідних повідомлень +### Вхідний debounce -Об’єднує швидку послідовність текстових повідомлень від одного й того ж відправника в один хід агента. Медіа/вкладення скидаються негайно. Команди керування оминають дебаунс. +Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди обходять debounce. ### TTS (text-to-speech) @@ -2137,12 +2138,12 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br } ``` -- `auto` керує типовим режимом автоматичного TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні налаштування, а `/tts status` показує фактичний стан. -- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку. +- `auto` керує типовим режимом автоматичного TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує фактичний стан. +- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумовування. - `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово має значення `false` (opt-in). -- API key використовують резервні значення `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-сервер і послаблює валідацію model/voice. +- API key резервно беруться з `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-сервер і послаблює валідацію моделі/голосу. --- @@ -2173,12 +2174,12 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ``` - `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька провайдерів Talk. -- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності й автоматично мігруються в `talk.providers.`. -- Voice ID використовують резервні значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. -- `providers.*.apiKey` приймає текстові рядки або об’єкти SecretRef. -- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано API key Talk. +- Застарілі пласкі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) підтримуються лише для сумісності й автоматично мігруються в `talk.providers.`. +- Voice ID резервно беруться з `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. +- `providers.*.apiKey` приймає відкриті рядки або об’єкти SecretRef. +- Резервний варіант `ELEVENLABS_API_KEY` застосовується лише тоді, коли API key Talk не налаштовано. - `providers.*.voiceAliases` дає змогу директивам Talk використовувати дружні назви. -- `silenceTimeoutMs` керує тим, як довго режим Talk чекає після тиші користувача, перш ніж надіслати стенограму. Якщо не задано, зберігається типове для платформи вікно паузи (`700 ms на macOS і Android, 900 ms на iOS`). +- `silenceTimeoutMs` керує тим, як довго режим Talk чекає після тиші користувача, перш ніж надіслати стенограму. Якщо не задано, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). --- @@ -2186,22 +2187,22 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ### Профілі інструментів -`tools.profile` задає базовий список дозволених значень перед `tools.allow`/`tools.deny`: +`tools.profile` задає базовий список дозволених перед `tools.allow`/`tools.deny`: -Локальний onboarding типово встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються). +Локальний онбординг типово встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються). -| Профіль | Містить | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | лише `session_status` | +| Профіль | Включає | +| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `minimal` | лише `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Без обмежень (те саме, що й без значення) | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | Без обмежень (те саме, що й без значення) | ### Групи інструментів | Група | Інструменти | | ------------------ | ------------------------------------------------------------------------------------------------------------------------ | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як псевдонім для `exec`) | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як alias для `exec`) | | `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | | `group:memory` | `memory_search`, `memory_get` | @@ -2216,7 +2217,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ### `tools.allow` / `tools.deny` -Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Нечутлива до регістру, підтримує шаблони `*`. Застосовується навіть тоді, коли Docker sandbox вимкнений. +Глобальна політика дозволу/заборони інструментів (deny має пріоритет). Нечутлива до регістру, підтримує шаблони `*`. Застосовується навіть тоді, коли sandbox Docker вимкнено. ```json5 { @@ -2242,7 +2243,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ### `tools.elevated` -Керує доступом elevated exec поза sandbox: +Керує підвищеним доступом `exec` поза sandbox: ```json5 { @@ -2258,9 +2259,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br } ``` -- Перевизначення для конкретного агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. +- Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. - `/elevated on|off|ask|full` зберігає стан для кожної сесії; вбудовані директиви застосовуються до одного повідомлення. -- Elevated `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово, або `node`, коли ціль exec — `node`). +- Підвищений `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціллю exec є `node`). ### `tools.exec` @@ -2285,7 +2286,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ### `tools.loopDetection` Перевірки безпеки циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення. -Налаштування можна визначати глобально в `tools.loopDetection` і перевизначати для конкретного агента в `agents.list[].tools.loopDetection`. +Параметри можна задавати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`. ```json5 { @@ -2306,10 +2307,10 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br } ``` -- `historySize`: максимальна історія викликів інструментів, яка зберігається для аналізу циклів. -- `warningThreshold`: поріг повторюваного шаблону без прогресу для попереджень. -- `criticalThreshold`: вищий поріг повторень для блокування критичних циклів. -- `globalCircuitBreakerThreshold`: поріг жорсткої зупинки для будь-якого виконання без прогресу. +- `historySize`: максимальна історія викликів інструментів, що зберігається для аналізу циклів. +- `warningThreshold`: поріг шаблону повторення без прогресу для попереджень. +- `criticalThreshold`: вищий поріг повторення для блокування критичних циклів. +- `globalCircuitBreakerThreshold`: жорсткий поріг зупинки для будь-якого запуску без прогресу. - `detectors.genericRepeat`: попереджати про повторні виклики того самого інструмента з тими самими аргументами. - `detectors.knownPollNoProgress`: попереджати/блокувати відомі інструменти опитування (`process.poll`, `command_status` тощо). - `detectors.pingPong`: попереджати/блокувати шаблони чергування пар без прогресу. @@ -2347,7 +2348,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ### `tools.media` -Налаштовує розуміння вхідних медіа (зображення/аудіо/відео): +Налаштовує обробку вхідних медіа (зображення/аудіо/відео): ```json5 { @@ -2390,12 +2391,12 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br **Запис CLI** (`type: "cli"`): - `command`: виконуваний файл для запуску -- `args`: шаблонізовані аргументи (підтримує `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) +- `args`: аргументи з шаблонами (підтримуються `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) **Спільні поля:** - `capabilities`: необов’язковий список (`image`, `audio`, `video`). Типові значення: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. -- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для конкретного запису. +- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису. - У разі помилки використовується наступний запис. Автентифікація провайдера дотримується стандартного порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`. @@ -2403,8 +2404,8 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br **Поля асинхронного завершення:** - `asyncCompletion.directSend`: коли `true`, завершені асинхронні завдання `music_generate` - і `video_generate` спочатку намагаються доставити результат прямо в канал. Типово: `false` - (застарілий шлях пробудження requester-session/доставки через модель). + і `video_generate` спочатку намагаються напряму доставити результат у канал. Типове значення: `false` + (застарілий шлях пробудження сесії запитувача/доставки моделлю). @@ -2423,9 +2424,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br ### `tools.sessions` -Керує тим, на які сесії можна націлюватися через інструменти сесій (`sessions_list`, `sessions_history`, `sessions_send`). +Керує тим, які сесії можуть бути ціллю для інструментів сесій (`sessions_list`, `sessions_history`, `sessions_send`). -Типово: `tree` (поточна сесія + сесії, породжені нею, наприклад субагенти). +Типове значення: `tree` (поточна сесія + сесії, породжені нею, наприклад субагенти). ```json5 { @@ -2440,10 +2441,10 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br Примітки: -- `self`: лише ключ поточної сесії. +- `self`: лише поточний ключ сесії. - `tree`: поточна сесія + сесії, породжені поточною сесією (субагенти). - `agent`: будь-яка сесія, що належить поточному id агента (може включати інших користувачів, якщо ви запускаєте сесії per-sender під тим самим id агента). -- `all`: будь-яка сесія. Націлювання між агентами все одно потребує `tools.agentToAgent`. +- `all`: будь-яка сесія. Націлювання між агентами все одно вимагає `tools.agentToAgent`. - Обмеження sandbox: коли поточна сесія працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` @@ -2469,15 +2470,15 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br Примітки: - Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє. -- Файли матеріалізуються в дочірньому workspace в `.openclaw/attachments//` із `.manifest.json`. +- Файли матеріалізуються в дочірньому workspace за шляхом `.openclaw/attachments//` з `.manifest.json`. - Вміст вкладень автоматично редагується під час збереження стенограми. - Входи Base64 перевіряються суворою перевіркою алфавіту/відступів і захистом розміру до декодування. -- Права доступу до файлів: `0700` для каталогів і `0600` для файлів. -- Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. +- Для каталогів використовуються права `0700`, а для файлів — `0600`. +- Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише тоді, коли `retainOnSessionKeep: true`. ### `tools.experimental` -Експериментальні прапорці вбудованих інструментів. Типово вимкнені, якщо не спрацьовує правило автоувімкнення strict-agentic GPT-5. +Прапори експериментальних вбудованих інструментів. Типово вимкнено, якщо не застосовується правило автоматичного ввімкнення strict-agentic GPT-5. ```json5 { @@ -2492,8 +2493,8 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br Примітки: - `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи. -- Типово: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для конкретного агента) не встановлено в `"strict-agentic"` для запуску сімейства GPT-5 від OpenAI або OpenAI Codex. Установіть `true`, щоб примусово ввімкнути інструмент поза цією областю, або `false`, щоб лишити його вимкненим навіть для strict-agentic запусків GPT-5. -- Коли ввімкнено, системний prompt також додає вказівки щодо використання, щоб модель застосовувала його лише для суттєвої роботи й тримала не більше одного кроку в стані `in_progress`. +- Типове значення: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цією областю, або `false`, щоб тримати його вимкненим навіть для strict-agentic запусків GPT-5. +- Коли інструмент увімкнено, системний запит також додає вказівки щодо використання, щоб модель застосовувала його лише для суттєвої роботи й тримала не більше одного кроку `in_progress`. ### `agents.defaults.subagents` @@ -2513,16 +2514,16 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ br } ``` -- `model`: типова модель для створених субагентів. Якщо пропущено, субагенти успадковують модель викликача. -- `allowAgents`: типовий список дозволених id цільових агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). -- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента не передає `runTimeoutSeconds`. `0` означає відсутність тайм-ауту. -- Політика інструментів для субагентів: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- `model`: типова модель для породжених субагентів. Якщо не задано, субагенти успадковують модель викликача. +- `allowAgents`: типовий список дозволених цільових id агентів для `sessions_spawn`, коли агент-запитувач не задає власне `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). +- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента пропускає `runTimeoutSeconds`. `0` означає відсутність тайм-ауту. +- Політика інструментів для субагента: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Власні провайдери та base URL +## Користувацькі провайдери та base URL -OpenClaw використовує вбудований каталог моделей. Додавайте власних провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. +OpenClaw використовує вбудований каталог моделей. Додавайте користувацьких провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -2551,42 +2552,42 @@ OpenClaw використовує вбудований каталог модел } ``` -- Використовуйте `authHeader: true` + `headers` для власних потреб автентифікації. -- Перевизначте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий псевдонім змінної середовища). -- Пріоритет злиття для однакових ID провайдерів: - - Непорожні значення `baseUrl` з `models.json` агента мають пріоритет. - - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті конфігурації/auth-profile. - - Значення `apiKey` провайдера, якими керує SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження визначених секретів. - - Значення заголовків провайдера, якими керує SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань). - - Порожні або відсутні `apiKey`/`baseUrl` агента використовують резервно `models.providers` у конфігурації. - - Для однакових моделей `contextWindow`/`maxTokens` використовують більше значення між явною конфігурацією та неявними значеннями каталогу. - - Для однакових моделей `contextTokens` зберігає явне обмеження runtime, якщо воно задане; використовуйте його, щоб обмежити ефективний контекст без зміни нативних метаданих моделі. - - Використовуйте `models.mode: "replace"`, коли хочете, щоб конфігурація повністю перезаписала `models.json`. - - Збереження маркерів є авторитетним щодо джерела: маркери записуються з активного знімка конфігурації джерела (до визначення значень), а не з визначених значень секретів runtime. +- Використовуйте `authHeader: true` + `headers` для нестандартних потреб автентифікації. +- Перевизначайте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий alias змінної середовища). +- Пріоритет злиття для провайдерів із відповідними ID: + - Непорожні значення `baseUrl` у `models.json` агента мають пріоритет. + - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті config/auth-profile. + - Значення `apiKey` провайдера, керовані через SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження визначених секретів. + - Значення заголовків провайдера, керовані через SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань). + - Порожні або відсутні `apiKey`/`baseUrl` агента резервно беруться з `models.providers` у конфігурації. + - Для відповідних моделей `contextWindow`/`maxTokens` використовують більше значення між явною конфігурацією та неявними значеннями каталогу. + - Для відповідних моделей `contextTokens` зберігає явне обмеження runtime, якщо воно задане; використовуйте це, щоб обмежити фактичний контекст без зміни нативних метаданих моделі. + - Використовуйте `models.mode: "replace"`, коли хочете, щоб конфігурація повністю переписала `models.json`. + - Збереження маркерів є авторитетним на рівні джерела: маркери записуються з активного знімка конфігурації джерела (до визначення), а не з визначених значень секретів runtime. -### Докладно про поля провайдера +### Відомості про поля провайдера - `models.mode`: поведінка каталогу провайдерів (`merge` або `replace`). -- `models.providers`: карта власних провайдерів, де ключем є id провайдера. +- `models.providers`: карта користувацьких провайдерів, де ключем є id провайдера. - `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо). -- `models.providers.*.apiKey`: облікові дані провайдера (рекомендується SecretRef/підстановка через env). +- `models.providers.*.apiKey`: облікові дані провайдера (надавайте перевагу SecretRef/підстановці з env). - `models.providers.*.auth`: стратегія автентифікації (`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вставляє `options.num_ctx` у запити (типово: `true`). -- `models.providers.*.authHeader`: примусово передає облікові дані в заголовку `Authorization`, коли це потрібно. -- `models.providers.*.baseUrl`: базова URL-адреса API upstream. -- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації проксі/tenant. -- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів провайдера моделей. - - `request.headers`: додаткові заголовки (зливаються з типовими заголовками провайдера). Значення приймають SecretRef. +- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вбудовує `options.num_ctx` у запити (типово: `true`). +- `models.providers.*.authHeader`: примусово передавати облікові дані в заголовку `Authorization`, коли це потрібно. +- `models.providers.*.baseUrl`: базовий URL API верхнього рівня. +- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації через проксі/тенант. +- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів до провайдерів моделей. + - `request.headers`: додаткові заголовки (зливаються з типовими значеннями провайдера). Значення приймають SecretRef. - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value`, необов’язковим `prefix`). - `request.proxy`: перевизначення HTTP-проксі. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`. - `request.tls`: перевизначення TLS для прямих з’єднань. Поля: `ca`, `cert`, `key`, `passphrase` (усі приймають SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS визначається в приватні, CGNAT або подібні діапазони, через захист HTTP fetch провайдера (opt-in оператора для довірених self-hosted OpenAI-сумісних endpoint). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-захист fetch. Типово `false`. + - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, коли DNS визначається в приватні, CGNAT або подібні діапазони, через захист SSRF вибірки HTTP провайдера (opt-in оператора для довірених self-hosted OpenAI-сумісних endpoint). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-захист fetch. Типове значення: `false`. - `models.providers.*.models`: явні записи каталогу моделей провайдера. - `models.providers.*.models.*.contextWindow`: метадані нативного вікна контексту моделі. -- `models.providers.*.models.*.contextTokens`: необов’язкове обмеження контексту runtime. Використовуйте це, коли вам потрібен менший ефективний бюджет контексту, ніж нативне `contextWindow` моделі. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` з непорожнім ненативним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це значення в `false` під час runtime. Порожній або пропущений `baseUrl` зберігає типову поведінку OpenAI. -- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-сумісних chat-endpoint, що підтримують лише рядки. Коли `true`, OpenClaw сплощує масиви чисто текстового `messages[].content` у прості рядки перед надсиланням запиту. -- `plugins.entries.amazon-bedrock.config.discovery`: кореневий розділ налаштувань авто-виявлення Bedrock. +- `models.providers.*.models.*.contextTokens`: необов’язкове обмеження контексту runtime. Використовуйте це, коли хочете менший фактичний бюджет контексту, ніж нативне `contextWindow` моделі. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім ненативним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це значення в `false` під час runtime. Порожній/пропущений `baseUrl` зберігає типову поведінку OpenAI. +- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-сумісних chat endpoint, що підтримують лише рядки. Коли `true`, OpenClaw зводить масиви `messages[].content` лише з текстом до звичайних рядків перед надсиланням запиту. +- `plugins.entries.amazon-bedrock.config.discovery`: кореневий розділ параметрів автознаходження Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне виявлення. - `plugins.entries.amazon-bedrock.config.discovery.region`: регіон AWS для виявлення. - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр provider-id для цільового виявлення. @@ -2630,7 +2631,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` для прямого Z.AI. +Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` — для прямого Z.AI. @@ -2647,7 +2648,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або `opencode-go/...` для каталогу Go. Скорочення: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`. +Установіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або посилання `opencode-go/...` для каталогу Go. Скорочений варіант: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`. @@ -2664,11 +2665,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` приймаються як псевдоніми. Скорочення: `openclaw onboard --auth-choice zai-api-key`. +Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` приймаються як alias. Скорочений варіант: `openclaw onboard --auth-choice zai-api-key`. - Загальний endpoint: `https://api.z.ai/api/paas/v4` - Endpoint для кодування (типовий): `https://api.z.ai/api/coding/paas/v4` -- Для загального endpoint визначте власного провайдера з перевизначенням base URL. +- Для загального endpoint визначте користувацького провайдера з перевизначенням base URL. @@ -2709,9 +2710,9 @@ OpenClaw використовує вбудований каталог модел Для endpoint у Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. -Нативні endpoint Moonshot заявляють сумісність зі streaming на спільному -транспорті `openai-completions`, і OpenClaw прив’язує це до можливостей endpoint, -а не лише до вбудованого id провайдера. +Нативні endpoint Moonshot оголошують сумісність використання потокової передачі на спільному +транспорті `openai-completions`, і OpenClaw визначає це за можливостями endpoint, +а не лише за вбудованим id провайдера. @@ -2729,11 +2730,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Anthropic-сумісний, вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. +Anthropic-сумісний, вбудований провайдер. Скорочений варіант: `openclaw onboard --auth-choice kimi-code-api-key`. - + ```json5 { @@ -2768,7 +2769,7 @@ Anthropic-сумісний, вбудований провайдер. Скоро } ``` -Base URL має не містити `/v1` (клієнт Anthropic додає його). Скорочення: `openclaw onboard --auth-choice synthetic-api-key`. +Base URL має не містити `/v1` (клієнт Anthropic додає його). Скорочений варіант: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2808,11 +2809,11 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -Установіть `MINIMAX_API_KEY`. Скорочення: +Установіть `MINIMAX_API_KEY`. Скорочені варіанти: `openclaw onboard --auth-choice minimax-global-api` або `openclaw onboard --auth-choice minimax-cn-api`. -Каталог моделей типово обмежується лише M2.7. -На Anthropic-сумісному streaming-шляху OpenClaw типово вимикає thinking MiniMax, +Каталог моделей типово містить лише M2.7. +На Anthropic-сумісному шляху потокової передачі OpenClaw типово вимикає thinking MiniMax, якщо ви явно не встановите `thinking` самостійно. `/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. @@ -2821,7 +2822,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й -Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; для резервного варіанта залишайте злитими розміщені моделі. +Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; зберігайте об’єднані hosted моделі для fallback. @@ -2852,14 +2853,14 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `allowBundled`: необов’язковий список дозволених лише для комплектних skills (керовані/workspace skills це не зачіпає). -- `load.extraDirs`: додаткові спільні корені skills (найнижчий пріоритет). -- `install.preferBrew`: коли true, надавати перевагу встановлювачам Homebrew, якщо `brew` - доступний, перш ніж переходити до інших типів встановлювачів. -- `install.nodeManager`: пріоритетний node-менеджер для специфікацій встановлення `metadata.openclaw.install` +- `allowBundled`: необов’язковий список дозволених лише для bundled skills (керовані/workspace Skills не зачіпаються). +- `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет). +- `install.preferBrew`: коли `true`, надавати перевагу встановленню через Homebrew, якщо `brew` + доступний, перш ніж переходити до інших типів інсталяторів. +- `install.nodeManager`: бажаний node-інсталятор для специфікацій `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). -- `entries..enabled: false` вимикає skill, навіть якщо він комплектний/встановлений. -- `entries..apiKey`: зручне поле для skills, які оголошують основну env-змінну (текстовий рядок або об’єкт SecretRef). +- `entries..enabled: false` вимикає Skill, навіть якщо він bundled/встановлений. +- `entries..apiKey`: зручний спосіб для Skills, що оголошують основну змінну середовища (відкритий рядок або об’єкт SecretRef). --- @@ -2887,47 +2888,47 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions` і `plugins.load.paths`. -- Виявлення приймає нативні Plugin OpenClaw, а також сумісні комплекти Codex і Claude, включно з комплектами Claude стандартного макета без manifest. -- **Зміни конфігурації потребують перезапуску gateway.** +- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. +- Виявлення приймає нативні Plugin OpenClaw, а також сумісні пакети Codex і Claude, включно з пакетами Claude стандартного компонування без маніфесту. +- **Зміни конфігурації вимагають перезапуску gateway.** - `allow`: необов’язковий список дозволених (завантажуються лише перелічені Plugin). `deny` має пріоритет. - `plugins.entries..apiKey`: зручне поле API key на рівні Plugin (коли Plugin це підтримує). -- `plugins.entries..env`: карта env-змінних у межах Plugin. -- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` і ігнорує поля зі зміною prompt від застарілого `before_agent_start`, зберігаючи застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hooks Plugin і підтримуваних каталогів hooks, наданих комплектами. -- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для кожного запуску фонових субагентів. -- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень субагентів. Використовуйте `"*"` лише тоді, коли свідомо хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (перевіряється схемою нативного Plugin OpenClaw, якщо вона доступна). -- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl. - - `apiKey`: API key Firecrawl (приймає SecretRef). Використовує резервно `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілий `tools.web.fetch.firecrawl.apiKey` або env-змінну `FIRECRAWL_API_KEY`. - - `baseUrl`: базова URL-адреса API Firecrawl (типово: `https://api.firecrawl.dev`). - - `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`). +- `plugins.entries..env`: карта змінних середовища в області Plugin. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` і ігнорує поля застарілого `before_agent_start`, які змінюють prompt, зберігаючи при цьому застарілі `modelOverride` і `providerOverride`. Це застосовується до нативних hook Plugin і підтримуваних каталогів hook, що надаються пакетами. +- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремих запусків фонових субагентів. +- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень субагентів. Використовуйте `"*"`, лише якщо ви свідомо хочете дозволити будь-яку модель. +- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (валідується нативною схемою Plugin OpenClaw, якщо вона доступна). +- `plugins.entries.firecrawl.config.webFetch`: параметри провайдера веб-вибірки Firecrawl. + - `apiKey`: API key Firecrawl (приймає SecretRef). Резервно береться з `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілого `tools.web.fetch.firecrawl.apiKey` або змінної середовища `FIRECRAWL_API_KEY`. + - `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`). + - `onlyMainContent`: витягувати зі сторінок лише основний вміст (типово: `true`). - `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні). - - `timeoutSeconds`: тайм-аут scrape-запиту в секундах (типово: `60`). -- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok). + - `timeoutSeconds`: тайм-аут запиту на скрапінг у секундах (типово: `60`). +- `plugins.entries.xai.config.xSearch`: параметри xAI X Search (вебпошук Grok). - `enabled`: увімкнути провайдера X Search. - - `model`: модель Grok, яку слід використовувати для пошуку (наприклад `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: налаштування memory Dreaming. Фази й пороги див. у [Dreaming](/uk/concepts/dreaming). - - `enabled`: головний перемикач Dreaming (типово `false`). - - `frequency`: Cron-ритм для кожного повного проходу Dreaming (типово `"0 3 * * *"`). - - політика фаз і пороги — це деталі реалізації (не користувацькі ключі конфігурації). -- Повна конфігурація memory міститься в [Довідник із конфігурації пам’яті](/uk/reference/memory-config): + - `model`: модель Grok для пошуку (наприклад, `"grok-4-1-fast"`). +- `plugins.entries.memory-core.config.dreaming`: параметри dreaming для пам’яті. Докладніше про фази та пороги див. у [Dreaming](/uk/concepts/dreaming). + - `enabled`: головний перемикач dreaming (типово `false`). + - `frequency`: Cron-інтервал для кожного повного проходу dreaming (типово `"0 3 * * *"`). + - політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації). +- Повна конфігурація пам’яті наведена в [Довіднику з конфігурації пам’яті](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені Plugin-комплекти Claude також можуть додавати вбудовані типові значення Pi із `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі конфігурації OpenClaw. -- `plugins.slots.memory`: вибрати id активного Plugin memory або `"none"`, щоб вимкнути Plugin memory. -- `plugins.slots.contextEngine`: вибрати id активного Plugin context engine; типово `"legacy"`, якщо ви не встановите та не виберете інший engine. -- `plugins.installs`: метадані встановлення, якими керує CLI і які використовуються `openclaw plugins update`. - - Містить `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Розглядайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI, а не ручному редагуванню. +- Увімкнені Plugin-пакети Claude також можуть додавати вбудовані типові значення Pi з `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі конфігурації OpenClaw. +- `plugins.slots.memory`: вибрати id активного Plugin пам’яті або `"none"` для вимкнення Plugin пам’яті. +- `plugins.slots.contextEngine`: вибрати id активного Plugin рушія контексту; типово `"legacy"`, якщо ви не встановите й не виберете інший рушій. +- `plugins.installs`: метадані встановлення, керовані CLI, які використовуються `openclaw plugins update`. + - Містять `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. + - Сприймайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI, а не ручному редагуванню. Див. [Plugins](/uk/tools/plugin). --- -## Browser +## Браузер ```json5 { @@ -2964,29 +2965,29 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й ``` - `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` у невстановленому стані вимкнено, тому навігація browser типово лишається суворою. -- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації browser у приватній мережі. -- У суворому режимі віддалені endpoint профілів CDP (`profiles.*.cdpUrl`) підлягають такому самому блокуванню приватної мережі під час перевірок доступності/виявлення. -- `ssrfPolicy.allowPrivateNetwork` усе ще підтримується як застарілий псевдонім. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо значення не задано, тому навігація браузера типово залишається суворою. +- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації браузера в приватній мережі. +- У суворому режимі endpoint віддалених профілів CDP (`profiles.*.cdpUrl`) підлягають тому самому блокуванню приватної мережі під час перевірок доступності/виявлення. +- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий alias. - У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. -- Віддалені профілі підтримують лише під’єднання (запуск/зупинка/скидання вимкнені). +- Віддалені профілі працюють лише в режимі приєднання (start/stop/reset вимкнено). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявив `/json/version`; використовуйте WS(S), - коли ваш провайдер дає вам пряму URL-адресу DevTools WebSocket. -- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть під’єднуватися на - вибраному хості або через підключений browser Node. -- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний - профіль browser на базі Chromium, як-от Brave або Edge. + коли ваш провайдер надає прямий URL DevTools WebSocket. +- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть приєднуватися на + вибраному хості або через підключений браузерний Node. +- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлюватися на конкретний + профіль браузера на базі Chromium, наприклад Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії на основі snapshot/ref замість націлювання CSS-селекторами, hooks завантаження одного файла, - без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без - `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. + дії на основі snapshot/ref замість націлювання на CSS-селектори, hook завантаження одного файла, + відсутність перевизначення тайм-аутів діалогів, відсутність `wait --load networkidle`, а також + `responsebody`, експорту PDF, перехоплення завантажень і пакетних дій. - Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно задавайте `cdpUrl` лише для віддаленого CDP. -- Порядок автовиявлення: browser за замовчуванням, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Служба керування: лише local loopback (порт визначається з `gateway.port`, типово `18791`). -- `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад - `--disable-gpu`, розмір вікна або прапорці налагодження). +- Порядок автовиявлення: типовий браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Служба керування: лише loopback (порт виводиться з `gateway.port`, типово `18791`). +- `extraArgs` додає додаткові прапори запуску до локального старту Chromium (наприклад, + `--disable-gpu`, розмір вікна або прапори налагодження). --- @@ -3004,8 +3005,8 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `seamColor`: колір акценту для chrome нативного UI застосунку (тон бульбашки Talk Mode тощо). -- `assistant`: перевизначення ідентичності Control UI. Використовує резервно ідентичність активного агента. +- `seamColor`: колір акценту для chrome рідного UI програми (відтінок бульбашки режиму Talk тощо). +- `assistant`: перевизначення identity для Control UI. Якщо не задано, використовується identity активного агента. --- @@ -3072,47 +3073,47 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` - + -- `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`. +- `mode`: `local` (запускати gateway) або `remote` (підключатися до віддаленого gateway). Gateway відмовляється запускатися, якщо значення не `local`. - `port`: єдиний мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (типово), `lan` (`0.0.0.0`), `tailnet` (лише IP Tailscale) або `custom`. -- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хостів (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Примітка щодо Docker**: типовий bind `loopback` слухає `127.0.0.1` усередині контейнера. За bridge-мережі Docker (`-p 18789:18789`) трафік приходить на `eth0`, тому gateway недосяжний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. -- **Auth**: типово обов’язкова. Non-loopback bind потребує auth gateway. На практиці це означає спільний token/password або reverse proxy з підтримкою identity-aware із `gateway.auth.mode: "trusted-proxy"`. Майстер onboarding типово генерує token. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно встановіть `gateway.auth.mode` у `token` або `password`. Потоки запуску та встановлення/ремонту сервісу завершуються помилкою, якщо налаштовано обидва, а mode не задано. -- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних конфігурацій local loopback; цей варіант навмисно не пропонується в підказках onboarding. -- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy із підтримкою identity-aware і довіряти заголовкам identity від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело проксі; reverse proxy loopback на тому ж хості не задовольняють trusted-proxy auth. -- `gateway.auth.allowTailscale`: коли `true`, заголовки identity Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). HTTP API endpoint **не** використовують цю auth через заголовки Tailscale; вони дотримуються звичайного HTTP auth mode gateway. Цей потік без token припускає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: необов’язковий лімітер невдалих спроб auth. Застосовується для кожної IP-адреси клієнта і для кожної області auth (shared-secret і device-token відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. - - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для однакового `{scope, clientIp}` серіалізуються перед записом невдачі. Тому паралельні хибні спроби від одного клієнта можуть спровокувати лімітер на другому запиті, замість того щоб обидві одночасно пройшли як звичайні невідповідності. - - `gateway.auth.rateLimit.exemptLoopback` типово `true`; установіть `false`, коли ви свідомо хочете також обмежувати localhost-трафік (для тестових конфігурацій або суворих розгортань із проксі). -- Спроби browser-origin WS auth завжди throttled із вимкненим винятком для loopback (додатковий захист від браузерного brute force на localhost). -- На loopback ці блокування для browser-origin ізольовані для кожного нормалізованого значення `Origin`, - тому повторні невдачі з одного localhost origin не блокують автоматично - інший origin. -- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічний, потребує auth). -- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли browser-клієнти очікуються з non-loopback origin. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервне визначення origin через заголовок Host для розгортань, що свідомо покладаються на політику origin за заголовком Host. -- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` `remote.url` має бути `ws://` або `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське break-glass перевизначення, яке дозволяє незашифрований `ws://` до довірених IP приватної мережі; типово plaintext лишається дозволеним лише для loopback. +- **Застарілі alias для bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не alias хостів (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Примітка щодо Docker**: типовий bind `loopback` слухає `127.0.0.1` усередині контейнера. За bridge-мережі Docker (`-p 18789:18789`) трафік надходить на `eth0`, тому gateway недоступний. Використовуйте `--network host`, або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. +- **Auth**: типово обов’язкова. Для bind не на loopback потрібна автентифікація gateway. На практиці це означає спільний token/password або reverse proxy з урахуванням identity із `gateway.auth.mode: "trusted-proxy"`. Wizard онбордингу типово генерує token. +- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Запуск, а також потоки встановлення/відновлення сервісу завершуються помилкою, якщо налаштовано обидва значення, а mode не задано. +- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних налаштувань loopback; цей варіант навмисно не пропонується в підказках онбордингу. +- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з урахуванням identity і довіряти заголовкам identity від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **джерело проксі не на loopback**; reverse proxy на тому самому хості через loopback не задовольняють вимоги trusted-proxy auth. +- `gateway.auth.allowTailscale`: коли `true`, заголовки identity Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). HTTP API endpoint **не** використовують цю auth заголовками Tailscale; вони дотримуються звичайного режиму HTTP auth gateway. Цей безтокеновий потік передбачає, що хост gateway є довіреним. Типове значення — `true`, коли `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб auth. Застосовується для кожної IP-адреси клієнта та для кожної області auth (спільний секрет і токен пристрою відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. + - В асинхронному шляху Tailscale Serve для Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом помилки. Тому одночасні хибні спроби від одного клієнта можуть спровокувати спрацьовування обмежувача вже на другому запиті, замість того щоб обидва запити пройшли як звичайні невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; установіть `false`, якщо ви свідомо хочете також обмежувати трафік localhost (для тестових конфігурацій або суворих проксі-розгортань). +- Спроби auth для WS із походження браузера завжди обмежуються, причому виняток для loopback вимкнено (додатковий захист від браузерного brute force на localhost). +- На loopback ці блокування для походження браузера ізольовані за нормалізованим + значенням `Origin`, тому повторні невдалі спроби з одного походження localhost не + блокують автоматично інше походження. +- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічно, потребує auth). +- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються клієнти браузера не з loopback-origin. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервний механізм origin на основі заголовка Host для розгортань, що свідомо покладаються на політику origin через Host-header. +- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське аварійне перевизначення, що дозволяє незашифрований `ws://` до довірених IP приватної мережі; типово незашифрований трафік лишається дозволеним лише для loopback. - `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway. -- `gateway.push.apns.relay.baseUrl`: базова HTTPS URL-адреса зовнішнього APNs relay, який використовують офіційні/TestFlight збірки iOS після публікації реєстрацій relay-backed у gateway. Ця URL-адреса має збігатися з URL relay, скомпільованою в збірку iOS. -- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання gateway-to-relay у мілісекундах. Типово `10000`. -- Реєстрації relay-backed делегуються конкретній identity gateway. Спарений застосунок iOS викликає `gateway.identity.get`, включає цю identity в реєстрацію relay і передає gateway право надсилання, прив’язане до реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові env-перевизначення для наведеної вище конфігурації relay. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: лише для розробки, аварійний дозвіл на loopback HTTP relay URL. У production URL relay мають лишатися на HTTPS. -- `gateway.channelHealthCheckMinutes`: інтервал моніторингу здоров’я каналів у хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски монітора здоров’я. Типово: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого socket у хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`. -- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора здоров’я для каналу/облікового запису за ковзну годину. Типово: `10`. -- `channels..healthMonitor.enabled`: відмова для окремого каналу від перезапусків монітора здоров’я, залишаючи глобальний монітор увімкненим. -- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису в багатооблікових каналах. Якщо задано, має пріоритет над перевизначенням на рівні каналу. +- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL для зовнішнього relay APNs, який використовують офіційні/TestFlight збірки iOS після публікації реєстрацій relay-backed у gateway. Цей URL має збігатися з URL relay, зібраним у збірці iOS. +- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. Типове значення: `10000`. +- Реєстрації на основі relay делегуються конкретній identity gateway. Пов’язана програма iOS отримує `gateway.identity.get`, включає цю identity у реєстрацію relay і пересилає gateway дозвіл на надсилання в області цієї реєстрації. Інший gateway не може повторно використати таку збережену реєстрацію. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення через env для наведеної вище конфігурації relay. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний механізм лише для розробки, що дозволяє loopback HTTP URL для relay. URL relay у продакшені мають залишатися на HTTPS. +- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типове значення: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor на канал/обліковий запис за ковзну годину. Типове значення: `10`. +- `channels..healthMonitor.enabled`: вимкнення перезапусків health-monitor для окремого каналу за збереження глобального монітора ввімкненим. +- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису в каналах із кількома обліковими записами. Якщо задано, має пріоритет над перевизначенням на рівні каналу. - Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не визначено, визначення завершується fail-closed (без маскування через резервний remote fallback). -- `trustedProxies`: IP reverse proxy, які завершують TLS або вставляють заголовки forwarded-client. Перелічуйте лише проксі, які ви контролюєте. Записи loopback усе ще дійсні для конфігурацій проксі на тому ж хості/локального виявлення (наприклад Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. Типово `false` для fail-closed поведінки. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef, але їх не вдалося визначити, визначення завершується із закритою відмовою (без маскування резервним fallback до remote). +- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або додають заголовки переадресованого клієнта. Вказуйте лише проксі, які ви контролюєте. Записи loopback усе ще є дійсними для конфігурацій same-host proxy/local-detection (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять запити loopback придатними для `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо відсутній `X-Forwarded-For`. Типове значення `false` для поведінки fail-closed. - `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список заборон). -- `gateway.tools.allow`: вилучає назви інструментів із типового HTTP-списку заборон. +- `gateway.tools.allow`: прибирає назви інструментів із типового списку HTTP-заборон. @@ -3124,10 +3125,10 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Порожні списки дозволених трактуються як відсутні; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` - і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання за URL. + Порожні списки дозволених розглядаються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` + і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання через URL. - Необов’язковий заголовок посиленого захисту відповіді: - - `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для HTTPS origin, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + - `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для HTTPS-origin, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Ізоляція кількох екземплярів @@ -3139,7 +3140,7 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -Зручні прапорці: `--dev` (використовує `~/.openclaw-dev` + порт `19001`), `--profile ` (використовує `~/.openclaw-`). +Зручні прапори: `--dev` (використовує `~/.openclaw-dev` + порт `19001`), `--profile ` (використовує `~/.openclaw-`). Див. [Multiple Gateways](/uk/gateway/multiple-gateways). @@ -3159,11 +3160,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). -- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовані; лише для локального/dev використання. -- `certPath`: шлях у файловій системі до файла TLS-сертифіката. -- `keyPath`: шлях у файловій системі до файла приватного ключа TLS; обмежте доступ правами. -- `caPath`: необов’язковий шлях до CA bundle для перевірки клієнта або власних ланцюгів довіри. +- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типове значення: `false`). +- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для локального/dev використання. +- `certPath`: шлях у файловій системі до файла сертифіката TLS. +- `keyPath`: шлях у файловій системі до файла приватного ключа TLS; обмежте до нього права доступу. +- `caPath`: необов’язковий шлях до набору CA для перевірки клієнта або користувацьких ланцюжків довіри. ### `gateway.reload` @@ -3180,12 +3181,12 @@ openclaw gateway --port 19001 ``` - `mode`: керує тим, як зміни конфігурації застосовуються під час runtime. - - `"off"`: ігнорувати live-редагування; зміни потребують явного перезапуску. + - `"off"`: ігнорувати зміни в реальному часі; для змін потрібен явний перезапуск. - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації. - `"hot"`: застосовувати зміни в процесі без перезапуску. - - `"hybrid"` (типово): спочатку пробувати hot reload; якщо потрібно — переходити до restart. + - `"hybrid"` (типово): спочатку спробувати hot reload; якщо потрібно, перейти до перезапуску. - `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число). -- `deferralTimeoutMs`: максимальний час у мс очікування завершення поточних операцій перед примусовим перезапуском (типово: `300000` = 5 хвилин). +- `deferralTimeoutMs`: максимальний час у мс очікування поточних операцій перед примусовим перезапуском (типово: `300000` = 5 хвилин). --- @@ -3223,15 +3224,15 @@ openclaw gateway --port 19001 ``` Auth: `Authorization: Bearer ` або `x-openclaw-token: `. -Hook-токени в query string відхиляються. +Токени hooks у рядку запиту відхиляються. Примітки щодо валідації та безпеки: -- `hooks.enabled=true` потребує непорожній `hooks.token`. +- `hooks.enabled=true` вимагає непорожнього `hooks.token`. - `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання токена Gateway відхиляється. - `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`. -- Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). -- Якщо mapping або preset використовує шаблонізований `sessionKey`, установіть `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не потребують цього opt-in. +- Якщо `hooks.allowRequestSessionKey=true`, обмежуйте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). +- Якщо mapping або preset використовує шаблонізований `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не вимагають цього opt-in. **Endpoint:** @@ -3239,30 +3240,30 @@ Hook-токени в query string відхиляються. - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - `sessionKey` із payload запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`). - `POST /hooks/` → визначається через `hooks.mappings` - - Значення `sessionKey` у mapping, згенеровані шаблоном, вважаються зовнішньо переданими і також потребують `hooks.allowRequestSessionKey=true`. + - Значення `sessionKey` у mapping, згенеровані шаблоном, розглядаються як зовнішньо надані й також вимагають `hooks.allowRequestSessionKey=true`. - + -- `match.path` зіставляється з підшляхом після `/hooks` (наприклад `/hooks/gmail` → `gmail`). -- `match.source` зіставляється з полем payload для загальних шляхів. -- Шаблони на кшталт `{{messages[0].subject}}` читають дані з payload. -- `transform` може вказувати на модуль JS/TS, який повертає дію hook. - - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються). -- `agentId` маршрутизує до конкретного агента; невідомі ID використовують резервно типового агента. -- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити всі, `[]` = заборонити всі). +- `match.path` зіставляє підшлях після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). +- `match.source` зіставляє поле payload для загальних шляхів. +- Шаблони на кшталт `{{messages[0].subject}}` читають значення з payload. +- `transform` може вказувати на модуль JS/TS, що повертає дію hook. + - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи й traversal відхиляються). +- `agentId` маршрутизує до конкретного агента; невідомі ID резервно спрямовуються до типового агента. +- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити все, `[]` = заборонити все). - `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook-агента без явного `sessionKey`. -- `allowRequestSessionKey`: дозволити викликачам `/hooks/agent` і session key у mapping, керованих шаблонами, встановлювати `sessionKey` (типово: `false`). +- `allowRequestSessionKey`: дозволяє викликачу `/hooks/agent` і ключам сесій mapping, керованим шаблоном, задавати `sessionKey` (типово: `false`). - `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`. - `deliver: true` надсилає фінальну відповідь у канал; `channel` типово дорівнює `last`. -- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо налаштовано каталог моделей). +- `model` перевизначає LLM для цього запуску hook (має бути дозволений, якщо задано каталог моделей). ### Інтеграція Gmail - Вбудований preset Gmail використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`. -- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes` так, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. -- Якщо вам потрібно `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість типового шаблонізованого. +- Якщо ви зберігаєте таку маршрутизацію для кожного повідомлення, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes`, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. +- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість шаблонного типового значення. ```json5 { @@ -3290,7 +3291,7 @@ Hook-токени в query string відхиляються. --- -## Хост canvas +## Хост Canvas ```json5 { @@ -3302,17 +3303,17 @@ Hook-токени в query string відхиляються. } ``` -- Обслуговує HTML/CSS/JS і A2UI, які може редагувати агент, через HTTP на порту Gateway: +- Обслуговує HTML/CSS/JS і A2UI, які може редагувати агент, через HTTP під портом Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Лише локально: залишайте `gateway.bind: "loopback"` (типово). -- Для non-loopback bind: маршрути canvas потребують auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway. -- WebView Node зазвичай не надсилають заголовки auth; після сполучення та підключення node Gateway оголошує URL можливостей, прив’язані до node, для доступу до canvas/A2UI. -- URL можливостей прив’язані до активної WS-сесії node і швидко спливають. Резервний варіант на основі IP не використовується. -- Вставляє клієнт live-reload у HTML, що обслуговується. +- Лише локально: зберігайте `gateway.bind: "loopback"` (типово). +- Для bind не на loopback: маршрути canvas вимагають auth Gateway (token/password/trusted-proxy), так само як і інші HTTP-поверхні Gateway. +- Node WebView зазвичай не надсилають заголовки auth; після сполучення та підключення Node Gateway рекламує URL можливостей із областю Node для доступу до canvas/A2UI. +- URL можливостей прив’язані до активної WS-сесії Node і швидко спливають. Резервний варіант на основі IP не використовується. +- Вбудовує клієнт live-reload у відданий HTML. - Автоматично створює початковий `index.html`, якщо каталог порожній. - Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`. -- Зміни потребують перезапуску gateway. +- Зміни вимагають перезапуску gateway. - Вимкніть live reload для великих каталогів або при помилках `EMFILE`. --- @@ -3331,11 +3332,11 @@ Hook-токени в query string відхиляються. } ``` -- `minimal` (типово): не включає `cliPath` + `sshPort` у TXT-записи. -- `full`: включає `cliPath` + `sshPort`. -- Ім’я хоста типово `openclaw`. Перевизначається через `OPENCLAW_MDNS_HOSTNAME`. +- `minimal` (типово): не включати `cliPath` + `sshPort` у TXT-записи. +- `full`: включати `cliPath` + `sshPort`. +- Ім’я хоста типово дорівнює `openclaw`. Перевизначається через `OPENCLAW_MDNS_HOSTNAME`. -### Wide-area (DNS-SD) +### Широка область (DNS-SD) ```json5 { @@ -3345,7 +3346,7 @@ Hook-токени в query string відхиляються. } ``` -Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS у Tailscale. +Записує уніфіковану зону DNS-SD в `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте це з DNS-сервером (рекомендовано CoreDNS) + split DNS у Tailscale. Налаштування: `openclaw dns setup --apply`. @@ -3353,7 +3354,7 @@ Hook-токени в query string відхиляються. ## Середовище -### `env` (вбудовані env-змінні) +### `env` (вбудовані змінні середовища) ```json5 { @@ -3370,14 +3371,14 @@ Hook-токени в query string відхиляються. } ``` -- Вбудовані env-змінні застосовуються лише тоді, коли в середовищі процесу відсутній цей ключ. -- Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден не перевизначає наявні змінні). +- Вбудовані змінні середовища застосовуються лише тоді, коли в середовищі процесу відсутній відповідний ключ. +- Файли `.env`: `.env` у CWD + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). - `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. -- Повний порядок пріоритету див. у [Environment](/uk/help/environment). +- Повний пріоритет див. у [Environment](/uk/help/environment). -### Підстановка env-змінних +### Підстановка змінних середовища -Посилайтеся на env-змінні в будь-якому рядку конфігурації через `${VAR_NAME}`: +Посилайтеся на змінні середовища в будь-якому рядку конфігурації через `${VAR_NAME}`: ```json5 { @@ -3387,16 +3388,16 @@ Hook-токени в query string відхиляються. } ``` -- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. +- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні/порожні змінні викликають помилку під час завантаження конфігурації. -- Екрануйте через `$${VAR}` для буквального `${VAR}`. +- Екрануйте як `$${VAR}` для буквального `${VAR}`. - Працює з `$include`. --- ## Секрети -Посилання на секрети є додатковими: текстові значення також продовжують працювати. +Посилання на секрети є адитивними: відкриті значення й далі працюють. ### `SecretRef` @@ -3410,15 +3411,15 @@ Hook-токени в query string відхиляються. - шаблон `provider`: `^[a-z][a-z0-9_-]{0,63}$` - шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` `id`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`) +- `source: "file"` `id`: абсолютний JSON pointer (наприклад, `"/providers/openai/apiKey"`) - шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `id` для `source: "exec"` не повинні містити сегментів шляху `.` або `..`, розділених `/` (наприклад `a/../b` відхиляється) +- `id` для `source: "exec"` не мають містити сегментів шляху `.` або `..`, розділених `/` (наприклад, `a/../b` відхиляється) ### Підтримувана поверхня облікових даних - Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface) - `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`. -- Посилання з `auth-profiles.json` включені у визначення під час runtime і покриття аудиту. +- Посилання в `auth-profiles.json` включені до визначення runtime і покриття аудиту. ### Конфігурація провайдерів секретів @@ -3450,13 +3451,13 @@ Hook-токени в query string відхиляються. Примітки: -- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має бути `"value"`). -- Провайдер `exec` потребує абсолютного шляху в `command` і використовує протокольні payload через stdin/stdout. -- Типово шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи symlink, перевіряючи шлях до визначеної цілі. +- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (`id` має бути `"value"` у режимі singleValue). +- Провайдер `exec` вимагає абсолютного шляху `command` і використовує payload протоколу через stdin/stdout. +- Типово шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання з перевіркою шляху визначеної цілі. - Якщо налаштовано `trustedDirs`, перевірка trusted-dir застосовується до шляху визначеної цілі. -- Середовище дочірнього процесу `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`. -- Посилання на секрети визначаються під час активації в знімок у пам’яті, а далі шляхи запитів читають лише цей знімок. -- Під час активації застосовується фільтрація активної поверхні: невизначені посилання на увімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. +- Середовище дочірнього процесу `exec` типово є мінімальним; явно передавайте потрібні змінні через `passEnv`. +- Посилання на секрети визначаються під час активації в знімок у пам’яті, після чого шляхи запиту читають лише цей знімок. +- Під час активації застосовується фільтрація активної поверхні: невизначені посилання на ввімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. --- @@ -3479,10 +3480,10 @@ Hook-токени в query string відхиляються. ``` - Профілі для окремого агента зберігаються в `/auth-profiles.json`. -- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для режимів статичних облікових даних. +- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. - Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані auth-profile на основі SecretRef. -- Статичні runtime-облікові дані беруться з визначених знімків у пам’яті; застарілі статичні записи `auth.json` очищуються при виявленні. -- Застарілий імпорт OAuth із `~/.openclaw/credentials/oauth.json`. +- Статичні облікові дані runtime беруться з визначених знімків у пам’яті; застарілі статичні записи `auth.json` очищаються при виявленні. +- Застарілий імпорт OAuth виконується з `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). - Поведінка runtime секретів і інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). @@ -3507,19 +3508,19 @@ Hook-токени в query string відхиляються. ``` - `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні - billing/insufficient-credit помилки (типово: `5`). Явний текст billing може - потрапити сюди навіть при відповідях `401`/`403`, але текстові - зіставлювачі для конкретних провайдерів лишаються обмеженими провайдером, якому вони належать (наприклад OpenRouter - `Key limit exceeded`). Повторювані повідомлення HTTP `402` про usage-window або - organization/workspace spend-limit натомість лишаються в гілці `rate_limit`. + помилки billing/недостатній кредит (типово: `5`). Явний текст про billing усе ще + може потрапляти сюди навіть у відповідях `401`/`403`, але текстові зіставлення, + специфічні для провайдера, залишаються в межах провайдера, якому вони належать (наприклад, OpenRouter + `Key limit exceeded`). Повторювані повідомлення HTTP `402` про вікно використання або + ліміти витрат organization/workspace натомість залишаються в шляху `rate_limit`. - `billingBackoffHoursByProvider`: необов’язкові перевизначення годин billing backoff для окремих провайдерів. -- `billingMaxHours`: верхня межа в годинах для експоненційного зростання billing backoff (типово: `24`). -- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для high-confidence збоїв `auth_permanent` (типово: `10`). -- `authPermanentMaxMinutes`: верхня межа в хвилинах для зростання backoff `auth_permanent` (типово: `60`). -- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників backoff (типово: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile в межах того самого провайдера для помилок перевантаження перед переходом до резервної моделі (типово: `1`). Сюди потрапляють форми "провайдер зайнятий", як-от `ModelNotReadyException`. +- `billingMaxHours`: обмеження в годинах для експоненційного зростання billing backoff (типово: `24`). +- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для високовпевнених збоїв `auth_permanent` (типово: `10`). +- `authPermanentMaxMinutes`: обмеження в хвилинах для зростання backoff `auth_permanent` (типово: `60`). +- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників backoff (типово: `24`). +- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile в межах одного провайдера для помилок перевантаження перед переходом до fallback моделі (типово: `1`). Сюди потрапляють форми на кшталт `ModelNotReadyException`, коли провайдер зайнятий. - `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile в межах того самого провайдера для помилок rate-limit перед переходом до резервної моделі (типово: `1`). Цей кошик rate-limit включає формулювання провайдера на кшталт `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile в межах одного провайдера для помилок rate-limit перед переходом до fallback моделі (типово: `1`). Цей кошик rate-limit включає текстові форми провайдерів, такі як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- @@ -3540,8 +3541,8 @@ Hook-токени в query string відхиляються. - Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Установіть `logging.file` для стабільного шляху. -- `consoleLevel` підвищується до `debug`, коли використовується `--verbose`. -- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис пригнічується (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. +- `consoleLevel` підвищується до `debug` з `--verbose`. +- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис пригнічується (додатне ціле число; типово: `524288000` = 500 MB). Для продакшен-розгортань використовуйте зовнішню ротацію логів. --- @@ -3579,19 +3580,19 @@ Hook-токени в query string відхиляються. ``` - `enabled`: головний перемикач для виводу інструментування (типово: `true`). -- `flags`: масив рядків-прапорців, що вмикають цільовий вивід журналу (підтримує шаблони з `*`, наприклад `"telegram.*"` або `"*"`). -- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислі сесії, поки сесія лишається в стані обробки. +- `flags`: масив рядків-прапорів, що вмикають цільовий вивід у журнал (підтримуються wildcard, такі як `"telegram.*"` або `"*"`). +- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислу сесію, поки сесія залишається в стані обробки. - `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). - `otel.endpoint`: URL колектора для експорту OTel. - `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`. -- `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel. -- `otel.serviceName`: назва сервісу для атрибутів ресурсу. +- `otel.headers`: додаткові заголовки HTTP/gRPC metadata, що надсилаються з запитами експорту OTel. +- `otel.serviceName`: ім’я сервісу для атрибутів ресурсу. - `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або logs. -- `otel.sampleRate`: частота вибірки trace `0`–`1`. -- `otel.flushIntervalMs`: періодичний інтервал скидання телеметрії в мс. -- `cacheTrace.enabled`: журналювати знімки cache trace для вбудованих запусків (типово: `false`). -- `cacheTrace.filePath`: шлях виводу для cache trace JSONL (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід cache trace (усе типово: `true`). +- `otel.sampleRate`: коефіцієнт семплювання trace `0`–`1`. +- `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс. +- `cacheTrace.enabled`: журналювати знімки трасування кешу для вбудованих запусків (типово: `false`). +- `cacheTrace.filePath`: шлях виводу для JSONL трасування кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід трасування кешу (усі типово: `true`). --- @@ -3615,10 +3616,10 @@ Hook-токени в query string відхиляються. - `channel`: канал релізів для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`. - `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`). -- `auto.enabled`: увімкнути фонове автооновлення для пакетних встановлень (типово: `false`). -- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням stable-каналу (типово: `6`; максимум: `168`). -- `auto.stableJitterHours`: додаткове вікно розподілу stable-каналу в годинах (типово: `12`; максимум: `168`). -- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу, у годинах (типово: `1`; максимум: `24`). +- `auto.enabled`: увімкнути фонове автооновлення для встановлень пакетів (типово: `false`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням для каналу stable (типово: `6`; максимум: `168`). +- `auto.stableJitterHours`: додаткове вікно розтягування розгортання stable у годинах (типово: `12`; максимум: `168`). +- `auto.betaCheckIntervalHours`: як часто виконуються перевірки каналу beta, у годинах (типово: `1`; максимум: `24`). --- @@ -3652,20 +3653,20 @@ Hook-токени в query string відхиляються. ``` - `enabled`: глобальний feature gate для ACP (типово: `false`). -- `dispatch.enabled`: незалежний gate для dispatch ходів ACP-сесій (типово: `true`). Установіть `false`, щоб лишити ACP-команди доступними, але блокувати виконання. -- `backend`: id типового runtime-бекенда ACP (має відповідати зареєстрованому ACP runtime Plugin). -- `defaultAgent`: резервний id цільового агента ACP, коли spawns не задають явну ціль. -- `allowedAgents`: список дозволених id агентів для runtime-сесій ACP; порожнє значення означає відсутність додаткового обмеження. -- `maxConcurrentSessions`: максимальна кількість одночасно активних ACP-сесій. -- `stream.coalesceIdleMs`: вікно скидання idle у мс для потокового тексту. -- `stream.maxChunkChars`: максимальний розмір chunk перед розбиттям проєкції потокового блока. +- `dispatch.enabled`: незалежний gate для диспетчеризації ходів сесій ACP (типово: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання. +- `backend`: id типового backend runtime ACP (має збігатися із зареєстрованим Plugin runtime ACP). +- `defaultAgent`: резервний id цільового агента ACP, коли spawn не задає явну ціль. +- `allowedAgents`: список дозволених id агентів для runtime-сесій ACP; порожнє значення означає відсутність додаткових обмежень. +- `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP. +- `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту. +- `stream.maxChunkChars`: максимальний розмір чанка перед розбиттям проєкції потокового блока. - `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів у межах одного ходу (типово: `true`). -- `stream.deliveryMode`: `"live"` транслює поступово; `"final_only"` буферизує до термінальних подій ходу. +- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до термінальних подій ходу. - `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`). -- `stream.maxOutputChars`: максимальна кількість символів виводу помічника, що проєктується за один ACP-хід. -- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлення ACP. -- `stream.tagVisibility`: запис назв тегів у зіставленні з булевими перевизначеннями видимості для потокових подій. -- `runtime.ttlMinutes`: idle TTL у хвилинах для воркерів ACP-сесій до моменту, коли вони стають придатними до очищення. +- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, що проєктуються за хід ACP. +- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлень ACP. +- `stream.tagVisibility`: запис імен тегів до булевих перевизначень видимості для потокових подій. +- `runtime.ttlMinutes`: idle TTL у хвилинах для робочих процесів сесій ACP до того, як вони стануть придатними для очищення. - `runtime.installCommand`: необов’язкова команда встановлення, яку слід виконати під час bootstrap середовища runtime ACP. --- @@ -3682,17 +3683,17 @@ Hook-токени в query string відхиляються. } ``` -- `cli.banner.taglineMode` керує стилем слогана banner: - - `"random"` (типово): ротаційні кумедні/сезонні слогани. +- `cli.banner.taglineMode` керує стилем слогана банера: + - `"random"` (типово): змінні кумедні/сезонні слогани. - `"default"`: фіксований нейтральний слоган (`All your chats, one OpenClaw.`). - - `"off"`: без тексту слогана (заголовок/версія banner усе одно показуються). -- Щоб приховати весь banner (а не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`. + - `"off"`: без тексту слогана (заголовок/версія банера все одно показуються). +- Щоб приховати весь банер (а не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Метадані, які записуються потоками покрокового налаштування CLI (`onboard`, `configure`, `doctor`): +Метадані, які записуються потоками керованого налаштування CLI (`onboard`, `configure`, `doctor`): ```json5 { @@ -3710,13 +3711,13 @@ Hook-токени в query string відхиляються. ## Identity -Див. поля identity у `agents.list` у розділі [Типові значення агентів](#agent-defaults). +Див. поля identity у `agents.list` у розділі [Типові значення агента](#agent-defaults). --- -## Bridge (застарілий, вилучений) +## Bridge (застаріле, вилучено) -Поточні збірки більше не включають TCP bridge. Node підключаються через Gateway WebSocket. Ключі `bridge.*` більше не входять до схеми конфігурації (валідація завершується помилкою, доки їх не буде вилучено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP bridge. Node підключаються через WebSocket Gateway. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). @@ -3756,11 +3757,11 @@ Hook-токени в query string відхиляються. } ``` -- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків Cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених стенограм Cron. Типово: `24h`; установіть `false`, щоб вимкнути. -- `runLog.maxBytes`: максимальний розмір файла журналу одного запуску (`cron/runs/.jsonl`) перед очищенням. Типово: `2_000_000` байтів. -- `runLog.keepLines`: найновіші рядки, які зберігаються при спрацюванні очищення журналу запуску. Типово: `2000`. -- `webhookToken`: bearer token, що використовується для доставки webhook POST у Cron (`delivery.mode = "webhook"`); якщо пропущено, заголовок auth не надсилається. -- `webhook`: застаріла legacy fallback URL-адреса webhook (http/https), що використовується лише для збережених завдань, у яких досі встановлено `notify: true`. +- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків Cron перед видаленням із `sessions.json`. Також керує очищенням архівованих видалених стенограм Cron. Типове значення: `24h`; установіть `false`, щоб вимкнути. +- `runLog.maxBytes`: максимальний розмір файла журналу одного запуску (`cron/runs/.jsonl`) перед обрізанням. Типове значення: `2_000_000` байтів. +- `runLog.keepLines`: найновіші рядки, які зберігаються, коли спрацьовує обрізання журналу запуску. Типове значення: `2000`. +- `webhookToken`: bearer token, який використовується для доставки POST через webhook Cron (`delivery.mode = "webhook"`); якщо пропущено, заголовок auth не надсилається. +- `webhook`: застарілий резервний URL webhook (http/https), який використовується лише для збережених завдань, що досі мають `notify: true`. ### `cron.retry` @@ -3778,9 +3779,9 @@ Hook-токени в query string відхиляються. - `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (типово: `3`; діапазон: `0`–`10`). - `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). -- `retryOn`: типи помилок, що запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати всі тимчасові типи. +- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати всі тимчасові типи. -Застосовується лише до одноразових завдань Cron. Повторювані завдання мають окрему обробку збоїв. +Застосовується лише до одноразових завдань Cron. Для повторюваних завдань використовується окрема обробка збоїв. ### `cron.failureAlert` @@ -3799,10 +3800,10 @@ Hook-токени в query string відхиляються. ``` - `enabled`: увімкнути сповіщення про збої для завдань Cron (типово: `false`). -- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мінімум: `1`). +- `after`: кількість послідовних збоїв, після яких спрацьовує сповіщення (додатне ціле число, мінімум: `1`). - `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). -- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST на налаштований Webhook. -- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки сповіщення. +- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` публікує в налаштований webhook. +- `accountId`: необов’язковий id облікового запису або каналу для області доставки сповіщення. ### `cron.failureDestination` @@ -3819,51 +3820,51 @@ Hook-токени в query string відхиляються. } ``` -- Типова ціль для сповіщень про збої Cron для всіх завдань. -- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних про ціль. +- Типова ціль для сповіщень про збої Cron у всіх завданнях. +- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли існує достатньо даних цілі. - `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки. -- `to`: явна ціль announce або URL Webhook. Обов’язково для режиму webhook. +- `to`: явна ціль announce або URL webhook. Обов’язкове для режиму webhook. - `accountId`: необов’язкове перевизначення облікового запису для доставки. -- `delivery.failureDestination` для конкретного завдання перевизначає це глобальне типове значення. -- Якщо не задано ні глобальну, ні окрему ціль збоїв, завдання, які вже доставляють через `announce`, у разі збою використовують резервно цю основну ціль announce. -- `delivery.failureDestination` підтримується лише для завдань із `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`. +- `delivery.failureDestination` для окремого завдання перевизначає це глобальне типове значення. +- Якщо не задано ні глобальної, ні окремої цілі збоїв, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної цілі announce. +- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`. -Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [фонові завдання](/uk/automation/tasks). +Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [background tasks](/uk/automation/tasks). --- ## Змінні шаблону моделі медіа -Плейсхолдери шаблону, що розгортаються в `tools.media.models[].args`: +Заповнювачі шаблону, які розгортаються в `tools.media.models[].args`: -| Змінна | Опис | -| ----------------- | ----------------------------------------------- | -| `{{Body}}` | Повний текст вхідного повідомлення | -| `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) | -| `{{BodyStripped}}`| Текст без згадувань у групі | -| `{{From}}` | Ідентифікатор відправника | -| `{{To}}` | Ідентифікатор одержувача | -| `{{MessageSid}}` | ID повідомлення каналу | -| `{{SessionId}}` | UUID поточної сесії | -| `{{IsNewSession}}`| `"true"`, коли створено нову сесію | -| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | -| `{{MediaPath}}` | Локальний шлях до медіа | -| `{{MediaType}}` | Тип медіа (image/audio/document/…) | -| `{{Transcript}}` | Аудіостенограма | -| `{{Prompt}}` | Визначений media prompt для записів CLI | -| `{{MaxChars}}` | Визначена максимальна кількість вихідних символів для записів CLI | -| `{{ChatType}}` | `"direct"` або `"group"` | -| `{{GroupSubject}}`| Тема групи (best effort) | -| `{{GroupMembers}}`| Попередній перегляд учасників групи (best effort) | -| `{{SenderName}}` | Відображуване ім’я відправника (best effort) | -| `{{SenderE164}}` | Номер телефону відправника (best effort) | +| Змінна | Опис | +| ----------------- | ------------------------------------------------- | +| `{{Body}}` | Повний текст вхідного повідомлення | +| `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) | +| `{{BodyStripped}}` | Текст із вилученими згадуваннями групи | +| `{{From}}` | Ідентифікатор відправника | +| `{{To}}` | Ідентифікатор призначення | +| `{{MessageSid}}` | ID повідомлення каналу | +| `{{SessionId}}` | UUID поточної сесії | +| `{{IsNewSession}}` | `"true"`, коли створено нову сесію | +| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | +| `{{MediaPath}}` | Локальний шлях до медіа | +| `{{MediaType}}` | Тип медіа (image/audio/document/…) | +| `{{Transcript}}` | Аудіостенограма | +| `{{Prompt}}` | Визначений запит медіа для записів CLI | +| `{{MaxChars}}` | Визначена максимальна кількість символів виводу для записів CLI | +| `{{ChatType}}` | `"direct"` або `"group"` | +| `{{GroupSubject}}` | Тема групи (best effort) | +| `{{GroupMembers}}` | Попередній перегляд учасників групи (best effort) | +| `{{SenderName}}` | Ім’я відображення відправника (best effort) | +| `{{SenderE164}}` | Номер телефону відправника (best effort) | | `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | --- ## Include конфігурації (`$include`) -Розбивайте конфігурацію на кілька файлів: +Розділяйте конфігурацію на кілька файлів: ```json5 // ~/.openclaw/openclaw.json @@ -3878,12 +3879,12 @@ Hook-токени в query string відхиляються. **Поведінка злиття:** -- Один файл: замінює об’єкт-контейнер. -- Масив файлів: глибоко зливається по порядку (пізніші перевизначають попередні). +- Один файл: замінює об’єкт, у якому міститься. +- Масив файлів: глибоко зливається по порядку (пізніші значення перевизначають попередні). - Сусідні ключі: зливаються після include (перевизначають включені значення). - Вкладені include: до 10 рівнів глибини. -- Шляхи: визначаються відносно файла, який включає, але мають залишатися всередині каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли вони все одно визначаються в межах цього кордону. -- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок розбору та циклічних include. +- Шляхи: визначаються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/форми з `../` дозволені лише тоді, коли після визначення вони все одно залишаються в цих межах. +- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок парсингу та циклічних include. --- diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index 61f727360..2a09c7291 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -1,62 +1,49 @@ --- read_when: - Ви хочете використовувати комплектний app-server harness Codex - - Вам потрібні посилання на модель Codex і приклади конфігурації - - Ви хочете вимкнути резервний перехід до PI для розгортань лише з Codex + - Вам потрібні посилання на моделі Codex і приклади конфігурації + - Ви хочете вимкнути резервне перемикання на PI для розгортань лише з Codex summary: Запускайте вбудовані ходи агента OpenClaw через комплектний app-server harness Codex title: Harness Codex x-i18n: - generated_at: "2026-04-21T00:08:16Z" + generated_at: "2026-04-22T05:35:01Z" model: gpt-5.4 provider: openai - source_hash: 3f0cdaf68be3b2257de1046103ff04f53f9d3a65ffc15ab7af5ab1f425643d6c + source_hash: d45dbd39a7d8ebb3a39d8dca3a5125c07b7168d1658ca07b85792645fb98613c source_path: plugins/codex-harness.md workflow: 15 --- # Harness Codex -Комплектний plugin `codex` дає OpenClaw змогу запускати вбудовані ходи агента через -app-server Codex замість вбудованого harness PI. +Комплектний plugin `codex` дає OpenClaw змогу запускати вбудовані ходи агента через app-server Codex замість вбудованого harness PI. -Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням -моделей, нативним відновленням потоку, нативною Compaction і виконанням app-server. -OpenClaw і далі керує каналами чату, файлами сесії, вибором моделі, інструментами, -схваленнями, доставкою медіа та видимим дзеркалом транскрипту. +Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням моделей, нативним відновленням потоку, нативною Compaction і виконанням app-server. OpenClaw, як і раніше, керує чат-каналами, файлами сесії, вибором моделі, інструментами, погодженнями, доставкою медіа та видимим дзеркалом транскрипту. -За замовчуванням harness вимкнений. Він вибирається лише тоді, коли plugin `codex` -увімкнений і розв’язана модель є моделлю `codex/*`, або коли ви явно -примусово задаєте `embeddedHarness.runtime: "codex"` чи `OPENCLAW_AGENT_RUNTIME=codex`. -Якщо ви ніколи не налаштовуєте `codex/*`, наявні запуски PI, OpenAI, Anthropic, Gemini, local -і custom-provider зберігають свою поточну поведінку. +За замовчуванням harness вимкнений. Він вибирається лише тоді, коли plugin `codex` увімкнено і визначена модель є моделлю `codex/*`, або коли ви явно примусово задаєте `embeddedHarness.runtime: "codex"` чи `OPENCLAW_AGENT_RUNTIME=codex`. +Якщо ви ніколи не налаштовуєте `codex/*`, наявні запуски PI, OpenAI, Anthropic, Gemini, local і custom-provider зберігають поточну поведінку. ## Виберіть правильний префікс моделі -OpenClaw має окремі маршрути для доступу у формі OpenAI та Codex: +OpenClaw має окремі маршрути для доступу у форматі OpenAI і Codex: -| Посилання на модель | Шлях runtime | Використовуйте, коли | -| --------------------- | ------------------------------------------- | ------------------------------------------------------------------------ | -| `openai/gpt-5.4` | Провайдер OpenAI через конвеєр OpenClaw/PI | Вам потрібен прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.4` | Провайдер OpenAI Codex OAuth через PI | Вам потрібен ChatGPT/Codex OAuth без harness app-server Codex. | +| Посилання на модель | Шлях виконання | Використовуйте, коли | +| --------------------- | ------------------------------------------- | ----------------------------------------------------------------------- | +| `openai/gpt-5.4` | Провайдер OpenAI через інфраструктуру OpenClaw/PI | Вам потрібен прямий доступ до OpenAI Platform API за допомогою `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.4` | Провайдер OpenAI Codex OAuth через PI | Вам потрібен ChatGPT/Codex OAuth без harness app-server Codex. | | `codex/gpt-5.4` | Комплектний провайдер Codex плюс harness Codex | Вам потрібне нативне виконання app-server Codex для вбудованого ходу агента. | -Harness Codex обробляє лише посилання на моделі `codex/*`. Наявні посилання `openai/*`, -`openai-codex/*`, Anthropic, Gemini, xAI, local і custom provider зберігають -свої звичайні шляхи. +Harness Codex обробляє лише посилання на моделі `codex/*`. Наявні посилання на провайдери `openai/*`, `openai-codex/*`, Anthropic, Gemini, xAI, local і custom зберігають свої звичайні шляхи. ## Вимоги - OpenClaw із доступним комплектним plugin `codex`. -- app-server Codex `0.118.0` або новіший. -- Доступна автентифікація Codex для процесу app-server. +- 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`, а також -необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і -`~/.codex/config.toml`. Використовуйте ті самі дані автентифікації, що й ваш локальний -app-server Codex. +Для live- і Docker-smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також з необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і `~/.codex/config.toml`. Використовуйте ті самі автентифікаційні матеріали, які застосовує ваш локальний app-server Codex. ## Мінімальна конфігурація @@ -83,7 +70,7 @@ app-server Codex. } ``` -Якщо у вашій конфігурації використовується `plugins.allow`, додайте туди також `codex`: +Якщо ваша конфігурація використовує `plugins.allow`, додайте туди також `codex`: ```json5 { @@ -98,14 +85,11 @@ app-server Codex. } ``` -Установлення `agents.defaults.model` або моделі агента в `codex/` також -автоматично вмикає комплектний plugin `codex`. Явний запис plugin усе ще -корисний у спільних конфігураціях, бо робить намір розгортання очевидним. +Установлення `agents.defaults.model` або моделі агента в `codex/` також автоматично вмикає комплектний plugin `codex`. Явний запис plugin усе одно корисний у спільних конфігураціях, тому що він робить намір розгортання очевидним. ## Додайте Codex без заміни інших моделей -Залишайте `runtime: "auto"`, якщо хочете використовувати Codex для моделей `codex/*`, а PI — для -всього іншого: +Залиште `runtime: "auto"`, якщо хочете використовувати Codex для моделей `codex/*`, а PI — для всього іншого: ```json5 { @@ -137,17 +121,16 @@ app-server Codex. } ``` -З такою структурою: +За такої конфігурації: - `/model codex` або `/model codex/gpt-5.4` використовує harness app-server Codex. - `/model gpt` або `/model openai/gpt-5.4` використовує шлях провайдера OpenAI. - `/model opus` використовує шлях провайдера Anthropic. -- Якщо вибрано модель не Codex, PI залишається harness сумісності. +- Якщо вибрано не-Codex-модель, PI залишається harness сумісності. ## Розгортання лише з Codex -Вимкніть резервний перехід до PI, якщо вам потрібно довести, що кожен вбудований хід агента використовує -harness Codex: +Вимкніть резервний перехід на PI, якщо вам потрібно підтвердити, що кожен вбудований хід агента використовує harness Codex: ```json5 { @@ -171,14 +154,11 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Коли резервний перехід вимкнено, OpenClaw завершується з помилкою на ранньому етапі, якщо plugin Codex вимкнений, -потрібна модель не є посиланням `codex/*`, app-server надто старий або -app-server не може запуститися. +Якщо резервний перехід вимкнено, OpenClaw завершується з помилкою на ранньому етапі, якщо plugin Codex вимкнено, запитувана модель не є посиланням `codex/*`, app-server надто старий або app-server не вдається запустити. ## Codex для окремого агента -Ви можете зробити одного агента лише Codex, а для агента за замовчуванням залишити звичайний -автовибір: +Ви можете зробити один агент лише для Codex, тоді як агент за замовчуванням зберігатиме звичайний автоматичний вибір: ```json5 { @@ -209,14 +189,11 @@ app-server не може запуститися. } ``` -Використовуйте звичайні команди сесії для перемикання агентів і моделей. `/new` створює нову -сесію OpenClaw, а harness Codex за потреби створює або відновлює свій sidecar app-server -потік. `/reset` очищає прив’язку сесії OpenClaw для цього потоку. +Використовуйте звичайні команди сесії для перемикання агентів і моделей. `/new` створює нову сесію OpenClaw, а harness Codex створює або відновлює свій sidecar-потік app-server за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього потоку. ## Виявлення моделей -За замовчуванням plugin Codex запитує app-server про доступні моделі. Якщо -виявлення завершується помилкою або спливає час очікування, він використовує комплектний резервний каталог: +За замовчуванням plugin Codex запитує app-server про доступні моделі. Якщо виявлення не вдається або завершується за тайм-аутом, він використовує комплектний резервний каталог: - `codex/gpt-5.4` - `codex/gpt-5.4-mini` @@ -242,8 +219,7 @@ app-server не може запуститися. } ``` -Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалася перевірка Codex і використовувався -резервний каталог: +Вимкніть виявлення, якщо хочете, щоб під час запуску не було перевірки Codex і використовувався лише резервний каталог: ```json5 { @@ -264,15 +240,13 @@ app-server не може запуститися. ## Підключення до app-server і політика -За замовчуванням plugin локально запускає Codex командою: +За замовчуванням plugin запускає Codex локально так: ```bash codex app-server --listen stdio:// ``` -За замовчуванням OpenClaw просить Codex запитувати нативні схвалення. Ви можете додатково -налаштувати цю політику, наприклад посилити її та направляти перевірки через -guardian: +За замовчуванням OpenClaw просить Codex запитувати нативні погодження. Ви можете додатково налаштувати цю політику, наприклад зробити її суворішою та спрямовувати перевірки через guardian: ```json5 { @@ -326,14 +300,13 @@ guardian: | `url` | не задано | URL app-server WebSocket. | | `authToken` | не задано | Bearer token для транспорту WebSocket. | | `headers` | `{}` | Додаткові заголовки WebSocket. | -| `requestTimeoutMs` | `60000` | Час очікування для викликів control-plane app-server. | -| `approvalPolicy` | `"on-request"` | Нативна політика схвалення Codex, що надсилається до запуску/відновлення/ходу потоку. | -| `sandbox` | `"workspace-write"` | Нативний режим sandbox Codex, що надсилається до запуску/відновлення потоку. | -| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб guardian Codex перевіряв нативні схвалення. | +| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control plane app-server. | +| `approvalPolicy` | `"on-request"` | Нативна політика погодження Codex, що надсилається під час start/resume/turn потоку. | +| `sandbox` | `"workspace-write"` | Нативний режим sandbox Codex, що надсилається під час start/resume потоку. | +| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб дозволити guardian Codex перевіряти нативні погодження. | | `serviceTier` | не задано | Необов’язковий рівень сервісу Codex, наприклад `"priority"`. | -Старіші змінні середовища все ще працюють як резервні варіанти для локального тестування, коли -відповідне поле конфігурації не задане: +Старі змінні середовища все ще працюють як резервний варіант для локального тестування, коли відповідне поле конфігурації не задано: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -341,11 +314,11 @@ guardian: - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` - `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` -Для відтворюваних розгортань рекомендовано використовувати конфігурацію. +Для відтворюваних розгортань перевага надається конфігурації. ## Поширені рецепти -Локальний Codex зі стандартним транспортом stdio: +Локальний Codex із транспортом stdio за замовчуванням: ```json5 { @@ -359,7 +332,7 @@ guardian: } ``` -Перевірка harness лише Codex із вимкненим резервним переходом до PI: +Перевірка harness лише з Codex, із вимкненим резервним переходом на PI: ```json5 { @@ -376,7 +349,7 @@ guardian: } ``` -Схвалення Codex із перевіркою guardian: +Погодження Codex, перевірені guardian: ```json5 { @@ -397,7 +370,7 @@ guardian: } ``` -Віддалений app-server із явними заголовками: +Віддалений app-server з явними заголовками: ```json5 { @@ -420,80 +393,55 @@ guardian: } ``` -Перемикання моделей залишається під контролем OpenClaw. Коли сесію OpenClaw приєднано -до наявного потоку Codex, наступний хід знову надсилає до -app-server поточні вибрані `codex/*` модель, провайдера, політику схвалення, sandbox і рівень сервісу. -Перемикання з `codex/gpt-5.4` на `codex/gpt-5.2` зберігає прив’язку до потоку, але просить Codex -продовжити роботу з новою вибраною моделлю. +Перемикання моделей залишається під контролем OpenClaw. Коли сесію OpenClaw приєднано до наявного потоку Codex, наступний хід знову надсилає в app-server поточно вибрану модель `codex/*`, провайдера, політику погодження, sandbox і рівень сервісу. Перемикання з `codex/gpt-5.4` на `codex/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 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 binding, який harness використовує для -звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає -поточну вибрану в OpenClaw модель `codex/*` до app-server і залишає розширену -історію увімкненою. +`/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає в app-server поточну вибрану модель OpenClaw `codex/*` і зберігає розширену історію увімкненою. -Поверхня команд потребує app-server Codex `0.118.0` або новішого. Окремі -методи керування позначаються як `unsupported by this Codex app-server`, якщо -майбутній або custom app-server не надає цей метод JSON-RPC. +Поверхня команд вимагає Codex app-server `0.118.0` або новішої версії. Окремі методи керування позначаються як `unsupported by this Codex app-server`, якщо майбутній або custom app-server не надає цей JSON-RPC-метод. ## Інструменти, медіа та Compaction Harness Codex змінює лише низькорівневий виконавець вбудованого агента. -OpenClaw і далі будує список інструментів і отримує динамічні результати інструментів від -harness. Текст, зображення, відео, музика, TTS, схвалення та вивід інструментів обміну повідомленнями -і далі проходять через звичайний шлях доставки OpenClaw. +OpenClaw, як і раніше, формує список інструментів і отримує динамічні результати інструментів від harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів обміну повідомленнями продовжують проходити через звичайний шлях доставки OpenClaw. -Коли вибрана модель використовує harness Codex, нативна Compaction потоку -делегується app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу, -пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало -включає запит користувача, фінальний текст асистента та полегшені записи міркувань або плану Codex, -коли їх видає app-server. +Коли вибрана модель використовує harness Codex, нативна Compaction потоку делегується app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу, пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало містить запит користувача, фінальний текст асистента та полегшені записи міркувань або плану Codex, коли app-server їх надсилає. -Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і -розуміння медіа й далі використовують відповідні налаштування провайдера/моделі, такі як -`agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і -`messages.tts`. +Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і розуміння медіа й надалі використовують відповідні налаштування провайдера/моделі, такі як `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і `messages.tts`. ## Усунення несправностей -**Codex не з’являється в `/model`:** увімкніть `plugins.entries.codex.enabled`, -задайте посилання на модель `codex/*` або перевірте, чи `plugins.allow` не виключає `codex`. +**Codex не з’являється в `/model`:** увімкніть `plugins.entries.codex.enabled`, задайте посилання на модель `codex/*` або перевірте, чи не виключає `plugins.allow` значення `codex`. -**OpenClaw переходить до PI:** задайте `embeddedHarness.fallback: "none"` або -`OPENCLAW_AGENT_HARNESS_FALLBACK=none` під час тестування. +**OpenClaw використовує PI замість Codex:** якщо жоден harness Codex не обробляє запуск, OpenClaw може використовувати PI як backend сумісності. Установіть `embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування, або `embeddedHarness.fallback: "none"`, щоб отримувати помилку, коли жоден plugin harness не підходить. Щойно вибрано app-server Codex, його збої відображаються безпосередньо без додаткового налаштування резервного переходу. -**app-server відхиляється:** оновіть Codex, щоб handshake app-server -повідомляв версію `0.118.0` або новішу. +**app-server відхиляється:** оновіть Codex, щоб handshake app-server повідомляв версію `0.118.0` або новішу. -**Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` -або вимкніть виявлення. +**Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` або вимкніть виявлення. -**Транспорт WebSocket одразу завершується з помилкою:** перевірте `appServer.url`, `authToken` -і що віддалений app-server використовує ту саму версію протоколу app-server Codex. +**Транспорт WebSocket відразу завершується помилкою:** перевірте `appServer.url`, `authToken` і що віддалений app-server використовує ту саму версію протоколу app-server Codex. -**Модель не Codex використовує PI:** це очікувана поведінка. Harness Codex обробляє лише -посилання на моделі `codex/*`. +**Не-Codex-модель використовує PI:** це очікувана поведінка. Harness Codex обробляє лише посилання на моделі `codex/*`. ## Пов’язане -- [Plugins harness агента](/uk/plugins/sdk-agent-harness) +- [Plugins Harness агента](/uk/plugins/sdk-agent-harness) - [Провайдери моделей](/uk/concepts/model-providers) - [Довідник із конфігурації](/uk/gateway/configuration-reference) - [Тестування](/uk/help/testing#live-codex-app-server-harness-smoke) diff --git a/docs/uk/plugins/sdk-agent-harness.md b/docs/uk/plugins/sdk-agent-harness.md index 6485d7b1d..cc58de986 100644 --- a/docs/uk/plugins/sdk-agent-harness.md +++ b/docs/uk/plugins/sdk-agent-harness.md @@ -1,53 +1,53 @@ --- read_when: - - Ви змінюєте вбудоване середовище виконання агента або реєстр harness агента - - Ви реєструєте harness агента з вбудованого або довіреного плагіна - - Вам потрібно зрозуміти, як плагін Codex пов’язаний із постачальниками моделей + - Ви змінюєте вбудоване середовище виконання агента або реєстр обв’язки агента + - Ви реєструєте обв’язку агента з bundled або trusted plugin + - Вам потрібно зрозуміти, як plugin Codex пов’язаний із постачальниками моделей sidebarTitle: Agent Harness -summary: Експериментальна поверхня SDK для плагінів, які замінюють низькорівневий вбудований виконавець агента -title: Плагіни Agent Harness +summary: Експериментальна поверхня SDK для plugin, які замінюють низькорівневий вбудований виконавець агента +title: Plugin обв’язки агента x-i18n: - generated_at: "2026-04-11T16:15:07Z" + generated_at: "2026-04-22T05:35:02Z" model: gpt-5.4 provider: openai - source_hash: 62b88fd24ce8b600179db27e16e8d764a2cd7a14e5c5df76374c33121aa5e365 + source_hash: 728fef59ae3cce29a3348842820f1f71a2eac98ae6b276179bce6c85d16613df source_path: plugins/sdk-agent-harness.md workflow: 15 --- -# Плагіни Agent Harness +# Plugin обв’язки агента -**Agent harness** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів. +**Обв’язка агента** — це низькорівневий виконавець одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів. -Використовуйте цю поверхню лише для вбудованих або довірених нативних плагінів. Контракт усе ще є експериментальним, оскільки типи параметрів навмисно віддзеркалюють поточний вбудований виконавець. +Використовуйте цю поверхню лише для bundled або trusted native plugin. Контракт усе ще експериментальний, оскільки типи параметрів навмисно віддзеркалюють поточний вбудований виконавець. -## Коли використовувати harness +## Коли використовувати обв’язку -Реєструйте harness агента, коли сімейство моделей має власне нативне середовище виконання сесій, а звичайний транспорт постачальника OpenClaw є хибною абстракцією. +Реєструйте обв’язку агента, коли сімейство моделей має власне native середовище виконання сесії і звичайний транспорт постачальника OpenClaw є хибною абстракцією. Приклади: -- нативний сервер coding-agent, який керує потоками та компакцією -- локальний CLI або демон, який має потоково передавати нативні події плану/міркувань/інструментів +- native сервер coding-agent, який керує потоками та Compaction +- локальний CLI або демон, який має транслювати native події плану/міркувань/інструментів - середовище виконання моделі, якому потрібен власний resume id на додачу до транскрипту сесії OpenClaw -**Не** реєструйте harness лише для того, щоб додати новий API LLM. Для звичайних HTTP- або WebSocket-API моделей створіть [плагін постачальника](/uk/plugins/sdk-provider-plugins). +**Не** реєструйте обв’язку лише для того, щоб додати новий API LLM. Для звичайних HTTP або WebSocket API моделей створіть [plugin постачальника](/uk/plugins/sdk-provider-plugins). -## Чим усе ще керує ядро +## Що все ще належить core -До вибору harness OpenClaw уже визначив: +Перш ніж буде вибрано обв’язку, OpenClaw уже визначив: -- постачальника й модель -- стан автентифікації середовища виконання +- постачальника і модель +- стан auth середовища виконання - рівень thinking і бюджет контексту - файл транскрипту/сесії OpenClaw -- робочий простір, sandbox і політику інструментів -- зворотні виклики відповідей каналу та потокові зворотні виклики -- політику резервного переходу між моделями та перемикання на живу модель +- workspace, sandbox і політику інструментів +- callback-функції відповіді каналу та callback-функції трансляції +- політику fallback моделі та живого перемикання моделі -Такий поділ є навмисним. Harness виконує підготовлену спробу; він не вибирає постачальників, не замінює доставлення через канал і не перемикає моделі непомітно. +Цей поділ є навмисним. Обв’язка виконує підготовлену спробу; вона не вибирає постачальників, не замінює доставку каналу і не перемикає моделі непомітно. -## Реєстрація harness +## Зареєструвати обв’язку **Імпорт:** `openclaw/plugin-sdk/agent-harness` @@ -85,49 +85,49 @@ export default definePluginEntry({ ## Політика вибору -OpenClaw вибирає harness після визначення постачальника/моделі: +OpenClaw вибирає обв’язку після визначення постачальника/моделі: -1. `OPENCLAW_AGENT_RUNTIME=` примусово вибирає зареєстрований harness з цим id. -2. `OPENCLAW_AGENT_RUNTIME=pi` примусово вибирає вбудований PI harness. -3. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані harness, чи підтримують вони визначеного постачальника/модель. -4. Якщо жоден зареєстрований harness не підходить, OpenClaw використовує PI, якщо резервний перехід на PI не вимкнено. +1. `OPENCLAW_AGENT_RUNTIME=` примусово вибирає зареєстровану обв’язку з цим id. +2. `OPENCLAW_AGENT_RUNTIME=pi` примусово вибирає вбудовану обв’язку PI. +3. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані обв’язки, чи підтримують вони визначеного постачальника/модель. +4. Якщо жодна зареєстрована обв’язка не підходить, OpenClaw використовує PI, якщо fallback до PI не вимкнено. -Помилки примусово вибраного harness плагіна відображаються як помилки виконання. У режимі `auto` OpenClaw може перейти на PI, якщо вибраний harness плагіна завершується помилкою до того, як хід породить побічні ефекти. Установіть `OPENCLAW_AGENT_HARNESS_FALLBACK=none` або `embeddedHarness.fallback: "none"`, щоб зробити такий резервний перехід жорсткою помилкою. +Збої обв’язок plugin відображаються як збої виконання. У режимі `auto` fallback до PI використовується лише тоді, коли жодна зареєстрована обв’язка plugin не підтримує визначеного постачальника/модель. Щойно обв’язка plugin заявила про виконання, OpenClaw не повторює той самий хід через PI, оскільки це може змінити семантику auth/середовища виконання або продублювати побічні ефекти. -Вбудований плагін Codex реєструє `codex` як id свого harness. Ядро обробляє його як звичайний id harness плагіна; специфічні для Codex псевдоніми мають належати плагіну або конфігурації оператора, а не спільному селектору середовища виконання. +Bundled plugin Codex реєструє `codex` як свій id обв’язки. Core розглядає це як звичайний id обв’язки plugin; специфічні для Codex псевдоніми мають належати plugin або конфігурації оператора, а не спільному селектору середовища виконання. -## Поєднання постачальника й harness +## Поєднання постачальника й обв’язки -Більшість harness також мають реєструвати постачальника. Постачальник робить посилання на моделі, статус автентифікації, метадані моделей і вибір `/model` видимими для решти OpenClaw. Потім harness заявляє про цей постачальник у `supports(...)`. +Більшість обв’язок також мають реєструвати постачальника. Постачальник робить посилання на моделі, стан auth, метадані моделі й вибір `/model` видимими для решти OpenClaw. Потім обв’язка заявляє про цей постачальник у `supports(...)`. -Вбудований плагін Codex дотримується цього шаблону: +Bundled plugin Codex дотримується цього шаблону: - id постачальника: `codex` -- посилання користувача на моделі: `codex/gpt-5.4`, `codex/gpt-5.2` або інша модель, повернена сервером застосунку Codex -- id harness: `codex` -- автентифікація: синтетична доступність постачальника, оскільки harness Codex керує нативним входом/сесією Codex -- запит до app-server: OpenClaw надсилає до Codex чистий id моделі й дозволяє harness взаємодіяти з нативним протоколом app-server +- посилання користувацьких моделей: `codex/gpt-5.4`, `codex/gpt-5.2` або інша модель, яку повертає сервер застосунку Codex +- id обв’язки: `codex` +- auth: синтетична доступність постачальника, оскільки обв’язка Codex керує native входом/сесією Codex +- запит до app-server: OpenClaw надсилає Codex базовий id моделі й дозволяє обв’язці спілкуватися з native протоколом app-server -Плагін Codex є додатковим. Звичайні посилання `openai/gpt-*` залишаються посиланнями постачальника OpenAI й продовжують використовувати звичайний шлях постачальника OpenClaw. Вибирайте `codex/gpt-*`, коли вам потрібні автентифікація під керуванням Codex, виявлення моделей Codex, нативні потоки та виконання через app-server Codex. `/model` може перемикатися між моделями Codex, які повертає app-server Codex, без потреби в облікових даних постачальника OpenAI. +Plugin Codex є адитивним. Звичайні посилання `openai/gpt-*` залишаються посиланнями постачальника OpenAI і продовжують використовувати звичайний шлях постачальника OpenClaw. Вибирайте `codex/gpt-*`, коли вам потрібні auth під керуванням Codex, виявлення моделей Codex, native потоки та виконання через app-server Codex. `/model` може перемикатися між моделями Codex, які повертає app-server Codex, без потреби в облікових даних постачальника OpenAI. -Налаштування для операторів, приклади префіксів моделей і конфігурації лише для Codex див. у [Codex Harness](/uk/plugins/codex-harness). +Щоб дізнатися про налаштування оператора, приклади префіксів моделей і конфігурації лише для Codex, див. [Обв’язка Codex](/uk/plugins/codex-harness). -OpenClaw вимагає Codex app-server версії `0.118.0` або новішої. Плагін Codex перевіряє handshake ініціалізації app-server і блокує старіші сервери або сервери без версії, щоб OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано. +OpenClaw вимагає Codex app-server `0.118.0` або новішої версії. Plugin Codex перевіряє initialize handshake app-server і блокує старіші або неверсіоновані сервери, щоб OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано. -### Режим нативного Codex harness +### Режим native обв’язки Codex -Вбудований harness `codex` — це нативний режим Codex для вбудованих ходів агента OpenClaw. Спочатку ввімкніть вбудований плагін `codex` і додайте `codex` до `plugins.allow`, якщо у вашій конфігурації використовується обмежувальний allowlist. Він відрізняється від `openai-codex/*`: +Bundled обв’язка `codex` — це native режим Codex для вбудованих ходів агента OpenClaw. Спочатку увімкніть bundled plugin `codex` і додайте `codex` у `plugins.allow`, якщо ваша конфігурація використовує обмежувальний allowlist. Він відрізняється від `openai-codex/*`: - `openai-codex/*` використовує OAuth ChatGPT/Codex через звичайний шлях постачальника OpenClaw. -- `codex/*` використовує вбудований постачальник Codex і спрямовує хід через app-server Codex. +- `codex/*` використовує bundled постачальник Codex і маршрутизує хід через app-server Codex. -Коли цей режим працює, Codex керує нативним id потоку, поведінкою resume, компакцією та виконанням app-server. OpenClaw усе ще керує каналом чату, видимим дзеркалом транскрипту, політикою інструментів, підтвердженнями, доставленням медіа та вибором сесії. Використовуйте `embeddedHarness.runtime: "codex"` разом із `embeddedHarness.fallback: "none"`, коли потрібно довести, що використовується шлях app-server Codex і що резервний перехід на PI не приховує несправний нативний harness. +Коли цей режим працює, Codex керує native id потоку, поведінкою resume, Compaction і виконанням app-server. OpenClaw усе ще керує каналом чату, видимим дзеркалом транскрипту, політикою інструментів, схваленнями, доставкою медіа та вибором сесії. Використовуйте `embeddedHarness.runtime: "codex"` разом із `embeddedHarness.fallback: "none"`, коли вам потрібно довести, що лише шлях app-server Codex може заявити про виконання. Ця конфігурація є лише захистом вибору: збої app-server Codex і так завершуються помилкою напряму, а не повторною спробою через PI. -## Вимкнення резервного переходу на PI +## Вимкнути fallback до PI -За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, установленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані harness плагінів можуть заявляти про пару постачальник/модель. Якщо жоден не підходить або якщо автоматично вибраний harness плагіна завершується помилкою до появи результату, OpenClaw переходить на PI. +За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, встановленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані обв’язки plugin можуть заявляти про пару постачальник/модель. Якщо жодна не підходить, OpenClaw повертається до PI. -Установіть `fallback: "none"`, коли потрібно довести, що harness плагіна є єдиним середовищем виконання, яке використовується. Це вимикає автоматичний резервний перехід на PI; це не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. +Установіть `fallback: "none"`, коли вам потрібно, щоб відсутність вибору обв’язки plugin завершувалася помилкою замість використання PI. Збої вже вибраних обв’язок plugin і так призводять до жорсткої помилки. Це не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. Для вбудованих запусків лише з Codex: @@ -145,7 +145,7 @@ OpenClaw вимагає Codex app-server версії `0.118.0` або нові } ``` -Якщо ви хочете, щоб будь-який зареєстрований harness плагіна міг заявляти про відповідні моделі, але ніколи не хочете, щоб OpenClaw непомітно переходив на PI, залиште `runtime: "auto"` і вимкніть резервний перехід: +Якщо ви хочете, щоб будь-яка зареєстрована обв’язка plugin могла заявляти про відповідні моделі, але ніколи не хочете, щоб OpenClaw непомітно повертався до PI, залиште `runtime: "auto"` і вимкніть fallback: ```json { @@ -160,7 +160,7 @@ OpenClaw вимагає Codex app-server версії `0.118.0` або нові } ``` -Перевизначення для окремих агентів використовують ту саму форму: +Перевизначення для окремого агента використовують ту саму форму: ```json { @@ -185,7 +185,7 @@ OpenClaw вимагає Codex app-server версії `0.118.0` або нові } ``` -`OPENCLAW_AGENT_RUNTIME` усе ще перевизначає налаштоване середовище виконання. Використовуйте `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути резервний перехід на PI через середовище. +`OPENCLAW_AGENT_RUNTIME` усе ще перевизначає налаштоване середовище виконання. Використовуйте `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути fallback до PI з оточення. ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -193,39 +193,39 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Якщо резервний перехід вимкнено, сесія завершується помилкою на ранньому етапі, коли запитаний harness не зареєстрований, не підтримує визначеного постачальника/модель або завершується помилкою до появи побічних ефектів ходу. Це зроблено навмисно для розгортань лише з Codex і для live-тестів, які мають довести, що шлях app-server Codex справді використовується. +Якщо fallback вимкнено, сесія завершується помилкою рано, коли запитана обв’язка не зареєстрована, не підтримує визначеного постачальника/модель або завершується помилкою до створення побічних ефектів ходу. Це зроблено навмисно для розгортань лише з Codex і для live-тестів, які мають довести, що шлях app-server Codex справді використовується. -Це налаштування керує лише вбудованим harness агента. Воно не вимикає маршрутизацію моделей, специфічну для постачальників, для зображень, відео, музики, TTS, PDF або інших типів. +Це налаштування керує лише вбудованою обв’язкою агента. Воно не вимикає маршрутизацію моделей постачальників для image, video, music, TTS, PDF або інших специфічних для постачальника типів. -## Нативні сесії та дзеркало транскрипту +## Native сесії та дзеркало транскрипту -Harness може зберігати нативний id сесії, id потоку або токен resume на боці демона. Явно пов’язуйте таку прив’язку із сесією OpenClaw і продовжуйте дзеркалити видимий користувачу вивід асистента/інструментів у транскрипт OpenClaw. +Обв’язка може зберігати native id сесії, id потоку або токен resume на боці демона. Явно пов’язуйте цю прив’язку із сесією OpenClaw і продовжуйте віддзеркалювати видимий для користувача вивід assistant/tool у транскрипт OpenClaw. Транскрипт OpenClaw залишається шаром сумісності для: - видимої в каналі історії сесії -- пошуку та індексації транскриптів -- повернення до вбудованого PI harness на наступному ході -- загальної поведінки `/new`, `/reset` і видалення сесії +- пошуку та індексації транскрипту +- повернення до вбудованої обв’язки PI на пізнішому ході +- узагальненої поведінки `/new`, `/reset` і видалення сесії -Якщо ваш harness зберігає побічну прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг очищати її, коли пов’язану сесію OpenClaw скинуто. +Якщо ваша обв’язка зберігає sidecar-прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг очистити її, коли пов’язану сесію OpenClaw скинуто. ## Результати інструментів і медіа -Ядро формує список інструментів OpenClaw і передає його в підготовлену спробу. Коли harness виконує динамічний виклик інструмента, повертайте результат інструмента через форму результату harness, а не надсилайте медіа в канал самостійно. +Core формує список інструментів OpenClaw і передає його в підготовлену спробу. Коли обв’язка виконує динамічний виклик інструмента, повертайте результат інструмента назад через форму результату обв’язки замість того, щоб самостійно надсилати медіа в канал. -Це забезпечує, що текст, зображення, відео, музика, TTS, підтвердження та результати інструментів обміну повідомленнями доставляються тим самим шляхом, що й для запусків на основі PI. +Це зберігає text, image, video, music, TTS, approval і виводи інструментів обміну повідомленнями на тому самому шляху доставки, що й для запусків на базі PI. ## Поточні обмеження -- Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроб/результатів досі містять назви `Pi` для сумісності. -- Установлення сторонніх harness є експериментальним. Віддавайте перевагу плагінам постачальників, доки вам не знадобиться нативне середовище виконання сесій. -- Перемикання harness між ходами підтримується. Не перемикайте harness посеред ходу після того, як уже почалися нативні інструменти, підтвердження, текст асистента або надсилання повідомлень. +- Публічний шлях імпорту є узагальненим, але деякі псевдоніми типів спроб/результатів усе ще містять назви `Pi` заради сумісності. +- Встановлення сторонніх обв’язок є експериментальним. Надавайте перевагу plugin постачальників, доки вам не знадобиться native середовище виконання сесії. +- Перемикання обв’язок між ходами підтримується. Не перемикайте обв’язки посеред ходу після того, як уже почалися native інструменти, схвалення, текст assistant або надсилання повідомлень. -## Пов’язані матеріали +## Пов’язане - [Огляд SDK](/uk/plugins/sdk-overview) -- [Допоміжні засоби середовища виконання](/uk/plugins/sdk-runtime) -- [Плагіни постачальників](/uk/plugins/sdk-provider-plugins) -- [Codex Harness](/uk/plugins/codex-harness) +- [Runtime Helpers](/uk/plugins/sdk-runtime) +- [Plugin постачальника](/uk/plugins/sdk-provider-plugins) +- [Обв’язка Codex](/uk/plugins/codex-harness) - [Постачальники моделей](/uk/concepts/model-providers)