diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index 39fb18768..000689e32 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -2,69 +2,69 @@ read_when: - Вам потрібні точні семантики полів конфігурації або значення за замовчуванням - Ви перевіряєте блоки конфігурації каналів, моделей, Gateway або інструментів -summary: Довідник із конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем -title: Довідник із конфігурації +summary: Довідник з конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем +title: Довідник з конфігурації x-i18n: - generated_at: "2026-04-18T03:32:03Z" + generated_at: "2026-04-19T10:22:59Z" model: gpt-5.4 provider: openai - source_hash: 4b504c9c6b47d7a327a0acf6934561c9b2606c01cc8ebe5526ccde73033d759f + source_hash: 22b10f1f133374cd29ef4a5ec4fb9c9938eb51184ad82e1aa2e5f6f7af58585e source_path: gateway/configuration-reference.md workflow: 15 --- -# Довідник із конфігурації +# Довідник з конфігурації -Основний довідник із конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Конфігурація](/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` -- [Slash Commands](/uk/tools/slash-commands) для поточного вбудованого + вбудованого каталогу команд -- сторінки відповідних каналів/plugin для поверхонь команд, специфічних для каналу +- [Довідник з конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації Dreaming у `plugins.entries.memory-core.config.dreaming` +- [Слеш-команди](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд +- сторінки відповідних каналів/Plugin для специфічних для каналів поверхонь команд -Формат конфігурації — **JSON5** (дозволені коментарі + кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано. +Формат конфігурації — **JSON5** (дозволено коментарі й кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено. --- ## Канали -Кожен канал запускається автоматично, коли існує його секція конфігурації (якщо не встановлено `enabled: false`). +Кожен канал запускається автоматично, коли існує його секція конфігурації (якщо не вказано `enabled: false`). -### Доступ до DM і груп +### Доступ у DM і групах Усі канали підтримують політики DM і політики груп: | Політика DM | Поведінка | | ------------------- | -------------------------------------------------------------- | -| `pairing` (типово) | Невідомі відправники отримують одноразовий код прив’язки; власник має схвалити | -| `allowlist` | Лише відправники з `allowFrom` (або сховища дозволів прив’язки) | +| `pairing` (типово) | Невідомі відправники отримують одноразовий код спарювання; власник має схвалити | +| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволів спарювання) | | `open` | Дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) | | `disabled` | Ігнорувати всі вхідні DM | -| Політика груп | Поведінка | -| --------------------- | ----------------------------------------------------- | -| `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволів | -| `open` | Обійти списки дозволів груп (обмеження за згадками все одно застосовується) | -| `disabled` | Блокувати всі повідомлення груп/кімнат | +| Політика груп | Поведінка | +| -------------------- | ------------------------------------------------------- | +| `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволених | +| `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`, щоб прив’язати конкретні ID каналів до моделі. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналу застосовується, коли сесія ще не має власного перевизначення моделі (наприклад, встановленого через `/model`). ```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.heartbeat.showAlerts`: включати стани деградації/помилок у вивід 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 у режимі чату із самим собою) + sendReadReceipts: true, // blue ticks (false in self-chat mode) groups: { "*": { requireMention: true }, }, @@ -164,9 +164,9 @@ WhatsApp працює через web-канал gateway (Baileys Web). Він з } ``` -- Вихідні команди типово використовують обліковий запис `default`, якщо він є; інакше — перший налаштований ID облікового запису (відсортовано). -- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. -- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується командою `openclaw doctor` у `whatsapp/default`. +- Вихідні команди типово використовують обліковий запис `default`, якщо він існує; інакше — перший налаштований ID облікового запису (відсортований). +- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний типовий вибір облікового запису, якщо він відповідає налаштованому ID облікового запису. +- Застарілий каталог автентифікації 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; явно ввімкніть, щоб уникнути обмежень частоти для редагування попереднього перегляду) + 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, @@ -225,13 +225,13 @@ 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` (працює в особистих і групових чатах). -- Політика повторних спроб: див. [Політика повторних спроб](/uk/concepts/retry). +- Токен бота: `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` (працює в особистих і групових чатах). +- Політика повторів: див. [Retry policy](/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, // опціонально для sessions_spawn({ thread: true }) + spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true }) }, voice: { enabled: true, @@ -333,36 +333,36 @@ WhatsApp працює через web-канал gateway (Baileys Web). Він з } ``` -- Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервним варіантом для типового облікового запису. -- Прямі вихідні виклики, які надають явний Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime. -- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. -- Використовуйте `user:` (DM) або `channel:` (канал guild) для цілей доставки; окремі числові ID відхиляються. +- Токен: `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"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно фільтруються). +- Повідомлення, створені ботом, типово ігноруються. `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` вимикає) +- `maxLinesPerMessage` (типово 17) розбиває високі повідомлення навіть тоді, коли вони коротші за 2000 символів. +- `channels.discord.threadBindings` керує маршрутизацією, прив’язаною до тредів Discord: + - `enabled`: перевизначення Discord для функцій сесій, прив’язаних до тредів (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язана доставка/маршрутизація) + - `idleHours`: перевизначення Discord для автоматичного зняття фокусу через неактивність у годинах (`0` вимикає) - `maxAgeHours`: перевизначення Discord для жорсткого максимального віку в годинах (`0` вимикає) - - `spawnSubagentSessions`: опціональний перемикач для автоматичного створення/прив’язки потоку `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. + - `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 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"` (типово). В автоматичному режимі погодження exec активуються, коли тих, хто погоджує, можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Discord, яким дозволено погоджувати exec-запити. Якщо не вказано, використовується `commands.ownerAllowFrom`. - - `agentFilter`: необов’язковий список дозволених ID агентів. Не вказуйте, щоб пересилати погодження для всіх агентів. - - `sessionFilter`: необов’язкові шаблони ключів сесії (підрядок або regex). - - `target`: куди надсилати запити на погодження. `"dm"` (типово) надсилає в DM тих, хто погоджує, `"channel"` — у вихідний канал, `"both"` — в обидва. Коли target містить `"channel"`, кнопки можуть використовувати лише визначені учасники, які погоджують. - - `cleanupAfterResolve`: коли `true`, видаляє DM-повідомлення про погодження після погодження, відхилення або тайм-ауту. +- OpenClaw додатково намагається відновити прийом голосу, виходячи з голосової сесії та приєднуючись повторно після повторних збоїв дешифрування. +- `channels.discord.streaming` — це канонічний ключ режиму потоку. Застарілі значення `streamMode` і булеві `streaming` мігруються автоматично. +- `channels.discord.autoPresence` зіставляє доступність runtime із присутністю бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. +- `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваними іменами/тегами (режим сумісності break-glass). +- `channels.discord.execApprovals`: доставка схвалень exec у стилі Discord і авторизація тих, хто схвалює. + - `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 зі схваленням після схвалення, відхилення або тайм-ауту. -**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (від `guilds..users` для всіх повідомлень). +**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (із `guilds..users` для всіх повідомлень). ### Google Chat @@ -393,10 +393,10 @@ WhatsApp працює через web-канал gateway (Baileys Web). Він з } ``` -- JSON service account: вбудований (`serviceAccount`) або з файлу (`serviceAccountFile`). -- Також підтримується SecretRef для service account (`serviceAccountRef`). -- Резервні змінні середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Використовуйте `spaces/` або `users/` для цілей доставки. +- JSON облікового запису сервісу: вбудований (`serviceAccount`) або на основі файла (`serviceAccountFile`). +- Також підтримується SecretRef облікового запису сервісу (`serviceAccountRef`). +- Резервні значення змінних середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- Використовуйте `spaces/` або `users/` як цілі доставки. - `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваним email principal (режим сумісності break-glass). ### Slack @@ -464,35 +464,35 @@ WhatsApp працює через web-канал gateway (Baileys Web). Він з } ``` -- **Socket mode** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для резервного варіанта змінних середовища типового облікового запису). -- **HTTP mode** вимагає `botToken` плюс `signingSecret` (у корені або для окремого облікового запису). +- **Socket mode** потребує і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як резервні змінні середовища для облікового запису за замовчуванням). +- **HTTP mode** потребує `botToken` плюс `signingSecret` (у корені або для окремого облікового запису). - `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті рядки або об’єкти SecretRef. - Знімки облікових записів Slack показують поля джерела/статусу для кожного облікового запису, такі як - `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у HTTP mode, + `botTokenSource`, `botTokenStatus`, `appTokenStatus`, а в HTTP mode — `signingSecretStatus`. `configured_unavailable` означає, що обліковий запис налаштовано через 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:` для цілей доставки. +- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ID облікового запису. +- `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` або звичайну доставку замість попереднього перегляду в стилі потоку. +- Власна потокова передача Slack плюс статус треду Slack у стилі помічника «is typing...» потребують цілі відповіді в треді. DM верхнього рівня типово залишаються поза тредом, тому вони використовують `typingReaction` або звичайну доставку замість попереднього перегляду у стилі треду. - `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: нативна для Slack доставка погоджень exec і авторизація тих, хто погоджує. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). +- `channels.slack.execApprovals`: доставка схвалень exec у стилі Slack і авторизація тих, хто схвалює. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). -| Група дій | Типово | Примітки | -| ------------ | -------- | ------------------------- | -| reactions | увімкнено | Реакції + список реакцій | -| messages | увімкнено | Читання/надсилання/редагування/видалення | -| pins | увімкнено | Закріплення/відкріплення/список | -| memberInfo | увімкнено | Інформація про учасника | -| emojiList | увімкнено | Список користувацьких emoji | +| Група дій | Типово | Примітки | +| ----------- | ------- | ------------------------ | +| reactions | увімкнено | Реакції + список реакцій | +| messages | увімкнено | Читання/надсилання/редагування/видалення | +| pins | увімкнено | Закріплення/відкріплення/список | +| memberInfo | увімкнено | Інформація про учасника | +| emojiList | увімкнено | Список власних emoji | ### Mattermost @@ -526,23 +526,23 @@ Mattermost постачається як Plugin: `openclaw plugins install @open } ``` -Режими чату: `oncall` (відповідати на згадку @, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса тригера). +Режими чату: `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. +- Власні slash callback-обробники автентифікуються токенами окремих команд, які + Mattermost повертає під час реєстрації slash-команд. Якщо реєстрація не вдається або + не активовано жодної команди, OpenClaw відхиляє callback-виклики з повідомленням `Unauthorized: invalid command token.` -- Для приватних/tailnet/internal хостів зворотних викликів Mattermost може вимагати, щоб - `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен зворотного виклику. - Використовуйте значення хоста/домену, а не повні URL. +- Для приватних/tailnet/internal хостів callback Mattermost може вимагати, щоб + `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен callback. + Використовуйте значення хоста/домену, а не повні URL-адреси. - `channels.mattermost.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Mattermost. - `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в каналах. - `channels.mattermost.groups..requireMention`: перевизначення обмеження за згадкою для окремого каналу (`"*"` для типового значення). -- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. +- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ID облікового запису. ### Signal @@ -566,12 +566,12 @@ 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` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ID облікового запису. ### BlueBubbles -BlueBubbles — рекомендований шлях для iMessage (на основі Plugin, налаштовується в `channels.bluebubbles`). +BlueBubbles — рекомендований шлях для iMessage (на базі Plugin, налаштовується в `channels.bluebubbles`). ```json5 { @@ -586,9 +586,9 @@ BlueBubbles — рекомендований шлях для iMessage (на ос } ``` -- Основні шляхи ключів, які тут охоплюються: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних ACP-сесій. Використовуйте BlueBubbles handle або рядок цілі (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Основні шляхи ключів, охоплені тут: `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). - Повну конфігурацію каналу BlueBubbles описано в [BlueBubbles](/uk/channels/bluebubbles). ### iMessage @@ -617,17 +617,17 @@ OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон а } ``` -- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. +- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ID облікового запису. -- Потрібен Full Disk Access до БД Messages. -- Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів. +- Потрібен Full Disk Access до бази даних Messages. +- Віддавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів. - `cliPath` може вказувати на SSH-обгортку; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. - `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (типово: `/Users/*/Library/Messages/Attachments`). -- SCP використовує сувору перевірку ключа хоста, тому переконайтеся, що ключ хоста relay вже існує в `~/.ssh/known_hosts`. +- 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). +- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних сесій ACP. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). - + ```bash #!/usr/bin/env bash @@ -668,20 +668,20 @@ Matrix працює через extension і налаштовується в `cha } ``` -- Автентифікація за токеном використовує `accessToken`; автентифікація за паролем використовує `userId` + `password`. -- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S)-proxy. Іменовані облікові записи можуть перевизначити це через `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"` (типово). В автоматичному режимі погодження exec активуються, коли тих, хто погоджує, можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Matrix (наприклад, `@owner:example.org`), яким дозволено погоджувати exec-запити. - - `agentFilter`: необов’язковий список дозволених ID агентів. Не вказуйте, щоб пересилати погодження для всіх агентів. - - `sessionFilter`: необов’язкові шаблони ключів сесії (підрядок або regex). - - `target`: куди надсилати запити на погодження. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`. +- Автентифікація токеном використовує `accessToken`; автентифікація паролем — `userId` + `password`. +- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S)-proxy. Іменовані облікові записи можуть перевизначати його через `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`: доставка схвалень exec у стилі Matrix і авторизація тих, хто схвалює. + - `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 і пошук live directory використовують ту саму політику proxy, що й runtime-трафік. +- `channels.matrix.dm.sessionScope` керує тим, як DM Matrix групуються в сесії: `per-user` (типово) об’єднує за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату. +- Перевірки статусу Matrix і пошук у live directory використовують ту саму політику proxy, що й трафік runtime. - Повну конфігурацію Matrix, правила націлювання та приклади налаштування описано в [Matrix](/uk/channels/matrix). ### Microsoft Teams @@ -701,8 +701,8 @@ Microsoft Teams працює через extension і налаштовуєтьс } ``` -- Основні шляхи ключів, які тут охоплюються: `channels.msteams`, `channels.msteams.configWrites`. -- Повну конфігурацію Teams (облікові дані, webhook, політика DM/груп, перевизначення для окремих team/channel) описано в [Microsoft Teams](/uk/channels/msteams). +- Основні шляхи ключів, охоплені тут: `channels.msteams`, `channels.msteams.configWrites`. +- Повну конфігурацію Teams (облікові дані, Webhook, політика DM/груп, перевизначення для окремих team/channel) описано в [Microsoft Teams](/uk/channels/msteams). ### IRC @@ -727,13 +727,13 @@ IRC працює через extension і налаштовується в `channe } ``` -- Основні шляхи ключів, які тут охоплюються: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. +- Основні шляхи ключів, охоплені тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ID облікового запису. - Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/обмеження за згадками) описано в [IRC](/uk/channels/irc). -### Кілька облікових записів (усі канали) +### Багато облікових записів (усі канали) -Запускайте кілька облікових записів для кожного каналу (кожен зі своїм `accountId`): +Запускайте кілька облікових записів на канал (кожен зі своїм `accountId`): ```json5 { @@ -754,28 +754,28 @@ IRC працює через extension і налаштовується в `channe } ``` -- `default` використовується, коли `accountId` не вказано (CLI + маршрутизація). +- `default` використовується, коли `accountId` пропущено (CLI + маршрутизація). - Токени середовища застосовуються лише до облікового запису **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 натомість може зберегти наявну відповідну іменовану/типову ціль. ### Інші extension-канали -Багато extension-каналів налаштовуються як `channels.` і описані на окремих сторінках своїх каналів (наприклад, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). -Див. повний покажчик каналів: [Канали](/uk/channels). +Багато extension-каналів налаштовуються як `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. **Типи згадок:** -- **Згадки в метаданих**: нативні @-згадки платформи. Ігноруються в режимі самочату WhatsApp. -- **Текстові шаблони**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Неприпустимі шаблони й небезпечне вкладене повторення ігноруються. -- Обмеження за згадками застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один шаблон). +- **Згадки в метаданих**: власні @-згадки платформи. Ігноруються в режимі self-chat WhatsApp. +- **Текстові шаблони**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Недійсні шаблони та небезпечні вкладені повторення ігноруються. +- Обмеження за згадками застосовується лише тоді, коли виявлення можливе (власні згадки або принаймні один шаблон). ```json5 { @@ -790,7 +790,7 @@ IRC працює через extension і налаштовується в `channe `messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначити його через `channels..historyLimit` (або для окремого облікового запису). Установіть `0`, щоб вимкнути. -#### Ліміти історії DM +#### Обмеження історії DM ```json5 { @@ -805,13 +805,13 @@ IRC працює через extension і налаштовується в `channe } ``` -Визначення: перевизначення для окремого DM → типове значення провайдера → без обмеження (зберігається все). +Розв’язання: перевизначення для конкретного DM → типове значення провайдера → без обмеження (зберігається все). -Підтримуються: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. +Підтримується: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. -#### Режим самочату +#### Режим self-chat -Додайте власний номер до `allowFrom`, щоб увімкнути режим самочату (ігнорує нативні @-згадки, відповідає лише на текстові шаблони): +Додайте свій власний номер до `allowFrom`, щоб увімкнути режим self-chat (ігнорує власні @-згадки, відповідає лише на текстові шаблони): ```json5 { @@ -832,7 +832,7 @@ IRC працює через extension і налаштовується в `channe } ``` -### Команди (обробка команд чату) +### Команди (обробка команд у чаті) ```json5 { @@ -859,40 +859,40 @@ IRC працює через extension і налаштовується в `channe } ``` - + -- Цей блок налаштовує поверхні команд. Для поточного каталогу вбудованих + вбудованих команд див. [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 вимкненим. -- Перевизначення для окремого каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди. -- Перевизначайте реєстрацію нативних команд Skills для окремого каналу за допомогою `channels..commands.nativeSkills`. +- Цей блок налаштовує поверхні команд. Актуальний каталог вбудованих + 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 вимкненим. +- Перевизначення для каналу: `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` залишається доступним для звичайних клієнтів оператора з правом запису. -- `mcp: true` вмикає `/mcp` для конфігурації MCP-сервера, яким керує OpenClaw, у `mcp.servers`. -- `plugins: true` вмикає `/plugins` для виявлення Plugin, встановлення та елементів керування ввімкненням/вимкненням. -- `channels..configWrites` керує мутаціями конфігурації для окремого каналу (типово: true). -- Для каналів із кількома обліковими записами `channels..accounts..configWrites` також керує записами, націленими на цей обліковий запис (наприклад, `/allowlist --config --account ` або `/config set channels..accounts....`). +- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів gateway `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; доступний лише для читання `/config show` залишається доступним для звичайних операторських клієнтів із правами запису. +- `mcp: true` вмикає `/mcp` для керованої OpenClaw конфігурації MCP-сервера в `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 власника в системному запиті. Установіть `ownerDisplaySecret`, щоб керувати хешуванням. -- `allowFrom` є окремим для кожного provider. Якщо встановлено, це **єдине** джерело авторизації (списки дозволів/прив’язка каналу та `useAccessGroups` ігноруються). -- `useAccessGroups: false` дозволяє командам обходити політики access-group, коли `allowFrom` не встановлено. +- `ownerAllowFrom` — це явний список дозволених власників для команд/інструментів лише для власника. Він відокремлений від `allowFrom`. +- `ownerDisplay: "hash"` хешує ID власника в системному промпті. Задайте `ownerDisplaySecret`, щоб керувати хешуванням. +- `allowFrom` задається окремо для кожного провайдера. Якщо його вказано, це **єдине** джерело авторизації (списки дозволених каналу/спарювання та `useAccessGroups` ігноруються). +- `useAccessGroups: false` дозволяє командам обходити політики груп доступу, коли `allowFrom` не задано. - Відповідність документації команд: - - каталог вбудованих + вбудованих команд: [Slash Commands](/uk/tools/slash-commands) - - поверхні команд, специфічні для каналів: [Канали](/uk/channels) + - вбудований + bundled каталог: [Slash Commands](/uk/tools/slash-commands) + - поверхні команд, специфічні для каналу: [Channels](/uk/channels) - команди QQ Bot: [QQ Bot](/uk/channels/qqbot) - - команди прив’язки: [Pairing](/uk/channels/pairing) + - команди спарювання: [Pairing](/uk/channels/pairing) - команда картки LINE: [LINE](/uk/channels/line) - - memory dreaming: [Dreaming](/uk/concepts/dreaming) + - dreaming пам’яті: [Dreaming](/uk/concepts/dreaming) --- -## Типові значення агентів +## Значення агентів за замовчуванням ### `agents.defaults.workspace` @@ -906,7 +906,7 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, який відображається в рядку Runtime системного запиту. Якщо не встановлено, OpenClaw визначає його автоматично, піднімаючись угору від workspace. +Необов’язковий корінь репозиторію, що показується в рядку Runtime системного промпта. Якщо не задано, OpenClaw автоматично визначає його, рухаючись угору від workspace. ```json5 { @@ -916,7 +916,7 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.skills` -Необов’язковий типовий список дозволів Skills для агентів, які не задають +Необов’язковий список дозволених Skills за замовчуванням для агентів, які не задають `agents.list[].skills`. ```json5 @@ -932,10 +932,10 @@ IRC працює через extension і налаштовується в `channe } ``` -- Не вказуйте `agents.defaults.skills`, щоб типово дозволити необмежені Skills. -- Не вказуйте `agents.list[].skills`, щоб успадкувати типові значення. -- Установіть `agents.list[].skills: []`, щоб не використовувати Skills. -- Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він +- Пропустіть `agents.defaults.skills`, щоб типово не обмежувати Skills. +- Пропустіть `agents.list[].skills`, щоб успадкувати типові значення. +- Установіть `agents.list[].skills: []`, щоб не мати жодних Skills. +- Непорожній список `agents.list[].skills` є фінальним набором для цього агента; він не об’єднується з типовими значеннями. ### `agents.defaults.skipBootstrap` @@ -950,9 +950,9 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.contextInjection` -Керує тим, коли bootstrap-файли workspace вбудовуються в системний запит. Типове значення: `"always"`. +Керує тим, коли bootstrap-файли workspace вбудовуються в системний промпт. Типове значення: `"always"`. -- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне вбудовування bootstrap workspace, зменшуючи розмір запиту. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст. +- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді помічника) пропускають повторне вбудовування bootstrap workspace, зменшуючи розмір промпта. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст. ```json5 { @@ -962,7 +962,7 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів для одного bootstrap-файлу workspace до обрізання. Типове значення: `12000`. +Максимальна кількість символів на один bootstrap-файл workspace до обрізання. Типове значення: `12000`. ```json5 { @@ -972,7 +972,7 @@ IRC працює через extension і налаштовується в `channe ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що вбудовуються в усі bootstrap-файли workspace. Типове значення: `60000`. +Максимальна загальна кількість символів, що вбудовуються з усіх bootstrap-файлів workspace. Типове значення: `60000`. ```json5 { @@ -985,7 +985,7 @@ IRC працює через extension і налаштовується в `channe Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається. Типове значення: `"once"`. -- `"off"`: ніколи не вбудовувати текст попередження в системний запит. +- `"off"`: ніколи не вбудовувати текст попередження в системний промпт. - `"once"`: вбудовувати попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано). - `"always"`: вбудовувати попередження під час кожного запуску, коли є обрізання. @@ -997,22 +997,22 @@ IRC працює через extension і налаштовується в `channe ### Карта відповідальності за бюджет контексту -OpenClaw має кілька великих бюджетів запиту/контексту, і вони -навмисно розділені за підсистемами замість того, щоб проходити через один -загальний параметр. +OpenClaw має кілька великих бюджетів промпта/контексту, і вони +навмисно розділені між підсистемами замість того, щоб усе проходило через +один загальний параметр. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: звичайне вбудовування bootstrap workspace. - `agents.defaults.startupContext.*`: - одноразова стартова преамбула для `/new` і `/reset`, включно з недавніми - файлами `memory/*.md` за день. + одноразова стартова прелюдія для `/new` і `/reset`, включно з нещодавніми щоденними + файлами `memory/*.md`. - `skills.limits.*`: - компактний список Skills, вбудований у системний запит. + компактний список Skills, вбудований у системний промпт. - `agents.defaults.contextLimits.*`: - обмежені фрагменти runtime і вбудовані блоки, що належать runtime. + обмежені runtime-уривки та вбудовані блоки, що належать runtime. - `memory.qmd.limits.*`: - розмір фрагментів індексованого пошуку в пам’яті та вбудовування. + уривки індексованого пошуку пам’яті та розміри вбудовування. Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший бюджет: @@ -1022,7 +1022,7 @@ OpenClaw має кілька великих бюджетів запиту/кон #### `agents.defaults.startupContext` -Керує стартовою преамбулою першого ходу, яка вбудовується в порожні запуски `/new` і `/reset`. +Керує стартовою прелюдією першого ходу, яка вбудовується при звичайних запусках `/new` і `/reset`. ```json5 { @@ -1043,7 +1043,7 @@ OpenClaw має кілька великих бюджетів запиту/кон #### `agents.defaults.contextLimits` -Спільні типові значення для обмежених поверхонь контексту runtime. +Спільні типові значення для обмежених поверхонь runtime-контексту. ```json5 { @@ -1060,17 +1060,17 @@ OpenClaw має кілька великих бюджетів запиту/кон } ``` -- `memoryGetMaxChars`: типове обмеження фрагмента `memory_get` до додавання - метаданих обрізання та повідомлення про продовження. +- `memoryGetMaxChars`: типове обмеження уривка `memory_get` до додавання метаданих + обрізання та повідомлення про продовження. - `memoryGetDefaultLines`: типове вікно рядків `memory_get`, коли `lines` - не вказано. -- `toolResultMaxChars`: обмеження результату live-інструмента, яке використовується для збережених результатів і - відновлення після переповнення. -- `postCompactionMaxChars`: обмеження фрагмента AGENTS.md, яке використовується під час оновлення вбудовування після Compaction. + пропущено. +- `toolResultMaxChars`: актуальне обмеження результату інструмента, що використовується для збережених результатів і + відновлення при переповненні. +- `postCompactionMaxChars`: обмеження уривка AGENTS.md, що використовується під час вбудовування оновлення після Compaction. #### `agents.list[].contextLimits` -Перевизначення для окремого агента для спільних параметрів `contextLimits`. Невказані поля успадковуються +Перевизначення для окремого агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються з `agents.defaults.contextLimits`. ```json5 @@ -1097,7 +1097,7 @@ OpenClaw має кілька великих бюджетів запиту/кон #### `skills.limits.maxSkillsPromptChars` -Глобальне обмеження для компактного списку Skills, вбудованого в системний запит. Це +Глобальне обмеження для компактного списку Skills, вбудованого в системний промпт. Це не впливає на читання файлів `SKILL.md` на вимогу. ```json5 @@ -1112,7 +1112,7 @@ OpenClaw має кілька великих бюджетів запиту/кон #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Перевизначення для окремого агента для бюджету запиту Skills. +Перевизначення для окремого агента для бюджету промпта Skills. ```json5 { @@ -1131,11 +1131,11 @@ OpenClaw має кілька великих бюджетів запиту/кон ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для найдовшої сторони зображення в блоках зображень transcript/tool перед викликами provider. +Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень transcript/tool перед викликами провайдера. Типове значення: `1200`. -Нижчі значення зазвичай зменшують використання vision-token і розмір payload запиту для запусків із великою кількістю знімків екрана. -Вищі значення зберігають більше візуальних деталей. +Менші значення зазвичай зменшують використання vision-токенів і розмір payload запиту для запусків із великою кількістю знімків екрана. +Більші значення зберігають більше візуальних деталей. ```json5 { @@ -1145,7 +1145,7 @@ OpenClaw має кілька великих бюджетів запиту/кон ### `agents.defaults.userTimezone` -Часовий пояс для контексту системного запиту (не для часових міток повідомлень). Якщо не встановлено, використовується часовий пояс хоста. +Часовий пояс для контексту системного промпта (не часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста. ```json5 { @@ -1155,7 +1155,7 @@ OpenClaw має кілька великих бюджетів запиту/кон ### `agents.defaults.timeFormat` -Формат часу в системному запиті. Типове значення: `auto` (налаштування ОС). +Формат часу в системному промпті. Типове значення: `auto` (налаштування ОС). ```json5 { @@ -1193,7 +1193,7 @@ OpenClaw має кілька великих бюджетів запиту/кон primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // global default provider params + params: { cacheRetention: "long" }, // глобальні типові параметри провайдера embeddedHarness: { runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none @@ -1213,47 +1213,47 @@ OpenClaw має кілька великих бюджетів запиту/кон ``` - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Форма рядка задає лише основну модель. - - Форма об’єкта задає основну модель плюс впорядковані 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-1` для OpenAI Images. - - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію provider/API key (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). - - Якщо не вказано, `image_generate` усе одно може визначити типове значення provider з автентифікацією. Спочатку він пробує поточного типового provider, потім решту зареєстрованих provider генерації зображень у порядку provider-id. + - Якщо ви вибираєте `provider/model` напряму, також налаштуйте відповідну автентифікацію/API-ключ провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). + - Якщо значення пропущено, `image_generate` усе одно може визначити типове значення провайдера на основі автентифікації. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації зображень у порядку 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 з автентифікацією. Спочатку він пробує поточного типового provider, потім решту зареєстрованих provider генерації музики в порядку provider-id. - - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію provider/API key. + - Якщо значення пропущено, `music_generate` усе одно може визначити типове значення провайдера на основі автентифікації. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації музики в порядку ID провайдера. + - Якщо ви вибираєте `provider/model` напряму, також налаштуйте відповідну автентифікацію/API-ключ провайдера. - `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`. - Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`. - - Якщо не вказано, `video_generate` усе одно може визначити типове значення provider з автентифікацією. Спочатку він пробує поточного типового provider, потім решту зареєстрованих provider генерації відео в порядку provider-id. - - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію provider/API key. - - Вбудований provider генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд і параметри рівня provider `size`, `aspectRatio`, `resolution`, `audio` і `watermark`. + - Якщо значення пропущено, `video_generate` усе одно може визначити типове значення провайдера на основі автентифікації. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації відео в порядку ID провайдера. + - Якщо ви вибираєте `provider/model` напряму, також налаштуйте відповідну автентифікацію/API-ключ провайдера. + - Bundled провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується інструментом `pdf` для маршрутизації моделі. - - Якщо не вказано, інструмент PDF використовує як резервний варіант `imageModel`, а потім визначену модель сесії/типову модель. + - Якщо значення пропущено, інструмент PDF використовує резервно `imageModel`, а потім — визначену модель сесії/типову модель. - `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. -- `pdfMaxPages`: типова максимальна кількість сторінок, що враховуються в режимі резервного вилучення інструмента `pdf`. -- `verboseDefault`: типовий рівень докладності для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`. -- `elevatedDefault`: типовий рівень elevated-виводу для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`. -- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4`). Якщо не вказати provider, OpenClaw спочатку пробує alias, потім унікальний збіг exact model id серед налаштованих provider, і лише потім використовує налаштований типовий provider (застаріла сумісна поведінка, тому краще явно вказувати `provider/model`). Якщо цей provider більше не надає налаштовану типову модель, OpenClaw переходить до першого налаштованого provider/model замість показу застарілого типового значення видаленого provider. -- `models`: налаштований каталог моделей і список дозволених значень для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для provider, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). -- `params`: глобальні типові параметри provider, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`). -- Пріоритет об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для окремої моделі), а потім `agents.list[].params` (відповідний agent 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. +- `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 переходить до першого налаштованого провайдера/моделі замість того, щоб показувати застаріле типове значення видаленого провайдера. +- `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. ### `agents.defaults.embeddedHarness` -`embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента. -Більшість розгортань мають залишати типове значення `{ runtime: "auto", fallback: "pi" }`. -Використовуйте це, коли довірений Plugin надає нативний harness, наприклад вбудований +`embeddedHarness` керує тим, який низькорівневий виконавець обробляє ходи вбудованого агента. +У більшості розгортань слід залишити типове значення `{ runtime: "auto", fallback: "pi" }`. +Використовуйте це, коли довірений Plugin надає нативний harness, наприклад bundled harness сервера застосунку Codex. ```json5 @@ -1270,15 +1270,15 @@ harness сервера застосунку 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 як резервний варіант сумісності. `"none"` призводить до помилки, якщо вибраний harness Plugin відсутній або не підтримується, замість того щоб непомітно використовувати PI. - Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає резервний перехід на PI для цього процесу. -- Для розгортань лише з Codex установіть `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. -- Це керує лише вбудованим chat harness. Генерація медіа, vision, PDF, музика, відео і TTS усе одно використовують свої налаштування provider/model. +- Для розгортань лише з Codex встановіть `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. +- Це керує лише вбудованим chat harness. Генерація медіа, vision, PDF, музики, відео та TTS і далі використовують свої налаштування провайдера/моделі. -**Вбудовані скорочення alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): +**Вбудовані скорочення-псевдоніми** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): -| Alias | Модель | +| Псевдонім | Модель | | ------------------- | -------------------------------------- | | `opus` | `anthropic/claude-opus-4-6` | | `sonnet` | `anthropic/claude-sonnet-4-6` | @@ -1289,15 +1289,15 @@ harness сервера застосунку Codex. | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Ваші налаштовані alias завжди мають пріоритет над типовими. +Ваші налаштовані псевдоніми завжди мають пріоритет над типовими. -Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не встановите `--thinking off` або самостійно не визначите `agents.defaults.models["zai/"].params.thinking`. +Моделі Z.AI 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 типово використовують `adaptive` thinking, коли явний рівень thinking не задано. ### `agents.defaults.cliBackends` -Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API provider недоступні. +Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють. ```json5 { @@ -1326,12 +1326,12 @@ harness сервера застосунку Codex. ``` - CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені. -- Сесії підтримуються, коли встановлено `sessionArg`. -- Пряма передача зображень підтримується, коли `imageArg` приймає шляхи до файлів. +- Сесії підтримуються, якщо задано `sessionArg`. +- Передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` -Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Установлюється на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами. +Замінює весь системний промпт, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для конкретного агента (`agents.list[].systemPromptOverride`). Значення для агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із промптом. ```json5 { @@ -1372,15 +1372,15 @@ harness сервера застосунку Codex. } ``` -- `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 запускають повні ходи агентів — коротші інтервали спалюють більше токенів. +- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API-ключ) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути. +- `includeSystemPromptSection`: якщо значення false, секція Heartbeat не включається в системний промпт і вбудовування `HEARTBEAT.md` у bootstrap-контекст пропускається. Типове значення: `true`. +- `suppressToolErrorWarnings`: якщо значення true, під час запусків Heartbeat попередження про помилки інструментів не додаються. +- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента Heartbeat, після чого його буде перервано. Якщо не вказано, використовується `agents.defaults.timeoutSeconds`. +- `directPolicy`: політика прямої доставки/доставки в DM. `allow` (типово) дозволяє пряму доставку до цілі. `block` забороняє пряму доставку до цілі й створює `reason=dm-blocked`. +- `lightContext`: якщо значення true, запуски Heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів workspace. +- `isolatedSession`: якщо значення true, кожен запуск Heartbeat виконується в новій сесії без попередньої історії розмови. Та сама схема ізоляції, що й у Cron `sessionTarget: "isolated"`. Зменшує витрати токенів на кожен Heartbeat приблизно зі ~100K до ~2-5K токенів. +- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, Heartbeat запускається **лише для цих агентів**. +- Heartbeat виконує повні ходи агента — менші інтервали спалюють більше токенів. ### `agents.defaults.compaction` @@ -1410,15 +1410,15 @@ harness сервера застосунку Codex. } ``` -- `mode`: `default` або `safeguard` (підсумовування шматками для довгої історії). Див. [Compaction](/uk/concepts/compaction). -- `provider`: id зареєстрованого compaction provider plugin. Якщо встановлено, замість вбудованого підсумовування LLM викликається `summarize()` provider. У разі збою використовується вбудований варіант. Встановлення provider примусово задає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). -- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції Compaction, перш ніж OpenClaw перерве її. Типове значення: `900`. +- `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 залишався безшумним. -- `memoryFlush`: безшумний агентний хід перед авто-Compaction для збереження довготривалої пам’яті. Пропускається, якщо workspace доступний лише для читання. +- `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 залишався безшумним. +- `memoryFlush`: безшумний агентний хід перед автоматичним Compaction для збереження тривких спогадів. Пропускається, якщо workspace доступний лише для читання. ### `agents.defaults.contextPruning` @@ -1447,18 +1447,18 @@ harness сервера застосунку Codex. - `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього дотику до кешу). -- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім, за потреби, повністю очищає старіші результати інструментів. +- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього торкання кешу). +- Обрізання спочатку м’яко скорочує надто великі результати інструментів, а потім за потреби повністю очищає старіші результати інструментів. **М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині. -**Повне очищення** замінює весь результат інструмента на заповнювач. +**Повне очищення** замінює весь результат інструмента на placeholder. Примітки: - Блоки зображень ніколи не обрізаються й не очищаються. -- Співвідношення базуються на символах (приблизно), а не на точній кількості токенів. -- Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається. +- Співвідношення базуються на символах (приблизно), а не на точних кількостях токенів. +- Якщо існує менше ніж `keepLastAssistants` повідомлень помічника, обрізання пропускається. @@ -1480,13 +1480,13 @@ harness сервера застосунку Codex. } ``` -- Канали, крім Telegram, вимагають явного `*.blockStreaming: true`, щоб увімкнути блокові відповіді. +- Канали, окрім 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 { @@ -1603,7 +1603,7 @@ harness сервера застосунку Codex. } ``` - + **Backend:** @@ -1611,15 +1611,15 @@ harness сервера застосунку Codex. - `ssh`: загальний віддалений runtime на основі SSH - `openshell`: runtime OpenShell -Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться до +Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переміщуються до `plugins.entries.openshell.config`. **Конфігурація backend SSH:** - `target`: ціль SSH у форматі `user@host[:port]` - `command`: команда клієнта SSH (типово: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace у межах області -- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, передані в OpenSSH +- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace за кожною областю +- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються до OpenSSH - `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує у тимчасові файли під час runtime - `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH @@ -1628,27 +1628,27 @@ harness сервера застосунку Codex. - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data` на основі SecretRef визначаються з активного знімка runtime секретів перед початком сесії sandbox +- Значення `*Data` на основі SecretRef визначаються з активного знімка runtime секретів до початку сесії sandbox **Поведінка backend SSH:** -- один раз заповнює віддалений workspace після створення або повторного створення -- потім зберігає віддалений workspace як канонічний -- маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH +- один раз ініціалізує віддалений workspace після створення або повторного створення +- потім підтримує віддалений workspace як канонічний +- маршрутизує `exec`, файлові інструменти й шляхи медіа через SSH - не синхронізує віддалені зміни назад на хост автоматично - не підтримує браузерні контейнери sandbox **Доступ до workspace:** -- `none`: workspace sandbox у межах області в `~/.openclaw/sandboxes` -- `ro`: workspace sandbox у `/workspace`, workspace агента монтується лише для читання в `/agent` -- `rw`: workspace агента монтується для читання/запису в `/workspace` +- `none`: workspace sandbox за областю в `~/.openclaw/sandboxes` +- `ro`: workspace sandbox у `/workspace`, workspace агента змонтовано лише для читання в `/agent` +- `rw`: workspace агента змонтовано для читання/запису в `/workspace` -**Область дії:** +**Область:** -- `session`: окремий контейнер + workspace для кожної сесії -- `agent`: один контейнер + workspace для кожного агента (типово) -- `shared`: спільний контейнер і workspace (без міжсесійної ізоляції) +- `session`: окремий контейнер + workspace на сесію +- `agent`: один контейнер + workspace на агента (типово) +- `shared`: спільний контейнер і workspace (без ізоляції між сесіями) **Конфігурація Plugin OpenShell:** @@ -1678,29 +1678,29 @@ harness сервера застосунку Codex. **Режим OpenShell:** -- `mirror`: перед `exec` заповнює віддалений workspace з локального, після `exec` синхронізує назад; локальний workspace залишається канонічним -- `remote`: один раз заповнює віддалений workspace під час створення sandbox, після чого віддалений workspace залишається канонічним +- `mirror`: ініціалізує віддалене середовище з локального перед `exec`, синхронізує назад після `exec`; локальний workspace залишається канонічним +- `remote`: один раз ініціалізує віддалене середовище, коли sandbox створюється, після чого віддалений workspace залишається канонічним -У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після етапу початкового заповнення. -Транспорт — SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією. +У режимі `remote` локальні редагування на хості, зроблені поза OpenClaw, не синхронізуються автоматично в sandbox після кроку ініціалізації. +Транспорт — SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою синхронізацією mirror. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, записуваного кореня, користувача root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, записуваного root і root-користувача. -**Для контейнерів типово використовується `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихід назовні. +**Для контейнерів типово встановлено `network: "none"`** — задайте `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. `"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (режим break-glass). **Вхідні вкладення** розміщуються в `media/inbound/*` в активному workspace. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні монтування та монтування для окремого агента об’єднуються. +**`docker.binds`** монтує додаткові каталоги хоста; глобальні й агентські bind-монтування об’єднуються. -**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в системний запит. Не потребує `browser.enabled` в `openclaw.json`. -Доступ спостерігача через noVNC типово використовує автентифікацію VNC, а OpenClaw видає URL із короткоживучим токеном (замість показу пароля в спільному URL). +**Ізольований браузер** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в системний промпт. Не потребує `browser.enabled` в `openclaw.json`. +Доступ спостерігача через noVNC типово використовує VNC-автентифікацію, і OpenClaw видає короткоживучий URL із токеном (замість того щоб розкривати пароль у спільному URL). -- `allowHostControl: false` (типово) блокує націлювання сесій sandbox на браузер хоста. -- `network` типово має значення `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна зв’язність bridge. -- `cdpSourceRange` необов’язково обмежує вхід CDP на межі контейнера до діапазону CIDR (наприклад, `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо встановлено (включно з `[]`), воно замінює `docker.binds` для контейнера браузера. +- `allowHostControl: false` (типово) блокує націлювання ізольованих сесій на браузер хоста. +- `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=` @@ -1720,26 +1720,26 @@ harness сервера застосунку Codex. - `--metrics-recording-only` - `--disable-extensions` (типово ввімкнено) - `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu` - типово ввімкнені й можуть бути вимкнені через - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо для використання WebGL/3D це потрібно. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш робочий процес + типово ввімкнені та можуть бути вимкнені через + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо цього потребує використання WebGL/3D. + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає extensions, якщо ваш workflow залежить від них. - `--renderer-process-limit=2` можна змінити через `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати типове обмеження процесів Chromium. - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. - - Типові значення є базовими для образу контейнера; щоб змінити типові значення контейнера, використовуйте - власний образ браузера з власним entrypoint. + - Типові значення — це базовий рівень образу контейнера; використовуйте власний образ браузера з власним + entrypoint, щоб змінити типові значення контейнера. -Ізоляція браузера та `sandbox.docker.binds` підтримуються лише для Docker. +Browser sandboxing і `sandbox.docker.binds` доступні лише для Docker. -Збірка образів: +Зберіть образи: ```bash -scripts/sandbox-setup.sh # main sandbox image -scripts/sandbox-browser-setup.sh # optional browser image +scripts/sandbox-setup.sh # основний образ sandbox +scripts/sandbox-browser-setup.sh # необов’язковий образ браузера ``` ### `agents.list` (перевизначення для окремого агента) @@ -1791,27 +1791,27 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `id`: стабільний id агента (обов’язково). -- `default`: якщо встановлено кілька значень, використовується перше (записується попередження). Якщо не встановлено жодного, типовим є перший запис у списку. -- `model`: рядкова форма перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback). Cron-завдання, які перевизначають лише `primary`, все одно успадковують типові fallback, якщо ви не встановите `fallbacks: []`. -- `params`: параметри потоку для окремого агента, об’єднані поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для специфічних для агента перевизначень, як-от `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. -- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо не вказано, агент успадковує `agents.defaults.skills`, якщо його встановлено; явний список замінює типові значення, а не об’єднується з ними, а `[]` означає відсутність Skills. -- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive`). Перевизначає `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`), коли агент має типово використовувати ACP harness sessions. +- `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`). Перевизначає `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, 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). +- `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. +- `subagents.allowAgents`: список дозволених ID агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). +- Захист успадкування sandbox: якщо сесія, що запитує, працює в sandbox, `sessions_spawn` відхиляє цілі, які працювали б без sandbox. +- `subagents.requireAgentId`: якщо true, блокує виклики `sessions_spawn`, які не містять `agentId` (примушує до явного вибору профілю; типово: false). --- ## Маршрутизація кількох агентів -Запускайте кілька ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). +Запускайте кілька ізольованих агентів усередині одного Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). ```json5 { @@ -1828,27 +1828,27 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -### Поля відповідності прив’язки +### Поля зіставлення прив’язок -- `type` (необов’язково): `route` для звичайної маршрутизації (якщо type відсутній, типово використовується route), `acp` для постійних ACP-прив’язок розмов. +- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип відсутній, типово використовується route), `acp` для постійних прив’язок розмов ACP. - `match.channel` (обов’язково) -- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо пропущено = типовий обліковий запис) +- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; пропущено = обліковий запис за замовчуванням) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (необов’язково; специфічно для каналу) +- `match.guildId` / `match.teamId` (необов’язково; залежить від каналу) - `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }` -**Детермінований порядок відповідності:** +**Детермінований порядок зіставлення:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (точний збіг, без peer/guild/team) +4. `match.accountId` (точний, без peer/guild/team) 5. `match.accountId: "*"` (для всього каналу) 6. Типовий агент У межах кожного рівня перемагає перший відповідний запис `bindings`. -Для записів `type: "acp"` OpenClaw виконує зіставлення за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує порядок рівнів route-binding вище. +Для записів `type: "acp"` OpenClaw виконує визначення за точною ідентичністю розмови (`match.channel` + account + `match.peer.id`) і не використовує порядок рівнів route-прив’язок, наведений вище. ### Профілі доступу для окремих агентів @@ -1870,7 +1870,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1949,7 +1949,7 @@ scripts/sandbox-browser-setup.sh # optional browser image --- -## Сесія +## Session ```json5 { @@ -1996,43 +1996,43 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` - + - **`scope`**: базова стратегія групування сесій для контекстів групового чату. - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу. - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли потрібен спільний контекст). - **`dmScope`**: як групуються DM. - `main`: усі DM спільно використовують основну сесію. - - `per-peer`: ізоляція за id відправника між каналами. - - `per-channel-peer`: ізоляція для кожної пари канал + відправник (рекомендовано для скриньок із кількома користувачами). - - `per-account-channel-peer`: ізоляція для кожної комбінації обліковий запис + канал + відправник (рекомендовано для кількох облікових записів). -- **`identityLinks`**: зіставлення канонічних id із peer із префіксом provider для спільного використання сесії між каналами. -- **`reset`**: основна політика скидання. `daily` скидає в локальний час `atHour`; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва параметри, використовується той, який спливає раніше. -- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застаріле `dm` приймається як alias для `direct`. -- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківської сесії, дозволене під час створення розгалуженої сесії потоку (типово `100000`). - - Якщо значення `totalTokens` батьківської сесії вище за це значення, OpenClaw запускає нову сесію потоку замість успадкування історії стенограми батьківської сесії. + - `per-peer`: ізоляція за ID відправника між каналами. + - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для вхідних скриньок із кількома користувачами). + - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для багатьохоблікових конфігурацій). +- **`identityLinks`**: відображає канонічні ID на peer-и з префіксом провайдера для спільного використання сесій між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, перемагає той, що спливає раніше. +- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`. +- **`parentForkMaxTokens`**: максимальне `totalTokens` батьківської сесії, дозволене під час створення розгалуженої сесії треду (типово `100000`). + - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw запускає нову сесію треду замість успадкування історії транскрипту батьківської сесії. - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти розгалуження від батьківської сесії. -- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного бакета прямого чату. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість ходів відповіді назад між агентами під час обміну агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong-ланцюжок. -- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. -- **`maintenance`**: очищення сховища сесій + елементи керування зберіганням. - - `mode`: `warn` лише видає попередження; `enforce` застосовує очищення. - - `pruneAfter`: поріг віку для застарілих записів (типово `30d`). +- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного кошика прямих чатів. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів відповіді між агентами під час обміну агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong-ланцюжок. +- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона перемагає. +- **`maintenance`**: очищення сховища сесій + керування зберіганням. + - `mode`: `warn` лише генерує попередження; `enforce` застосовує очищення. + - `pruneAfter`: віковий поріг для застарілих записів (типово `30d`). - `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`). - - `rotateBytes`: ротує `sessions.json`, коли він перевищує цей розмір (типово `10mb`). - - `resetArchiveRetention`: строк зберігання архівів стенограм `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. - - `maxDiskBytes`: необов’язковий жорсткий бюджет каталогу сесій на диску. У режимі `warn` записує попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. - - `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово `80%` від `maxDiskBytes`. -- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до потоків. - - `enabled`: головний типовий перемикач (provider можуть перевизначити; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: типове автоматичне зняття фокуса через неактивність у годинах (`0` вимикає; provider можуть перевизначити) - - `maxAgeHours`: типове жорстке максимальне значення віку в годинах (`0` вимикає; provider можуть перевизначити) + - `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` вимикає; провайдери можуть перевизначати) --- -## Повідомлення +## Messages ```json5 { @@ -2064,36 +2064,36 @@ scripts/sandbox-browser-setup.sh # optional browser image ### Префікс відповіді -Перевизначення для окремого каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Визначення (перемагає найконкретніше): обліковий запис → канал → глобальне значення. `""` вимикає й зупиняє каскад. `"auto"` виводить `[{identity.name}]`. +Розв’язання (перемагає найспецифічніше): обліковий запис → канал → глобальне значення. `""` вимикає й зупиняє каскад. `"auto"` виводить `[{identity.name}]`. **Змінні шаблону:** -| Змінна | Опис | Приклад | -| ---------------- | ------------------------ | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| Змінна | Опис | Приклад | +| ---------------- | ---------------------- | --------------------------- | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | | `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва provider | `anthropic` | -| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Назва identity агента | (те саме, що й `"auto"`) | +| `{provider}` | Назва провайдера | `anthropic` | +| `{thinkingLevel}`| Поточний рівень thinking | `high`, `low`, `off` | +| `{identity.name}`| Назва ідентичності агента | (те саме, що `"auto"`) | -Змінні нечутливі до регістру. `{think}` — alias для `{thinkingLevel}`. +Змінні нечутливі до регістру. `{think}` — псевдонім для `{thinkingLevel}`. ### Реакція підтвердження - Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. -- Перевизначення для окремого каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення identity. +- Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. +- Порядок розв’язання: обліковий запис → канал → `messages.ackReaction` → резервне значення з identity. - Область: `group-mentions` (типово), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: видаляє реакцію підтвердження після відповіді в Slack, Discord і Telegram. +- `removeAckAfterReply`: видаляє підтвердження після відповіді в Slack, Discord і Telegram. - `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram. - У Slack і Discord відсутнє значення зберігає реакції статусу увімкненими, коли активні реакції підтвердження. - У Telegram установіть його явно в `true`, щоб увімкнути реакції статусу життєвого циклу. + У Slack і Discord, якщо значення не задано, реакції статусу залишаються ввімкненими, коли активні реакції підтвердження. + У Telegram задайте це значення явно як `true`, щоб увімкнути реакції статусу життєвого циклу. -### Inbound debounce +### Debounce вхідних повідомлень -Об’єднує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди обходять debounce. +Об’єднує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення скидаються негайно. Керувальні команди обходять debounce. ### TTS (text-to-speech) @@ -2136,12 +2136,12 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` керує типовим режимом auto-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні налаштування, а `/tts status` показує фактичний стан. +- `auto` керує типовим режимом 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-сервер і послаблює перевірку моделі/голосу. +- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (потрібне явне ввімкнення). +- API-ключі резервно беруться з `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. +- `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок розв’язання: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. +- Коли `openai.baseUrl` вказує на endpoint, що не належить OpenAI, OpenClaw розглядає його як OpenAI-сумісний TTS-сервер і послаблює перевірку моделі/голосу. --- @@ -2171,13 +2171,13 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кілька provider Talk. -- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності й автоматично мігруються до `talk.providers.`. -- Для Voice ID використовуються резервні значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. +- `talk.provider` має відповідати ключу в `talk.providers`, якщо налаштовано кілька провайдерів Talk. +- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) підтримуються лише для сумісності й автоматично мігруються в `talk.providers.`. +- Резервні значення для ID голосу беруться з `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. - `providers.*.apiKey` приймає відкриті рядки або об’єкти SecretRef. -- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли ключ API Talk не налаштовано. +- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано API-ключ Talk. - `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви. -- `silenceTimeoutMs` керує тим, скільки режим Talk чекає після тиші користувача, перш ніж надіслати стенограму. Якщо не встановлено, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). +- `silenceTimeoutMs` керує тим, скільки режим Talk чекає після мовчання користувача перед надсиланням транскрипту. Якщо не задано, використовується типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). --- @@ -2185,22 +2185,22 @@ scripts/sandbox-browser-setup.sh # optional browser image ### Профілі інструментів -`tools.profile` задає базовий список дозволених значень перед `tools.allow`/`tools.deny`: +`tools.profile` задає базовий список дозволених інструментів перед `tools.allow`/`tools.deny`: -Локальний onboarding за замовчуванням встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються). +Локальний онбординг типово задає для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються). | Профіль | Містить | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `minimal` | лише `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Без обмежень (так само, як без значення) | +| `full` | Без обмежень (те саме, що й коли не задано) | ### Групи інструментів | Група | Інструменти | | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як alias для `exec`) | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як псевдонім для `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` | @@ -2211,11 +2211,11 @@ scripts/sandbox-browser-setup.sh # optional browser image | `group:nodes` | `nodes` | | `group:agents` | `agents_list` | | `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Усі вбудовані інструменти (без provider Plugin) | +| `group:openclaw` | Усі вбудовані інструменти (не включає Plugin провайдерів) | ### `tools.allow` / `tools.deny` -Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Нечутлива до регістру, підтримує шаблони `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено. +Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Нечутлива до регістру, підтримує wildcard `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено. ```json5 { @@ -2225,7 +2225,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.byProvider` -Додатково обмежує інструменти для конкретних provider або моделей. Порядок: базовий профіль → профіль provider → allow/deny. +Додатково обмежує інструменти для конкретних провайдерів або моделей. Порядок: базовий профіль → профіль провайдера → allow/deny. ```json5 { @@ -2241,7 +2241,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.elevated` -Керує elevated-доступом до exec поза sandbox: +Керує підвищеним доступом до `exec` поза sandbox: ```json5 { @@ -2257,9 +2257,9 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. -- `/elevated on|off|ask|full` зберігає стан для кожної сесії; inline-директиви застосовуються до одного повідомлення. -- Elevated `exec` обходить sandboxing і використовує налаштований шлях виходу (`gateway` типово, або `node`, коли ціль exec — `node`). +- Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише ще більше обмежувати. +- `/elevated on|off|ask|full` зберігає стан для кожної сесії; вбудовані директиви застосовуються до одного повідомлення. +- Підвищений `exec` обходить sandboxing і використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціль `exec` — `node`). ### `tools.exec` @@ -2283,7 +2283,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.loopDetection` -Перевірки безпеки циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб активувати виявлення. +Перевірки безпеки циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення. Налаштування можна визначити глобально в `tools.loopDetection` і перевизначити для окремого агента в `agents.list[].tools.loopDetection`. ```json5 @@ -2307,11 +2307,11 @@ scripts/sandbox-browser-setup.sh # optional browser image - `historySize`: максимальна історія викликів інструментів, що зберігається для аналізу циклів. - `warningThreshold`: поріг повторюваного шаблону без прогресу для попереджень. -- `criticalThreshold`: вищий поріг повторення для блокування критичних циклів. -- `globalCircuitBreakerThreshold`: поріг жорсткої зупинки для будь-якого виконання без прогресу. +- `criticalThreshold`: вищий поріг повторів для блокування критичних циклів. +- `globalCircuitBreakerThreshold`: поріг жорсткої зупинки для будь-якого запуску без прогресу. - `detectors.genericRepeat`: попереджати про повторні виклики того самого інструмента з тими самими аргументами. -- `detectors.knownPollNoProgress`: попереджати/блокувати відомі інструменти polling (`process.poll`, `command_status` тощо). -- `detectors.pingPong`: попереджати/блокувати чергувальні парні шаблони без прогресу. +- `detectors.knownPollNoProgress`: попереджати/блокувати відомі polling-інструменти (`process.poll`, `command_status` тощо). +- `detectors.pingPong`: попереджати/блокувати шаблони чергування пар без прогресу. - Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, валідація завершується помилкою. ### `tools.web` @@ -2380,29 +2380,29 @@ scripts/sandbox-browser-setup.sh # optional browser image -**Запис provider** (`type: "provider"` або пропущено): +**Запис провайдера** (`type: "provider"` або пропущено): -- `provider`: id API provider (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) -- `model`: перевизначення id моделі +- `provider`: ID API-провайдера (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) +- `model`: перевизначення ID моделі - `profile` / `preferredProfile`: вибір профілю `auth-profiles.json` **Запис 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`: перевизначення для конкретного запису. +- У разі помилок використовується наступний запис. -Автентифікація provider використовує стандартний порядок: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`. +Автентифікація провайдера дотримується стандартного порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`. **Поля асинхронного завершення:** - `asyncCompletion.directSend`: коли `true`, завершені асинхронні завдання `music_generate` - і `video_generate` спочатку намагаються доставити результат безпосередньо в канал. Типове значення: `false` + і `video_generate` спочатку намагаються доставитися безпосередньо в канал. Типове значення: `false` (застарілий шлях пробудження сесії запитувача/доставки моделі). @@ -2424,7 +2424,7 @@ scripts/sandbox-browser-setup.sh # optional browser image Керує тим, на які сесії можуть націлюватися інструменти сесій (`sessions_list`, `sessions_history`, `sessions_send`). -Типове значення: `tree` (поточна сесія + сесії, породжені нею, наприклад субагенти). +Типове значення: `tree` (поточна сесія + сесії, породжені нею, наприклад subagents). ```json5 { @@ -2440,14 +2440,14 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: - `self`: лише ключ поточної сесії. -- `tree`: поточна сесія + сесії, породжені поточною сесією (субагенти). -- `agent`: будь-яка сесія, що належить поточному id агента (може включати інших користувачів, якщо ви запускаєте сесії per-sender під тим самим id агента). -- `all`: будь-яка сесія. Націлювання між агентами все одно вимагає `tools.agentToAgent`. -- Обмеження sandbox: коли поточна сесія працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється на `tree`, навіть якщо `tools.sessions.visibility="all"`. +- `tree`: поточна сесія + сесії, породжені поточною сесією (subagents). +- `agent`: будь-яка сесія, що належить поточному ID агента (може включати інших користувачів, якщо ви запускаєте сесії per-sender під тим самим ID агента). +- `all`: будь-яка сесія. Націлювання між агентами все одно потребує `tools.agentToAgent`. +- Обмеження sandbox: коли поточна сесія працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` -Керує підтримкою inline-вкладень для `sessions_spawn`. +Керує підтримкою вбудованих вкладень для `sessions_spawn`. ```json5 { @@ -2467,16 +2467,16 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: -- Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP відхиляє їх. -- Файли матеріалізуються в дочірньому workspace за шляхом `.openclaw/attachments//` разом із `.manifest.json`. -- Вміст вкладень автоматично редагується під час збереження transcript. -- Входи base64 перевіряються за суворими правилами алфавіту/відступів і з попередньою перевіркою розміру до декодування. +- Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє. +- Файли матеріалізуються в дочірньому workspace у `.openclaw/attachments//` із `.manifest.json`. +- Вміст вкладень автоматично редагується в збереженому transcript. +- Входи Base64 перевіряються строгими перевірками алфавіту/паддінгу та захистом розміру до декодування. - Права доступу до файлів: `0700` для каталогів і `0600` для файлів. - Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише тоді, коли `retainOnSessionKeep: true`. ### `tools.experimental` -Прапори експериментальних вбудованих інструментів. Типово вимкнені, якщо не застосовується правило автоматичного ввімкнення strict-agentic GPT-5. +Експериментальні прапорці вбудованих інструментів. Типово вимкнено, якщо не застосовується правило автоувімкнення strict-agentic GPT-5. ```json5 { @@ -2491,8 +2491,8 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: - `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи. -- Типове значення: `false`, якщо лише `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цією областю, або `false`, щоб залишити його вимкненим навіть для запусків strict-agentic GPT-5. -- Коли інструмент увімкнено, системний запит також додає вказівки щодо використання, щоб модель застосовувала його лише для суттєвої роботи й тримала не більше одного кроку у стані `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` @@ -2512,16 +2512,16 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `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`. --- -## Власні provider і base URL +## Власні провайдери та base URL -OpenClaw використовує вбудований каталог моделей. Додавайте власні provider через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. +OpenClaw використовує вбудований каталог моделей. Додавайте власних провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -2551,49 +2551,49 @@ OpenClaw використовує вбудований каталог модел ``` - Використовуйте `authHeader: true` + `headers` для власних потреб автентифікації. -- Перевизначайте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий alias змінної середовища). -- Пріоритет об’єднання для provider з однаковими ID: - - Непорожні значення `baseUrl` в `models.json` агента мають пріоритет. - - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цей provider не керується через SecretRef у поточному контексті config/auth-profile. - - Значення `apiKey` provider, якими керує SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження визначених секретів. - - Значення заголовків provider, якими керує 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. +- Перевизначайте корінь конфігурації агента через `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-значень секретів. -### Подробиці полів provider +### Деталі полів провайдера -- `models.mode`: поведінка каталогу provider (`merge` або `replace`). -- `models.providers`: карта власних provider, ключем якої є id provider. +- `models.mode`: поведінка каталогу провайдерів (`merge` або `replace`). +- `models.providers`: власна карта провайдерів із ключами за ID провайдера. - `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо). -- `models.providers.*.apiKey`: облікові дані provider (краще використовувати підстановку 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 upstream API. -- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації proxy/tenant. -- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів model-provider. - - `request.headers`: додаткові заголовки (об’єднуються з типовими значеннями provider). Значення приймають SecretRef. - - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію provider), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value`, необов’язковим `prefix`). - - `request.proxy`: перевизначення HTTP proxy. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`. +- `models.providers.*.authHeader`: примусово передавати облікові дані в заголовку `Authorization`, коли це потрібно. +- `models.providers.*.baseUrl`: базова URL-адреса зовнішнього API. +- `models.providers.*.headers`: додаткові статичні заголовки для proxy/маршрутизації tenant. +- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів провайдера моделей. + - `request.headers`: додаткові заголовки (об’єднуються з типовими значеннями провайдера). Значення приймають SecretRef. + - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (із `token`), `"header"` (із `headerName`, `value`, необов’язковим `prefix`). + - `request.proxy`: перевизначення HTTP proxy. Режими: `"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 provider (opt-in оператора для довірених власних OpenAI-сумісних endpoint). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-запобіжник fetch. Типове значення `false`. -- `models.providers.*.models`: явні записи каталогу моделей provider. -- `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`: корінь налаштувань auto-discovery Bedrock. -- `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути або вимкнути неявне виявлення. + - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS визначається в приватні, CGNAT або подібні діапазони, через захист SSRF HTTP fetch провайдера (opt-in оператора для довірених власноруч розміщених 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. +- `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне виявлення. - `plugins.entries.amazon-bedrock.config.discovery.region`: регіон AWS для виявлення. -- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр provider-id для цільового виявлення. +- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр за ID провайдера для цільового виявлення. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: інтервал опитування для оновлення виявлення. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервне вікно контексту для виявлених моделей. - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервна максимальна кількість вихідних токенів для виявлених моделей. -### Приклади provider +### Приклади провайдерів @@ -2629,7 +2629,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. @@ -2646,7 +2646,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`. @@ -2663,11 +2663,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` є прийнятними alias. Скорочений варіант: `openclaw onboard --auth-choice zai-api-key`. +Задайте `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` приймаються як псевдоніми. Скорочення: `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 визначте власний provider із перевизначенням base URL. +- Endpoint для кодування (типово): `https://api.z.ai/api/coding/paas/v4` +- Для загального endpoint визначте власного провайдера з перевизначенням base URL. @@ -2708,9 +2708,9 @@ OpenClaw використовує вбудований каталог модел Для endpoint у Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. -Нативні endpoint Moonshot оголошують сумісність використання потокового передавання через спільний -транспорт `openai-completions`, і OpenClaw визначає це за можливостями endpoint, -а не лише за id вбудованого provider. +Власні endpoint Moonshot оголошують сумісність використання потокової передачі на спільному +транспорті `openai-completions`, і OpenClaw орієнтується на можливості endpoint, +а не лише на вбудований ID провайдера. @@ -2728,11 +2728,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Anthropic-сумісний, вбудований provider. Скорочений варіант: `openclaw onboard --auth-choice kimi-code-api-key`. +Сумісний з Anthropic, вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. - + ```json5 { @@ -2767,11 +2767,11 @@ Anthropic-сумісний, вбудований provider. Скорочений } ``` -Base URL має не містити `/v1` (клієнт Anthropic додає його). Скорочений варіант: `openclaw onboard --auth-choice synthetic-api-key`. +Base URL має не містити `/v1` (клієнт Anthropic додає його). Скорочення: `openclaw onboard --auth-choice synthetic-api-key`. - + ```json5 { @@ -2807,11 +2807,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-сумісному шляху потокового передавання OpenClaw типово вимикає thinking MiniMax, +На Anthropic-сумісному шляху потокової передачі OpenClaw типово вимикає thinking MiniMax, якщо ви явно не задасте `thinking` самостійно. `/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. @@ -2820,7 +2820,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й -Див. [Локальні моделі](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; зберігайте розміщені моделі в merged-стані як резервний варіант. +Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; залишайте hosted моделі об’єднаними для резервного переходу. @@ -2851,13 +2851,13 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `allowBundled`: необов’язковий список дозволів лише для вбудованих Skills (керовані/workspace Skills не зачіпаються). +- `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, навіть якщо він вбудований/встановлений. +- `install.preferBrew`: коли значення true, віддавати перевагу інсталяторам Homebrew, якщо `brew` + доступний, перед переходом до інших типів інсталяторів. +- `install.nodeManager`: пріоритет менеджера Node для специфікацій + `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). +- `entries..enabled: false` вимикає Skill, навіть якщо він bundled/установлений. - `entries..apiKey`: зручний параметр для Skills, які оголошують основну env-змінну (відкритий рядок або об’єкт SecretRef). --- @@ -2886,47 +2886,47 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. -- Виявлення приймає нативні Plugin OpenClaw, а також сумісні bundles Codex і bundles Claude, включно з bundles Claude стандартного компонування без маніфесту. +- Завантажується з `~/.openclaw/extensions`, `/.openclaw/extensions` і `plugins.load.paths`. +- Виявлення приймає нативні Plugin OpenClaw, а також сумісні bundled Codex і bundled Claude, включно з bundled Claude стандартного макета без маніфесту. - **Зміни конфігурації потребують перезапуску gateway.** -- `allow`: необов’язковий список дозволів (завантажуються лише перелічені Plugin). `deny` має пріоритет. -- `plugins.entries..apiKey`: зручне поле API key на рівні Plugin (коли Plugin це підтримує). +- `allow`: необов’язковий список дозволених (завантажуються лише перелічені Plugin). `deny` має пріоритет. +- `plugins.entries..apiKey`: зручне поле API-ключа на рівні Plugin (коли Plugin це підтримує). - `plugins.entries..env`: карта env-змінних у межах Plugin. -- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` та ігнорує поля legacy `before_agent_start`, що змінюють prompt, зберігаючи legacy `modelOverride` і `providerOverride`. Застосовується до нативних hooks Plugin і підтримуваних каталогів hooks, наданих bundle. -- `plugins.entries..subagent.allowModelOverride`: явно довіряє цьому Plugin запитувати перевизначення `provider` і `model` для окремих запусків фонових субагентів. -- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень субагента. Використовуйте `"*"`, лише якщо ви свідомо хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (валідується за схемою нативного Plugin OpenClaw, якщо вона доступна). -- `plugins.entries.firecrawl.config.webFetch`: налаштування provider веб-отримання Firecrawl. - - `apiKey`: API key Firecrawl (приймає SecretRef). Використовує резервне значення з `plugins.entries.firecrawl.config.webSearch.apiKey`, legacy `tools.web.fetch.firecrawl.apiKey` або env-змінної `FIRECRAWL_API_KEY`. - - `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`). - - `onlyMainContent`: витягувати лише основний вміст зі сторінок (типово: `true`). +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` та ігнорує поля, що змінюють промпт, із застарілого `before_agent_start`, зберігаючи водночас застарілі `modelOverride` і `providerOverride`. Застосовується до нативних хуків Plugin і підтримуваних каталогів хуків, що надаються bundled. +- `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-ключ 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`). - `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні). - `timeoutSeconds`: тайм-аут запиту scrape у секундах (типово: `60`). - `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (веб-пошук Grok). - - `enabled`: увімкнути provider X Search. + - `enabled`: увімкнути провайдера X Search. - `model`: модель Grok для пошуку (наприклад, `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming. Див. [Dreaming](/uk/concepts/dreaming) для фаз і порогів. +- `plugins.entries.memory-core.config.dreaming`: налаштування dreaming пам’яті. Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів. - `enabled`: головний перемикач dreaming (типово `false`). - - `frequency`: частота Cron для кожного повного циклу dreaming (типово `"0 3 * * *"`). - - політика фаз і пороги є деталями реалізації (не ключами конфігурації для користувача). -- Повна конфігурація пам’яті знаходиться в [Довіднику з конфігурації пам’яті](/uk/reference/memory-config): + - `frequency`: каденція Cron для кожного повного проходу dreaming (типово `"0 3 * * *"`). + - політика фаз і пороги — це деталі реалізації (не користувацькі ключі конфігурації). +- Повна конфігурація пам’яті міститься в [Memory configuration reference](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені bundles 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, а не ручним редагуванням. +- Увімкнені bundled 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 { @@ -2963,28 +2963,29 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й ``` - `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`. -- Якщо `ssrfPolicy.dangerouslyAllowPrivateNetwork` не встановлено, воно вимкнене, тому навігація браузера типово залишається суворою. -- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли свідомо довіряєте браузерній навігації в приватній мережі. -- У суворому режимі endpoint віддалених профілів CDP (`profiles.*.cdpUrl`) підлягають тому самому блокуванню приватної мережі під час перевірок доступності/виявлення. -- `ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як legacy alias. -- У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. -- Віддалені профілі — лише для підключення (запуск/зупинка/скидання вимкнено). +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо значення не задано, тож навігація browser типово залишається строгою. +- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації browser у приватній мережі. +- У строгому режимі endpoint віддалених CDP-профілів (`profiles.*.cdpUrl`) під час перевірок досяжності/виявлення підпадають під те саме блокування приватної мережі. +- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім. +- У строгому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. +- Віддалені профілі працюють лише в режимі attach-only (start/stop/reset вимкнені). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. - Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявив `/json/version`; використовуйте WS(S), - коли provider надає прямий URL DevTools WebSocket. -- Профілі `existing-session` працюють лише на хості й використовують Chrome MCP замість CDP. + Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S), + коли ваш провайдер надає прямий DevTools WebSocket URL. +- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися + на вибраному хості або через підключений browser Node. - Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний - профіль браузера на основі Chromium, наприклад Brave або Edge. + профіль браузера на базі Chromium, наприклад Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії на основі snapshot/ref замість націлювання за CSS-селекторами, хуки завантаження - одного файла, без перевизначення тайм-аутів діалогів, без `wait --load networkidle` і без - `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. + дії на основі snapshot/ref замість націлювання через CSS-селектори, хуки + завантаження одного файла, відсутність перевизначення тайм-аутів діалогів, відсутність `wait --load networkidle`, + а також відсутність `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. - Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно задавайте `cdpUrl` лише для віддаленого CDP. -- Порядок автовиявлення: типовий браузер, якщо він на основі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Служба керування: лише loopback (порт визначається з `gateway.port`, типово `18791`). -- `extraArgs` додає додаткові прапори запуску до локального запуску Chromium (наприклад - `--disable-gpu`, розмір вікна або прапори налагодження). +- Порядок автовиявлення: типовий браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Сервіс керування: лише loopback (порт визначається з `gateway.port`, типово `18791`). +- `extraArgs` додає додаткові прапорці запуску до локального запуску Chromium (наприклад + `--disable-gpu`, розміри вікна або прапорці налагодження). --- @@ -3002,8 +3003,8 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `seamColor`: колір акценту для chrome нативного UI застосунку (відтінок бульбашки Talk Mode тощо). -- `assistant`: перевизначення identity для Control UI. Використовує identity активного агента як резервне значення. +- `seamColor`: акцентний колір для chrome нативного UI застосунку (відтінок бульбашки режиму Talk тощо). +- `assistant`: перевизначення ідентичності для Control UI. Якщо не задано, використовується ідентичність активного агента. --- @@ -3070,47 +3071,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`. -- **Застарілі 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**: типово обов’язкова. Не-loopback bind вимагають auth gateway. На практиці це означає спільний token/password або reverse proxy з урахуванням identity з `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. Використовуйте лише для довірених локальних конфігурацій loopback; цей варіант навмисно не пропонується в запитах onboarding. -- `gateway.auth.mode: "trusted-proxy"`: делегує auth reverse proxy з урахуванням identity та довіряє заголовкам identity від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy loopback на тому самому хості не задовольняють auth trusted-proxy. -- `gateway.auth.allowTailscale`: коли `true`, заголовки identity Tailscale Serve можуть задовольнити auth для Control UI/WebSocket (перевіряється через `tailscale whois`). Endpoint HTTP API **не** використовують цю auth через заголовки Tailscale; вони дотримуються звичайного режиму HTTP auth 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-трафік (для тестових конфігурацій або суворих розгортань proxy). -- Спроби auth WS з походження браузера завжди обмежуються без винятку для loopback (додатковий захист від brute force localhost із браузера). -- На loopback ці блокування з походження браузера ізолюються за нормалізованим значенням `Origin`, - тому повторні збої з одного localhost-origin не призводять автоматично +- **Застарілі псевдоніми 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**: типово обов’язкова. Не-loopback bind-и вимагають auth gateway. На практиці це означає спільний token/password або reverse proxy з урахуванням identity із `gateway.auth.mode: "trusted-proxy"`. Майстер онбордингу типово генерує token. +- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Під час запуску, а також у потоках встановлення/відновлення сервісу, виникає помилка, якщо налаштовано обидва значення, а `mode` не задано. +- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних конфігурацій із local loopback; цей варіант навмисно не пропонується в запитах онбордингу. +- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з урахуванням identity і довіряти заголовкам identity із `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy loopback на тому ж хості не задовольняють auth trusted-proxy. +- `gateway.auth.allowTailscale`: коли `true`, заголовки identity Tailscale Serve можуть задовольняти auth Control UI/WebSocket (перевіряється через `tailscale whois`). Endpoint HTTP API **не** використовують цю auth за заголовками Tailscale; вони натомість дотримуються звичайного режиму HTTP auth gateway. Цей потік без token припускає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: необов’язкове обмеження невдалих спроб auth. Застосовується для кожного IP клієнта й для кожної області auth (спільний секрет і token пристрою відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`. + - На асинхронному шляху Control UI Tailscale Serve невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом збою. Тому паралельні неправильні спроби від того самого клієнта можуть спрацювати на лімітер уже на другому запиті, замість того щоб обидві одночасно пройти як звичайні невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` типово дорівнює `true`; задайте `false`, якщо свідомо хочете також обмежувати трафік localhost (для тестових конфігурацій або строгих розгортань через proxy). +- Спроби WS auth із browser-origin завжди обмежуються без винятку для loopback (захист у глибину від browser-атак brute force на localhost). +- На loopback ці блокування для browser-origin ізолюються за нормалізованим значенням `Origin`, + тож повторні збої з одного localhost-origin не призводять автоматично до блокування іншого origin. -- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічний доступ, вимагає auth). -- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються клієнти браузера з не-loopback origin. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, що вмикає резервний варіант origin на основі заголовка Host для розгортань, які свідомо покладаються на політику origin заголовка Host. +- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічний, потребує auth). +- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються browser-клієнти з не-loopback origin. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, що вмикає резервне визначення origin за Host-header для розгортань, які свідомо покладаються на політику origin за Host-header. - `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійне клієнтське перевизначення, яке дозволяє відкритий `ws://` до довірених IP приватної мережі; типово відкритий текст, як і раніше, дозволено лише для loopback. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське break-glass перевизначення, яке дозволяє відкритий `ws://` до довірених IP приватної мережі; типово відкритий текст і далі дозволено лише для loopback. - `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway. -- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL зовнішнього APNs relay, який використовують офіційні/TestFlight iOS-збірки після публікації relay-backed registrations у gateway. Цей URL має збігатися з URL relay, скомпільованим в iOS-збірку. -- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. Типове значення `10000`. -- Relay-backed registrations делегуються конкретній identity gateway. Прив’язаний застосунок iOS викликає `gateway.identity.get`, включає цю identity в relay registration і пересилає до gateway дозвіл надсилання в межах registration. Інший gateway не може повторно використати це збережене registration. +- `gateway.push.apns.relay.baseUrl`: базова HTTPS URL-адреса зовнішнього APNs relay, який використовують офіційні/TestFlight iOS-збірки після публікації relay-реєстрацій до 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 relay URL. У production URL relay мають залишатися на HTTPS. -- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типове значення: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого socket у хвилинах. Має бути більшим або рівним `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 і не визначено, визначення завершується із закритою відмовою (без маскування резервним remote-варіантом). -- `trustedProxies`: IP reverse proxy, які завершують TLS або додають заголовки переспрямованого клієнта. Указуйте лише proxy, якими ви керуєте. Записи loopback усе ще дійсні для конфігурацій proxy на тому самому хості/локального виявлення (наприклад, 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. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: лише для розробки, обхідний шлях для URL relay HTTP на loopback. У production URL relay мають залишатися на HTTPS. +- `gateway.channelHealthCheckMinutes`: інтервал монітору здоров’я каналів у хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски монітором здоров’я. Типове значення: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітором здоров’я на канал/обліковий запис за ковзну годину. Типове значення: `10`. +- `channels..healthMonitor.enabled`: вимкнення перезапусків монітором здоров’я для конкретного каналу, зберігаючи глобальний монітор увімкненим. +- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису в багатьохоблікових каналах. Якщо задано, має пріоритет над перевизначенням на рівні каналу. +- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резерв лише тоді, коли `gateway.auth.*` не задано. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не визначено, визначення завершується із fail-closed (без маскування резервним `remote`). +- `trustedProxies`: IP reverse proxy, які завершують TLS або вбудовують заголовки forwarded-client. Указуйте лише ті proxy, які ви контролюєте. Записи loopback і далі коректні для конфігурацій 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-списку заборон. @@ -3118,18 +3119,18 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й - Chat Completions: типово вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Посилення захисту URL-входів Responses: +- Захист URL-входів Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Порожні allowlist вважаються невстановленими; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` + Порожні списки allowlist трактуються як незадані; використовуйте `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)) ### Ізоляція кількох екземплярів -Запускайте кілька gateway на одному хості з унікальними портами та каталогами стану: +Запускайте кілька gateway на одному хості з унікальними портами й каталогами стану: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3137,9 +3138,9 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -Зручні прапори: `--dev` (використовує `~/.openclaw-dev` + порт `19001`), `--profile ` (використовує `~/.openclaw-`). +Зручні прапорці: `--dev` (використовує `~/.openclaw-dev` + порт `19001`), `--profile ` (використовує `~/.openclaw-`). -Див. [Кілька Gateway](/uk/gateway/multiple-gateways). +Див. [Multiple Gateways](/uk/gateway/multiple-gateways). ### `gateway.tls` @@ -3157,11 +3158,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). -- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для локального використання/розробки. +- `enabled`: вмикає завершення TLS на listener gateway (HTTPS/WSS) (типово: `false`). +- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для local/dev використання. - `certPath`: шлях у файловій системі до файла TLS-сертифіката. -- `keyPath`: шлях у файловій системі до приватного ключа TLS; тримайте його з обмеженими правами доступу. -- `caPath`: необов’язковий шлях до комплекту CA для перевірки клієнта або власних ланцюжків довіри. +- `keyPath`: шлях у файловій системі до приватного TLS-ключа; тримайте його з обмеженими правами доступу. +- `caPath`: необов’язковий шлях до CA bundle для перевірки клієнта або власних ланцюжків довіри. ### `gateway.reload` @@ -3177,13 +3178,13 @@ openclaw gateway --port 19001 } ``` -- `mode`: керує тим, як зміни конфігурації застосовуються під час runtime. - - `"off"`: ігнорує live-редагування; зміни вимагають явного перезапуску. - - `"restart"`: завжди перезапускає процес gateway при зміні конфігурації. - - `"hot"`: застосовує зміни в межах процесу без перезапуску. - - `"hybrid"` (типово): спочатку пробує hot reload; за потреби переходить до перезапуску. -- `debounceMs`: вікно debounce в мс перед застосуванням змін конфігурації (невід’ємне ціле число). -- `deferralTimeoutMs`: максимальний час у мс, протягом якого очікується завершення операцій у процесі перед примусовим перезапуском (типово: `300000` = 5 хвилин). +- `mode`: керує тим, як під час runtime застосовуються зміни конфігурації. + - `"off"`: ігнорувати live-зміни; зміни потребують явного перезапуску. + - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації. + - `"hot"`: застосовувати зміни в процесі без перезапуску. + - `"hybrid"` (типово): спочатку пробувати hot reload; якщо потрібно — переходити до перезапуску. +- `debounceMs`: debounce-вікно в мс перед застосуванням змін конфігурації (невід’ємне ціле число). +- `deferralTimeoutMs`: максимальний час у мс, щоб чекати завершення поточних операцій перед примусовим перезапуском (типово: `300000` = 5 хвилин). --- @@ -3221,36 +3222,36 @@ openclaw gateway --port 19001 ``` Auth: `Authorization: Bearer ` або `x-openclaw-token: `. -Токени hooks у рядку запиту відхиляються. +Токени hook у рядку запиту відхиляються. Примітки щодо валідації та безпеки: -- `hooks.enabled=true` вимагає непорожнього `hooks.token`. -- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання токена Gateway відхиляється. +- `hooks.enabled=true` потребує непорожній `hooks.token`. +- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання token Gateway відхиляється. - `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`. -- Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). +- Якщо `hooks.allowRequestSessionKey=true`, обмежуйте `hooks.allowedSessionKeyPrefixes` (наприклад, `["hook:"]`). -**Endpoint:** +**Endpoint-и:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - `sessionKey` із payload запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`). - `POST /hooks/` → визначається через `hooks.mappings` - + -- `match.path` відповідає підшляху після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). -- `match.source` відповідає полю payload для загальних шляхів. -- Шаблони на кшталт `{{messages[0].subject}}` читають значення з payload. +- `match.path` зіставляє підшлях після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). +- `match.source` зіставляє поле payload для загальних шляхів. +- Шаблони на кшталт `{{messages[0].subject}}` читають дані з payload. - `transform` може вказувати на модуль JS/TS, який повертає дію hook. - - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та вихід за межі каталогу відхиляються). -- `agentId` маршрутизує до конкретного агента; невідомі ID використовують типового агента як резервний варіант. -- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або відсутність = дозволити всі, `[]` = заборонити всі). + - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються). +- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до типового агента. +- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити всі, `[]` = заборонити всі). - `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook-агента без явного `sessionKey`. -- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` задавати `sessionKey` (типово: `false`). -- `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + зіставлення), наприклад `["hook:"]`. +- `allowRequestSessionKey`: дозволити викликачам `/hooks/agent` задавати `sessionKey` (типово: `false`). +- `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. - `deliver: true` надсилає фінальну відповідь у канал; `channel` типово дорівнює `last`. -- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо задано каталог моделей). +- `model` перевизначає LLM для цього запуску hook (має бути дозволена, якщо задано каталог моделей). @@ -3277,12 +3278,12 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, якщо це налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. +- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, якщо налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. - Не запускайте окремий `gog gmail watch serve` паралельно з Gateway. --- -## Canvas host +## Хост Canvas ```json5 { @@ -3294,18 +3295,18 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Обслуговує HTML/CSS/JS та A2UI, які може редагувати агент, через HTTP на порту Gateway: +- Обслуговує редаговані агентом HTML/CSS/JS і A2UI через HTTP на порту Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Лише локально: зберігайте `gateway.bind: "loopback"` (типово). -- Для не-loopback bind: маршрути canvas вимагають auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway. -- Node WebViews зазвичай не надсилають заголовки auth; після прив’язки та підключення node Gateway рекламує URL можливостей у межах node для доступу до canvas/A2UI. +- Лише локально: залишайте `gateway.bind: "loopback"` (типово). +- Для не-loopback bind-ів маршрути 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`, коли каталог порожній. +- Автоматично створює стартовий `index.html`, якщо каталог порожній. - Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`. - Зміни потребують перезапуску gateway. -- Вимкніть live reload для великих каталогів або у разі помилок `EMFILE`. +- Вимкніть live reload для великих каталогів або помилок `EMFILE`. --- @@ -3323,9 +3324,9 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `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) @@ -3337,7 +3338,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS Tailscale. +Записує unicast-зону DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + Tailscale split DNS. Налаштування: `openclaw dns setup --apply`. @@ -3362,10 +3363,10 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Вбудовані env-змінні застосовуються лише тоді, коли в середовищі процесу бракує цього ключа. -- Файли `.env`: `.env` у поточному робочому каталозі + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). -- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. -- Повний порядок пріоритету див. у [Environment](/uk/help/environment). +- Вбудовані env-змінні застосовуються лише тоді, коли в середовищі процесу відсутній ключ. +- Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). +- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашого login shell. +- Повний пріоритет див. у [Environment](/uk/help/environment). ### Підстановка env-змінних @@ -3379,7 +3380,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Відповідають лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. +- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації. - Екрануйте через `$${VAR}` для буквального `${VAR}`. - Працює з `$include`. @@ -3388,11 +3389,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Секрети -Посилання на секрети є адитивними: відкриті значення й далі працюють. +SecretRef є адитивними: відкриті значення також і далі працюють. ### `SecretRef` -Використовуйте один об’єкт такої форми: +Використовуйте одну форму об’єкта: ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } @@ -3401,18 +3402,18 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. Валідація: - шаблон `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"`) -- шаблон id для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- id для `source: "exec"` не мають містити сегменти шляху `.` або `..`, розділені `/` (наприклад, `a/../b` відхиляється) +- шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- `id` для `source: "file"`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`) +- шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- `id` для `source: "exec"` не має містити slash-delimited сегментів шляху `.` або `..` (наприклад, `a/../b` відхиляється) ### Підтримувана поверхня облікових даних -- Канонічна матриця: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface) -- `secrets apply` націлюється на підтримувані шляхи облікових даних `openclaw.json`. -- Посилання `auth-profiles.json` включено до визначення runtime і охоплення аудиту. +- Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface) +- `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`. +- Посилання в `auth-profiles.json` включені до runtime-визначення та охоплення аудиту. -### Конфігурація provider секретів +### Конфігурація провайдерів секретів ```json5 { @@ -3442,13 +3443,13 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. Примітки: -- Provider `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue значення `id` має бути `"value"`). -- Provider `exec` вимагає абсолютний шлях `command` і використовує payload протоколу через stdin/stdout. +- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue значення `id` має бути `"value"`). +- Провайдер `exec` потребує абсолютного шляху `command` і використовує протокольні payload через stdin/stdout. - Типово шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання з перевіркою шляху визначеної цілі. - Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до шляху визначеної цілі. - Середовище дочірнього процесу `exec` типово мінімальне; явно передавайте потрібні змінні через `passEnv`. -- Посилання на секрети визначаються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. -- Під час активації застосовується фільтрація активної поверхні: невизначені посилання на ввімкнених поверхнях призводять до збою запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. +- SecretRef визначаються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. +- Під час активації застосовується фільтрація активної поверхні: невизначені посилання на ввімкнених поверхнях призводять до збою запуску/reload, тоді як неактивні поверхні пропускаються з діагностикою. --- @@ -3471,12 +3472,12 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - Профілі для окремого агента зберігаються в `/auth-profiles.json`. -- `auth-profiles.json` підтримує посилання на рівні значення (`keyRef` для `api_key`, `tokenRef` для `token`) для режимів статичних облікових даних. -- Профілі в режимі OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілю auth на основі SecretRef. -- Статичні облікові дані runtime надходять із визначених знімків у пам’яті; legacy-записи статичного `auth.json` очищаються після виявлення. -- Застарілі імпорти OAuth з `~/.openclaw/credentials/oauth.json`. +- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. +- Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілів auth на основі SecretRef. +- Статичні runtime-облікові дані надходять із визначених знімків у пам’яті; застарілі статичні записи `auth.json` очищаються при виявленні. +- Застарілі імпорти OAuth із `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). -- Поведінка runtime секретів і інструменти `audit/configure/apply`: [Керування секретами](/uk/gateway/secrets). +- Поведінка runtime секретів і інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). ### `auth.cooldowns` @@ -3498,20 +3499,20 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні - помилки білінгу/недостатнього кредиту (типово: `5`). Явний текст білінгу все одно може - потрапити сюди навіть за відповідей `401`/`403`, але text matcher для окремих provider - залишаються в межах provider, якому вони належать (наприклад, OpenRouter - `Key limit exceeded`). Повторювані повідомлення `402` про вікно використання або - ліміти витрат organization/workspace натомість залишаються в шляху `rate_limit`. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин billing backoff для окремих provider. -- `billingMaxHours`: обмеження в годинах для експоненційного зростання billing backoff (типово: `24`). -- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для збоїв `auth_permanent` із високою впевненістю (типово: `10`). -- `authPermanentMaxMinutes`: обмеження в хвилинах для зростання backoff `auth_permanent` (типово: `60`). -- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників backoff (типово: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile того самого provider для помилок перевантаження перед переходом до резервної моделі (типово: `1`). Такі стани зайнятості provider, як `ModelNotReadyException`, потрапляють сюди. -- `overloadedBackoffMs`: фіксована затримка перед повторною спробою перевантаженого provider/ротації профілю (типово: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile того самого provider для помилок rate-limit перед переходом до резервної моделі (типово: `1`). До цього кошика rate-limit входить текст, характерний для provider, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `billingBackoffHours`: базова затримка в годинах, коли профіль не проходить через справжні + помилки білінгу/недостатнього кредиту (типово: `5`). Явний текст про білінг + усе одно може потрапляти сюди навіть на відповідях `401`/`403`, але текстові + зіставлювачі, специфічні для провайдера, залишаються в межах свого провайдера (наприклад, OpenRouter + `Key limit exceeded`). Відтворювані повідомлення HTTP `402` про вікно використання або + ліміти витрат organization/workspace натомість залишаються на шляху `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин затримки білінгу для конкретного провайдера. +- `billingMaxHours`: обмеження в годинах для експоненційного зростання затримки білінгу (типово: `24`). +- `authPermanentBackoffMinutes`: базова затримка в хвилинах для високовпевнених збоїв `auth_permanent` (типово: `10`). +- `authPermanentMaxMinutes`: обмеження в хвилинах для зростання затримки `auth_permanent` (типово: `60`). +- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників затримки (типово: `24`). +- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок перевантаження перед переходом до резервної моделі (типово: `1`). Форми на кшталт `ModelNotReadyException`, що означають зайнятість провайдера, потрапляють сюди. +- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`). +- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок rate-limit перед переходом до резервної моделі (типово: `1`). До цього кошика rate-limit належить і текст, специфічний для провайдера, такий як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- @@ -3531,9 +3532,9 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. -- Установіть `logging.file`, щоб використовувати стабільний шлях. +- Задайте `logging.file` для стабільного шляху. - `consoleLevel` підвищується до `debug`, коли використовується `--verbose`. -- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого записи припиняються (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. +- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис припиняється (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. --- @@ -3571,19 +3572,19 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - `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.traces` / `otel.metrics` / `otel.logs`: увімкнення експорту трасувань, метрик або журналів. -- `otel.sampleRate`: коефіцієнт вибірки трасувань `0`–`1`. +- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт трасувань, метрик або журналів. +- `otel.sampleRate`: коефіцієнт семплювання трасувань `0`–`1`. - `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс. -- `cacheTrace.enabled`: журналює знімки трасування кешу для вбудованих запусків (типово: `false`). -- `cacheTrace.filePath`: шлях виводу для JSONL трасування кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід трасування кешу (усі типово: `true`). +- `cacheTrace.enabled`: логувати знімки cache trace для вбудованих запусків (типово: `false`). +- `cacheTrace.filePath`: шлях виводу для JSONL cache trace (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід cache trace (усі типово: `true`). --- @@ -3608,9 +3609,9 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - `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.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням stable-каналу (типово: `6`; максимум: `168`). +- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (типово: `12`; максимум: `168`). +- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу, у годинах (типово: `1`; максимум: `24`). --- @@ -3643,21 +3644,21 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `enabled`: глобальний feature gate ACP (типово: `false`). -- `dispatch.enabled`: незалежний gate для диспетчеризації ходів ACP-сесій (типово: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання. -- `backend`: id типового backend runtime ACP (має відповідати зареєстрованому ACP runtime Plugin). -- `defaultAgent`: резервний цільовий id агента ACP, коли створення сесій не задає явної цілі. -- `allowedAgents`: список дозволених id агентів для ACP runtime sessions; порожнє значення означає відсутність додаткових обмежень. -- `maxConcurrentSessions`: максимальна кількість одночасно активних ACP-сесій. -- `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту. -- `stream.maxChunkChars`: максимальний розмір фрагмента перед розбиттям проєкції потокового блока. -- `stream.repeatSuppression`: пригнічує повторювані рядки статусу/інструментів у межах одного ходу (типово: `true`). -- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до термінальних подій ходу. +- `enabled`: глобальний feature gate для ACP (типово: `false`). +- `dispatch.enabled`: незалежний gate для dispatch ходів сесій ACP (типово: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання. +- `backend`: ID типового runtime-backend ACP (має відповідати зареєстрованому runtime Plugin ACP). +- `defaultAgent`: резервний ID цільового агента ACP, коли spawn-и не задають явну ціль. +- `allowedAgents`: список дозволених ID агентів для runtime-сесій ACP; порожнє значення означає відсутність додаткових обмежень. +- `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP. +- `stream.coalesceIdleMs`: idle-вікно скидання в мс для потокового тексту. +- `stream.maxChunkChars`: максимальний розмір частини перед розбиттям проєкції потокового блока. +- `stream.repeatSuppression`: пригнічувати повторні рядки статусу/інструментів на хід (типово: `true`). +- `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. --- @@ -3674,17 +3675,17 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `cli.banner.taglineMode` керує стилем слогана банера: - - `"random"` (типово): ротаційні кумедні/сезонні слогани. - - `"default"`: фіксований нейтральний слоган (`All your chats, one OpenClaw.`). - - `"off"`: без тексту слогана (назва/версія банера все одно показуються). -- Щоб приховати весь банер (а не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`. +- `cli.banner.taglineMode` керує стилем tagline у banner: + - `"random"` (типово): ротаційні кумедні/сезонні tagline. + - `"default"`: фіксований нейтральний tagline (`All your chats, one OpenClaw.`). + - `"off"`: без тексту tagline (назва/версія banner усе одно показуються). +- Щоб приховати весь banner (а не лише tagline), задайте env `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Метадані, які записують потоки покрокового налаштування CLI (`onboard`, `configure`, `doctor`): +Метадані, записані керованими CLI потоками налаштування (`onboard`, `configure`, `doctor`): ```json5 { @@ -3700,15 +3701,15 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. --- -## Identity +## Ідентичність -Див. поля identity в `agents.list` у розділі [Типові значення агентів](#agent-defaults). +Див. поля identity в `agents.list` у розділі [Значення агентів за замовчуванням](#agent-defaults). --- -## Bridge (legacy, removed) +## Bridge (застарілий, вилучений) -Поточні збірки більше не містять TCP bridge. Node підключаються через WebSocket Gateway. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде вилучено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP bridge. Node підключаються через WebSocket Gateway. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). @@ -3748,11 +3749,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `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`: застарілий 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 до Cron Webhook (`delivery.mode = "webhook"`); якщо не задано, заголовок auth не надсилається. +- `webhook`: застаріла резервна URL-адреса legacy Webhook (http/https), яка використовується лише для збережених завдань, що все ще мають `notify: true`. ### `cron.retry` @@ -3768,11 +3769,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань у разі тимчасових помилок (типово: `3`; діапазон: `0`–`10`). +- `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` @@ -3790,11 +3791,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `enabled`: увімкнути сповіщення про збої для завдань Cron (типово: `false`). -- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мінімум: `1`). -- `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для одного й того самого завдання (невід’ємне ціле число). -- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST до налаштованого webhook. -- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки сповіщень. +- `enabled`: увімкнути сповіщення про збої для Cron-завдань (типово: `false`). +- `after`: кількість послідовних збоїв до спрацювання сповіщення (додатне ціле число, мінімум: `1`). +- `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). +- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` робить POST на налаштований Webhook. +- `accountId`: необов’язковий ID облікового запису або каналу для визначення області доставки сповіщення. ### `cron.failureDestination` @@ -3812,13 +3813,13 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - Типова ціль для сповіщень про збої Cron для всіх завдань. -- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли доступно достатньо даних цілі. +- `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"`. +- Коли не задано ні глобальну, ні специфічну для завдання ціль збою, завдання, які вже доставляють через `announce`, під час збою повертаються до цієї основної announce-цілі. +- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` самого завдання не дорівнює `"webhook"`. Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [фонові завдання](/uk/automation/tasks). @@ -3826,36 +3827,36 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Змінні шаблону моделі медіа -Заповнювачі шаблону, що розгортаються в `tools.media.models[].args`: +Placeholder-и шаблону, які розгортаються в `tools.media.models[].args`: | Змінна | Опис | | ----------------- | ----------------------------------------------- | -| `{{Body}}` | Повне тіло вхідного повідомлення | -| `{{RawBody}}` | Сире тіло (без обгорток історії/відправника) | -| `{{BodyStripped}}`| Тіло з вилученими згадками в групі | +| `{{Body}}` | Повний текст вхідного повідомлення | +| `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) | +| `{{BodyStripped}}`| Текст без згадок у групі | | `{{From}}` | Ідентифікатор відправника | -| `{{To}}` | Ідентифікатор призначення | +| `{{To}}` | Ідентифікатор цілі | | `{{MessageSid}}` | ID повідомлення каналу | | `{{SessionId}}` | UUID поточної сесії | | `{{IsNewSession}}`| `"true"`, коли створено нову сесію | | `{{MediaUrl}}` | Псевдо-URL вхідного медіа | | `{{MediaPath}}` | Локальний шлях до медіа | | `{{MediaType}}` | Тип медіа (image/audio/document/…) | -| `{{Transcript}}` | Аудіостенограма | -| `{{Prompt}}` | Визначений prompt медіа для записів CLI | -| `{{MaxChars}}` | Визначена максимальна кількість символів виводу для записів CLI | +| `{{Transcript}}` | Аудіотранскрипт | +| `{{Prompt}}` | Визначений медіа-промпт для записів CLI | +| `{{MaxChars}}` | Визначена максимальна кількість вихідних символів для записів CLI | | `{{ChatType}}` | `"direct"` або `"group"` | -| `{{GroupSubject}}`| Тема групи (за можливості) | -| `{{GroupMembers}}`| Попередній список учасників групи (за можливості) | -| `{{SenderName}}` | Відображуване ім’я відправника (за можливості) | -| `{{SenderE164}}` | Номер телефону відправника (за можливості) | -| `{{Provider}}` | Підказка provider (`whatsapp`, `telegram`, `discord` тощо) | +| `{{GroupSubject}}`| Тема групи (best effort) | +| `{{GroupMembers}}`| Попередній перегляд учасників групи (best effort) | +| `{{SenderName}}` | Відображуване ім’я відправника (best effort) | +| `{{SenderE164}}` | Номер телефону відправника (best effort) | +| `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | --- ## Включення конфігурації (`$include`) -Розділяйте конфігурацію на кілька файлів: +Розбивайте конфігурацію на кілька файлів: ```json5 // ~/.openclaw/openclaw.json @@ -3870,13 +3871,13 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. **Поведінка об’єднання:** -- Один файл: замінює об’єкт-контейнер. -- Масив файлів: глибоко об’єднується за порядком (пізніші перевизначають ранніші). -- Сусідні ключі: об’єднуються після включень (перевизначають включені значення). -- Вкладені включення: до 10 рівнів глибини. -- Шляхи: визначаються відносно файла, що включає, але мають залишатися всередині каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/форми `../` дозволені лише тоді, коли вони все одно визначаються в межах цієї границі. -- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок розбору та циклічних включень. +- Один файл: замінює об’єкт, у якому міститься. +- Масив файлів: глибоко об’єднується за порядком (пізніші значення перевизначають попередні). +- Сусідні ключі: об’єднуються після include (перевизначають включені значення). +- Вкладені include: до 10 рівнів глибини. +- Шляхи: визначаються відносно файла, що включає, але мають залишатися всередині каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/форми з `../` дозволені лише тоді, коли вони все одно визначаються в межах цієї межі. +- Помилки: чіткі повідомлення для відсутніх файлів, помилок розбору та циклічних include. --- -_Пов’язане: [Конфігурація](/uk/gateway/configuration) · [Приклади конфігурації](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ +_Пов’язане: [Configuration](/uk/gateway/configuration) · [Configuration Examples](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ diff --git a/docs/uk/help/faq.md b/docs/uk/help/faq.md index 7560bbfdc..091511359 100644 --- a/docs/uk/help/faq.md +++ b/docs/uk/help/faq.md @@ -1,21 +1,21 @@ --- read_when: - - Відповіді на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки під час виконання + - Відповіді на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки під час роботи системи - Тріаж проблем, про які повідомляють користувачі, перед глибшим налагодженням -summary: Поширені запитання про налаштування, конфігурацію та використання OpenClaw +summary: Часті запитання про налаштування, конфігурацію та використання OpenClaw title: Поширені запитання x-i18n: - generated_at: "2026-04-19T06:50:16Z" + generated_at: "2026-04-19T10:22:59Z" model: gpt-5.4 provider: openai - source_hash: f569fb0412797314a11c41a1bbfa14f5892d2d368544fa67800823a6457000e6 + source_hash: de5a3b612607fc86c883466ff803b82466415644b7211d1c176f87e07641bb97 source_path: help/faq.md workflow: 15 --- # Поширені запитання -Швидкі відповіді та глибше усунення несправностей для реальних конфігурацій (локальна розробка, VPS, multi-agent, OAuth/API keys, резервне перемикання моделей). Для діагностики під час виконання дивіться [Усунення несправностей](/uk/gateway/troubleshooting). Повний довідник із конфігурації дивіться в [Конфігурація](/uk/gateway/configuration). +Швидкі відповіді та глибше усунення несправностей для реальних сценаріїв налаштування (локальна розробка, VPS, multi-agent, OAuth/API-ключі, резервне перемикання моделей). Для діагностики під час роботи див. [Усунення несправностей](/uk/gateway/troubleshooting). Повний довідник із конфігурації див. у [Конфігурація](/uk/gateway/configuration). ## Перші 60 секунд, якщо щось зламалося @@ -25,23 +25,23 @@ x-i18n: openclaw status ``` - Швидкий локальний підсумок: ОС + оновлення, доступність gateway/service, agents/sessions, конфігурація provider + проблеми під час виконання (коли Gateway доступний). + Швидкий локальний підсумок: ОС + оновлення, доступність gateway/сервісу, агенти/сесії, конфігурація провайдера + проблеми під час роботи (коли gateway доступний). -2. **Звіт, який можна вставити та поділитися ним без змін (безпечно для поширення)** +2. **Звіт, який можна вставити (безпечний для поширення)** ```bash openclaw status --all ``` - Діагностика лише для читання з хвостом журналу (токени приховані). + Діагностика в режимі лише читання з хвостом журналу (токени приховано). -3. **Стан daemon + port** +3. **Стан демона + порту** ```bash openclaw gateway status ``` - Показує runtime supervisor у порівнянні з доступністю RPC, цільову URL-адресу probe та яку конфігурацію, імовірно, використовував сервіс. + Показує час роботи supervisor у порівнянні з доступністю RPC, цільову URL-адресу probe та те, яку конфігурацію сервіс імовірно використовував. 4. **Глибокі probe-перевірки** @@ -49,10 +49,10 @@ x-i18n: openclaw status --deep ``` - Виконує живу probe-перевірку стану Gateway, зокрема probe-перевірки каналів, коли вони підтримуються - (потрібен доступний Gateway). Див. [Стан](/uk/gateway/health). + Виконує живу probe-перевірку стану gateway, зокрема probe-перевірки каналів, якщо підтримуються + (потрібен доступний gateway). Див. [Health](/uk/gateway/health). -5. **Перегляд останнього журналу в реальному часі** +5. **Перегляд останнього журналу** ```bash openclaw logs --follow @@ -64,7 +64,7 @@ x-i18n: tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - Файлові журнали відокремлені від журналів сервісу; див. [Журналювання](/uk/logging) та [Усунення несправностей](/uk/gateway/troubleshooting). + Журнали у файлах відокремлені від журналів сервісу; див. [Логування](/uk/logging) і [Усунення несправностей](/uk/gateway/troubleshooting). 6. **Запустіть doctor (виправлення)** @@ -72,48 +72,48 @@ x-i18n: openclaw doctor ``` - Виправляє/мігрує config/state + виконує перевірки стану. Див. [Doctor](/uk/gateway/doctor). + Виправляє/мігрує конфігурацію/стан + виконує перевірки стану. Див. [Doctor](/uk/gateway/doctor). -7. **Знімок стану Gateway** +7. **Знімок стану gateway** ```bash openclaw health --json - openclaw health --verbose # показує цільову URL-адресу + шлях до config у разі помилок + openclaw health --verbose # показує цільову URL-адресу + шлях до конфігурації в разі помилок ``` - Запитує у запущеного Gateway повний знімок стану (лише WS). Див. [Стан](/uk/gateway/health). + Запитує у запущеного gateway повний знімок стану (лише WS). Див. [Health](/uk/gateway/health). -## Швидкий старт і налаштування першого запуску +## Швидкий старт і початкове налаштування - - Використайте локального AI agent, який може **бачити вашу машину**. Це набагато ефективніше, ніж питати - в Discord, тому що більшість випадків "я застряг" — це **локальні проблеми конфігурації або середовища**, + + Використайте локального AI-агента, який може **бачити вашу машину**. Це набагато ефективніше, ніж запитувати + у Discord, тому що більшість випадків "я застряг" — це **проблеми локальної конфігурації або середовища**, які віддалені помічники не можуть перевірити. - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - Ці інструменти можуть читати репозиторій, запускати команди, перевіряти журнали та допомагати виправляти - налаштування на рівні машини (PATH, сервіси, дозволи, файли автентифікації). Надайте їм **повну копію вихідного коду** - через придатне до змін встановлення (git install): + Ці інструменти можуть читати репозиторій, виконувати команди, перевіряти журнали та допомагати виправляти + налаштування на рівні машини (PATH, сервіси, дозволи, файли автентифікації). Надайте їм **повний checkout вихідного коду** + через hackable (git) install: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Це встановлює OpenClaw **із git checkout**, тому agent може читати код + документацію та + Це встановлює OpenClaw **із git checkout**, тож агент може читати код + документацію та аналізувати точну версію, яку ви використовуєте. Ви завжди можете повернутися до стабільної версії пізніше, повторно запустивши інсталятор без `--install-method git`. - Порада: попросіть agent **спланувати та супроводжувати** виправлення (крок за кроком), а потім виконати лише - потрібні команди. Це зменшує обсяг змін і полегшує їх аудит. + Порада: попросіть агента **спланувати й проконтролювати** виправлення (крок за кроком), а потім виконати лише + потрібні команди. Так зміни залишаться невеликими, і їх буде простіше перевірити. - Якщо ви знайдете справжню помилку або виправлення, будь ласка, створіть issue на GitHub або надішліть PR: + Якщо ви виявили справжню помилку або виправлення, будь ласка, створіть GitHub issue або надішліть PR: [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) - Почніть із цих команд (діліться виводом, коли просите про допомогу): + Почніть із цих команд (поділіться виводом, коли звертаєтеся по допомогу): ```bash openclaw status @@ -123,14 +123,14 @@ x-i18n: Що вони роблять: - - `openclaw status`: швидкий знімок стану gateway/agent + базова конфігурація. - - `openclaw models status`: перевіряє автентифікацію provider + доступність моделей. - - `openclaw doctor`: перевіряє та виправляє поширені проблеми config/state. + - `openclaw status`: швидкий знімок стану gateway/агента + базова конфігурація. + - `openclaw models status`: перевіряє автентифікацію провайдера + доступність моделей. + - `openclaw doctor`: перевіряє та виправляє поширені проблеми конфігурації/стану. Інші корисні перевірки CLI: `openclaw status --all`, `openclaw logs --follow`, `openclaw gateway status`, `openclaw health --verbose`. - Швидкий цикл налагодження: [Перші 60 секунд, якщо щось зламалося](#перші-60-секунд-якщо-щось-зламалося). + Швидкий цикл налагодження: [Перші 60 секунд, якщо щось зламалося](#перші-60-секунд,-якщо-щось-зламалося). Документація зі встановлення: [Встановлення](/uk/install), [Прапорці інсталятора](/uk/install/installer), [Оновлення](/uk/install/updating). @@ -138,19 +138,19 @@ x-i18n: Поширені причини пропуску Heartbeat: - - `quiet-hours`: поза налаштованим вікном active-hours - - `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожній каркас або лише заголовки - - `no-tasks-due`: режим задач `HEARTBEAT.md` активний, але жоден з інтервалів задачі ще не настав + - `quiet-hours`: поза межами налаштованого вікна active-hours + - `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожню/заголовкову заготовку + - `no-tasks-due`: режим завдань `HEARTBEAT.md` активний, але жоден із інтервалів завдань ще не настав - `alerts-disabled`: усю видимість heartbeat вимкнено (`showOk`, `showAlerts` і `useIndicator` усі вимкнені) - У режимі задач часові позначки настання строку оновлюються лише після завершення - реального запуску heartbeat. Пропущені запуски не позначають задачі як виконані. + У режимі завдань часові позначки настання оновлюються лише після завершення + реального запуску heartbeat. Пропущені запуски не позначають завдання як виконані. - Документація: [Heartbeat](/uk/gateway/heartbeat), [Автоматизація та задачі](/uk/automation). + Документація: [Heartbeat](/uk/gateway/heartbeat), [Автоматизація й завдання](/uk/automation). - + Репозиторій рекомендує запуск із вихідного коду та використання онбордингу: ```bash @@ -158,9 +158,9 @@ x-i18n: openclaw onboard --install-daemon ``` - Майстер також може автоматично зібрати ресурси UI. Після онбордингу зазвичай Gateway запускають на порту **18789**. + Майстер також може автоматично збирати UI-ресурси. Після онбордингу зазвичай Gateway працює на порту **18789**. - Із вихідного коду (contributors/dev): + Із вихідного коду (контриб'ютори/розробка): ```bash git clone https://github.com/openclaw/openclaw.git @@ -171,90 +171,90 @@ x-i18n: openclaw onboard ``` - Якщо у вас ще немає глобального встановлення, запускайте через `pnpm openclaw onboard`. + Якщо у вас ще немає глобального встановлення, запустіть через `pnpm openclaw onboard`. - - Майстер відкриває ваш браузер із чистою (без токена) URL-адресою dashboard одразу після онбордингу, а також друкує посилання в підсумку. Залиште цю вкладку відкритою; якщо вона не запустилася, скопіюйте й вставте надруковану URL-адресу на тій самій машині. + + Майстер відкриває ваш браузер із чистою (без токенів) URL-адресою панелі керування одразу після онбордингу, а також виводить посилання в підсумку. Залиште цю вкладку відкритою; якщо вона не запустилася, скопіюйте й вставте надруковану URL-адресу на цій самій машині. - + **Localhost (та сама машина):** - Відкрийте `http://127.0.0.1:18789/`. - - Якщо запитується shared-secret auth, вставте налаштований token або password у налаштуваннях Control UI. - - Джерело token: `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`). - - Джерело password: `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). - - Якщо shared secret ще не налаштовано, згенеруйте token командою `openclaw doctor --generate-gateway-token`. + - Якщо система просить автентифікацію спільним секретом, вставте налаштований токен або пароль у налаштуваннях Control UI. + - Джерело токена: `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`). + - Джерело пароля: `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). + - Якщо спільний секрет ще не налаштовано, згенеруйте токен за допомогою `openclaw doctor --generate-gateway-token`. **Не на localhost:** - - **Tailscale Serve** (рекомендовано): залиште bind loopback, виконайте `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` має значення `true`, заголовки ідентичності задовольняють автентифікацію Control UI/WebSocket (без вставлення shared secret, за умови довіреного вузла Gateway); HTTP API усе одно вимагають shared-secret auth, якщо ви навмисно не використовуєте private-ingress `none` або trusted-proxy HTTP auth. - Невдалі одночасні спроби автентифікації Serve від того самого клієнта серіалізуються до того, як обмежувач невдалої автентифікації зафіксує їх, тому друга невдала повторна спроба вже може показувати `retry later`. - - **Прив’язка tailnet**: виконайте `openclaw gateway --bind tailnet --token ""` (або налаштуйте password auth), відкрийте `http://:18789/`, а потім вставте відповідний shared secret у налаштуваннях dashboard. - - **Зворотний proxy з урахуванням ідентичності**: тримайте Gateway за trusted proxy не в loopback, налаштуйте `gateway.auth.mode: "trusted-proxy"`, а потім відкрийте URL-адресу proxy. - - **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. Shared-secret auth усе одно застосовується через tunnel; якщо з’явиться запит, вставте налаштований token або password. + - **Tailscale Serve** (рекомендовано): залиште bind loopback, запустіть `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` має значення `true`, заголовки ідентифікації задовольняють автентифікацію Control UI/WebSocket (без вставлення спільного секрету, за умови довіреного хоста gateway); HTTP API, як і раніше, вимагають автентифікації спільним секретом, якщо ви навмисно не використовуєте private-ingress `none` або trusted-proxy HTTP auth. + Невдалі одночасні спроби автентифікації Serve від того самого клієнта серіалізуються до того, як обмежувач невдалих автентифікацій їх зафіксує, тому друга невдала повторна спроба вже може показати `retry later`. + - **Bind до tailnet**: запустіть `openclaw gateway --bind tailnet --token ""` (або налаштуйте автентифікацію паролем), відкрийте `http://:18789/`, а потім вставте відповідний спільний секрет у налаштуваннях панелі. + - **Зворотний proxy з урахуванням ідентифікації**: залиште Gateway за trusted proxy не в loopback, налаштуйте `gateway.auth.mode: "trusted-proxy"`, а потім відкрийте URL proxy. + - **SSH-тунель**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. Автентифікація спільним секретом і надалі застосовується через тунель; вставте налаштований токен або пароль, якщо система запросить. - Див. [Dashboard](/web/dashboard) і [Web surfaces](/web) щодо режимів bind та деталей автентифікації. + Див. [Панель керування](/web/dashboard) і [Веб-поверхні](/web) для деталей режимів bind і автентифікації. - + Вони керують різними рівнями: - - `approvals.exec`: пересилає запити на схвалення до місць призначення чату - - `channels..execApprovals`: робить цей канал нативним клієнтом схвалення для exec approvals + - `approvals.exec`: пересилає запити на погодження до чат-призначень + - `channels..execApprovals`: робить цей канал нативним клієнтом погодження для погоджень exec - Політика host exec усе ще є справжнім бар’єром схвалення. Конфігурація чату лише визначає, де з’являються - запити на схвалення та як люди можуть на них відповідати. + Політика host exec і далі є справжнім шлюзом погодження. Конфігурація чату лише керує тим, + де з'являються запити на погодження та як люди можуть на них відповідати. - У більшості конфігурацій вам **не** потрібні обидві: + У більшості налаштувань вам **не** потрібні обидві: - - Якщо чат уже підтримує команди та відповіді, `/approve` у тому самому чаті працює через спільний шлях. - - Якщо підтримуваний нативний канал може безпечно визначити тих, хто схвалює, OpenClaw тепер автоматично вмикає нативні схвалення DM-first, коли `channels..execApprovals.enabled` не задано або має значення `"auto"`. - - Коли доступні нативні картки/кнопки схвалення, цей нативний UI є основним шляхом; agent має включати ручну команду `/approve`, лише якщо результат інструмента показує, що схвалення в чаті недоступні або єдиним шляхом є ручне схвалення. - - Використовуйте `approvals.exec` лише тоді, коли запити також потрібно пересилати в інші чати або явні ops rooms. - - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише тоді, коли ви явно хочете, щоб запити на схвалення надсилалися назад у вихідну кімнату/тему. - - Схвалення Plugin — це ще окрема категорія: за замовчуванням вони використовують `/approve` у тому самому чаті, необов’язкове пересилання `approvals.plugin`, і лише деякі нативні канали зберігають нативну обробку схвалень Plugin поверх цього. + - Якщо чат уже підтримує команди та відповіді, `/approve` у тому ж чаті працює через спільний шлях. + - Якщо підтримуваний нативний канал може безпечно визначати тих, хто погоджує, OpenClaw тепер автоматично вмикає нативні погодження DM-first, коли `channels..execApprovals.enabled` не задано або має значення `"auto"`. + - Коли доступні нативні картки/кнопки погодження, цей нативний UI є основним шляхом; агент має включати ручну команду `/approve` лише в тому разі, якщо результат інструмента вказує, що погодження в чаті недоступні або ручне погодження є єдиним шляхом. + - Використовуйте `approvals.exec` лише тоді, коли запити також потрібно пересилати в інші чати або окремі ops-кімнати. + - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише тоді, коли ви явно хочете, щоб запити на погодження публікувалися назад у вихідну кімнату/тему. + - Погодження Plugin — це ще окрема категорія: за замовчуванням вони використовують `/approve` у тому ж чаті, необов'язкове пересилання `approvals.plugin`, і лише деякі нативні канали додатково підтримують нативну обробку погоджень Plugin. - Коротко: пересилання потрібне для маршрутизації, конфігурація нативного клієнта — для багатшого UX, специфічного для каналу. - Див. [Exec Approvals](/uk/tools/exec-approvals). + Коротко: пересилання потрібне для маршрутизації, а конфігурація нативного клієнта — для багатшого UX, специфічного для каналу. + Див. [Погодження Exec](/uk/tools/exec-approvals). - - Потрібен Node **>= 22**. Рекомендовано `pnpm`. Bun **не рекомендується** для Gateway. + + Потрібен Node **>= 22**. Рекомендовано `pnpm`. Bun **не рекомендовано** для Gateway. - Так. Gateway є легким — у документації зазначено, що для особистого використання достатньо **512 МБ–1 ГБ RAM**, **1 ядра** та приблизно **500 МБ** - диска, а також вказано, що **Raspberry Pi 4 може його запускати**. + Так. Gateway є легким — у документації вказано, що для особистого використання достатньо **512MB-1GB RAM**, **1 core** і приблизно **500MB** + диска, а також зазначено, що **Raspberry Pi 4 може його запускати**. - Якщо вам потрібен додатковий запас ресурсів (журнали, медіа, інші сервіси), **рекомендовано 2 ГБ**, але це - не жорсткий мінімум. + Якщо вам потрібен додатковий запас ресурсів (журнали, медіа, інші сервіси), **рекомендовано 2GB**, + але це не жорсткий мінімум. - Порада: невеликий Pi/VPS може розмістити Gateway, а ви можете підключати **Node** на ноутбуці/телефоні для + Порада: невеликий Pi/VPS може розміщувати Gateway, а ви можете під'єднувати **nodes** на ноутбуці/телефоні для локального екрана/камери/canvas або виконання команд. Див. [Nodes](/uk/nodes). - Коротко: це працює, але очікуйте певних шорсткостей. + Коротко: це працює, але очікуйте певних труднощів. - - Використовуйте **64-бітну** ОС і Node >= 22. - - Надавайте перевагу **придатному до змін встановленню (git install)**, щоб ви могли бачити журнали та швидко оновлюватися. + - Використовуйте **64-bit** ОС і тримайте Node >= 22. + - Віддавайте перевагу **hackable (git) install**, щоб мати змогу бачити журнали та швидко оновлюватися. - Починайте без channels/Skills, а потім додавайте їх по одному. - - Якщо виникають дивні проблеми з бінарними файлами, зазвичай це проблема **сумісності ARM**. + - Якщо натрапите на дивні проблеми з бінарними файлами, зазвичай це проблема **ARM compatibility**. Документація: [Linux](/uk/platforms/linux), [Встановлення](/uk/install). - - Цей екран залежить від того, чи доступний Gateway і чи пройдена автентифікація. TUI також автоматично надсилає - "Wake up, my friend!" під час першого hatch. Якщо ви бачите цей рядок **без відповіді** - і значення токенів залишається 0, agent так і не запустився. + + Цей екран залежить від того, чи доступний Gateway і чи пройдено автентифікацію. TUI також надсилає + "Wake up, my friend!" автоматично під час першого запуску. Якщо ви бачите цей рядок **без відповіді** + і кількість токенів залишається 0, агент так і не запустився. 1. Перезапустіть Gateway: @@ -262,7 +262,7 @@ x-i18n: openclaw gateway restart ``` - 2. Перевірте статус + auth: + 2. Перевірте статус + автентифікацію: ```bash openclaw status @@ -276,31 +276,31 @@ x-i18n: openclaw doctor ``` - Якщо Gateway віддалений, переконайтеся, що tunnel/Tailscale-з’єднання активне і що UI + Якщо Gateway віддалений, переконайтеся, що тунель/Tailscale-з'єднання працює і що UI вказує на правильний Gateway. Див. [Віддалений доступ](/uk/gateway/remote). - Так. Скопіюйте **каталог state** і **workspace**, а потім один раз запустіть Doctor. Це - збереже вашого бота **точно таким самим** (memory, history сеансів, auth і channel - state), якщо ви скопіюєте **обидва** розташування: + Так. Скопіюйте **каталог стану** і **workspace**, а потім один раз запустіть Doctor. Це + збереже вашого бота "точно таким самим" (пам'ять, історія сесій, автентифікація та стан + каналу), якщо ви скопіюєте **обидва** розташування: 1. Встановіть OpenClaw на новій машині. 2. Скопіюйте `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`) зі старої машини. - 3. Скопіюйте ваш workspace (типово: `~/.openclaw/workspace`). + 3. Скопіюйте свій workspace (типово: `~/.openclaw/workspace`). 4. Запустіть `openclaw doctor` і перезапустіть сервіс Gateway. - Це зберігає config, auth profiles, облікові дані WhatsApp, sessions і memory. Якщо ви в - remote mode, пам’ятайте, що session store і workspace належать хосту gateway. + Це зберігає конфігурацію, профілі автентифікації, облікові дані WhatsApp, сесії та пам’ять. Якщо ви працюєте + у віддаленому режимі, пам’ятайте, що хост gateway є власником сховища сесій і workspace. - **Важливо:** якщо ви лише commit/push свій workspace на GitHub, ви створюєте резервну - копію **memory + bootstrap files**, але **не** history сеансів або auth. Вони зберігаються - в `~/.openclaw/` (наприклад, `~/.openclaw/agents//sessions/`). + **Важливо:** якщо ви лише commit/push свій workspace на GitHub, ви створюєте резервну копію + **пам’яті + bootstrap-файлів**, але **не** історії сесій чи автентифікації. Вони зберігаються + у `~/.openclaw/` (наприклад, `~/.openclaw/agents//sessions/`). Пов’язане: [Міграція](/uk/install/migrating), [Де що зберігається на диску](#де-що-зберігається-на-диску), - [Workspace agent](/uk/concepts/agent-workspace), [Doctor](/uk/gateway/doctor), - [Remote mode](/uk/gateway/remote). + [Workspace агента](/uk/concepts/agent-workspace), [Doctor](/uk/gateway/doctor), + [Віддалений режим](/uk/gateway/remote). @@ -308,15 +308,15 @@ x-i18n: Перегляньте changelog на GitHub: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Найновіші записи — угорі. Якщо верхній розділ позначено як **Unreleased**, наступний датований + Найновіші записи розміщені вгорі. Якщо верхній розділ позначено як **Unreleased**, тоді наступний датований розділ — це остання випущена версія. Записи згруповано за **Highlights**, **Changes** і - **Fixes** (а також розділами документації/іншими, коли потрібно). + **Fixes** (а також за розділами документації/іншими, коли потрібно). - + Деякі з’єднання Comcast/Xfinity помилково блокують `docs.openclaw.ai` через Xfinity - Advanced Security. Вимкніть її або додайте `docs.openclaw.ai` до allowlist, а потім спробуйте знову. + Advanced Security. Вимкніть її або додайте `docs.openclaw.ai` до allowlist, а потім повторіть спробу. Будь ласка, допоможіть нам розблокувати сайт, повідомивши тут: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). Якщо ви все ще не можете відкрити сайт, документація дзеркалюється на GitHub: @@ -331,18 +331,18 @@ x-i18n: - `beta` = рання збірка для тестування Зазвичай stable-реліз спочатку потрапляє в **beta**, а потім явний - крок просування переміщує цю саму версію до `latest`. Maintainers також можуть - публікувати відразу в `latest`, коли це потрібно. Саме тому beta і stable можуть + крок просування переводить цю саму версію в `latest`. За потреби супроводжувачі також можуть + публікувати одразу в `latest`. Саме тому beta і stable можуть вказувати на **одну й ту саму версію** після просування. Подивіться, що змінилося: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Однорядкові команди встановлення та різницю між beta і dev дивіться в accordion нижче. + Однорядкові команди встановлення та різницю між beta і dev див. в акордеоні нижче. - + **Beta** — це npm dist-tag `beta` (може збігатися з `latest` після просування). **Dev** — це рухома вершина `main` (git); коли її публікують, вона використовує npm dist-tag `dev`. @@ -363,7 +363,7 @@ x-i18n: - + Є два варіанти: 1. **Канал dev (git checkout):** @@ -372,7 +372,7 @@ x-i18n: openclaw update --channel dev ``` - Це перемикає на гілку `main` і оновлює з вихідного коду. + Це перемикає вас на гілку `main` і оновлює з вихідного коду. 2. **Hackable install (із сайту інсталятора):** @@ -380,7 +380,7 @@ x-i18n: curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Так ви отримуєте локальний репозиторій, який можна редагувати, а потім оновлювати через git. + Це дає вам локальний репозиторій, який можна редагувати, а потім оновлювати через git. Якщо ви віддаєте перевагу чистому клонуванню вручну, використайте: @@ -396,14 +396,14 @@ x-i18n: - - Приблизний орієнтир: + + Орієнтовно: - **Встановлення:** 2–5 хвилин - - **Онбординг:** 5–15 хвилин залежно від того, скільки channels/models ви налаштовуєте + - **Онбординг:** 5–15 хвилин залежно від кількості channels/models, які ви налаштовуєте - Якщо все зависає, скористайтеся [Інсталятор завис?](#швидкий-старт-і-налаштування-першого-запуску) - і швидким циклом налагодження в [Я застряг](#швидкий-старт-і-налаштування-першого-запуску). + Якщо все зависає, скористайтеся [Інсталятор завис?](#швидкий-старт-і-початкове-налаштування) + і швидким циклом налагодження в [Я застряг](#швидкий-старт-і-початкове-налаштування). @@ -435,44 +435,44 @@ x-i18n: Set-PSDebug -Trace 0 ``` - Більше параметрів: [Прапорці інсталятора](/uk/install/installer). + Інші параметри: [Прапорці інсталятора](/uk/install/installer). - + Дві поширені проблеми у Windows: **1) npm error spawn git / git not found** - - Встановіть **Git for Windows** і переконайтеся, що `git` є у вашому PATH. + - Установіть **Git for Windows** і переконайтеся, що `git` є у вашому PATH. - Закрийте й знову відкрийте PowerShell, а потім повторно запустіть інсталятор. **2) після встановлення openclaw is not recognized** - - Ваш глобальний каталог bin для npm відсутній у PATH. + - Ваша глобальна папка bin для npm відсутня в PATH. - Перевірте шлях: ```powershell npm config get prefix ``` - - Додайте цей каталог до вашого користувацького PATH (суфікс `\bin` у Windows не потрібен; у більшості систем це `%AppData%\npm`). + - Додайте цей каталог до свого PATH користувача (суфікс `\bin` у Windows не потрібен; у більшості систем це `%AppData%\npm`). - Закрийте й знову відкрийте PowerShell після оновлення PATH. - Якщо вам потрібне найплавніше налаштування у Windows, використовуйте **WSL2** замість нативного Windows. + Якщо ви хочете найзручніше налаштування у Windows, використовуйте **WSL2** замість нативної Windows. Документація: [Windows](/uk/platforms/windows). - Зазвичай це невідповідність code page консолі в нативних оболонках Windows. + Зазвичай це невідповідність кодової сторінки консолі в нативних оболонках Windows. Симптоми: - - вивід `system.run`/`exec` відображає китайський текст як mojibake - - та сама команда виглядає нормально в іншому профілі термінала + - вивід `system.run`/`exec` показує китайський текст як mojibake + - та сама команда має нормальний вигляд в іншому профілі термінала - Швидкий обхідний спосіб у PowerShell: + Швидкий обхідний шлях у PowerShell: ```powershell chcp 65001 @@ -487,7 +487,7 @@ x-i18n: openclaw gateway restart ``` - Якщо ви все ще відтворюєте цю проблему в останній версії OpenClaw, відстежуйте/повідомляйте про неї тут: + Якщо це все ще відтворюється в останній версії OpenClaw, відстежуйте/повідомляйте тут: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) @@ -505,8 +505,8 @@ x-i18n: - - Коротка відповідь: дотримуйтесь інструкції для Linux, а потім запустіть онбординг. + + Коротка відповідь: дотримуйтеся посібника для Linux, а потім запустіть онбординг. - Швидкий шлях для Linux + встановлення сервісу: [Linux](/uk/platforms/linux). - Повний покроковий посібник: [Початок роботи](/uk/start/getting-started). @@ -514,16 +514,16 @@ x-i18n: - - Підійде будь-який Linux VPS. Встановіть на сервері, а потім використовуйте SSH/Tailscale для доступу до Gateway. + + Підійде будь-який Linux VPS. Установіть на сервері, а потім використовуйте SSH/Tailscale для доступу до Gateway. Посібники: [exe.dev](/uk/install/exe-dev), [Hetzner](/uk/install/hetzner), [Fly.io](/uk/install/fly). - Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). + Віддалений доступ: [Віддалений gateway](/uk/gateway/remote). - - Ми підтримуємо **хаб хостингу** з поширеними провайдерами. Виберіть одного та дотримуйтесь інструкції: + + Ми підтримуємо **хаб хостингу** з поширеними провайдерами. Виберіть один і дотримуйтеся посібника: - [VPS hosting](/uk/vps) (усі провайдери в одному місці) - [Fly.io](/uk/install/fly) @@ -531,22 +531,22 @@ x-i18n: - [exe.dev](/uk/install/exe-dev) Як це працює в хмарі: **Gateway працює на сервері**, а ви отримуєте до нього доступ - з ноутбука/телефона через Control UI (або Tailscale/SSH). Ваші state + workspace - зберігаються на сервері, тож вважайте хост джерелом істини та робіть його резервні копії. + зі свого ноутбука/телефона через Control UI (або Tailscale/SSH). Ваші state + workspace + зберігаються на сервері, тож вважайте хост джерелом істини та створюйте його резервні копії. - Ви можете підключати **Node** (Mac/iOS/Android/headless) до цього хмарного Gateway, щоб отримати доступ - до локального екрана/камери/canvas або запускати команди на ноутбуці, залишаючи + Ви можете під’єднати **nodes** (Mac/iOS/Android/headless) до цього хмарного Gateway, щоб отримати доступ + до локального екрана/камери/canvas або виконувати команди на своєму ноутбуці, зберігаючи Gateway у хмарі. - Хаб: [Платформи](/uk/platforms). Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). - Node: [Nodes](/uk/nodes), [CLI Nodes](/cli/nodes). + Хаб: [Платформи](/uk/platforms). Віддалений доступ: [Віддалений gateway](/uk/gateway/remote). + Nodes: [Nodes](/uk/nodes), [CLI Nodes](/cli/nodes). - - Коротка відповідь: **можливо, але не рекомендовано**. Під час оновлення може перезапускатися - Gateway (що розриває активний сеанс), може знадобитися чистий git checkout, а також - може знадобитися підтвердження. Безпечніше: запускати оновлення з оболонки як оператор. + + Коротка відповідь: **можливо, але не рекомендовано**. Процес оновлення може перезапустити + Gateway (що розірве активну сесію), може потребувати чистого git checkout і + може запитувати підтвердження. Безпечніше запускати оновлення з оболонки від імені оператора. Використовуйте CLI: @@ -558,7 +558,7 @@ x-i18n: openclaw update --no-restart ``` - Якщо автоматизація з agent усе ж потрібна: + Якщо вам усе ж потрібно автоматизувати це через агента: ```bash openclaw update --yes --no-restart @@ -570,35 +570,35 @@ x-i18n: - `openclaw onboard` — це рекомендований шлях налаштування. У **local mode** він проводить вас через: + `openclaw onboard` — рекомендований шлях налаштування. У **локальному режимі** він проводить вас через: - - **Налаштування моделей/auth** (OAuth провайдера, API keys, Anthropic setup-token, а також варіанти локальних моделей, як-от LM Studio) - - Розташування **workspace** + **bootstrap files** + - **Налаштування моделі/автентифікації** (OAuth провайдера, API-ключі, setup-token Anthropic, а також варіанти локальних моделей, як-от LM Studio) + - Розташування **workspace** + bootstrap-файли - **Налаштування Gateway** (bind/port/auth/tailscale) - - **Channels** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також вбудовані channel plugins, як-от QQ Bot) - - **Встановлення daemon** (LaunchAgent на macOS; systemd user unit на Linux/WSL2) + - **Channels** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також вбудовані channel plugins, наприклад QQ Bot) + - **Установлення демона** (LaunchAgent у macOS; користувацький systemd unit у Linux/WSL2) - **Перевірки стану** та вибір **Skills** - Він також попереджає, якщо налаштована вами модель невідома або для неї відсутня auth. + Він також попереджає, якщо ваша налаштована модель невідома або для неї відсутня автентифікація. - - Ні. Ви можете запускати OpenClaw з **API keys** (Anthropic/OpenAI/інші) або з + + Ні. Ви можете використовувати OpenClaw з **API-ключами** (Anthropic/OpenAI/інші) або з **лише локальними моделями**, щоб ваші дані залишалися на вашому пристрої. Підписки (Claude Pro/Max або OpenAI Codex) — це необов’язкові способи автентифікації в цих провайдерів. Для Anthropic в OpenClaw практичний поділ такий: - - **Anthropic API key**: звичайне виставлення рахунків за Anthropic API - - **Claude CLI / auth через підписку Claude в OpenClaw**: співробітники Anthropic + - **API-ключ Anthropic**: звичайна оплата Anthropic API + - **Claude CLI / автентифікація через підписку Claude в OpenClaw**: співробітники Anthropic повідомили нам, що таке використання знову дозволене, і OpenClaw розглядає використання `claude -p` як санкціоноване для цієї інтеграції, якщо Anthropic не опублікує нову політику - Для довготривалих хостів gateway Anthropic API keys усе ще є - більш передбачуваним варіантом налаштування. OAuth OpenAI Codex явно підтримується для зовнішніх - інструментів, як-от OpenClaw. + Для довготривалих хостів gateway API-ключі Anthropic все ще є + більш передбачуваним варіантом. OAuth OpenAI Codex явно підтримується для зовнішніх + інструментів на кшталт OpenClaw. OpenClaw також підтримує інші розміщені варіанти у стилі підписки, зокрема **Qwen Cloud Coding Plan**, **MiniMax Coding Plan** і @@ -611,26 +611,26 @@ x-i18n: - + Так. Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож - OpenClaw вважає auth через підписку Claude та використання `claude -p` санкціонованими + OpenClaw вважає автентифікацію через підписку Claude та використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. Якщо вам потрібне - найпередбачуваніше серверне налаштування, використовуйте натомість Anthropic API key. + максимально передбачуване серверне налаштування, натомість використовуйте API-ключ Anthropic. - + Так. Співробітники Anthropic повідомили нам, що таке використання знову дозволене, тож OpenClaw вважає - повторне використання Claude CLI та використання `claude -p` санкціонованими для цієї інтеграції, + повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. - Anthropic setup-token і далі доступний як підтримуваний шлях token в OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI та `claude -p`, коли це доступно. - Для production або multi-user навантажень auth через Anthropic API key усе ще є - безпечнішим і передбачуванішим вибором. Якщо вам потрібні інші розміщені + setup-token Anthropic і далі доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI та `claude -p`, коли це можливо. + Для production або багатокористувацьких навантажень автентифікація за API-ключем Anthropic і далі є + безпечнішим і більш передбачуваним вибором. Якщо вам потрібні інші розміщені варіанти у стилі підписки в OpenClaw, див. [OpenAI](/uk/providers/openai), [Qwen / Model Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax) і [GLM Models](/uk/providers/glm). @@ -641,121 +641,121 @@ x-i18n: Це означає, що вашу **квоту/ліміт запитів Anthropic** вичерпано для поточного вікна. Якщо ви використовуєте **Claude CLI**, дочекайтеся скидання вікна або оновіть свій план. Якщо ви -використовуєте **Anthropic API key**, перевірте Anthropic Console -щодо використання/білінгу та за потреби підвищте ліміти. +використовуєте **API-ключ Anthropic**, перевірте Anthropic Console +щодо використання/оплати та за потреби збільште ліміти. - Якщо повідомлення має саме такий вигляд: + Якщо повідомлення конкретно таке: `Extra usage is required for long context requests`, запит намагається використати - 1M context beta від Anthropic (`context1m: true`). Це працює лише тоді, коли ваші - облікові дані мають право на білінг long-context (білінг API key або + бета-функцію Anthropic 1M context (`context1m: true`). Це працює лише тоді, коли ваші + облікові дані мають право на виставлення рахунків за довгий контекст (оплата через API-ключ або шлях входу Claude в OpenClaw з увімкненим Extra Usage). - Порада: налаштуйте **резервну модель**, щоб OpenClaw міг продовжувати відповідати, коли provider обмежений rate limit. + Порада: задайте **резервну модель**, щоб OpenClaw міг і далі відповідати, поки провайдер обмежений rate limit. Див. [Models](/cli/models), [OAuth](/uk/concepts/oauth) і [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/uk/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). - Так. OpenClaw має вбудований provider **Amazon Bedrock (Converse)**. За наявності маркерів AWS env OpenClaw може автоматично виявити каталог streaming/text Bedrock і об’єднати його як неявний provider `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати запис provider вручну. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо ви віддаєте перевагу керованому потоку ключів, OpenAI-сумісний proxy перед Bedrock також залишається коректним варіантом. + Так. OpenClaw має вбудований провайдер **Amazon Bedrock (Converse)**. Якщо присутні маркери середовища AWS, OpenClaw може автоматично виявити каталог Bedrock для streaming/text і об’єднати його як неявний провайдер `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати запис провайдера вручну. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо ви віддаєте перевагу керованому потоку ключів, OpenAI-сумісний proxy перед Bedrock також залишається дійсним варіантом. - - OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід через ChatGPT). Під час онбордингу можна виконати потік OAuth, і за потреби буде встановлено модель за замовчуванням `openai-codex/gpt-5.4`. Див. [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). + + OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід через ChatGPT). Онбординг може виконати OAuth-потік і встановить модель за замовчуванням на `openai-codex/gpt-5.4`, коли це доречно. Див. [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). - + OpenClaw розглядає ці два шляхи окремо: - `openai-codex/gpt-5.4` = OAuth ChatGPT/Codex - `openai/gpt-5.4` = прямий API OpenAI Platform - В OpenClaw вхід ChatGPT/Codex прив’язаний до маршруту `openai-codex/*`, - а не до прямого маршруту `openai/*`. Якщо ви хочете використовувати прямий шлях API в - OpenClaw, задайте `OPENAI_API_KEY` (або еквівалентну конфігурацію provider OpenAI). - Якщо ви хочете використовувати вхід ChatGPT/Codex в OpenClaw, використовуйте `openai-codex/*`. + В OpenClaw вхід через ChatGPT/Codex прив’язано до маршруту `openai-codex/*`, + а не до прямого маршруту `openai/*`. Якщо вам потрібен прямий API-шлях в + OpenClaw, задайте `OPENAI_API_KEY` (або еквівалентну конфігурацію провайдера OpenAI). + Якщо вам потрібен вхід ChatGPT/Codex в OpenClaw, використовуйте `openai-codex/*`. - - `openai-codex/*` використовує маршрут OAuth Codex, а його доступні вікна квот - керуються OpenAI та залежать від плану. На практиці ці ліміти можуть відрізнятися від - досвіду використання сайту/застосунку ChatGPT, навіть коли обидва прив’язані до одного облікового запису. + + `openai-codex/*` використовує маршрут Codex OAuth, а його придатні до використання вікна квот + керуються OpenAI і залежать від плану. На практиці ці ліміти можуть відрізнятися від + досвіду на вебсайті/в застосунку ChatGPT, навіть якщо обидва прив’язані до одного облікового запису. - OpenClaw може показувати поточні видимі вікна використання/квоти provider у - `openclaw models status`, але не вигадує і не нормалізує права доступу ChatGPT web - до прямого API. Якщо вам потрібен прямий шлях білінгу/лімітів OpenAI Platform, - використовуйте `openai/*` з API key. + OpenClaw може показувати поточні видимі вікна використання/квот провайдера в + `openclaw models status`, але не вигадує і не нормалізує + можливості ChatGPT web у прямий API-доступ. Якщо вам потрібен прямий шлях + оплати/лімітів OpenAI Platform, використовуйте `openai/*` з API-ключем. - + Так. OpenClaw повністю підтримує **OAuth підписки OpenAI Code (Codex)**. - OpenAI явно дозволяє використання OAuth підписки в зовнішніх інструментах/робочих процесах - на кшталт OpenClaw. Під час онбордингу потік OAuth можна виконати за вас. + OpenAI явно дозволяє використання OAuth підписки в зовнішніх інструментах/процесах + на кшталт OpenClaw. Онбординг може виконати OAuth-потік за вас. Див. [OAuth](/uk/concepts/oauth), [Провайдери моделей](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). - Gemini CLI використовує **потік auth Plugin**, а не client id чи secret у `openclaw.json`. + Gemini CLI використовує **потік автентифікації Plugin**, а не client id чи secret у `openclaw.json`. Кроки: - 1. Встановіть Gemini CLI локально, щоб `gemini` був у `PATH` + 1. Установіть Gemini CLI локально, щоб `gemini` був у `PATH` - Homebrew: `brew install gemini-cli` - npm: `npm install -g @google/gemini-cli` 2. Увімкніть Plugin: `openclaw plugins enable google` 3. Увійдіть: `openclaw models auth login --provider google-gemini-cli --set-default` 4. Модель за замовчуванням після входу: `google-gemini-cli/gemini-3-flash-preview` - 5. Якщо запити не працюють, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway + 5. Якщо запити не вдаються, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway - Це зберігає OAuth tokens у профілях auth на хості gateway. Докладніше: [Провайдери моделей](/uk/concepts/model-providers). + Це зберігає OAuth-токени в профілях автентифікації на хості gateway. Докладніше: [Провайдери моделей](/uk/concepts/model-providers). - - Зазвичай ні. OpenClaw потребує великого context + сильного захисту; малі карти обрізаються та дають витоки. Якщо все ж потрібно, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантизовані моделі підвищують ризик prompt injection — див. [Безпека](/uk/gateway/security). + + Зазвичай ні. OpenClaw потребує великого контексту + сильної безпеки; малі карти обрізають контекст і дають витоки. Якщо вже потрібно, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантовані моделі підвищують ризик prompt injection — див. [Безпека](/uk/gateway/security). - - Вибирайте endpoints, прив’язані до регіону. OpenRouter надає варіанти з хостингом у США для MiniMax, Kimi та GLM; вибирайте варіант із хостингом у США, щоб дані залишалися в регіоні. Ви все одно можете вказувати Anthropic/OpenAI поруч із ними, використовуючи `models.mode: "merge"`, щоб резервні варіанти залишалися доступними, водночас дотримуючись вибраного вами provider із прив’язкою до регіону. + + Обирайте endpoint-и, закріплені за регіоном. OpenRouter надає варіанти з хостингом у США для MiniMax, Kimi і GLM; виберіть варіант із хостингом у США, щоб дані залишалися в регіоні. Ви все одно можете перелічувати Anthropic/OpenAI поряд із ними, використовуючи `models.mode: "merge"`, щоб резервні варіанти залишалися доступними, водночас дотримуючись вибраного регіонального провайдера. - - Ні. OpenClaw працює на macOS або Linux (Windows через WSL2). Mac mini — необов’язковий варіант: - деякі люди купують його як постійно увімкнений хост, але також підійдуть невеликий VPS, домашній сервер або пристрій класу Raspberry Pi. + + Ні. OpenClaw працює на macOS або Linux (Windows через WSL2). Mac mini — необов’язковий варіант: дехто + купує його як хост, що завжди ввімкнений, але також підійде невеликий VPS, домашній сервер або пристрій класу Raspberry Pi. - Mac потрібен лише для **інструментів, доступних тільки на macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux або деінде. Якщо вам потрібні інші інструменти лише для macOS, запускайте Gateway на Mac або підключайте Node macOS. + Mac потрібен лише **для інструментів тільки для macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux чи деінде. Якщо вам потрібні інші інструменти лише для macOS, запускайте Gateway на Mac або під’єднайте macOS node. Документація: [BlueBubbles](/uk/channels/bluebubbles), [Nodes](/uk/nodes), [Віддалений режим Mac](/uk/platforms/mac/remote). - Вам потрібен **якийсь пристрій macOS**, на якому виконано вхід у Messages. Це **не обов’язково** має бути Mac mini — - підійде будь-який Mac. Для iMessage **використовуйте [BlueBubbles](/uk/channels/bluebubbles)** (рекомендовано) — сервер BlueBubbles працює на macOS, тоді як Gateway може працювати на Linux або деінде. + Вам потрібен **якийсь пристрій macOS**, у якому виконано вхід у Messages. Це **не обов’язково** має бути Mac mini — + підійде будь-який Mac. Для iMessage **використовуйте [BlueBubbles](/uk/channels/bluebubbles)** (рекомендовано) — сервер BlueBubbles працює на macOS, а Gateway може працювати на Linux або деінде. - Поширені конфігурації: + Поширені варіанти налаштування: - - Запускайте Gateway на Linux/VPS, а сервер BlueBubbles — на будь-якому Mac, де виконано вхід у Messages. - - Запускайте все на Mac, якщо хочете найпростішу конфігурацію на одній машині. + - Запускайте Gateway на Linux/VPS, а сервер BlueBubbles — на будь-якому Mac, у якому виконано вхід у Messages. + - Запускайте все на Mac, якщо хочете найпростішу конфігурацію з однією машиною. Документація: [BlueBubbles](/uk/channels/bluebubbles), [Nodes](/uk/nodes), [Віддалений режим Mac](/uk/platforms/mac/remote). - - Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може підключатися як - **Node** (супутній пристрій). Node не запускають Gateway — вони надають додаткові + + Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може під’єднуватися як + **node** (додатковий пристрій). Nodes не запускають Gateway — вони надають додаткові можливості, як-от screen/camera/canvas і `system.run` на цьому пристрої. - Типова схема: + Поширений сценарій: - - Gateway на Mac mini (постійно увімкнений). - - MacBook Pro запускає застосунок macOS або хост Node і підключається до Gateway. + - Gateway на Mac mini (завжди ввімкнений). + - MacBook Pro запускає застосунок macOS або host node і під’єднується до Gateway. - Використовуйте `openclaw nodes status` / `openclaw nodes list`, щоб побачити його. Документація: [Nodes](/uk/nodes), [CLI Nodes](/cli/nodes). @@ -763,41 +763,41 @@ x-i18n: - Bun **не рекомендується**. Ми бачимо помилки під час виконання, особливо з WhatsApp і Telegram. - Для стабільних Gateway використовуйте **Node**. + Bun **не рекомендовано**. Ми спостерігаємо помилки під час роботи, особливо з WhatsApp і Telegram. + Для стабільних gateway використовуйте **Node**. - Якщо ви все ж хочете експериментувати з Bun, робіть це на неproduction Gateway + Якщо ви все ж хочете поекспериментувати з Bun, робіть це на неproduction gateway без WhatsApp/Telegram. - `channels.telegram.allowFrom` — це **Telegram user ID** відправника-людини (числовий). Це не ім’я користувача бота. + `channels.telegram.allowFrom` — це **Telegram user ID** людини-відправника (числовий). Це не ім’я користувача бота. - Під час онбордингу приймається введення `@username` і воно перетворюється на числовий ID, але авторизація OpenClaw використовує лише числові ID. + Онбординг приймає введення `@username` і перетворює його на числовий ID, але авторизація OpenClaw використовує лише числові ID. - Безпечніший варіант (без стороннього бота): + Безпечніше (без стороннього бота): - - Напишіть своєму боту в DM, потім виконайте `openclaw logs --follow` і прочитайте `from.id`. + - Напишіть своєму боту в DM, а потім виконайте `openclaw logs --follow` і прочитайте `from.id`. Офіційний Bot API: - - Напишіть своєму боту в DM, потім викличте `https://api.telegram.org/bot/getUpdates` і прочитайте `message.from.id`. + - Напишіть своєму боту в DM, а потім викличте `https://api.telegram.org/bot/getUpdates` і прочитайте `message.from.id`. Сторонній варіант (менш приватний): - - Напишіть у DM `@userinfobot` або `@getidsbot`. + - Напишіть `@userinfobot` або `@getidsbot`. Див. [/channels/telegram](/uk/channels/telegram#access-control-and-activation). - Так, через **маршрутизацію multi-agent**. Прив’яжіть **DM** WhatsApp кожного відправника (peer `kind: "direct"`, E.164 відправника, наприклад `+15551234567`) до іншого `agentId`, щоб кожна людина мала власні workspace і session store. Відповіді все одно надходитимуть з **того самого облікового запису WhatsApp**, а контроль доступу для DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для кожного облікового запису WhatsApp. Див. [Маршрутизація Multi-Agent](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp). + Так, через **маршрутизацію multi-agent**. Прив’яжіть **DM** WhatsApp кожного відправника (peer `kind: "direct"`, E.164 відправника на кшталт `+15551234567`) до іншого `agentId`, щоб кожна людина мала власний workspace і сховище сесій. Відповіді все одно надходитимуть з **того самого облікового запису WhatsApp**, а контроль доступу DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для кожного облікового запису WhatsApp. Див. [Маршрутизація Multi-Agent](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp). - - Так. Використовуйте маршрутизацію multi-agent: задайте кожному agent свою модель за замовчуванням, а потім прив’яжіть вхідні маршрути (обліковий запис provider або конкретні peers) до кожного agent. Приклад конфігурації наведено в [Маршрутизація Multi-Agent](/uk/concepts/multi-agent). Див. також [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration). + + Так. Використовуйте маршрутизацію multi-agent: призначте кожному агенту власну модель за замовчуванням, а потім прив’яжіть вхідні маршрути (обліковий запис провайдера або конкретні peers) до кожного агента. Приклад конфігурації наведено в [Маршрутизація Multi-Agent](/uk/concepts/multi-agent). Див. також [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration). @@ -811,13 +811,13 @@ x-i18n: ``` Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH сервісу містить `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб інструменти, встановлені через `brew`, визначалися в non-login оболонках. - Останні збірки також додають попереду поширені каталоги user bin у Linux systemd services (наприклад, `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` і `FNM_DIR`, якщо вони задані. + Останні збірки також додають поширені каталоги bin користувача на Linux у сервіси systemd (наприклад, `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` і `FNM_DIR`, якщо вони задані. - - **Hackable (git) install:** повний checkout вихідного коду, можна редагувати, найкраще для contributors. - Ви локально запускаєте збірки й можете вносити зміни до коду/документації. + - **Hackable (git) install:** повний checkout вихідного коду, можна редагувати, найкраще для контриб’юторів. + Ви локально виконуєте збірки та можете вносити зміни в код/документацію. - **npm install:** глобальне встановлення CLI, без репозиторію, найкраще для сценарію "просто запустити". Оновлення надходять із npm dist-tags. @@ -825,12 +825,12 @@ x-i18n: - - Так. Установіть інший варіант, а потім запустіть Doctor, щоб сервіс gateway вказував на нову entrypoint. - Це **не видаляє ваші дані** — змінюється лише спосіб встановлення коду OpenClaw. Ваші state + + Так. Установіть інший варіант, а потім запустіть Doctor, щоб сервіс gateway вказував на нову точку входу. + Це **не видаляє ваші дані** — воно лише змінює встановлення коду OpenClaw. Ваш state (`~/.openclaw`) і workspace (`~/.openclaw/workspace`) залишаються недоторканими. - Із npm на git: + З npm на git: ```bash git clone https://github.com/openclaw/openclaw.git @@ -841,7 +841,7 @@ x-i18n: openclaw gateway restart ``` - Із git на npm: + З git на npm: ```bash npm install -g openclaw@latest @@ -849,67 +849,67 @@ x-i18n: openclaw gateway restart ``` - Doctor виявляє невідповідність entrypoint сервісу gateway і пропонує переписати конфігурацію сервісу відповідно до поточного встановлення (використовуйте `--repair` в автоматизації). + Doctor виявляє невідповідність точки входу сервісу gateway і пропонує переписати конфігурацію сервісу відповідно до поточного встановлення (в automation використовуйте `--repair`). Поради щодо резервного копіювання: див. [Стратегія резервного копіювання](#де-що-зберігається-на-диску). - Коротка відповідь: **якщо вам потрібна надійність 24/7, використовуйте VPS**. Якщо вам потрібен - найменший поріг входу і вас влаштовують сон/перезапуски, запускайте локально. + Коротка відповідь: **якщо вам потрібна надійність 24/7, використовуйте VPS**. Якщо ви хочете + найменше тертя і вас влаштовують сон/перезапуски, запускайте локально. **Ноутбук (локальний Gateway)** - - **Плюси:** немає витрат на сервер, прямий доступ до локальних файлів, видиме вікно браузера. - - **Мінуси:** сон/обриви мережі = відключення, оновлення ОС/перезавантаження переривають роботу, машина має залишатися активною. + - **Переваги:** немає витрат на сервер, прямий доступ до локальних файлів, видиме вікно браузера. + - **Недоліки:** сон/мережеві збої = відключення, оновлення ОС/перезавантаження переривають роботу, пристрій має залишатися активним. **VPS / хмара** - - **Плюси:** завжди увімкнений, стабільна мережа, немає проблем зі сном ноутбука, легше підтримувати безперервну роботу. - - **Мінуси:** часто працює без графічного інтерфейсу (використовуйте знімки екрана), віддалений доступ до файлів, для оновлень потрібен SSH. + - **Переваги:** постійно ввімкнено, стабільна мережа, немає проблем через сон ноутбука, простіше підтримувати безперервну роботу. + - **Недоліки:** часто працює headless (використовуйте знімки екрана), доступ до файлів лише віддалено, для оновлень потрібно підключатися через SSH. - **Примітка щодо OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord усі добре працюють на VPS. Єдиний реальний компроміс — **браузер без графічного інтерфейсу** проти видимого вікна. Див. [Браузер](/uk/tools/browser). + **Примітка щодо OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord чудово працюють із VPS. Єдина справжня відмінність — **headless browser** проти видимого вікна. Див. [Browser](/uk/tools/browser). - **Рекомендований варіант за замовчуванням:** VPS, якщо у вас раніше були відключення gateway. Локальний запуск чудово підходить, коли ви активно користуєтеся Mac і хочете локальний доступ до файлів або автоматизацію UI з видимим браузером. + **Рекомендований варіант за замовчуванням:** VPS, якщо раніше у вас були відключення gateway. Локальний запуск чудово підходить, коли ви активно користуєтеся Mac і хочете мати доступ до локальних файлів або автоматизацію UI з видимим браузером. - Не обов’язково, але **рекомендовано для надійності та ізоляції**. + Це не обов’язково, але **рекомендовано для надійності та ізоляції**. - - **Виділений хост (VPS/Mac mini/Pi):** завжди увімкнений, менше переривань через сон/перезавантаження, чистіші дозволи, легше підтримувати безперервну роботу. - - **Спільний ноутбук/настільний комп’ютер:** цілком підходить для тестування й активного використання, але очікуйте пауз, коли машина переходить у сон або оновлюється. + - **Виділений хост (VPS/Mac mini/Pi):** завжди ввімкнений, менше переривань через сон/перезавантаження, чистіші дозволи, простіше підтримувати безперервну роботу. + - **Спільний ноутбук/настільний ПК:** цілком підходить для тестування й активного використання, але очікуйте пауз, коли машина засинає або оновлюється. - Якщо ви хочете поєднати обидва підходи, тримайте Gateway на виділеному хості, а ноутбук підключайте як **Node** для локальних інструментів screen/camera/exec. Див. [Nodes](/uk/nodes). - Рекомендації з безпеки дивіться в [Безпека](/uk/gateway/security). + Якщо хочете поєднати найкраще з обох варіантів, тримайте Gateway на виділеному хості, а ноутбук під’єднайте як **node** для локальних інструментів screen/camera/exec. Див. [Nodes](/uk/nodes). + Рекомендації з безпеки див. у [Безпека](/uk/gateway/security). - OpenClaw є легким. Для базового Gateway + одного chat channel: + OpenClaw є легким. Для базового Gateway + одного чат-каналу: - - **Абсолютний мінімум:** 1 vCPU, 1 ГБ RAM, ~500 МБ диска. - - **Рекомендовано:** 1–2 vCPU, 2 ГБ RAM або більше для запасу (журнали, медіа, кілька каналів). Інструменти Node та автоматизація браузера можуть бути ресурсомісткими. + - **Абсолютний мінімум:** 1 vCPU, 1GB RAM, ~500MB диска. + - **Рекомендовано:** 1–2 vCPU, 2GB RAM або більше із запасом (журнали, медіа, кілька каналів). Інструменти Node та автоматизація браузера можуть бути ресурсомісткими. - ОС: використовуйте **Ubuntu LTS** (або будь-яку сучасну Debian/Ubuntu). Шлях встановлення для Linux найкраще протестовано саме там. + ОС: використовуйте **Ubuntu LTS** (або будь-який сучасний Debian/Ubuntu). Шлях встановлення для Linux там протестовано найкраще. Документація: [Linux](/uk/platforms/linux), [VPS hosting](/uk/vps). - Так. Ставтеся до VM так само, як до VPS: вона має бути завжди увімкнена, доступна та мати достатньо - RAM для Gateway і всіх каналів, які ви вмикаєте. + Так. Ставтеся до VM так само, як до VPS: вона має бути постійно ввімкнена, доступна та мати достатньо + RAM для Gateway і будь-яких channels, які ви вмикаєте. Базові рекомендації: - - **Абсолютний мінімум:** 1 vCPU, 1 ГБ RAM. - - **Рекомендовано:** 2 ГБ RAM або більше, якщо ви запускаєте кілька каналів, автоматизацію браузера чи медіаінструменти. - - **ОС:** Ubuntu LTS або інша сучасна Debian/Ubuntu. + - **Абсолютний мінімум:** 1 vCPU, 1GB RAM. + - **Рекомендовано:** 2GB RAM або більше, якщо ви запускаєте кілька каналів, автоматизацію браузера або медіаінструменти. + - **ОС:** Ubuntu LTS або інший сучасний Debian/Ubuntu. Якщо ви використовуєте Windows, **WSL2 — це найпростіший варіант налаштування у стилі VM** і він має найкращу - сумісність з інструментами. Див. [Windows](/uk/platforms/windows), [VPS hosting](/uk/vps). + сумісність інструментів. Див. [Windows](/uk/platforms/windows), [VPS hosting](/uk/vps). Якщо ви запускаєте macOS у VM, див. [macOS VM](/uk/install/macos-vm). @@ -918,28 +918,28 @@ x-i18n: ## Що таке OpenClaw? - - OpenClaw — це персональний AI assistant, який ви запускаєте на власних пристроях. Він відповідає в тих messaging surfaces, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat і вбудовані channel plugins, як-от QQ Bot), а також може працювати з голосом + live Canvas на підтримуваних платформах. **Gateway** — це завжди увімкнена control plane; assistant — це сам продукт. + + OpenClaw — це персональний AI-помічник, який ви запускаєте на власних пристроях. Він відповідає у вже знайомих вам каналах обміну повідомленнями (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat, а також у вбудованих channel plugins, наприклад QQ Bot) і також може працювати з голосом + live Canvas на підтримуваних платформах. **Gateway** — це постійно ввімкнена площина керування; асистент і є продуктом. - OpenClaw — це не "просто обгортка для Claude". Це **local-first control plane**, яка дозволяє запускати - потужного assistant на **вашому власному обладнанні**, з доступом через chat apps, якими ви вже користуєтеся, зі - session history, memory та інструментами — без передавання контролю над вашими робочими процесами розміщеному - SaaS. + OpenClaw — це не "просто обгортка для Claude". Це **локальна control plane**, яка дає змогу запускати + потужного асистента на **вашому власному обладнанні**, доступного з чат-застосунків, якими ви вже користуєтеся, із + сесійною історією, пам’яттю та інструментами — без передачі контролю над вашими робочими процесами + SaaS-сервісу. Основні переваги: - **Ваші пристрої, ваші дані:** запускайте Gateway де завгодно (Mac, Linux, VPS) і зберігайте - workspace + history сеансів локально. + workspace + історію сесій локально. - **Реальні канали, а не вебпісочниця:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage тощо, а також мобільний голос і Canvas на підтримуваних платформах. - - **Незалежність від моделі:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо з маршрутизацією - і резервним перемиканням на рівні agent. + - **Незалежність від моделі:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо, з маршрутизацією + та резервним перемиканням на рівні агентів. - **Варіант лише локально:** запускайте локальні моделі, щоб **усі дані могли залишатися на вашому пристрої**, якщо хочете. - - **Маршрутизація multi-agent:** окремі agents для кожного каналу, облікового запису чи задачі, кожен із власним - workspace та типовими налаштуваннями. - - **Відкритий код і придатність до змін:** перевіряйте, розширюйте й самостійно розміщуйте без vendor lock-in. + - **Маршрутизація multi-agent:** окремі агенти для каналу, облікового запису чи завдання, кожен зі своїм + workspace і параметрами за замовчуванням. + - **Відкритий код і гнучкість:** перевіряйте, розширюйте та self-host без прив’язки до постачальника. Документація: [Gateway](/uk/gateway), [Channels](/uk/channels), [Multi-agent](/uk/concepts/multi-agent), [Пам’ять](/uk/concepts/memory). @@ -949,50 +949,50 @@ x-i18n: Хороші перші проєкти: - - Створити вебсайт (WordPress, Shopify або простий статичний сайт). + - Створити сайт (WordPress, Shopify або простий статичний сайт). - Прототипувати мобільний застосунок (структура, екрани, план API). - - Організувати файли та папки (очищення, найменування, теги). - - Підключити Gmail і автоматизувати зведення або подальші дії. + - Упорядкувати файли та папки (очищення, іменування, теги). + - Підключити Gmail і автоматизувати зведення або follow-up. - Він може виконувати великі задачі, але найкраще працює, коли ви розбиваєте їх на етапи та + Він може працювати з великими завданнями, але найкраще працює, коли ви розбиваєте їх на етапи і використовуєте sub agents для паралельної роботи. - Повсякденна користь зазвичай виглядає так: + Щоденні виграші зазвичай виглядають так: - - **Персональні зведення:** підсумки inbox, календаря та новин, які вас цікавлять. - - **Дослідження та чернетки:** швидкі дослідження, підсумки та перші чернетки листів або документів. - - **Нагадування та подальші дії:** підказки й контрольні списки на основі Cron або Heartbeat. - - **Автоматизація браузера:** заповнення форм, збирання даних і повторювані вебзадачі. - - **Координація між пристроями:** надішліть задачу з телефону, дозвольте Gateway виконати її на сервері й отримайте результат назад у чаті. + - **Персональні зведення:** підсумки inbox, календаря та новин, які для вас важливі. + - **Дослідження й чернетки:** швидкий пошук інформації, підсумки та перші чернетки для листів або документів. + - **Нагадування та follow-up:** підштовхування й чеклісти на основі cron або Heartbeat. + - **Автоматизація браузера:** заповнення форм, збирання даних і повторювані вебзавдання. + - **Координація між пристроями:** надішліть завдання з телефону, дозвольте Gateway виконати його на сервері та отримайте результат назад у чаті. - - Так, для **дослідження, кваліфікації та підготовки чернеток**. Він може сканувати сайти, складати короткі списки, - підсумовувати інформацію про потенційних клієнтів і писати чернетки outreach або рекламних текстів. + + Так, для **дослідження, кваліфікації та створення чернеток**. Він може сканувати сайти, формувати короткі списки, + підсумовувати потенційних клієнтів і писати чернетки outreach або рекламних текстів. - Для **outreach або запуску реклами** залишайте людину в циклі. Уникайте спаму, дотримуйтеся місцевих законів і - політик платформ та перевіряйте все перед надсиланням. Найбезпечніший шаблон — дозволити - OpenClaw підготувати чернетку, а вам — схвалити її. + Для **outreach або рекламних кампаній** залишайте людину в циклі. Уникайте спаму, дотримуйтеся місцевих законів і + політик платформ та перевіряйте все перед надсиланням. Найбезпечніший підхід — + коли OpenClaw готує чернетку, а ви її погоджуєте. Документація: [Безпека](/uk/gateway/security). - OpenClaw — це **персональний assistant** і рівень координації, а не заміна IDE. Використовуйте - Claude Code або Codex для найшвидшого прямого циклу кодування в репозиторії. Використовуйте OpenClaw, коли вам + OpenClaw — це **персональний асистент** і рівень координації, а не заміна IDE. Використовуйте + Claude Code або Codex для найшвидшого прямого циклу програмування в репозиторії. Використовуйте OpenClaw, коли вам потрібні довготривала пам’ять, доступ із різних пристроїв і оркестрація інструментів. Переваги: - - **Постійна пам’ять + workspace** між сеансами - - **Доступ із кількох платформ** (WhatsApp, Telegram, TUI, WebChat) - - **Оркестрація інструментів** (browser, files, scheduling, hooks) - - **Завжди увімкнений Gateway** (запускайте на VPS, взаємодійте звідусіль) + - **Постійна пам’ять + workspace** між сесіями + - **Багатоплатформний доступ** (WhatsApp, Telegram, TUI, WebChat) + - **Оркестрація інструментів** (браузер, файли, планування, hooks) + - **Постійно ввімкнений Gateway** (запуск на VPS, взаємодія звідусіль) - **Nodes** для локальних browser/screen/camera/exec Вітрина: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -1000,72 +1000,72 @@ x-i18n: -## Skills і автоматизація +## Skills та автоматизація - - Використовуйте керовані overrides замість редагування копії в репозиторії. Розміщуйте свої зміни в `~/.openclaw/skills//SKILL.md` (або додайте папку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет такий: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → вбудовані → `skills.load.extraDirs`, тож керовані overrides усе одно мають вищий пріоритет за вбудовані Skills без змін у git. Якщо вам потрібно, щоб skill було встановлено глобально, але видно лише деяким agents, зберігайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` та `agents.list[].skills`. Лише зміни, варті upstream, повинні жити в репозиторії та надсилатися як PR. + + Використовуйте керовані override замість редагування копії в репозиторії. Помістіть свої зміни в `~/.openclaw/skills//SKILL.md` (або додайте папку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет такий: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → вбудовані → `skills.load.extraDirs`, тож керовані override усе одно мають пріоритет над вбудованими Skills без змін у git. Якщо вам потрібно, щоб skill було встановлено глобально, але видно лише деяким агентам, зберігайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` та `agents.list[].skills`. Лише зміни, варті апстриму, мають жити в репозиторії та надсилатися як PR. - - Так. Додайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Типовий порядок пріоритету: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → вбудовані → `skills.load.extraDirs`. `clawhub` типово встановлює в `./skills`, що OpenClaw трактує як `/skills` у наступному сеансі. Якщо skill має бути видимий лише певним agents, поєднуйте це з `agents.defaults.skills` або `agents.list[].skills`. + + Так. Додайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Стандартний порядок пріоритету: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → вбудовані → `skills.load.extraDirs`. `clawhub` за замовчуванням встановлює в `./skills`, що OpenClaw трактує як `/skills` під час наступної сесії. Якщо skill має бути видимим лише певним агентам, поєднайте це з `agents.defaults.skills` або `agents.list[].skills`. - - Сьогодні підтримуються такі шаблони: + + Наразі підтримуються такі шаблони: - - **Завдання Cron**: ізольовані завдання можуть задавати override `model` для кожного завдання. - - **Sub-agents**: маршрутизуйте задачі до окремих agents з різними моделями за замовчуванням. - - **Перемикання на вимогу**: використовуйте `/model`, щоб у будь-який час змінити модель поточного сеансу. + - **Cron jobs**: ізольовані завдання можуть задавати override `model` для кожного завдання. + - **Sub-agents**: маршрутизуйте завдання до окремих агентів із різними моделями за замовчуванням. + - **Перемикання на вимогу**: використовуйте `/model`, щоб будь-коли змінити модель поточної сесії. - Див. [Завдання Cron](/uk/automation/cron-jobs), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent) та [Slash commands](/uk/tools/slash-commands). + Див. [Cron jobs](/uk/automation/cron-jobs), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent) і [Slash-команди](/uk/tools/slash-commands). - - Використовуйте **sub-agents** для довгих або паралельних задач. Sub-agents працюють у власному сеансі, - повертають підсумок і зберігають чутливість вашого основного чату. + + Використовуйте **sub-agents** для довгих або паралельних завдань. Sub-agents працюють у власній сесії, + повертають підсумок і не дають основному чату зависнути. - Попросіть свого бота "spawn a sub-agent for this task" або використайте `/subagents`. - Використовуйте `/status` у чаті, щоб бачити, що Gateway робить прямо зараз (і чи він зайнятий). + Попросіть бота "spawn a sub-agent for this task" або використайте `/subagents`. + Використовуйте `/status` у чаті, щоб бачити, що Gateway робить зараз (і чи він зайнятий). - Порада щодо токенів: і довгі задачі, і sub-agents споживають токени. Якщо вартість критична, задайте + Порада щодо токенів: довгі завдання і sub-agents обидва споживають токени. Якщо вас хвилює вартість, задайте дешевшу модель для sub-agents через `agents.defaults.subagents.model`. - Документація: [Sub-agents](/uk/tools/subagents), [Фонові задачі](/uk/automation/tasks). + Документація: [Sub-agents](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks). - - Використовуйте прив’язки thread. Ви можете прив’язати thread Discord до subagent або цільового сеансу, щоб подальші повідомлення в цьому thread залишалися в межах прив’язаного сеансу. + + Використовуйте прив’язки thread. Ви можете прив’язати Discord thread до subagent або цілі сесії, щоб подальші повідомлення в цьому thread залишалися в межах прив’язаної сесії. - Базовий потік: + Базовий процес: - - Виконайте spawn через `sessions_spawn` з `thread: true` (і, за потреби, `mode: "session"` для постійного подальшого продовження). - - Або прив’яжіть вручну за допомогою `/focus `. - - Використовуйте `/agents`, щоб переглянути стан прив’язки. - - Використовуйте `/session idle ` і `/session max-age `, щоб керувати автоматичним зняттям фокуса. + - Створіть через `sessions_spawn` з `thread: true` (і за потреби `mode: "session"` для постійного follow-up). + - Або прив’яжіть вручну через `/focus `. + - Використовуйте `/agents`, щоб перевірити стан прив’язки. + - Використовуйте `/session idle ` і `/session max-age ` для керування автоматичним зняттям фокуса. - Використовуйте `/unfocus`, щоб від’єднати thread. Потрібна конфігурація: - - Глобальні типові налаштування: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - - Overrides для Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. - - Автоматична прив’язка під час spawn: задайте `channels.discord.threadBindings.spawnSubagentSessions: true`. + - Глобальні значення за замовчуванням: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. + - Override для Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. + - Автоприв’язка під час spawn: задайте `channels.discord.threadBindings.spawnSubagentSessions: true`. - Документація: [Sub-agents](/uk/tools/subagents), [Discord](/uk/channels/discord), [Довідник із конфігурації](/uk/gateway/configuration-reference), [Slash commands](/uk/tools/slash-commands). + Документація: [Sub-agents](/uk/tools/subagents), [Discord](/uk/channels/discord), [Довідник із конфігурації](/uk/gateway/configuration-reference), [Slash-команди](/uk/tools/slash-commands). - - Спочатку перевірте визначений маршрут запитувача: + + Спочатку перевірте розв’язаний маршрут запитувача: - - Доставка subagent у режимі completion надає перевагу будь-якому прив’язаному thread або маршруту conversation, якщо такий існує. - - Якщо джерело completion містить лише channel, OpenClaw повертається до збереженого маршруту сеансу запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно могла спрацювати. - - Якщо немає ані прив’язаного маршруту, ані придатного збереженого маршруту, пряма доставка може не спрацювати, і результат натомість повернеться до queued delivery сеансу, а не буде негайно опублікований у чаті. - - Недійсні або застарілі цілі все ще можуть примусити перехід до queue fallback або остаточного збою доставки. - - Якщо остання видима відповідь assistant дочірнього елемента — це точний silent token `NO_REPLY` / `no_reply` або рівно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує announce, замість того щоб публікувати застарілий попередній прогрес. - - Якщо дочірній елемент перевищив час очікування після лише викликів інструментів, announce може згорнути це в короткий підсумок часткового прогресу замість відтворення сирого виводу інструментів. + - Доставка subagent у режимі completion віддає перевагу будь-якому прив’язаному thread або маршруту розмови, якщо такий існує. + - Якщо джерело completion містить лише channel, OpenClaw повертається до збереженого маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно могла спрацювати. + - Якщо немає ні прив’язаного маршруту, ні придатного збереженого маршруту, пряма доставка може не вдатися, і результат замість негайної публікації в чаті перейде до доставки через чергу сесії. + - Некоректні або застарілі цілі все одно можуть примусово спричинити перехід до черги або остаточну невдачу доставки. + - Якщо остання видима відповідь асистента дочірньої сесії — це точний тихий токен `NO_REPLY` / `no_reply` або точно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує анонс замість публікації застарілого попереднього прогресу. + - Якщо дочірня сесія завершилася за тайм-аутом лише після викликів інструментів, анонс може згорнути це в короткий підсумок часткового прогресу замість відтворення сирого виводу інструментів. Налагодження: @@ -1073,7 +1073,7 @@ x-i18n: openclaw tasks show ``` - Документація: [Sub-agents](/uk/tools/subagents), [Фонові задачі](/uk/automation/tasks), [Інструменти сеансів](/uk/concepts/session-tool). + Документація: [Sub-agents](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks), [Інструменти сесій](/uk/concepts/session-tool). @@ -1083,9 +1083,9 @@ x-i18n: Контрольний список: - - Підтвердьте, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не задано. + - Переконайтеся, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не задано. - Перевірте, що Gateway працює 24/7 (без сну/перезапусків). - - Перевірте налаштування timezone для завдання (`--tz` проти timezone хоста). + - Перевірте налаштування часового поясу для завдання (`--tz` проти часового поясу хоста). Налагодження: @@ -1094,21 +1094,21 @@ x-i18n: openclaw cron runs --id --limit 50 ``` - Документація: [Завдання Cron](/uk/automation/cron-jobs), [Автоматизація та задачі](/uk/automation). + Документація: [Cron jobs](/uk/automation/cron-jobs), [Автоматизація й завдання](/uk/automation). - + Спочатку перевірте режим доставки: - - `--no-deliver` / `delivery.mode: "none"` означає, що жодне зовнішнє повідомлення не очікується. - - Відсутня або недійсна announce target (`channel` / `to`) означає, що runner пропустив вихідну доставку. - - Збої auth каналу (`unauthorized`, `Forbidden`) означають, що runner намагався виконати доставку, але облікові дані її заблокували. - - Тихий ізольований результат (`NO_REPLY` / `no_reply` only) вважається навмисно непридатним для доставки, тому runner також пригнічує queued fallback delivery. + - `--no-deliver` / `delivery.mode: "none"` означає, що зовнішнє повідомлення не очікується. + - Відсутня або некоректна ціль анонсу (`channel` / `to`) означає, що runner пропустив вихідну доставку. + - Збої автентифікації channel (`unauthorized`, `Forbidden`) означають, що runner намагався доставити повідомлення, але облікові дані це заблокували. + - Тихий ізольований результат (`NO_REPLY` / `no_reply` only) вважається навмисно непридатним до доставки, тож runner також пригнічує доставку через queued fallback. - Для ізольованих завдань cron runner керує фінальною доставкою. Очікується, що agent - поверне простий текстовий підсумок, який runner надішле. `--no-deliver` залишає - цей результат внутрішнім; він не дозволяє agent натомість надсилати його безпосередньо через + Для ізольованих Cron jobs остаточною доставкою керує runner. Очікується, + що агент поверне текстовий підсумок, який runner надішле. `--no-deliver` залишає + цей результат внутрішнім; він не дозволяє агенту натомість надсилати напряму через message tool. Налагодження: @@ -1118,27 +1118,27 @@ x-i18n: openclaw tasks show ``` - Документація: [Завдання Cron](/uk/automation/cron-jobs), [Фонові задачі](/uk/automation/tasks). + Документація: [Cron jobs](/uk/automation/cron-jobs), [Фонові завдання](/uk/automation/tasks). - - Зазвичай це шлях live model-switch, а не дубльоване планування. + + Зазвичай це шлях live-перемикання моделі, а не дубльоване планування. - Ізольований cron може зберегти runtime handoff моделі й виконати повторну спробу, коли активний - запуск викидає `LiveSessionModelSwitchError`. Повторна спроба зберігає перемкнені - provider/model, а якщо перемикання містило новий override auth profile, cron + Ізольований cron може зберегти передачу моделі під час виконання та повторити спробу, коли активний + запуск викидає `LiveSessionModelSwitchError`. Повторна спроба зберігає перемкнений + provider/model, а якщо перемикання містило новий override профілю автентифікації, cron також зберігає його перед повторною спробою. Пов’язані правила вибору: - - Override моделі Gmail hook має найвищий пріоритет, коли застосовний. - - Далі — `model` для окремого завдання. - - Потім — будь-який збережений override моделі сеансу cron. - - Потім — звичайний вибір моделі agent/за замовчуванням. + - Override моделі для Gmail hook має найвищий пріоритет, якщо застосовно. + - Потім `model` для конкретного завдання. + - Потім будь-який збережений override моделі cron-session. + - Потім звичайний вибір моделі агента/за замовчуванням. - Цикл повторних спроб обмежений. Після початкової спроби плюс 2 повторні спроби через перемикання - cron припиняє роботу замість нескінченного циклу. + Цикл повторних спроб обмежений. Після початкової спроби плюс 2 повторних спроб перемикання + cron зупиняється замість нескінченного циклу. Налагодження: @@ -1147,12 +1147,12 @@ x-i18n: openclaw tasks show ``` - Документація: [Завдання Cron](/uk/automation/cron-jobs), [CLI cron](/cli/cron). + Документація: [Cron jobs](/uk/automation/cron-jobs), [CLI cron](/cli/cron). - Використовуйте нативні команди `openclaw skills` або розміщуйте Skills у своєму workspace. UI Skills для macOS недоступний на Linux. + Використовуйте нативні команди `openclaw skills` або поміщайте Skills у свій workspace. UI Skills для macOS недоступний на Linux. Переглянути Skills можна на [https://clawhub.ai](https://clawhub.ai). ```bash @@ -1166,39 +1166,39 @@ x-i18n: openclaw skills check ``` - Нативна команда `openclaw skills install` записує у каталог `skills/` - активного workspace. Установлюйте окремий CLI `clawhub`, лише якщо хочете публікувати або - синхронізувати власні Skills. Для спільних установлень між agents розміщуйте skill у + Нативна команда `openclaw skills install` записує в каталог `skills/` + активного workspace. Окремий CLI `clawhub` установлюйте лише якщо хочете публікувати або + синхронізувати власні Skills. Для спільних установлень між агентами помістіть skill у `~/.openclaw/skills` і використовуйте `agents.defaults.skills` або - `agents.list[].skills`, якщо хочете обмежити, які agents можуть його бачити. + `agents.list[].skills`, якщо хочете звузити коло агентів, які можуть його бачити. - + Так. Використовуйте планувальник Gateway: - - **Завдання Cron** для запланованих або повторюваних задач (зберігаються після перезапусків). - - **Heartbeat** для періодичних перевірок "основного сеансу". - - **Ізольовані завдання** для автономних agents, які публікують підсумки або доставляють їх у чати. + - **Cron jobs** для запланованих або повторюваних завдань (зберігаються після перезапусків). + - **Heartbeat** для періодичних перевірок "основної сесії". + - **Ізольовані завдання** для автономних агентів, які публікують підсумки або доставляють їх у чати. - Документація: [Завдання Cron](/uk/automation/cron-jobs), [Автоматизація та задачі](/uk/automation), + Документація: [Cron jobs](/uk/automation/cron-jobs), [Автоматизація й завдання](/uk/automation), [Heartbeat](/uk/gateway/heartbeat). - - Не безпосередньо. Skills для macOS обмежуються `metadata.openclaw.os` разом із потрібними бінарними файлами, і Skills з’являються в system prompt лише тоді, коли вони придатні на **хості Gateway**. На Linux Skills лише для `darwin` (як-от `apple-notes`, `apple-reminders`, `things-mac`) не завантажуються, якщо ви не перевизначите це обмеження. + + Не напряму. Skills для macOS обмежуються через `metadata.openclaw.os` плюс потрібні бінарні файли, і Skills з’являються в системному prompt лише тоді, коли вони придатні на **хості Gateway**. На Linux skills лише для `darwin` (як-от `apple-notes`, `apple-reminders`, `things-mac`) не завантажаться, якщо не перевизначити це обмеження. Є три підтримувані шаблони: **Варіант A — запускати Gateway на Mac (найпростіше).** - Запускайте Gateway там, де є бінарні файли macOS, а потім підключайтеся з Linux у [remote mode](#gateway-ports-already-running-and-remote-mode) або через Tailscale. Skills завантажуються звичайним чином, тому що хост Gateway — це macOS. + Запускайте Gateway там, де існують бінарні файли macOS, а потім підключайтеся з Linux у [віддаленому режимі](#gateway-ports-already-running-and-remote-mode) або через Tailscale. Skills завантажуються нормально, тому що хост Gateway — це macOS. - **Варіант B — використовувати Node macOS (без SSH).** - Запускайте Gateway на Linux, підключіть Node macOS (menubar app) і встановіть **Node Run Commands** у "Always Ask" або "Always Allow" на Mac. OpenClaw може вважати Skills лише для macOS придатними, коли потрібні бінарні файли є на Node. Agent запускає ці Skills через інструмент `nodes`. Якщо ви виберете "Always Ask", схвалення "Always Allow" у запиті додасть цю команду до allowlist. + **Варіант B — використовувати macOS node (без SSH).** + Запускайте Gateway на Linux, під’єднайте macOS node (застосунок у рядку меню) і встановіть **Node Run Commands** у "Always Ask" або "Always Allow" на Mac. OpenClaw може вважати skills лише для macOS придатними, коли потрібні бінарні файли існують на node. Агент запускає ці skills через інструмент `nodes`. Якщо ви виберете "Always Ask", підтвердження "Always Allow" у prompt додасть цю команду до allowlist. - **Варіант C — проксувати бінарні файли macOS через SSH (просунутий варіант).** - Залиште Gateway на Linux, але налаштуйте так, щоб потрібні CLI-бінарні файли визначалися як SSH-обгортки, що виконуються на Mac. Потім перевизначте skill, щоб дозволити Linux і він залишався придатним. + **Варіант C — проксувати бінарні файли macOS через SSH (просунутий).** + Залиште Gateway на Linux, але зробіть так, щоб потрібні CLI-бінарні файли визначалися як SSH-обгортки, які запускаються на Mac. Потім перевизначте skill, щоб дозволити Linux і він залишався придатним. 1. Створіть SSH-обгортку для бінарного файла (приклад: `memo` для Apple Notes): @@ -1208,8 +1208,8 @@ x-i18n: exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. Додайте обгортку до `PATH` на хості Linux (наприклад, `~/bin/memo`). - 3. Перевизначте metadata skill (workspace або `~/.openclaw/skills`), щоб дозволити Linux: + 2. Додайте обгортку до `PATH` на Linux-хості (наприклад, `~/bin/memo`). + 3. Перевизначте метадані skill (у workspace або `~/.openclaw/skills`), щоб дозволити Linux: ```markdown --- @@ -1219,25 +1219,25 @@ x-i18n: --- ``` - 4. Почніть новий сеанс, щоб знімок Skills оновився. + 4. Запустіть нову сесію, щоб знімок Skills оновився. - Наразі вбудованої немає. + На сьогодні вбудованої немає. Варіанти: - - **Власний skill / Plugin:** найкраще для надійного доступу до API (і Notion, і HeyGen мають API). - - **Автоматизація браузера:** працює без коду, але повільніше й менш надійно. + - **Користувацький skill / Plugin:** найкращий варіант для надійного доступу до API (і Notion, і HeyGen мають API). + - **Автоматизація браузера:** працює без коду, але повільніше та менш надійно. - Якщо ви хочете зберігати контекст для кожного клієнта окремо (робочі процеси агентства), простий шаблон такий: + Якщо ви хочете зберігати контекст окремо для кожного клієнта (робочі процеси агентства), простий шаблон такий: - Одна сторінка Notion на клієнта (контекст + налаштування + активна робота). - - Попросіть agent отримувати цю сторінку на початку сеансу. + - Попросіть агента отримувати цю сторінку на початку сесії. - Якщо вам потрібна нативна інтеграція, створіть feature request або побудуйте skill, - націлений на ці API. + Якщо вам потрібна нативна інтеграція, створіть запит на функцію або створіть skill, + орієнтований на ці API. Установлення Skills: @@ -1246,32 +1246,32 @@ x-i18n: openclaw skills update --all ``` - Нативні встановлення потрапляють у каталог `skills/` активного workspace. Для спільних Skills між agents розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо спільне встановлення мають бачити лише деякі agents, налаштуйте `agents.defaults.skills` або `agents.list[].skills`. Деякі Skills очікують наявності бінарних файлів, установлених через Homebrew; на Linux це означає Linuxbrew (див. запис FAQ про Homebrew на Linux вище). Див. [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і [ClawHub](/uk/tools/clawhub). + Нативні встановлення потрапляють у каталог `skills/` активного workspace. Для спільних Skills між агентами розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо спільне встановлення мають бачити лише деякі агенти, налаштуйте `agents.defaults.skills` або `agents.list[].skills`. Деякі Skills очікують бінарні файли, установлені через Homebrew; на Linux це означає Linuxbrew (див. запис FAQ про Homebrew на Linux вище). Див. [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і [ClawHub](/uk/tools/clawhub). - - Використовуйте вбудований профіль браузера `user`, який підключається через Chrome DevTools MCP: + + Використовуйте вбудований профіль браузера `user`, який під’єднується через Chrome DevTools MCP: ```bash openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot ``` - Якщо вам потрібна власна назва, створіть явний профіль MCP: + Якщо вам потрібна власна назва, створіть явний MCP-профіль: ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - Цей шлях є локальним для хоста. Якщо Gateway запущено деінде, або запускайте хост Node на машині з браузером, або використовуйте віддалений CDP. + Цей шлях може використовувати браузер локального хоста або під’єднаний browser node. Якщо Gateway працює деінде, або запустіть host node на машині з браузером, або використовуйте віддалений CDP. - Поточні обмеження `existing-session` / `user`: + Поточні обмеження для `existing-session` / `user`: - - дії виконуються через ref, а не через CSS-selector + - дії ґрунтуються на ref, а не на CSS-селекторах - завантаження файлів потребує `ref` / `inputRef` і наразі підтримує лише один файл за раз - - `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії все ще потребують керованого браузера або сирого профілю CDP + - `responsebody`, експорт у PDF, перехоплення завантажень і пакетні дії все ще потребують керованого браузера або сирого CDP-профілю @@ -1279,97 +1279,98 @@ x-i18n: ## Ізоляція та пам’ять - - Так. Див. [Ізоляція](/uk/gateway/sandboxing). Для специфічного налаштування Docker (повний Gateway у Docker або образи sandbox) див. [Docker](/uk/install/docker). + + Так. Див. [Ізоляція](/uk/gateway/sandboxing). Для налаштування, специфічного для Docker (повний gateway у Docker або образи ізоляції), див. [Docker](/uk/install/docker). - Типовий образ орієнтований на безпеку й запускається від користувача `node`, тому він не + Образ за замовчуванням орієнтований насамперед на безпеку та запускається від користувача `node`, тому він не містить системних пакетів, Homebrew або вбудованих браузерів. Для повнішого налаштування: - Зберігайте `/home/node` через `OPENCLAW_HOME_VOLUME`, щоб кеші не зникали. - - Вбудовуйте системні залежності в образ через `OPENCLAW_DOCKER_APT_PACKAGES`. - - Установіть браузери Playwright через вбудований CLI: + - Додавайте системні залежності до образу через `OPENCLAW_DOCKER_APT_PACKAGES`. + - Установлюйте браузери Playwright через вбудований CLI: `node /app/node_modules/playwright-core/cli.js install chromium` - Задайте `PLAYWRIGHT_BROWSERS_PATH` і переконайтеся, що цей шлях зберігається. - Документація: [Docker](/uk/install/docker), [Браузер](/uk/tools/browser). + Документація: [Docker](/uk/install/docker), [Browser](/uk/tools/browser). - - Так — якщо ваш приватний трафік — це **DM**, а публічний трафік — це **групи**. + + Так — якщо ваш приватний трафік це **DM**, а публічний трафік це **групи**. - Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб сеанси груп/channel (ключі не-main) запускалися в Docker, а основний сеанс DM залишався на хості. Потім обмежте, які інструменти доступні в ізольованих сеансах, через `tools.sandbox.tools`. + Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб сесії груп/channel (ключі не-main) працювали в Docker, а основна DM-сесія залишалася на хості. Потім обмежте, які інструменти доступні в ізольованих сесіях, через `tools.sandbox.tools`. - Покрокове налаштування + приклад конфігурації: [Групи: особисті DM + публічні групи](/uk/channels/groups#pattern-personal-dms-public-groups-single-agent) + Покрокове налаштування + приклад конфігурації: [Групи: приватні DM + публічні групи](/uk/channels/groups#pattern-personal-dms-public-groups-single-agent) - Довідник з ключової конфігурації: [Конфігурація Gateway](/uk/gateway/configuration-reference#agentsdefaultssandbox) + Довідник із ключової конфігурації: [Конфігурація Gateway](/uk/gateway/configuration-reference#agentsdefaultssandbox) - Задайте `agents.defaults.sandbox.docker.binds` як `["host:path:mode"]` (наприклад, `"/home/user/src:/src:ro"`). Глобальні прив’язки та прив’язки на рівні agent об’єднуються; прив’язки на рівні agent ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого й пам’ятайте, що прив’язки обходять файлові межі sandbox. + Установіть `agents.defaults.sandbox.docker.binds` у `["host:path:mode"]` (наприклад, `"/home/user/src:/src:ro"`). Глобальні прив’язки й прив’язки для окремого агента об’єднуються; прив’язки для окремого агента ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для будь-чого чутливого й пам’ятайте, що прив’язки обходять файлові межі sandbox. - OpenClaw перевіряє джерела bind за нормалізованим шляхом і за канонічним шляхом, визначеним через найглибший наявний батьківський елемент. Це означає, що виходи через symlink-батьківський шлях усе одно блокуються за принципом fail closed, навіть коли останній сегмент шляху ще не існує, а перевірки allowed-root усе одно застосовуються після розв’язання symlink. + OpenClaw перевіряє джерела bind і за нормалізованим шляхом, і за канонічним шляхом, який визначається через найглибший наявний батьківський елемент. Це означає, що виходи за межі через symlink-батьківський шлях однаково надійно блокуються, навіть коли останній сегмент шляху ще не існує, а перевірки allowed-root і далі застосовуються після розв’язання symlink. - Див. [Ізоляція](/uk/gateway/sandboxing#custom-bind-mounts) і [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) для прикладів і приміток із безпеки. + Приклади та примітки з безпеки див. у [Ізоляція](/uk/gateway/sandboxing#custom-bind-mounts) і [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check). - Пам’ять OpenClaw — це просто файли Markdown у workspace agent: + Пам’ять OpenClaw — це просто Markdown-файли у workspace агента: - Щоденні нотатки в `memory/YYYY-MM-DD.md` - - Кураторські довгострокові нотатки в `MEMORY.md` (лише для main/private sessions) + - Кураторські довгострокові нотатки в `MEMORY.md` (лише для main/private-сесій) OpenClaw також виконує **тихе попереднє скидання пам’яті перед Compaction**, щоб нагадати моделі - записати стійкі нотатки перед автоматичним Compaction. Це працює лише тоді, коли workspace - доступний для запису (sandbox у режимі лише читання пропускають це). Див. [Пам’ять](/uk/concepts/memory). + записати стійкі нотатки перед автоматичним Compaction. Це виконується лише тоді, коли workspace + доступний для запису (sandbox лише для читання пропускають це). Див. [Пам’ять](/uk/concepts/memory). - - Попросіть бота **записати факт у пам’ять**. Довгострокові нотатки мають зберігатися в `MEMORY.md`, + + Попросіть бота **записати факт у пам’ять**. Довготривалі нотатки мають зберігатися в `MEMORY.md`, короткостроковий контекст — у `memory/YYYY-MM-DD.md`. Це все ще напрям, який ми вдосконалюємо. Корисно нагадувати моделі зберігати спогади; вона знатиме, що робити. Якщо вона й далі забуває, перевірте, що Gateway використовує той самий workspace під час кожного запуску. - Документація: [Пам’ять](/uk/concepts/memory), [Workspace agent](/uk/concepts/agent-workspace). + Документація: [Пам’ять](/uk/concepts/memory), [Workspace агента](/uk/concepts/agent-workspace). - Файли пам’яті зберігаються на диску й існують, доки ви їх не видалите. Обмеженням є ваше - сховище, а не модель. **Контекст сеансу** все одно обмежений - вікном context моделі, тому довгі розмови можуть стискатися або обрізатися. Саме тому + Файли пам’яті зберігаються на диску й існують, доки ви їх не видалите. Обмеженням є + ваше сховище, а не модель. **Контекст сесії** все одно обмежений + вікном контексту моделі, тому довгі розмови можуть проходити Compaction або обрізання. Саме тому існує пошук у пам’яті — він повертає в контекст лише релевантні частини. Документація: [Пам’ять](/uk/concepts/memory), [Контекст](/uk/concepts/context). - - Лише якщо ви використовуєте **OpenAI embeddings**. OAuth Codex покриває chat/completions і + + Лише якщо ви використовуєте **ембедінги OpenAI**. Codex OAuth покриває чат/completions і **не** надає доступу до embeddings, тож **вхід через Codex (OAuth або - вхід через Codex CLI)** не допомагає для семантичного пошуку в пам’яті. Для OpenAI embeddings - усе одно потрібен справжній API key (`OPENAI_API_KEY` або `models.providers.openai.apiKey`). + вхід через Codex CLI)** не допомагає для семантичного пошуку в пам’яті. Для ембедінгів OpenAI + все одно потрібен справжній API-ключ (`OPENAI_API_KEY` або `models.providers.openai.apiKey`). - Якщо ви явно не задаєте provider, OpenClaw автоматично вибирає provider, коли - може визначити API key (auth profiles, `models.providers.*.apiKey` або env vars). - Він надає перевагу OpenAI, якщо вдається визначити ключ OpenAI, інакше Gemini, якщо вдається визначити ключ Gemini, + Якщо ви явно не задаєте провайдера, OpenClaw автоматично вибирає провайдера, коли + може визначити API-ключ (профілі автентифікації, `models.providers.*.apiKey` або змінні середовища). + Він віддає перевагу OpenAI, якщо визначається ключ OpenAI, інакше Gemini, якщо визначається ключ Gemini, потім Voyage, потім Mistral. Якщо жоден віддалений ключ недоступний, пошук у пам’яті - залишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштовано й наявний шлях до локальної моделі, OpenClaw - надає перевагу `local`. Ollama підтримується, якщо ви явно задаєте + залишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштовано й наявний шлях + до локальної моделі, OpenClaw + віддає перевагу `local`. Ollama підтримується, коли ви явно задаєте `memorySearch.provider = "ollama"`. - Якщо ви хочете залишатися локально, задайте `memorySearch.provider = "local"` (і за потреби - `memorySearch.fallback = "none"`). Якщо вам потрібні Gemini embeddings, задайте + Якщо ви хочете залишатися локальними, задайте `memorySearch.provider = "local"` (і за бажанням + `memorySearch.fallback = "none"`). Якщо вам потрібні ембедінги Gemini, задайте `memorySearch.provider = "gemini"` і надайте `GEMINI_API_KEY` (або - `memorySearch.remote.apiKey`). Ми підтримуємо embedding-моделі **OpenAI, Gemini, Voyage, Mistral, Ollama або local** — - див. [Пам’ять](/uk/concepts/memory) для деталей налаштування. + `memorySearch.remote.apiKey`). Ми підтримуємо моделі ембедінгів **OpenAI, Gemini, Voyage, Mistral, Ollama або local** — + подробиці налаштування див. у [Пам’ять](/uk/concepts/memory). @@ -1380,49 +1381,49 @@ x-i18n: Ні — **стан OpenClaw локальний**, але **зовнішні сервіси все одно бачать те, що ви їм надсилаєте**. - - **Локально за замовчуванням:** sessions, файли пам’яті, config і workspace зберігаються на хості Gateway + - **Локально за замовчуванням:** сесії, файли пам’яті, конфігурація та workspace живуть на хості Gateway (`~/.openclaw` + каталог вашого workspace). - - **Віддалено за необхідністю:** повідомлення, які ви надсилаєте провайдерам моделей (Anthropic/OpenAI тощо), надходять до - їхніх API, а chat platforms (WhatsApp/Telegram/Slack тощо) зберігають дані повідомлень на + - **Віддалено за потребою:** повідомлення, які ви надсилаєте провайдерам моделей (Anthropic/OpenAI тощо), потрапляють до + їхніх API, а чат-платформи (WhatsApp/Telegram/Slack тощо) зберігають дані повідомлень на своїх серверах. - - **Ви контролюєте масштаб:** використання локальних моделей залишає prompts на вашій машині, але трафік - channel усе одно проходить через сервери відповідного каналу. + - **Ви контролюєте слід:** використання локальних моделей залишає prompt-и на вашій машині, але трафік + каналів усе одно проходить через сервери відповідного каналу. - Пов’язане: [Workspace agent](/uk/concepts/agent-workspace), [Пам’ять](/uk/concepts/memory). + Пов’язане: [Workspace агента](/uk/concepts/agent-workspace), [Пам’ять](/uk/concepts/memory). Усе зберігається в `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`): - | Path | Призначення | - | --------------------------------------------------------------- | ----------------------------------------------------------------- | - | `$OPENCLAW_STATE_DIR/openclaw.json` | Основний config (JSON5) | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Legacy OAuth import (копіюється в auth profiles під час першого використання) | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles (OAuth, API keys і необов’язкові `keyRef`/`tokenRef`) | - | `$OPENCLAW_STATE_DIR/secrets.json` | Необов’язкове файлове корисне навантаження secret для провайдерів `file` SecretRef | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Legacy compatibility file (статичні записи `api_key` очищаються) | - | `$OPENCLAW_STATE_DIR/credentials/` | Стан provider (наприклад, `whatsapp//creds.json`) | - | `$OPENCLAW_STATE_DIR/agents/` | Стан для кожного agent (agentDir + sessions) | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | History та стан розмов (для кожного agent) | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані sessions (для кожного agent) | + | Шлях | Призначення | + | --------------------------------------------------------------- | ------------------------------------------------------------------ | + | `$OPENCLAW_STATE_DIR/openclaw.json` | Основна конфігурація (JSON5) | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Імпорт застарілого OAuth (копіюється в профілі автентифікації під час першого використання) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Профілі автентифікації (OAuth, API-ключі та необов’язкові `keyRef`/`tokenRef`) | + | `$OPENCLAW_STATE_DIR/secrets.json` | Необов’язкове файлове секретне корисне навантаження для провайдерів `file` SecretRef | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Файл застарілої сумісності (статичні записи `api_key` очищено) | + | `$OPENCLAW_STATE_DIR/credentials/` | Стан провайдера (наприклад, `whatsapp//creds.json`) | + | `$OPENCLAW_STATE_DIR/agents/` | Стан для кожного агента окремо (agentDir + сесії) | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | Історія розмов і стан (для кожного агента) | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані сесій (для кожного агента) | - Шлях legacy single-agent: `~/.openclaw/agent/*` (мігрується командою `openclaw doctor`). + Застарілий шлях для одного агента: `~/.openclaw/agent/*` (мігрується командою `openclaw doctor`). - Ваш **workspace** (`AGENTS.md`, файли пам’яті, Skills тощо) зберігається окремо та налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). + Ваш **workspace** (`AGENTS.md`, файли пам’яті, Skills тощо) зберігається окремо й налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). - Ці файли зберігаються у **workspace agent**, а не в `~/.openclaw`. + Ці файли мають зберігатися в **workspace агента**, а не в `~/.openclaw`. - - **Workspace (для кожного agent):** `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, - `MEMORY.md` (або legacy fallback `memory.md`, коли `MEMORY.md` відсутній), + - **Workspace (для кожного агента):** `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, + `MEMORY.md` (або застарілий резервний варіант `memory.md`, якщо `MEMORY.md` відсутній), `memory/YYYY-MM-DD.md`, необов’язковий `HEARTBEAT.md`. - - **Каталог state (`~/.openclaw`)**: config, стан channel/provider, auth profiles, sessions, журнали + - **Каталог state (`~/.openclaw`)**: конфігурація, стан channel/provider, профілі автентифікації, сесії, журнали, і спільні Skills (`~/.openclaw/skills`). - Типовий workspace: `~/.openclaw/workspace`, налаштовується через: + Workspace за замовчуванням — `~/.openclaw/workspace`, налаштовується через: ```json5 { @@ -1431,26 +1432,26 @@ x-i18n: ``` Якщо бот "забуває" після перезапуску, переконайтеся, що Gateway використовує той самий - workspace під час кожного запуску (і пам’ятайте: remote mode використовує **workspace хоста gateway**, + workspace під час кожного запуску (і пам’ятайте: віддалений режим використовує **workspace хоста gateway**, а не вашого локального ноутбука). - Порада: якщо ви хочете зберегти поведінку або вподобання надовго, попросіть бота **записати це в - AGENTS.md або MEMORY.md**, а не покладайтеся на history чату. + Порада: якщо ви хочете закріпити поведінку або вподобання, попросіть бота **записати це в + AGENTS.md або MEMORY.md**, а не покладайтеся на історію чату. - Див. [Workspace agent](/uk/concepts/agent-workspace) і [Пам’ять](/uk/concepts/memory). + Див. [Workspace агента](/uk/concepts/agent-workspace) і [Пам’ять](/uk/concepts/memory). - Розмістіть свій **workspace agent** у **приватному** git-репозиторії та робіть його резервні копії в - приватному місці (наприклад, GitHub private). Це охоплює memory + файли AGENTS/SOUL/USER - і дозволяє пізніше відновити "розум" assistant. + Помістіть свій **workspace агента** в **приватний** git-репозиторій і зберігайте його резервну копію десь + приватно (наприклад, у приватному GitHub). Це охоплює пам’ять + файли AGENTS/SOUL/USER + та дає змогу пізніше відновити "розум" асистента. - **Не** виконуйте commit для будь-чого з `~/.openclaw` (облікові дані, sessions, tokens або зашифровані payload secret). - Якщо вам потрібне повне відновлення, окремо робіть резервні копії і workspace, і каталогу state + **Не** робіть commit нічого з `~/.openclaw` (облікові дані, сесії, токени або зашифровані корисні навантаження секретів). + Якщо вам потрібне повне відновлення, окремо створіть резервні копії і workspace, і каталогу state (див. питання про міграцію вище). - Документація: [Workspace agent](/uk/concepts/agent-workspace). + Документація: [Workspace агента](/uk/concepts/agent-workspace). @@ -1458,16 +1459,16 @@ x-i18n: Див. окремий посібник: [Видалення](/uk/install/uninstall). - - Так. Workspace — це **типовий cwd** і якір пам’яті, а не жорстка sandbox. - Відносні шляхи розв’язуються в межах workspace, але абсолютні шляхи можуть отримувати доступ до інших - розташувань хоста, якщо sandboxing не ввімкнено. Якщо вам потрібна ізоляція, використовуйте - [`agents.defaults.sandbox`](/uk/gateway/sandboxing) або налаштування sandbox для окремого agent. Якщо ви - хочете, щоб репозиторій був типовим робочим каталогом, вкажіть `workspace` - цього agent на корінь репозиторію. Репозиторій OpenClaw — це лише вихідний код; тримайте - workspace окремо, якщо ви свідомо не хочете, щоб agent працював усередині нього. + + Так. Workspace — це **cwd за замовчуванням** і якір пам’яті, а не жорстка sandbox-ізоляція. + Відносні шляхи розв’язуються всередині workspace, але абсолютні шляхи можуть звертатися до інших + розташувань хоста, якщо sandbox не ввімкнено. Якщо вам потрібна ізоляція, використовуйте + [`agents.defaults.sandbox`](/uk/gateway/sandboxing) або налаштування sandbox для окремого агента. Якщо ви + хочете, щоб репозиторій був робочим каталогом за замовчуванням, вкажіть `workspace` + цього агента на корінь репозиторію. Репозиторій OpenClaw — це лише вихідний код; тримайте + workspace окремо, якщо тільки ви навмисно не хочете, щоб агент працював усередині нього. - Приклад (репозиторій як типовий cwd): + Приклад (репозиторій як cwd за замовчуванням): ```json5 { @@ -1481,30 +1482,30 @@ x-i18n: - - Стан sessions належить **хосту gateway**. Якщо ви використовуєте remote mode, потрібне вам сховище sessions розташоване на віддаленій машині, а не на вашому локальному ноутбуці. Див. [Керування сеансами](/uk/concepts/session). + + Станом сесій керує **хост gateway**. Якщо ви працюєте у віддаленому режимі, потрібне вам сховище сесій знаходиться на віддаленій машині, а не на вашому локальному ноутбуці. Див. [Керування сесіями](/uk/concepts/session). -## Основи config +## Основи конфігурації - - OpenClaw читає необов’язковий config **JSON5** з `$OPENCLAW_CONFIG_PATH` (типово: `~/.openclaw/openclaw.json`): + + OpenClaw читає необов’язкову конфігурацію **JSON5** з `$OPENCLAW_CONFIG_PATH` (типово: `~/.openclaw/openclaw.json`): ``` $OPENCLAW_CONFIG_PATH ``` - Якщо файл відсутній, використовуються досить безпечні значення за замовчуванням (зокрема типовий workspace `~/.openclaw/workspace`). + Якщо файл відсутній, використовуються досить безпечні значення за замовчуванням (зокрема workspace за замовчуванням `~/.openclaw/workspace`). - - Прив’язки не-loopback **потребують коректного шляху auth gateway**. На практиці це означає: + + Bind не-loopback **потребують дійсного шляху автентифікації gateway**. На практиці це означає: - - auth зі shared secret: token або password - - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим identity-aware reverse proxy не в режимі loopback + - автентифікація спільним секретом: токен або пароль + - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим identity-aware reverse proxy не-loopback ```json5 { @@ -1520,32 +1521,32 @@ x-i18n: Примітки: - - `gateway.remote.token` / `.password` самі по собі **не** вмикають auth локального gateway. + - `gateway.remote.token` / `.password` самі по собі **не** вмикають локальну автентифікацію gateway. - Локальні шляхи виклику можуть використовувати `gateway.remote.*` як fallback лише тоді, коли `gateway.auth.*` не задано. - - Для auth через password задайте `gateway.auth.mode: "password"` разом із `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). - - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і його не вдається визначити, визначення завершується fail closed (без маскування через remote fallback). - - Конфігурації Control UI зі shared secret проходять автентифікацію через `connect.params.auth.token` або `connect.params.auth.password` (зберігаються в налаштуваннях app/UI). Режими з передаванням ідентичності, як-от Tailscale Serve або `trusted-proxy`, натомість використовують заголовки запиту. Уникайте розміщення shared secrets в URL. - - З `gateway.auth.mode: "trusted-proxy"` reverse proxy loopback на тому ж хості все одно **не** задовольняють auth trusted-proxy. Trusted proxy має бути налаштованим джерелом не-loopback. + - Для автентифікації паролем замість цього задайте `gateway.auth.mode: "password"` разом із `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). + - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не вдається розв’язати, розв’язання завершується надійним блокуванням (без маскування віддаленим fallback). + - Конфігурації Control UI зі спільним секретом проходять автентифікацію через `connect.params.auth.token` або `connect.params.auth.password` (зберігаються в налаштуваннях застосунку/UI). Режими з передаванням ідентичності, як-от Tailscale Serve або `trusted-proxy`, натомість використовують заголовки запиту. Уникайте розміщення спільних секретів в URL. + - З `gateway.auth.mode: "trusted-proxy"` reverse proxy loopback на тому самому хості все одно **не** задовольняють автентифікацію trusted-proxy. Trusted proxy має бути налаштованим джерелом не-loopback. - - OpenClaw типово примусово застосовує auth gateway, зокрема для loopback. У звичайному типовому сценарії це означає auth через token: якщо не налаштовано явний шлях auth, під час запуску gateway використовується режим token і token генерується автоматично зі збереженням у `gateway.auth.token`, тому **локальні WS-клієнти мають проходити автентифікацію**. Це блокує іншим локальним процесам можливість викликати Gateway. + + OpenClaw примусово вмикає автентифікацію gateway за замовчуванням, зокрема для loopback. У звичайному типовому сценарії це означає автентифікацію токеном: якщо явний шлях автентифікації не налаштовано, під час запуску gateway використовується режим токена і він автоматично генерується, зберігаючись у `gateway.auth.token`, тож **локальні WS-клієнти мають проходити автентифікацію**. Це блокує інші локальні процеси від виклику Gateway. - Якщо ви надаєте перевагу іншому шляху auth, можна явно вибрати режим password (або, для non-loopback identity-aware reverse proxy, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно задайте `gateway.auth.mode: "none"` у своєму config. Doctor може будь-коли згенерувати token для вас: `openclaw doctor --generate-gateway-token`. + Якщо ви віддаєте перевагу іншому шляху автентифікації, ви можете явно вибрати режим пароля (або, для не-loopback identity-aware reverse proxy, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно задайте `gateway.auth.mode: "none"` у своїй конфігурації. Doctor може будь-коли згенерувати для вас токен: `openclaw doctor --generate-gateway-token`. - - Gateway відстежує config і підтримує hot-reload: + + Gateway відстежує конфігурацію і підтримує гаряче перезавантаження: - - `gateway.reload.mode: "hybrid"` (типово): безпечні зміни застосовуються гаряче, для критичних виконується перезапуск + - `gateway.reload.mode: "hybrid"` (типово): безпечно застосовує зміни без перезапуску, а для критичних виконує перезапуск - також підтримуються `hot`, `restart`, `off` - - Задайте `cli.banner.taglineMode` у config: + + Задайте `cli.banner.taglineMode` у конфігурації: ```json5 { @@ -1557,24 +1558,24 @@ x-i18n: } ``` - - `off`: приховує текст tagline, але залишає рядок назви/версії банера. + - `off`: приховує текст слогана, але залишає рядок заголовка/версії банера. - `default`: щоразу використовує `All your chats, one OpenClaw.`. - - `random`: ротація кумедних/сезонних tagline (типова поведінка). - - Якщо ви взагалі не хочете банер, задайте env `OPENCLAW_HIDE_BANNER=1`. + - `random`: змінні кумедні/сезонні слогани (типова поведінка). + - Якщо ви не хочете жодного банера взагалі, задайте змінну середовища `OPENCLAW_HIDE_BANNER=1`. - - `web_fetch` працює без API key. `web_search` залежить від вибраного - provider: + + `web_fetch` працює без API-ключа. `web_search` залежить від вибраного + провайдера: - - Провайдери на основі API, такі як Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, вимагають звичайного налаштування API key. - - Ollama Web Search не потребує key, але використовує налаштований вами хост Ollama і вимагає `ollama signin`. - - DuckDuckGo не потребує key, але це неофіційна інтеграція на основі HTML. - - SearXNG не потребує key / є self-hosted; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. + - Провайдери на основі API, такі як Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, потребують звичайного налаштування API-ключа. + - Ollama Web Search не потребує ключа, але використовує налаштований вами хост Ollama і вимагає `ollama signin`. + - DuckDuckGo не потребує ключа, але це неофіційна інтеграція на основі HTML. + - SearXNG не потребує ключа / може бути self-hosted; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. - **Рекомендовано:** виконайте `openclaw configure --section web` і виберіть provider. - Альтернативи через environment: + **Рекомендовано:** виконайте `openclaw configure --section web` і виберіть провайдера. + Альтернативи через змінні середовища: - Brave: `BRAVE_API_KEY` - Exa: `EXA_API_KEY` @@ -1609,66 +1610,66 @@ x-i18n: }, fetch: { enabled: true, - provider: "firecrawl", // optional; omit for auto-detect + provider: "firecrawl", // необов’язково; пропустіть для авто-визначення }, }, }, } ``` - Конфігурація web-search, специфічна для provider, тепер розміщується в `plugins.entries..config.webSearch.*`. - Legacy-шляхи provider у `tools.web.search.*` усе ще тимчасово завантажуються для сумісності, але їх не слід використовувати в нових config. - Конфігурація fallback для Firecrawl web-fetch розміщується в `plugins.entries.firecrawl.config.webFetch.*`. + Конфігурація вебпошуку, специфічна для провайдера, тепер розміщується в `plugins.entries..config.webSearch.*`. + Застарілі шляхи провайдера `tools.web.search.*` усе ще тимчасово завантажуються для сумісності, але їх не слід використовувати для нових конфігурацій. + Конфігурація запасного web-fetch Firecrawl розміщується в `plugins.entries.firecrawl.config.webFetch.*`. Примітки: - Якщо ви використовуєте allowlist, додайте `web_search`/`web_fetch`/`x_search` або `group:web`. - - `web_fetch` увімкнено за замовчуванням (якщо його не вимкнено явно). - - Якщо `tools.web.fetch.provider` не вказано, OpenClaw автоматично визначає перший готовий fallback provider для fetch із доступних облікових даних. Наразі вбудованим provider є Firecrawl. - - Daemon читають env vars з `~/.openclaw/.env` (або середовища сервісу). + - `web_fetch` увімкнено за замовчуванням (якщо його явно не вимкнено). + - Якщо `tools.web.fetch.provider` пропущено, OpenClaw автоматично визначає першого готового запасного провайдера fetch із доступних облікових даних. Наразі вбудований провайдер — Firecrawl. + - Демони читають змінні середовища з `~/.openclaw/.env` (або із середовища сервісу). - Документація: [Web tools](/uk/tools/web). + Документація: [Вебінструменти](/uk/tools/web). - - `config.apply` замінює **весь config**. Якщо ви надсилаєте частковий об’єкт, усе - інше видаляється. + + `config.apply` замінює **всю конфігурацію**. Якщо ви надсилаєте частковий об’єкт, усе + інше буде видалено. Відновлення: - Відновіть із резервної копії (git або скопійований `~/.openclaw/openclaw.json`). - - Якщо резервної копії немає, повторно виконайте `openclaw doctor` і заново налаштуйте channels/models. - - Якщо це було неочікувано, створіть bug report і додайте останній відомий config або будь-яку резервну копію. - - Локальний coding agent часто може відновити робочий config із журналів або history. + - Якщо резервної копії немає, повторно запустіть `openclaw doctor` і заново налаштуйте channels/models. + - Якщо це було неочікувано, створіть bug-звіт і додайте свою останню відому конфігурацію або будь-яку резервну копію. + - Локальний агент для кодування часто може відновити працездатну конфігурацію з журналів або історії. - Як уникнути: + Як уникнути цього: - - Для невеликих змін використовуйте `openclaw config set`. - - Для інтерактивного редагування використовуйте `openclaw configure`. - - Спочатку використовуйте `config.schema.lookup`, якщо не впевнені щодо точного шляху або форми поля; він повертає вузол неглибокої schema плюс підсумки безпосередніх дочірніх елементів для подальшого заглиблення. - - Для часткових редагувань через RPC використовуйте `config.patch`; залиште `config.apply` лише для повної заміни config. - - Якщо ви використовуєте доступний лише owner інструмент `gateway` із запуску agent, він усе одно відхилятиме записи в `tools.exec.ask` / `tools.exec.security` (включно з legacy-псевдонімами `tools.bash.*`, які нормалізуються до тих самих захищених шляхів exec). + - Використовуйте `openclaw config set` для невеликих змін. + - Використовуйте `openclaw configure` для інтерактивного редагування. + - Спершу використовуйте `config.schema.lookup`, коли ви не впевнені щодо точного шляху або форми поля; він повертає вузол поверхневої схеми та короткі підсумки безпосередніх дочірніх елементів для подальшого заглиблення. + - Використовуйте `config.patch` для часткових RPC-редагувань; залишайте `config.apply` лише для повної заміни конфігурації. + - Якщо ви використовуєте доступний лише власнику інструмент `gateway` із запуску агента, він усе одно відхиляє запис у `tools.exec.ask` / `tools.exec.security` (зокрема застарілі псевдоніми `tools.bash.*`, які нормалізуються до тих самих захищених шляхів exec). - Документація: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/uk/gateway/doctor). + Документація: [Конфігурація](/cli/config), [Налаштування](/cli/configure), [Doctor](/uk/gateway/doctor). - - Типовий шаблон — **один Gateway** (наприклад, Raspberry Pi) плюс **Nodes** і **agents**: + + Поширений шаблон — це **один Gateway** (наприклад, Raspberry Pi) плюс **nodes** і **agents**: - - **Gateway (центральний):** володіє channels (Signal/WhatsApp), routing і sessions. - - **Nodes (пристрої):** Mac/iOS/Android підключаються як периферійні пристрої й надають локальні інструменти (`system.run`, `canvas`, `camera`). - - **Agents (workers):** окремі мозки/workspaces для спеціальних ролей (наприклад, "Hetzner ops", "Personal data"). - - **Sub-agents:** запускають фонову роботу з main agent, коли вам потрібен паралелізм. - - **TUI:** підключається до Gateway і перемикає agents/sessions. + - **Gateway (центральний):** керує channels (Signal/WhatsApp), маршрутизацією та сесіями. + - **Nodes (пристрої):** Mac/iOS/Android підключаються як периферія та надають локальні інструменти (`system.run`, `canvas`, `camera`). + - **Agents (workers):** окремі мозки/workspace для спеціалізованих ролей (наприклад, "Hetzner ops", "Personal data"). + - **Sub-agents:** запускають фонову роботу з основного агента, коли вам потрібен паралелізм. + - **TUI:** підключається до Gateway і дає змогу перемикати agents/sessions. Документація: [Nodes](/uk/nodes), [Віддалений доступ](/uk/gateway/remote), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [TUI](/web/tui). - - Так. Це параметр config: + + Так. Це параметр конфігурації: ```json5 { @@ -1681,154 +1682,154 @@ x-i18n: } ``` - Типове значення — `false` (із графічним інтерфейсом). Режим headless з більшою ймовірністю активує перевірки anti-bot на деяких сайтах. Див. [Браузер](/uk/tools/browser). + Типове значення — `false` (з графічним інтерфейсом). Headless-режим з більшою ймовірністю викликає перевірки anti-bot на деяких сайтах. Див. [Browser](/uk/tools/browser). - У режимі headless використовується **той самий рушій Chromium** і він підходить для більшості сценаріїв автоматизації (форми, кліки, скрапінг, входи). Основні відмінності: + Headless використовує **той самий рушій Chromium** і працює для більшості сценаріїв автоматизації (форми, кліки, скрапінг, входи). Основні відмінності: - Немає видимого вікна браузера (використовуйте знімки екрана, якщо вам потрібна візуалізація). - - Деякі сайти суворіше ставляться до автоматизації в режимі headless (CAPTCHA, anti-bot). - Наприклад, X/Twitter часто блокує сеанси headless. + - Деякі сайти суворіше ставляться до автоматизації в headless-режимі (CAPTCHA, anti-bot). + Наприклад, X/Twitter часто блокує headless-сесії. - Задайте `browser.executablePath` для вашого бінарного файла Brave (або будь-якого браузера на основі Chromium) і перезапустіть Gateway. - Див. повні приклади config у [Браузер](/uk/tools/browser#use-brave-or-another-chromium-based-browser). + Установіть `browser.executablePath` на бінарний файл Brave (або будь-якого браузера на основі Chromium) і перезапустіть Gateway. + Повні приклади конфігурації див. у [Browser](/uk/tools/browser#use-brave-or-another-chromium-based-browser). -## Віддалені Gateway і Nodes +## Віддалені gateway і nodes - Повідомлення Telegram обробляються **gateway**. Gateway запускає agent і + Повідомлення Telegram обробляються **gateway**. Gateway запускає агента і лише потім викликає nodes через **Gateway WebSocket**, коли потрібен інструмент node: Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - Nodes не бачать вхідний трафік provider; вони отримують лише виклики RPC node. + Nodes не бачать вхідного трафіку провайдера; вони отримують лише виклики node RPC. - - Коротка відповідь: **підключіть ваш комп’ютер як Node**. Gateway працює в іншому місці, але може - викликати інструменти `node.*` (screen, camera, system) на вашій локальній машині через Gateway WebSocket. + + Коротка відповідь: **під’єднайте свій комп’ютер як node**. Gateway працює в іншому місці, але може + викликати інструменти `node.*` (екран, камера, система) на вашій локальній машині через Gateway WebSocket. Типове налаштування: - 1. Запустіть Gateway на завжди увімкненому хості (VPS/домашній сервер). - 2. Підключіть хост Gateway і ваш комп’ютер до однієї tailnet. - 3. Переконайтеся, що Gateway WS доступний (прив’язка tailnet або SSH tunnel). - 4. Локально відкрийте застосунок macOS і підключіться в режимі **Remote over SSH** (або безпосередньо через tailnet), - щоб він міг зареєструватися як Node. - 5. Схваліть Node на Gateway: + 1. Запустіть Gateway на хості, який завжди ввімкнено (VPS/домашній сервер). + 2. Додайте хост Gateway і свій комп’ютер до однієї tailnet. + 3. Переконайтеся, що Gateway WS доступний (bind tailnet або SSH-тунель). + 4. Відкрийте локально застосунок macOS і підключіться в режимі **Remote over SSH** (або безпосередньо через tailnet), + щоб він міг зареєструватися як node. + 5. Підтвердьте node на Gateway: ```bash openclaw devices list openclaw devices approve ``` - Окремий TCP bridge не потрібен; Nodes підключаються через Gateway WebSocket. + Окремий TCP-міст не потрібен; nodes підключаються через Gateway WebSocket. - Нагадування щодо безпеки: підключення Node macOS дозволяє `system.run` на цій машині. Підключайте - лише пристрої, яким ви довіряєте, і перегляньте [Безпека](/uk/gateway/security). + Нагадування щодо безпеки: під’єднання macOS node дозволяє `system.run` на цій машині. Підключайте + лише пристрої, яким довіряєте, і перегляньте [Безпека](/uk/gateway/security). - Документація: [Nodes](/uk/nodes), [Протокол Gateway](/uk/gateway/protocol), [Віддалений режим macOS](/uk/platforms/mac/remote), [Безпека](/uk/gateway/security). + Документація: [Nodes](/uk/nodes), [Протокол Gateway](/uk/gateway/protocol), [віддалений режим macOS](/uk/platforms/mac/remote), [Безпека](/uk/gateway/security). - + Перевірте базові речі: - - Gateway працює: `openclaw gateway status` + - Gateway запущено: `openclaw gateway status` - Стан Gateway: `openclaw status` - - Стан channel: `openclaw channels status` + - Стан channels: `openclaw channels status` - Потім перевірте auth і routing: + Потім перевірте автентифікацію й маршрутизацію: - Якщо ви використовуєте Tailscale Serve, переконайтеся, що `gateway.auth.allowTailscale` налаштовано правильно. - - Якщо ви підключаєтеся через SSH tunnel, підтвердьте, що локальний tunnel активний і вказує на правильний port. - - Переконайтеся, що ваші allowlist (DM або group) містять ваш обліковий запис. + - Якщо ви підключаєтеся через SSH-тунель, переконайтеся, що локальний тунель працює і вказує на правильний порт. + - Переконайтеся, що ваші allowlist (DM або група) містять ваш обліковий запис. Документація: [Tailscale](/uk/gateway/tailscale), [Віддалений доступ](/uk/gateway/remote), [Channels](/uk/channels). - - Так. Вбудованого bridge "bot-to-bot" немає, але це можна налаштувати кількома + + Так. Вбудованого мосту "бот-до-бота" немає, але це можна реалізувати кількома надійними способами: - **Найпростіше:** використовуйте звичайний chat channel, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). - Нехай Bot A надсилає повідомлення Bot B, а потім Bot B відповідає як завжди. + **Найпростіше:** використовуйте звичайний чат-канал, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). + Нехай Bot A надсилає повідомлення Bot B, а тоді Bot B відповідає як зазвичай. - **CLI bridge (загальний):** запустіть скрипт, який викликає інший Gateway через - `openclaw agent --message ... --deliver`, націлюючи його на чат, який слухає інший бот. - Якщо один бот працює на віддаленому VPS, спрямуйте ваш CLI на той віддалений Gateway + **Міст CLI (універсальний):** запустіть скрипт, який викликає інший Gateway через + `openclaw agent --message ... --deliver`, націливши його на чат, де інший бот + слухає. Якщо один бот працює на віддаленому VPS, спрямуйте свій CLI на цей віддалений Gateway через SSH/Tailscale (див. [Віддалений доступ](/uk/gateway/remote)). - Приклад шаблону (запускається з машини, яка може досягти цільового Gateway): + Приклад шаблону (запускається з машини, яка може дістатися до цільового Gateway): ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - Порада: додайте запобіжник, щоб два боти не зациклювалися нескінченно (відповідь лише на згадування, channel + Порада: додайте запобіжник, щоб два боти не зациклилися нескінченно (лише згадки, channel allowlist або правило "не відповідати на повідомлення ботів"). - Документація: [Віддалений доступ](/uk/gateway/remote), [CLI Agent](/cli/agent), [Надсилання Agent](/uk/tools/agent-send). + Документація: [Віддалений доступ](/uk/gateway/remote), [CLI агента](/cli/agent), [Надсилання агентом](/uk/tools/agent-send). - - Ні. Один Gateway може розміщувати кількох agents, кожен із власним workspace, типовими моделями - і routing. Це типовий сценарій, і він значно дешевший і простіший, ніж запускати - один VPS на agent. + + Ні. Один Gateway може розміщувати кількох агентів, кожен зі своїм workspace, моделями за замовчуванням + і маршрутизацією. Це стандартне налаштування, і воно значно дешевше та простіше, ніж запускати + один VPS на кожного агента. Використовуйте окремі VPS лише тоді, коли вам потрібна жорстка ізоляція (межі безпеки) або дуже - різні config, якими ви не хочете ділитися. В іншому разі тримайте один Gateway і - використовуйте кількох agents або sub-agents. + різні конфігурації, якими ви не хочете ділитися. В інших випадках достатньо одного Gateway і + кількох агентів або sub-agents. - - Так — Nodes є основним способом отримати доступ до вашого ноутбука з віддаленого Gateway, і вони - надають більше, ніж просто доступ до shell. Gateway працює на macOS/Linux (Windows через WSL2) і є - легким (достатньо невеликого VPS або пристрою рівня Raspberry Pi; 4 ГБ RAM більш ніж досить), тому типовим - варіантом є завжди увімкнений хост і ваш ноутбук як Node. + + Так — nodes є основним способом доступу до вашого ноутбука з віддаленого Gateway і вони + дають більше, ніж просто доступ до оболонки. Gateway працює на macOS/Linux (Windows через WSL2) і є + легким (достатньо невеликого VPS або пристрою класу Raspberry Pi; 4 GB RAM більш ніж достатньо), тому поширене + налаштування — це хост, що завжди ввімкнений, плюс ваш ноутбук як node. - - **Не потрібен вхідний SSH.** Nodes самі підключаються до Gateway WebSocket і використовують pairing пристроїв. - - **Безпечніший контроль виконання.** `system.run` контролюється allowlist/schvalеннями Node на цьому ноутбуці. + - **Вхідний SSH не потрібен.** Nodes самі підключаються до Gateway WebSocket і використовують сполучення пристроїв. + - **Безпечніший контроль виконання.** `system.run` обмежується allowlist/погодженнями node на цьому ноутбуці. - **Більше інструментів пристрою.** Nodes надають `canvas`, `camera` і `screen` на додачу до `system.run`. - - **Локальна автоматизація браузера.** Тримайте Gateway на VPS, але запускайте Chrome локально через хост Node на ноутбуці або підключайтеся до локального Chrome на хості через Chrome MCP. + - **Локальна автоматизація браузера.** Тримайте Gateway на VPS, але запускайте Chrome локально через host node на ноутбуці, або підключайтеся до локального Chrome на хості через Chrome MCP. - SSH підходить для епізодичного доступу до shell, але Nodes простіші для постійних робочих процесів agent і + SSH підходить для разового доступу до оболонки, але nodes простіші для постійних робочих процесів агентів і автоматизації пристроїв. - Документація: [Nodes](/uk/nodes), [CLI Nodes](/cli/nodes), [Браузер](/uk/tools/browser). + Документація: [Nodes](/uk/nodes), [CLI Nodes](/cli/nodes), [Browser](/uk/tools/browser). - - Ні. На хості має працювати лише **один gateway**, якщо тільки ви навмисно не запускаєте ізольовані профілі (див. [Кілька gateway](/uk/gateway/multiple-gateways)). Nodes — це периферійні компоненти, які підключаються - до gateway (Nodes iOS/Android або режим macOS "node mode" у застосунку menubar). Для headless-хостів node - і керування через CLI див. [CLI Node host](/cli/node). + + Ні. На одному хості має працювати лише **один gateway**, якщо тільки ви навмисно не запускаєте ізольовані профілі (див. [Кілька gateway](/uk/gateway/multiple-gateways)). Nodes — це периферійні елементи, які підключаються + до gateway (nodes iOS/Android або macOS у "режимі node" в застосунку рядка меню). Для headless + host nodes і керування через CLI див. [CLI host node](/cli/node). Повний перезапуск потрібен для змін `gateway`, `discovery` і `canvasHost`. - + Так. - - `config.schema.lookup`: перевірити одне піддерево config із його неглибоким вузлом schema, відповідною підказкою UI та зведеннями безпосередніх дочірніх елементів перед записом - - `config.get`: отримати поточний snapshot + hash - - `config.patch`: безпечне часткове оновлення (кращий варіант для більшості редагувань через RPC); виконує hot-reload, коли це можливо, і перезапускає, коли потрібно - - `config.apply`: перевіряє й замінює весь config; виконує hot-reload, коли це можливо, і перезапускає, коли потрібно - - Інструмент runtime `gateway`, доступний лише owner, як і раніше відмовляється переписувати `tools.exec.ask` / `tools.exec.security`; legacy-аліаси `tools.bash.*` нормалізуються до тих самих захищених шляхів exec + - `config.schema.lookup`: перевірити одне піддерево конфігурації з його поверхневим вузлом схеми, відповідною UI-підказкою та короткими підсумками безпосередніх дочірніх елементів перед записом + - `config.get`: отримати поточний знімок + хеш + - `config.patch`: безпечне часткове оновлення (бажаний варіант для більшості RPC-редагувань); виконує гаряче перезавантаження, коли це можливо, і перезапуск, коли це потрібно + - `config.apply`: перевірити й замінити всю конфігурацію; виконує гаряче перезавантаження, коли це можливо, і перезапуск, коли це потрібно + - Інструмент runtime `gateway`, доступний лише власнику, як і раніше, відмовляється переписувати `tools.exec.ask` / `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec - + ```json5 { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, @@ -1843,15 +1844,15 @@ x-i18n: Мінімальні кроки: - 1. **Встановіть і виконайте вхід на VPS** + 1. **Установіть і виконайте вхід на VPS** ```bash curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up ``` - 2. **Встановіть і виконайте вхід на Mac** - - Використайте застосунок Tailscale і увійдіть у ту саму tailnet. + 2. **Установіть і виконайте вхід на Mac** + - Використайте застосунок Tailscale і ввійдіть у ту саму tailnet. 3. **Увімкніть MagicDNS (рекомендовано)** - У консолі адміністратора Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім’я. 4. **Використовуйте ім’я хоста tailnet** @@ -1864,53 +1865,53 @@ x-i18n: openclaw gateway --tailscale serve ``` - Це залишає gateway прив’язаним до loopback і надає HTTPS через Tailscale. Див. [Tailscale](/uk/gateway/tailscale). + Це залишає gateway прив’язаним до loopback і відкриває HTTPS через Tailscale. Див. [Tailscale](/uk/gateway/tailscale). - - Serve відкриває **Control UI + WS Gateway**. Nodes підключаються через той самий endpoint Gateway WS. + + Serve відкриває **Gateway Control UI + WS**. Nodes підключаються через той самий endpoint Gateway WS. Рекомендоване налаштування: 1. **Переконайтеся, що VPS і Mac перебувають в одній tailnet**. - 2. **Використовуйте застосунок macOS у remote mode** (SSH-ціллю може бути ім’я хоста tailnet). - Застосунок тунелюватиме порт Gateway і підключиться як Node. - 3. **Схваліть Node** на gateway: + 2. **Використовуйте застосунок macOS у віддаленому режимі** (ціллю SSH може бути ім’я хоста tailnet). + Застосунок протунелює порт Gateway і підключиться як node. + 3. **Підтвердьте node** на gateway: ```bash openclaw devices list openclaw devices approve ``` - Документація: [Протокол Gateway](/uk/gateway/protocol), [Discovery](/uk/gateway/discovery), [Віддалений режим macOS](/uk/platforms/mac/remote). + Документація: [Протокол Gateway](/uk/gateway/protocol), [Discovery](/uk/gateway/discovery), [віддалений режим macOS](/uk/platforms/mac/remote). - + Якщо вам потрібні лише **локальні інструменти** (screen/camera/exec) на другому ноутбуці, додайте його як - **Node**. Це дозволяє зберегти один Gateway і уникнути дублювання config. Локальні інструменти node + **node**. Це дозволяє зберегти єдиний Gateway і уникнути дублювання конфігурації. Локальні інструменти node наразі доступні лише на macOS, але ми плануємо поширити їх і на інші ОС. - Встановлюйте другий Gateway лише тоді, коли вам потрібна **жорстка ізоляція** або два повністю окремі боти. + Установлюйте другий Gateway лише тоді, коли вам потрібна **жорстка ізоляція** або два повністю окремі боти. Документація: [Nodes](/uk/nodes), [CLI Nodes](/cli/nodes), [Кілька gateway](/uk/gateway/multiple-gateways). -## Env vars і завантаження .env +## Змінні середовища та завантаження .env - - OpenClaw читає env vars із батьківського процесу (shell, launchd/systemd, CI тощо) і додатково завантажує: + + OpenClaw читає змінні середовища з батьківського процесу (оболонка, launchd/systemd, CI тощо) і додатково завантажує: - `.env` з поточного робочого каталогу - - глобальний fallback `.env` з `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`) + - глобальний резервний `.env` з `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`) - Жоден із файлів `.env` не перевизначає наявні env vars. + Жоден файл `.env` не перевизначає вже наявні змінні середовища. - Ви також можете визначати inline env vars у config (застосовуються, лише якщо їх немає в env процесу): + Ви також можете визначати вбудовані змінні середовища в конфігурації (застосовуються лише за відсутності в середовищі процесу): ```json5 { @@ -1921,15 +1922,15 @@ x-i18n: } ``` - Див. [/environment](/uk/help/environment) для повного порядку пріоритетів і джерел. + Повний порядок пріоритету й джерела див. у [/environment](/uk/help/environment). - + Є два поширені способи виправлення: - 1. Помістіть відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися, навіть коли сервіс не успадковує env вашого shell. - 2. Увімкніть імпорт із shell (необов’язкова зручність): + 1. Помістіть відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися, навіть коли сервіс не успадковує змінні середовища вашої оболонки. + 2. Увімкніть імпорт із оболонки (зручність із явним увімкненням): ```json5 { @@ -1942,52 +1943,52 @@ x-i18n: } ``` - Це запускає ваш login shell і імпортує лише відсутні очікувані ключі (ніколи не перевизначає наявні). Еквіваленти env vars: + Це запускає вашу login-оболонку й імпортує лише відсутні очікувані ключі (ніколи нічого не перевизначає). Еквіваленти змінних середовища: `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`. - `openclaw models status` показує, чи увімкнено **імпорт env із shell**. "Shell env: off" - **не** означає, що ваших env vars немає — це лише означає, що OpenClaw не буде - автоматично завантажувати ваш login shell. + `openclaw models status` показує, чи ввімкнено **імпорт змінних середовища з оболонки**. "Shell env: off" + **не** означає, що ваших змінних середовища немає — це лише означає, що OpenClaw не завантажуватиме + вашу login-оболонку автоматично. - Якщо Gateway працює як сервіс (launchd/systemd), він не успадковує env вашого shell. - Виправити це можна одним зі способів: + Якщо Gateway працює як сервіс (launchd/systemd), він не успадковує середовище + вашої оболонки. Виправте це одним зі способів: - 1. Помістіть token у `~/.openclaw/.env`: + 1. Помістіть токен у `~/.openclaw/.env`: ``` COPILOT_GITHUB_TOKEN=... ``` - 2. Або увімкніть імпорт із shell (`env.shellEnv.enabled: true`). - 3. Або додайте його до блоку `env` у config (застосовується лише за відсутності). + 2. Або ввімкніть імпорт із оболонки (`env.shellEnv.enabled: true`). + 3. Або додайте його до блоку `env` у конфігурації (застосовується лише за відсутності). - Потім перезапустіть gateway і знову перевірте: + Потім перезапустіть gateway і ще раз перевірте: ```bash openclaw models status ``` - Tokens Copilot читаються з `COPILOT_GITHUB_TOKEN` (також `GH_TOKEN` / `GITHUB_TOKEN`). + Токени Copilot читаються з `COPILOT_GITHUB_TOKEN` (а також `GH_TOKEN` / `GITHUB_TOKEN`). Див. [/concepts/model-providers](/uk/concepts/model-providers) і [/environment](/uk/help/environment). -## Sessions і кілька чатів +## Сесії та кілька чатів - Надішліть `/new` або `/reset` як окреме повідомлення. Див. [Керування сеансами](/uk/concepts/session). + Надішліть `/new` або `/reset` як окреме повідомлення. Див. [Керування сесіями](/uk/concepts/session). - - Sessions можуть завершуватися після `session.idleMinutes`, але це **вимкнено за замовчуванням** (типове значення **0**). - Задайте додатне значення, щоб увімкнути завершення через неактивність. Коли це ввімкнено, **наступне** - повідомлення після періоду неактивності починає новий session id для цього ключа чату. - Це не видаляє transcripts — просто починається новий session. + + Термін дії сесій може завершуватися після `session.idleMinutes`, але це **вимкнено за замовчуванням** (типове значення **0**). + Задайте додатне значення, щоб увімкнути завершення після простою. Коли цю функцію ввімкнено, **наступне** + повідомлення після періоду простою починає новий ідентифікатор сесії для цього ключа чату. + Це не видаляє транскрипти — лише починає нову сесію. ```json5 { @@ -1999,35 +2000,35 @@ x-i18n: - - Так, через **маршрутизацію multi-agent** і **sub-agents**. Ви можете створити одного координатора - agent і кількох worker agents із власними workspace і моделями. + + Так, через **маршрутизацію multi-agent** і **sub-agents**. Ви можете створити одного агента-координатора + і кількох агентів-worker зі своїми workspace і моделями. - Втім, це краще розглядати як **цікавий експеримент**. Це потребує багато токенів і часто - менш ефективно, ніж використання одного бота з окремими sessions. Типова модель, яку - ми бачимо, — це один бот, з яким ви спілкуєтеся, але з різними sessions для паралельної роботи. Цей - бот також може запускати sub-agents за потреби. + Водночас це краще розглядати як **цікавий експеримент**. Це витрачає багато токенів і часто + менш ефективно, ніж використання одного бота з окремими сесіями. Типова модель, яку ми + уявляємо, — це один бот, з яким ви спілкуєтеся, з різними сесіями для паралельної роботи. Цей + бот також може запускати sub-agents, коли потрібно. Документація: [Маршрутизація multi-agent](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [CLI Agents](/cli/agents). - - Context сеансу обмежений вікном моделі. Довгі чати, великі виводи інструментів або багато + + Контекст сесії обмежений вікном моделі. Довгі чати, великі виводи інструментів або багато файлів можуть спричинити Compaction або обрізання. Що допомагає: - Попросіть бота підсумувати поточний стан і записати його у файл. - - Використовуйте `/compact` перед довгими задачами, а `/new` — при зміні теми. - - Тримайте важливий context у workspace і просіть бота перечитувати його. - - Використовуйте sub-agents для довгої або паралельної роботи, щоб основний чат залишався меншим. - - Виберіть модель із більшим вікном context, якщо це трапляється часто. + - Використовуйте `/compact` перед довгими завданнями і `/new` під час зміни теми. + - Тримайте важливий контекст у workspace і просіть бота перечитувати його. + - Використовуйте sub-agents для довгих або паралельних завдань, щоб основний чат залишався меншим. + - Виберіть модель із більшим вікном контексту, якщо це трапляється часто. - Використайте команду reset: + Використовуйте команду скидання: ```bash openclaw reset @@ -2047,50 +2048,50 @@ x-i18n: Примітки: - - Онбординг також пропонує **Reset**, якщо бачить наявний config. Див. [Онбординг (CLI)](/uk/start/wizard). - - Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скиньте кожен каталог state (типові значення: `~/.openclaw-`). - - Dev reset: `openclaw gateway --dev --reset` (лише для dev; очищає config dev + credentials + sessions + workspace). + - Онбординг також пропонує **Reset**, якщо бачить наявну конфігурацію. Див. [Онбординг (CLI)](/uk/start/wizard). + - Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скиньте кожен каталог state (типово це `~/.openclaw-`). + - Скидання для dev: `openclaw gateway --dev --reset` (лише для dev; очищає конфігурацію dev + облікові дані + сесії + workspace). - - Використайте один із варіантів: + + Використайте один із цих варіантів: - - **Compact** (зберігає розмову, але підсумовує старіші ходи): + - **Compaction** (зберігає розмову, але підсумовує старіші ходи): ``` /compact ``` - або `/compact `, щоб спрямувати підсумок. + або `/compact `, щоб керувати підсумком. - - **Reset** (новий session ID для того самого ключа чату): + - **Скидання** (новий ідентифікатор сесії для того самого ключа чату): ``` /new /reset ``` - Якщо це трапляється й далі: + Якщо це відбувається й надалі: - - Увімкніть або налаштуйте **обрізання sessions** (`agents.defaults.contextPruning`), щоб скорочувати старий вивід інструментів. - - Використовуйте модель із більшим вікном context. + - Увімкніть або налаштуйте **обрізання сесії** (`agents.defaults.contextPruning`), щоб скорочувати старий вивід інструментів. + - Використовуйте модель із більшим вікном контексту. - Документація: [Compaction](/uk/concepts/compaction), [Обрізання sessions](/uk/concepts/session-pruning), [Керування сеансами](/uk/concepts/session). + Документація: [Compaction](/uk/concepts/compaction), [Обрізання сесії](/uk/concepts/session-pruning), [Керування сесіями](/uk/concepts/session). - Це помилка перевірки provider: модель видала блок `tool_use` без обов’язкового - `input`. Зазвичай це означає, що history сеансу застаріла або пошкоджена (часто після довгих threads - або зміни інструмента/schema). + Це помилка перевірки провайдера: модель видала блок `tool_use` без обов’язкового + `input`. Зазвичай це означає, що історія сесії застаріла або пошкоджена (часто після довгих thread + або зміни tool/schema). - Виправлення: почніть новий session за допомогою `/new` (окремим повідомленням). + Виправлення: почніть нову сесію за допомогою `/new` (окреме повідомлення). - - Heartbeat запускається кожні **30 хв** за замовчуванням (**1 год** при використанні OAuth auth). Налаштуйте або вимкніть це: + + Heartbeat виконується кожні **30m** за замовчуванням (**1h** при використанні OAuth-автентифікації). Налаштуйте або вимкніть це: ```json5 { @@ -2105,16 +2106,16 @@ x-i18n: ``` Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки та markdown-заголовки - на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб зберегти API calls. - Якщо файл відсутній, heartbeat усе одно запускається, і модель вирішує, що робити. + на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб заощадити виклики API. + Якщо файл відсутній, heartbeat усе одно виконується, і модель сама вирішує, що робити. - Overrides для окремого agent використовують `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). + Override для окремого агента використовують `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). - - Ні. OpenClaw працює з **вашого власного облікового запису**, тож якщо ви перебуваєте в групі, OpenClaw може її бачити. - За замовчуванням відповіді в групах блокуються, доки ви не дозволите відправників (`groupPolicy: "allowlist"`). + + Ні. OpenClaw працює від **вашого власного облікового запису**, тож якщо ви є в групі, OpenClaw може її бачити. + За замовчуванням відповіді в групі блокуються, доки ви не дозволите відправників (`groupPolicy: "allowlist"`). Якщо ви хочете, щоб запускати відповіді в групі могли лише **ви**: @@ -2132,7 +2133,7 @@ x-i18n: - Варіант 1 (найшвидший): дивіться хвіст журналів і надішліть тестове повідомлення в групу: + Варіант 1 (найшвидший): перегляньте журнали в реальному часі й надішліть тестове повідомлення в групу: ```bash openclaw logs --follow --json @@ -2141,7 +2142,7 @@ x-i18n: Знайдіть `chatId` (або `from`), що закінчується на `@g.us`, наприклад: `1234567890-1234567890@g.us`. - Варіант 2 (якщо вже налаштовано / внесено до allowlist): перелічіть групи з config: + Варіант 2 (якщо вже налаштовано/додано до allowlist): перелічіть групи з конфігурації: ```bash openclaw directory groups list --channel whatsapp @@ -2152,128 +2153,128 @@ x-i18n: - Є дві поширені причини: + Дві поширені причини: - - Увімкнено gating за згадуванням (типово). Ви маєте @згадати бота (або відповідати `mentionPatterns`). - - Ви налаштували `channels.whatsapp.groups` без `"*"`, і групу не внесено до allowlist. + - Увімкнено вимогу згадки (типово). Ви маєте @згадати бота (або збігтися з `mentionPatterns`). + - Ви налаштували `channels.whatsapp.groups` без `"*"`, і групу не додано до allowlist. - Див. [Групи](/uk/channels/groups) і [Повідомлення груп](/uk/channels/group-messages). + Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). - - Прямі чати типово зводяться до main session. Групи/channels мають власні ключі session, а теми Telegram / threads Discord — це окремі sessions. Див. [Групи](/uk/channels/groups) і [Повідомлення груп](/uk/channels/group-messages). + + Прямі чати за замовчуванням згортаються в основну сесію. Групи/channels мають власні ключі сесій, а теми Telegram / thread у Discord є окремими сесіями. Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). - + Жорстких обмежень немає. Десятки (навіть сотні) — це нормально, але звертайте увагу на: - - **Зростання дискового простору:** sessions + transcripts зберігаються в `~/.openclaw/agents//sessions/`. - - **Вартість токенів:** більше agents означає більше одночасного використання моделей. - - **Операційні витрати:** auth profiles, workspaces і channel routing для кожного agent. + - **Зростання диска:** сесії + транскрипти зберігаються в `~/.openclaw/agents//sessions/`. + - **Витрати токенів:** більше агентів означає більше одночасного використання моделей. + - **Операційні накладні витрати:** профілі автентифікації для кожного агента, workspace і маршрутизація каналів. Поради: - - Тримайте один **активний** workspace на agent (`agents.defaults.workspace`). - - Очищайте старі sessions (видаляйте записи JSONL або записи сховища), якщо диск розростається. - - Використовуйте `openclaw doctor`, щоб виявляти зайві workspaces і невідповідності профілів. + - Тримайте один **активний** workspace на агента (`agents.defaults.workspace`). + - Очищайте старі сесії (видаляйте JSONL або записи сховища), якщо диск розростається. + - Використовуйте `openclaw doctor`, щоб виявляти зайві workspace і невідповідності профілів. - Так. Використовуйте **маршрутизацію Multi-Agent**, щоб запускати кілька ізольованих agents і маршрутизувати вхідні повідомлення за - channel/account/peer. Slack підтримується як channel і може бути прив’язаний до конкретних agents. + Так. Використовуйте **Маршрутизацію Multi-Agent**, щоб запускати кількох ізольованих агентів і маршрутизувати вхідні повідомлення за + каналом/обліковим записом/peer. Slack підтримується як канал і може бути прив’язаний до конкретних агентів. - Доступ до браузера потужний, але це не "робити все, що може людина" — anti-bot, CAPTCHA і MFA - все ще можуть блокувати автоматизацію. Для найнадійнішого керування браузером використовуйте локальний Chrome MCP на хості - або CDP на машині, яка фактично запускає браузер. + Доступ до браузера потужний, але це не "зробити все, що може людина" — anti-bot, CAPTCHA і MFA + все ще можуть блокувати автоматизацію. Для найнадійнішого керування браузером використовуйте локальний Chrome MCP на хості, + або використовуйте CDP на машині, яка фактично запускає браузер. - Рекомендована схема налаштування: + Рекомендоване налаштування: - - Завжди увімкнений хост Gateway (VPS/Mac mini). - - Один agent на кожну роль (bindings). - - Канали Slack, прив’язані до цих agents. - - Локальний браузер через Chrome MCP або Node, коли потрібно. + - Хост Gateway, який завжди ввімкнений (VPS/Mac mini). + - Один агент на роль (bindings). + - Channel(s) Slack, прив’язані до цих агентів. + - Локальний браузер через Chrome MCP або node, коли потрібно. Документація: [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [Slack](/uk/channels/slack), - [Браузер](/uk/tools/browser), [Nodes](/uk/nodes). + [Browser](/uk/tools/browser), [Nodes](/uk/nodes). -## Моделі: значення за замовчуванням, вибір, псевдоніми, перемикання +## Моделі: типові значення, вибір, псевдоніми, перемикання - Модель за замовчуванням в OpenClaw — це те, що ви задаєте як: + Модель OpenClaw за замовчуванням — це те, що ви встановили як: ``` agents.defaults.model.primary ``` - На моделі посилаються як `provider/model` (приклад: `openai/gpt-5.4`). Якщо ви пропускаєте provider, OpenClaw спочатку намагається знайти псевдонім, потім — унікальний збіг налаштованого provider для цього точного model id, і лише після цього використовує налаштований provider за замовчуванням як застарілий шлях сумісності. Якщо цей provider більше не надає налаштовану модель за замовчуванням, OpenClaw перемикається на перший налаштований provider/model замість того, щоб показувати застаріле типове значення від видаленого provider. Вам усе одно слід **явно** задавати `provider/model`. + На моделі посилаються у форматі `provider/model` (наприклад: `openai/gpt-5.4`). Якщо ви пропускаєте провайдера, OpenClaw спочатку намагається знайти псевдонім, потім — унікальний збіг налаштованого провайдера для точного id моделі, і лише після цього повертається до налаштованого провайдера за замовчуванням як до застарілого шляху сумісності. Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw повертається до першого налаштованого провайдера/моделі замість того, щоб показувати застарілу модель за замовчуванням від видаленого провайдера. Вам все одно слід **явно** задавати `provider/model`. - **Рекомендоване значення за замовчуванням:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку provider. - **Для agents з інструментами або недовіреним input:** надавайте перевагу силі моделі над вартістю. - **Для звичайного/низькоризикового чату:** використовуйте дешевші резервні моделі та маршрутизуйте за роллю agent. + **Рекомендований варіант за замовчуванням:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів. + **Для агентів з увімкненими інструментами або агентів із недовіреним вводом:** ставте силу моделі вище за вартість. + **Для звичайного/низькоризикового чату:** використовуйте дешевші резервні моделі та маршрутизуйте за роллю агента. Для MiniMax є окрема документація: [MiniMax](/uk/providers/minimax) і [Локальні моделі](/uk/gateway/local-models). - Правило великого пальця: використовуйте **найкращу модель, яку можете собі дозволити** для високоризикових задач, і дешевшу - модель для звичайного чату або підсумків. Ви можете маршрутизувати моделі за agent і використовувати sub-agents для - паралелізації довгих задач (кожен sub-agent споживає токени). Див. [Моделі](/uk/concepts/models) і + Практичне правило: використовуйте **найкращу модель, яку можете собі дозволити** для важливих завдань, і дешевшу + модель для звичайного чату або підсумків. Ви можете маршрутизувати моделі для кожного агента й використовувати sub-agents для + паралелізації довгих завдань (кожен sub-agent споживає токени). Див. [Моделі](/uk/concepts/models) і [Sub-agents](/uk/tools/subagents). - Сильне попередження: слабші або надмірно квантизовані моделі більш вразливі до prompt - injection і небезпечної поведінки. Див. [Безпека](/uk/gateway/security). + Серйозне попередження: слабші/надмірно квантизовані моделі вразливіші до prompt injection + і небезпечної поведінки. Див. [Безпека](/uk/gateway/security). - Докладніше: [Моделі](/uk/concepts/models). + Більше контексту: [Моделі](/uk/concepts/models). - - Використовуйте **команди моделей** або редагуйте лише поля **model**. Уникайте повної заміни config. + + Використовуйте **команди моделей** або редагуйте лише поля **model**. Уникайте повної заміни конфігурації. Безпечні варіанти: - - `/model` у чаті (швидко, для окремого session) - - `openclaw models set ...` (оновлює лише config моделі) + - `/model` у чаті (швидко, для окремої сесії) + - `openclaw models set ...` (оновлює лише конфігурацію моделі) - `openclaw configure --section model` (інтерактивно) - редагуйте `agents.defaults.model` у `~/.openclaw/openclaw.json` - Уникайте `config.apply` із частковим об’єктом, якщо не маєте наміру замінити весь config. - Для редагувань через RPC спочатку перевіряйте через `config.schema.lookup` і надавайте перевагу `config.patch`. Payload lookup надає нормалізований шлях, документацію/обмеження неглибокої schema та зведення безпосередніх дочірніх елементів + Уникайте `config.apply` з частковим об’єктом, якщо тільки ви не хочете замінити всю конфігурацію. + Для RPC-редагувань спочатку перегляньте через `config.schema.lookup` і віддавайте перевагу `config.patch`. Корисне навантаження lookup дає вам нормалізований шлях, документацію/обмеження поверхневої схеми та короткі підсумки безпосередніх дочірніх елементів для часткових оновлень. - Якщо ви все ж перезаписали config, відновіть його з резервної копії або повторно виконайте `openclaw doctor` для відновлення. + Якщо ви все ж перезаписали конфігурацію, відновіть її з резервної копії або повторно запустіть `openclaw doctor` для виправлення. - Документація: [Моделі](/uk/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/uk/gateway/doctor). + Документація: [Моделі](/uk/concepts/models), [Налаштування](/cli/configure), [Конфігурація](/cli/config), [Doctor](/uk/gateway/doctor). - Так. Ollama — найпростіший шлях для локальних моделей. + Так. Ollama — найпростіший шлях до локальних моделей. Найшвидше налаштування: - 1. Встановіть Ollama з `https://ollama.com/download` + 1. Установіть Ollama з `https://ollama.com/download` 2. Завантажте локальну модель, наприклад `ollama pull gemma4` - 3. Якщо вам потрібні також хмарні моделі, виконайте `ollama signin` - 4. Виконайте `openclaw onboard` і виберіть `Ollama` + 3. Якщо ви також хочете хмарні моделі, виконайте `ollama signin` + 4. Запустіть `openclaw onboard` і виберіть `Ollama` 5. Виберіть `Local` або `Cloud + Local` Примітки: - - `Cloud + Local` надає вам хмарні моделі плюс ваші локальні моделі Ollama + - `Cloud + Local` дає вам хмарні моделі плюс ваші локальні моделі Ollama - хмарні моделі, такі як `kimi-k2.5:cloud`, не потребують локального завантаження - для ручного перемикання використовуйте `openclaw models list` і `openclaw models set ollama/` - Примітка щодо безпеки: менші або сильно квантизовані моделі більш вразливі до prompt + Примітка щодо безпеки: менші або сильно квантизовані моделі вразливіші до prompt injection. Ми наполегливо рекомендуємо **великі моделі** для будь-якого бота, який може використовувати інструменти. - Якщо ви все ж хочете маленькі моделі, увімкніть sandboxing і суворі allowlist інструментів. + Якщо ви все ж хочете малі моделі, увімкніть sandboxing і суворі allowlist інструментів. Документація: [Ollama](/uk/providers/ollama), [Локальні моделі](/uk/gateway/local-models), [Провайдери моделей](/uk/concepts/model-providers), [Безпека](/uk/gateway/security), @@ -2282,9 +2283,9 @@ x-i18n: - - Ці розгортання можуть відрізнятися й змінюватися з часом; фіксованої рекомендації щодо provider немає. - - Перевіряйте поточне налаштування runtime на кожному gateway за допомогою `openclaw models status`. - - Для чутливих до безпеки agents з інструментами використовуйте найсильнішу доступну модель останнього покоління. + - Ці розгортання можуть відрізнятися й змінюватися з часом; фіксованої рекомендації щодо провайдера немає. + - Перевіряйте поточні налаштування під час роботи на кожному gateway через `openclaw models status`. + - Для чутливих до безпеки агентів/агентів з увімкненими інструментами використовуйте найсильнішу модель останнього покоління з доступних. @@ -2300,27 +2301,27 @@ x-i18n: /model gemini-flash-lite ``` - Це вбудовані псевдоніми. Власні псевдоніми можна додавати через `agents.defaults.models`. + Це вбудовані псевдоніми. Користувацькі псевдоніми можна додати через `agents.defaults.models`. Ви можете переглянути доступні моделі за допомогою `/model`, `/model list` або `/model status`. - `/model` (і `/model list`) показує компактний нумерований вибір. Вибирайте за номером: + `/model` (і `/model list`) показує компактний нумерований вибір. Вибір за номером: ``` /model 3 ``` - Ви також можете примусово задати конкретний auth profile для provider (для session): + Ви також можете примусово задати конкретний профіль автентифікації для провайдера (для окремої сесії): ``` /model opus@anthropic:default /model opus@anthropic:work ``` - Порада: `/model status` показує, який agent активний, який файл `auth-profiles.json` використовується та який auth profile буде випробувано наступним. - Також він показує налаштований endpoint provider (`baseUrl`) і режим API (`api`), коли це доступно. + Порада: `/model status` показує, який агент активний, який файл `auth-profiles.json` використовується і який профіль автентифікації буде спробовано далі. + Він також показує налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), якщо вони доступні. - **Як зняти прив’язку profile, який я задав через @profile?** + **Як відкріпити профіль, який я задав через @profile?** Повторно виконайте `/model` **без** суфікса `@profile`: @@ -2329,27 +2330,27 @@ x-i18n: ``` Якщо ви хочете повернутися до значення за замовчуванням, виберіть його через `/model` (або надішліть `/model `). - Використовуйте `/model status`, щоб підтвердити, який auth profile активний. + Використовуйте `/model status`, щоб підтвердити, який профіль автентифікації активний. - - Так. Задайте одну модель як типову, а потім перемикайтеся за потреби: + + Так. Задайте одну як типову і перемикайтеся за потреби: - - **Швидке перемикання (для session):** `/model gpt-5.4` для щоденних задач, `/model openai-codex/gpt-5.4` для кодування через Codex OAuth. - - **Типова + перемикання:** задайте `agents.defaults.model.primary` як `openai/gpt-5.4`, а потім перемикайтеся на `openai-codex/gpt-5.4` для кодування (або навпаки). - - **Sub-agents:** маршрутизуйте задачі кодування до sub-agents з іншою типовою моделлю. + - **Швидке перемикання (для окремої сесії):** `/model gpt-5.4` для щоденних завдань, `/model openai-codex/gpt-5.4` для програмування через Codex OAuth. + - **Типова + перемикання:** задайте `agents.defaults.model.primary` як `openai/gpt-5.4`, а потім перемикайтеся на `openai-codex/gpt-5.4` для програмування (або навпаки). + - **Sub-agents:** маршрутизуйте завдання програмування до sub-agents з іншою типовою моделлю. - Див. [Моделі](/uk/concepts/models) і [Slash commands](/uk/tools/slash-commands). + Див. [Моделі](/uk/concepts/models) і [Slash-команди](/uk/tools/slash-commands). - Використовуйте або перемикач для session, або значення за замовчуванням у config: + Використовуйте або перемикач для сесії, або типове значення в конфігурації: - - **Для session:** надішліть `/fast on`, поки session використовує `openai/gpt-5.4` або `openai-codex/gpt-5.4`. - - **Типово для моделі:** задайте `agents.defaults.models["openai/gpt-5.4"].params.fastMode` як `true`. - - **Також для Codex OAuth:** якщо ви також використовуєте `openai-codex/gpt-5.4`, задайте той самий прапорець і там. + - **Для окремої сесії:** надішліть `/fast on`, поки сесія використовує `openai/gpt-5.4` або `openai-codex/gpt-5.4`. + - **Типове значення для моделі:** задайте `agents.defaults.models["openai/gpt-5.4"].params.fastMode` як `true`. + - **Також для Codex OAuth:** якщо ви також використовуєте `openai-codex/gpt-5.4`, задайте там той самий прапорець. Приклад: @@ -2374,40 +2375,40 @@ x-i18n: } ``` - Для OpenAI fast mode відповідає `service_tier = "priority"` у підтримуваних нативних запитах Responses. Перевизначення `/fast` для session мають вищий пріоритет за типові значення config. + Для OpenAI fast mode відповідає `service_tier = "priority"` у підтримуваних нативних запитах Responses. Параметри сесії `/fast` мають вищий пріоритет за типові значення конфігурації. - Див. [Thinking і fast mode](/uk/tools/thinking) та [OpenAI fast mode](/uk/providers/openai#openai-fast-mode). + Див. [Thinking і fast mode](/uk/tools/thinking) і [OpenAI fast mode](/uk/providers/openai#openai-fast-mode). Якщо задано `agents.defaults.models`, це стає **allowlist** для `/model` і будь-яких - перевизначень session. Вибір моделі, якої немає в цьому списку, повертає: + перевизначень сесії. Вибір моделі, якої немає в цьому списку, повертає: ``` Model "provider/model" is not allowed. Use /model to list available models. ``` Ця помилка повертається **замість** звичайної відповіді. Виправлення: додайте модель до - `agents.defaults.models`, приберіть allowlist або виберіть модель із `/model list`. + `agents.defaults.models`, видаліть allowlist або виберіть модель із `/model list`. - Це означає, що **provider не налаштовано** (не знайдено config provider MiniMax або auth - profile), тому модель неможливо визначити. + Це означає, що **провайдер не налаштований** (не знайдено конфігурацію провайдера MiniMax або профіль + автентифікації), тож модель не вдається визначити. Контрольний список для виправлення: - 1. Оновіться до актуального релізу OpenClaw (або запускайте з вихідного коду `main`), а потім перезапустіть gateway. - 2. Переконайтеся, що MiniMax налаштовано (майстер або JSON) або що auth MiniMax - існує в env/auth profiles, щоб можна було підставити відповідний provider + 1. Оновіться до поточного релізу OpenClaw (або запускайте з вихідного коду `main`), а потім перезапустіть gateway. + 2. Переконайтеся, що MiniMax налаштовано (майстер або JSON), або що автентифікація MiniMax + існує в env/профілях автентифікації, щоб можна було підключити відповідний провайдер (`MINIMAX_API_KEY` для `minimax`, `MINIMAX_OAUTH_TOKEN` або збережений OAuth MiniMax для `minimax-portal`). - 3. Використовуйте точний model id (з урахуванням регістру) для вашого шляху auth: + 3. Використовуйте точний id моделі (з урахуванням регістру) для вашого шляху автентифікації: `minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed` для налаштування - через API key, або `minimax-portal/MiniMax-M2.7` / - `minimax-portal/MiniMax-M2.7-highspeed` для налаштування через OAuth. + з API-ключем, або `minimax-portal/MiniMax-M2.7` / + `minimax-portal/MiniMax-M2.7-highspeed` для налаштування OAuth. 4. Виконайте: ```bash @@ -2420,11 +2421,11 @@ x-i18n: - - Так. Використовуйте **MiniMax як модель за замовчуванням** і перемикайте моделі **для session** за потреби. - Резервні моделі призначені для **помилок**, а не для "складних задач", тому використовуйте `/model` або окремого agent. + + Так. Використовуйте **MiniMax як типову** і перемикайте моделі **для окремої сесії** за потреби. + Резервні варіанти призначені для **помилок**, а не для "складних завдань", тому використовуйте `/model` або окремого агента. - **Варіант A: перемикання для session** + **Варіант A: перемикання для окремої сесії** ```json5 { @@ -2447,11 +2448,11 @@ x-i18n: /model gpt ``` - **Варіант B: окремі agents** + **Варіант B: окремі агенти** - - Agent A типово: MiniMax - - Agent B типово: OpenAI - - Маршрутизуйте за agent або використовуйте `/agent` для перемикання + - Типова модель агента A: MiniMax + - Типова модель агента B: OpenAI + - Маршрутизуйте за агентом або використовуйте `/agent` для перемикання Документація: [Моделі](/uk/concepts/models), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [MiniMax](/uk/providers/minimax), [OpenAI](/uk/providers/openai). @@ -2469,7 +2470,7 @@ x-i18n: - `gemini-flash` → `google/gemini-3-flash-preview` - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` - Якщо ви задасте власний псевдонім із такою самою назвою, ваше значення матиме пріоритет. + Якщо ви задасте власний псевдонім із такою самою назвою, використовуватиметься ваше значення. @@ -2491,11 +2492,11 @@ x-i18n: } ``` - Тоді `/model sonnet` (або `/`, коли підтримується) визначатиметься як цей model ID. + Тоді `/model sonnet` (або `/`, коли підтримується) розв’язується до цього ID моделі. - + OpenRouter (оплата за токени; багато моделей): ```json5 @@ -2524,12 +2525,12 @@ x-i18n: } ``` - Якщо ви посилаєтеся на provider/model, але потрібний ключ provider відсутній, ви отримаєте помилку auth під час виконання (наприклад, `No API key found for provider "zai"`). + Якщо ви посилаєтеся на `provider/model`, але потрібний ключ провайдера відсутній, ви отримаєте помилку автентифікації під час роботи (наприклад, `No API key found for provider "zai"`). - **No API key found for provider після додавання нового agent** + **No API key found for provider після додавання нового агента** - Зазвичай це означає, що **новий agent** має порожнє сховище auth. Auth є окремим для кожного agent і - зберігається тут: + Зазвичай це означає, що в **нового агента** порожнє сховище автентифікації. Автентифікація прив’язана до агента і + зберігається в: ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2537,10 +2538,10 @@ x-i18n: Варіанти виправлення: - - Виконайте `openclaw agents add ` і налаштуйте auth у майстрі. - - Або скопіюйте `auth-profiles.json` з `agentDir` основного agent у `agentDir` нового agent. + - Виконайте `openclaw agents add ` і налаштуйте автентифікацію під час роботи майстра. + - Або скопіюйте `auth-profiles.json` з `agentDir` основного агента в `agentDir` нового агента. - **Не** використовуйте спільний `agentDir` для кількох agents; це призводить до колізій auth/session. + **Не** використовуйте спільний `agentDir` для кількох агентів; це спричиняє конфлікти автентифікації/сесій. @@ -2551,105 +2552,106 @@ x-i18n: Резервне перемикання відбувається у два етапи: - 1. **Ротація auth profile** в межах того самого provider. - 2. **Резервне перемикання моделі** на наступну модель із `agents.defaults.model.fallbacks`. + 1. **Ротація профілів автентифікації** в межах одного провайдера. + 2. **Резервний перехід між моделями** до наступної моделі в `agents.defaults.model.fallbacks`. - До профілів, що дають збій, застосовуються cooldown (експоненційний backoff), тож OpenClaw може й далі відповідати, навіть коли provider обмежений rate limit або тимчасово не працює. + До профілів, які дають збій, застосовуються періоди очікування (експоненційний backoff), тож OpenClaw може продовжувати відповідати, навіть коли провайдер обмежений rate limit або тимчасово недоступний. - Кошик rate limit включає не лише звичайні відповіді `429`. OpenClaw - також вважає вартими резервного перемикання rate limit такі повідомлення, як `Too many concurrent requests`, + Кошик rate limit містить не лише звичайні відповіді `429`. OpenClaw + також розглядає такі повідомлення, як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `resource exhausted` і періодичні - обмеження вікон використання (`weekly/monthly limit reached`). + обмеження вікна використання (`weekly/monthly limit reached`) як + ліміти, гідні резервного перемикання. - Деякі відповіді, схожі на billing, не мають коду `402`, а деякі відповіді HTTP `402` - також залишаються в цьому тимчасовому кошику. Якщо provider повертає - явний текст billing у `401` або `403`, OpenClaw усе одно може залишити це в - лінії billing, але зіставлення текстів, специфічних для provider, залишаються обмеженими - provider, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Якщо повідомлення `402` - натомість виглядає як таке, що можна повторити для вікна використання або - ліміту витрат organization/workspace (`daily limit reached, resets tomorrow`, + Деякі відповіді, схожі на billing, мають не `402`, а деякі відповіді HTTP `402` + також лишаються в цьому тимчасовому кошику. Якщо провайдер повертає + явний billing-текст у `401` або `403`, OpenClaw все одно може залишити це в + категорії billing, але текстові зіставлення, специфічні для провайдера, залишаються в межах + провайдера, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Якщо ж повідомлення `402` + натомість схоже на вікно використання з повторною спробою або + ліміт витрат organization/workspace (`daily limit reached, resets tomorrow`, `organization spending limit exceeded`), OpenClaw трактує це як - `rate_limit`, а не як тривале вимкнення через billing. + `rate_limit`, а не як тривале блокування через billing. - Помилки переповнення context відрізняються: сигнатури на кшталт + Помилки переповнення контексту — це інше: сигнатури на кшталт `request_too_large`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model` або `ollama error: context length - exceeded` залишаються на шляху Compaction/повторної спроби замість переходу до - резервного перемикання моделі. + exceeded` лишаються на шляху Compaction/повторної спроби замість переходу до + резервної моделі. - Загальний текст server error навмисно вужчий, ніж "усе, що містить - unknown/error". OpenClaw дійсно трактує тимчасові форми, обмежені provider, - такі як просте Anthropic `An unknown error occurred`, просте OpenRouter + Загальний текст серверної помилки навмисно вужчий за "все, що містить + unknown/error". OpenClaw дійсно трактує тимчасові форми, обмежені контекстом провайдера, + такі як порожнє Anthropic `An unknown error occurred`, порожнє OpenRouter `Provider returned error`, помилки причини зупинки на кшталт `Unhandled stop reason: - error`, JSON-payload `api_error` із тимчасовим текстом server error + error`, JSON-корисні навантаження `api_error` із тимчасовим серверним текстом (`internal server error`, `unknown error, 520`, `upstream error`, `backend - error`) і помилки зайнятості provider, такі як `ModelNotReadyException`, як - сигнали timeout/overloaded, варті резервного перемикання, коли контекст provider - збігається. + error`) і помилки зайнятості провайдера на кшталт `ModelNotReadyException` як + сигнали тайм-ауту/перевантаження, гідні резервного перемикання, коли контекст + провайдера збігається. Загальний внутрішній fallback-текст на кшталт `LLM request failed with an unknown - error.` залишається консервативним і сам по собі не запускає резервне перемикання моделі. + error.` лишається консервативним і сам по собі не запускає резервне перемикання моделі. - Це означає, що система спробувала використати ID auth profile `anthropic:default`, але не змогла знайти для нього облікові дані в очікуваному сховищі auth. + Це означає, що система спробувала використати ID профілю автентифікації `anthropic:default`, але не змогла знайти для нього облікові дані в очікуваному сховищі автентифікації. **Контрольний список для виправлення:** - - **Підтвердьте, де зберігаються auth profiles** (нові та legacy-шляхи) - - Поточний шлях: `~/.openclaw/agents//agent/auth-profiles.json` - - Legacy: `~/.openclaw/agent/*` (мігрується командою `openclaw doctor`) - - **Підтвердьте, що Gateway завантажує вашу env var** - - Якщо ви задали `ANTHROPIC_API_KEY` у своєму shell, але запускаєте Gateway через systemd/launchd, він може її не успадкувати. Помістіть її в `~/.openclaw/.env` або ввімкніть `env.shellEnv`. - - **Переконайтеся, що ви редагуєте правильного agent** - - У конфігураціях multi-agent може бути кілька файлів `auth-profiles.json`. - - **Перевірте стан model/auth** - - Використовуйте `openclaw models status`, щоб побачити налаштовані моделі та чи автентифіковано providers. + - **Підтвердьте, де зберігаються профілі автентифікації** (нові чи застарілі шляхи) + - Поточний: `~/.openclaw/agents//agent/auth-profiles.json` + - Застарілий: `~/.openclaw/agent/*` (мігрується командою `openclaw doctor`) + - **Переконайтеся, що Gateway завантажує вашу змінну середовища** + - Якщо ви задали `ANTHROPIC_API_KEY` у своїй оболонці, але запускаєте Gateway через systemd/launchd, він може її не успадковувати. Помістіть її в `~/.openclaw/.env` або ввімкніть `env.shellEnv`. + - **Переконайтеся, що ви редагуєте правильного агента** + - У налаштуваннях multi-agent може бути кілька файлів `auth-profiles.json`. + - **Виконайте базову перевірку стану моделі/автентифікації** + - Використовуйте `openclaw models status`, щоб побачити налаштовані моделі та те, чи пройшли провайдери автентифікацію. **Контрольний список для виправлення "No credentials found for profile anthropic"** - Це означає, що виконання прив’язане до auth profile Anthropic, але Gateway - не може знайти його у своєму сховищі auth. + Це означає, що запуск закріплено за профілем автентифікації Anthropic, але Gateway + не може знайти його у своєму сховищі автентифікації. - **Використовуйте Claude CLI** - Виконайте `openclaw models auth login --provider anthropic --method cli --set-default` на хості gateway. - - **Якщо ви хочете натомість використовувати API key** + - **Якщо ви натомість хочете використовувати API-ключ** - Помістіть `ANTHROPIC_API_KEY` у `~/.openclaw/.env` на **хості gateway**. - - Очистьте будь-який закріплений порядок, який примусово вимагає відсутній profile: + - Очистьте будь-який закріплений порядок, який примушує використовувати відсутній профіль: ```bash openclaw models auth order clear --provider anthropic ``` - - **Підтвердьте, що ви запускаєте команди на хості gateway** - - У remote mode auth profiles зберігаються на машині gateway, а не на вашому ноутбуці. + - **Переконайтеся, що ви виконуєте команди на хості gateway** + - У віддаленому режимі профілі автентифікації зберігаються на машині gateway, а не на вашому ноутбуці. - - Якщо ваш config моделі містить Google Gemini як резервний варіант (або ви перемкнулися на скорочення Gemini), OpenClaw спробує його під час резервного перемикання моделі. Якщо ви не налаштували облікові дані Google, ви побачите `No API key found for provider "google"`. + + Якщо у вашій конфігурації моделі Google Gemini вказано як резервний варіант (або ви перемкнулися на скорочення Gemini), OpenClaw спробує його під час резервного перемикання моделі. Якщо ви не налаштували облікові дані Google, побачите `No API key found for provider "google"`. - Виправлення: або надайте auth Google, або приберіть / не використовуйте моделі Google у `agents.defaults.model.fallbacks` / псевдонімах, щоб резервне перемикання не вело туди. + Виправлення: або надайте автентифікацію Google, або видаліть/не використовуйте моделі Google у `agents.defaults.model.fallbacks` / псевдонімах, щоб резервне перемикання не маршрутизувалося туди. **LLM request rejected: thinking signature required (Google Antigravity)** - Причина: history сеансу містить **блоки thinking без сигнатур** (часто через - перерваний/частковий потік). Google Antigravity вимагає сигнатури для блоків thinking. + Причина: історія сесії містить **thinking-блоки без сигнатур** (часто через + перерваний/частковий потік). Google Antigravity вимагає сигнатури для thinking-блоків. - Виправлення: OpenClaw тепер прибирає непідписані блоки thinking для Google Antigravity Claude. Якщо це все ще з’являється, почніть **новий session** або задайте `/thinking off` для цього agent. + Виправлення: тепер OpenClaw видаляє thinking-блоки без сигнатур для Google Antigravity Claude. Якщо це все ще з’являється, почніть **нову сесію** або задайте `/thinking off` для цього агента. -## Auth profiles: що це таке і як ними керувати +## Профілі автентифікації: що це таке і як ними керувати -Пов’язане: [/concepts/oauth](/uk/concepts/oauth) (потоки OAuth, зберігання tokens, шаблони для кількох облікових записів) +Пов’язане: [/concepts/oauth](/uk/concepts/oauth) (потоки OAuth, зберігання токенів, шаблони для кількох облікових записів) - - Auth profile — це іменований запис облікових даних (OAuth або API key), прив’язаний до provider. Профілі зберігаються тут: + + Профіль автентифікації — це іменований запис облікових даних (OAuth або API-ключ), прив’язаний до провайдера. Профілі зберігаються в: ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2657,73 +2659,73 @@ x-i18n: - - OpenClaw використовує ID з префіксом provider, наприклад: + + OpenClaw використовує ID з префіксом провайдера, наприклад: - - `anthropic:default` (поширений варіант, коли немає email-ідентичності) + - `anthropic:default` (поширено, коли немає ідентичності email) - `anthropic:` для OAuth-ідентичностей - - власні ID, які ви вибираєте (наприклад, `anthropic:work`) + - користувацькі ID, які ви обираєте (наприклад, `anthropic:work`) - - Так. Config підтримує необов’язкові metadata для profiles і порядок для кожного provider (`auth.order.`). Це **не** зберігає secrets; це зіставляє ID з provider/mode і задає порядок ротації. + + Так. Конфігурація підтримує необов’язкові метадані для профілів і порядок для кожного провайдера (`auth.order.`). Це **не** зберігає секрети; це зіставляє ID з провайдером/режимом і задає порядок ротації. - OpenClaw може тимчасово пропустити profile, якщо він перебуває у короткому **cooldown** (rate limits/timeouts/auth failures) або в довшому стані **disabled** (billing/insufficient credits). Щоб перевірити це, виконайте `openclaw models status --json` і перегляньте `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`. + OpenClaw може тимчасово пропустити профіль, якщо він перебуває в короткому **періоді очікування** (rate limit/тайм-аути/збої автентифікації) або в довшому **вимкненому** стані (billing/недостатньо кредитів). Щоб перевірити це, виконайте `openclaw models status --json` і перевірте `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`. - Cooldown через rate limit можуть бути обмежені model. Profile, що перебуває в cooldown - для однієї моделі, усе ще може бути придатним для спорідненої моделі на тому самому provider, - тоді як вікна billing/disabled усе одно блокують увесь profile. + Періоди очікування через rate limit можуть бути обмежені моделлю. Профіль, який перебуває в очікуванні + для однієї моделі, усе ще може бути придатним для спорідненої моделі того самого провайдера, + тоді як billing/вимкнені вікна й далі блокують увесь профіль. - Ви також можете задати **override порядку для окремого agent** (зберігається в `auth-state.json` цього agent) через CLI: + Ви також можете задати **перевизначення порядку для окремого агента** (зберігається в `auth-state.json` цього агента) через CLI: ```bash - # За замовчуванням використовується налаштований типовий agent (можна опустити --agent) + # Типово використовує налаштованого агента за замовчуванням (опустіть --agent) openclaw models auth order get --provider anthropic - # Зафіксувати ротацію на одному profile (пробувати лише цей) + # Зафіксувати ротацію на одному профілі (пробувати лише його) openclaw models auth order set --provider anthropic anthropic:default - # Або задати явний порядок (резервне перемикання в межах provider) + # Або задати явний порядок (резервний порядок у межах провайдера) openclaw models auth order set --provider anthropic anthropic:work anthropic:default - # Очистити override (повернення до config auth.order / round-robin) + # Очистити перевизначення (повернутися до config auth.order / round-robin) openclaw models auth order clear --provider anthropic ``` - Щоб націлитися на конкретного agent: + Щоб націлитися на конкретного агента: ```bash openclaw models auth order set --provider anthropic --agent main anthropic:default ``` - Щоб перевірити, що насправді буде спробовано, використовуйте: + Щоб перевірити, що буде фактично спробовано, використовуйте: ```bash openclaw models status --probe ``` - Якщо збережений profile опущено в явному порядку, probe показує - `excluded_by_auth_order` для цього profile замість того, щоб непомітно пробувати його. + Якщо збережений профіль опущено з явного порядку, probe покаже + `excluded_by_auth_order` для цього профілю замість того, щоб мовчки пробувати його. - + OpenClaw підтримує обидва варіанти: - **OAuth** часто використовує доступ за підпискою (де це застосовно). - - **API keys** використовують оплату за токени. + - **API-ключі** використовують оплату за токени. - Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і API keys. + Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth та API-ключі. -## Gateway: порти, "already running" і remote mode +## Gateway: порти, "already running" і віддалений режим - - `gateway.port` керує єдиним мультиплексованим port для WebSocket + HTTP (Control UI, hooks тощо). + + `gateway.port` керує єдиним мультиплексованим портом для WebSocket + HTTP (Control UI, hooks тощо). Пріоритет: @@ -2734,18 +2736,18 @@ x-i18n: - Тому що "running" — це точка зору **supervisor** (launchd/systemd/schtasks). RPC probe — це фактичне підключення CLI до gateway WebSocket і виклик `status`. + Тому що "running" — це погляд **supervisor** (launchd/systemd/schtasks). Probe RPC — це фактичне підключення CLI до gateway WebSocket і виклик `status`. - Використовуйте `openclaw gateway status` і довіряйте таким рядкам: + Використовуйте `openclaw gateway status` і довіряйте цим рядкам: - `Probe target:` (URL, який probe фактично використав) - - `Listening:` (що насправді прив’язано до port) - - `Last gateway error:` (поширена першопричина, коли процес живий, але port не слухає) + - `Listening:` (що фактично прив’язано до порту) + - `Last gateway error:` (поширена першопричина, коли процес живий, але порт не слухає) - Ви редагуєте один файл config, а сервіс запускає інший (часто через невідповідність `--profile` / `OPENCLAW_STATE_DIR`). + Ви редагуєте один файл конфігурації, тоді як сервіс використовує інший (часто через невідповідність `--profile` / `OPENCLAW_STATE_DIR`). Виправлення: @@ -2753,19 +2755,19 @@ x-i18n: openclaw gateway install --force ``` - Запустіть це з тим самим `--profile` / environment, який має використовувати сервіс. + Запустіть це з тим самим `--profile` / середовищем, яке ви хочете використовувати для сервісу. - OpenClaw примусово застосовує runtime lock, негайно прив’язуючи прослуховувач WebSocket під час запуску (типово `ws://127.0.0.1:18789`). Якщо прив’язка завершується з `EADDRINUSE`, викидається `GatewayLockError`, що означає: вже слухає інший екземпляр. + OpenClaw примусово встановлює блокування під час роботи, одразу прив’язуючи listener WebSocket під час запуску (типово `ws://127.0.0.1:18789`). Якщо bind завершується помилкою `EADDRINUSE`, викидається `GatewayLockError`, що означає, що інший екземпляр уже слухає. - Виправлення: зупиніть інший екземпляр, звільніть port або запустіть через `openclaw gateway --port `. + Виправлення: зупиніть інший екземпляр, звільніть порт або запускайте з `openclaw gateway --port `. - - Задайте `gateway.mode: "remote"` і вкажіть віддалений URL WebSocket, за потреби з віддаленими обліковими даними shared secret: + + Задайте `gateway.mode: "remote"` і вкажіть віддалену URL-адресу WebSocket, за потреби разом із клієнтськими обліковими даними спільного секрету для віддаленого доступу: ```json5 { @@ -2782,90 +2784,90 @@ x-i18n: Примітки: - - `openclaw gateway` запускається лише тоді, коли `gateway.mode` має значення `local` (або якщо ви передаєте прапорець override). - - Застосунок macOS стежить за файлом config і живо перемикає режими, коли ці значення змінюються. - - `gateway.remote.token` / `.password` — це лише облікові дані remote на стороні клієнта; вони самі по собі не вмикають auth локального gateway. + - `openclaw gateway` запускається лише тоді, коли `gateway.mode` має значення `local` (або якщо ви передали прапорець перевизначення). + - Застосунок macOS відстежує файл конфігурації й перемикає режими в реальному часі, коли ці значення змінюються. + - `gateway.remote.token` / `.password` — це лише клієнтські облікові дані для віддаленого доступу; самі по собі вони не вмикають локальну автентифікацію gateway. - - Ваш шлях auth gateway і метод auth UI не збігаються. + + Шлях автентифікації вашого gateway і метод автентифікації UI не збігаються. Факти (з коду): - - Control UI зберігає token у `sessionStorage` для поточного сеансу вкладки браузера та вибраного URL gateway, тож оновлення тієї самої вкладки працюють без відновлення довготривалого збереження token у localStorage. - - За `AUTH_TOKEN_MISMATCH` довірені клієнти можуть виконати одну обмежену повторну спробу з кешованим token пристрою, коли gateway повертає підказки для повторної спроби (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). - - Ця повторна спроба з кешованим token тепер повторно використовує кешовані схвалені scopes, збережені разом із token пристрою. Виклики з явним `deviceToken` / явними `scopes` і надалі зберігають власний запитаний набір scope замість успадкування кешованих scopes. - - Поза цим шляхом повторної спроби пріоритет auth для connect такий: спочатку явний shared token/password, потім явний `deviceToken`, потім збережений token пристрою, потім bootstrap token. - - Перевірки scope bootstrap token мають префікси ролей. Вбудований allowlist bootstrap operator задовольняє лише запити operator; node або інші ролі, що не є operator, усе одно потребують scopes під власним префіксом ролі. + - Control UI зберігає токен у `sessionStorage` для поточної сесії вкладки браузера та вибраної URL-адреси gateway, тож оновлення в цій самій вкладці продовжують працювати без відновлення довготривалого зберігання токена в localStorage. + - За `AUTH_TOKEN_MISMATCH` довірені клієнти можуть виконати одну обмежену повторну спробу з кешованим токеном пристрою, коли gateway повертає підказки для повтору (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). + - Ця повторна спроба з кешованим токеном тепер повторно використовує кешовані схвалені scopes, збережені разом із токеном пристрою. Виклики з явними `deviceToken` / явними `scopes` і далі зберігають запитаний ними набір scopes замість успадкування кешованих scopes. + - Поза цим шляхом повторної спроби пріоритет автентифікації підключення такий: спочатку явний спільний токен/пароль, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap-токен. + - Перевірки scope bootstrap-токена мають префікс ролі. Вбудований allowlist bootstrap-оператора задовольняє лише запити оператора; node або інші ролі, що не є оператором, і далі потребують scopes під власним префіксом ролі. Виправлення: - - Найшвидше: `openclaw dashboard` (друкує + копіює URL dashboard, намагається відкрити; показує підказку SSH, якщо середовище headless). - - Якщо у вас ще немає token: `openclaw doctor --generate-gateway-token`. - - Якщо це remote, спочатку створіть tunnel: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. - - Режим shared secret: задайте `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` або `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, а потім вставте відповідний secret у налаштуваннях Control UI. - - Режим Tailscale Serve: переконайтеся, що `gateway.auth.allowTailscale` увімкнено і ви відкриваєте URL Serve, а не сирий loopback/tailnet URL, який обходить заголовки ідентичності Tailscale. - - Режим trusted-proxy: переконайтеся, що ви проходите через налаштований identity-aware proxy не в loopback, а не через loopback-proxy на тому самому хості чи сирий URL gateway. - - Якщо невідповідність зберігається після однієї повторної спроби, перевидайте/повторно схваліть token paired device: + - Найшвидше: `openclaw dashboard` (виводить і копіює URL-адресу dashboard, намагається відкрити; показує підказку SSH, якщо режим headless). + - Якщо у вас ще немає токена: `openclaw doctor --generate-gateway-token`. + - Якщо віддалено, спочатку підніміть тунель: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. + - Режим спільного секрету: задайте `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` або `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, а потім вставте відповідний секрет у налаштуваннях Control UI. + - Режим Tailscale Serve: переконайтеся, що `gateway.auth.allowTailscale` увімкнено і ви відкриваєте URL-адресу Serve, а не сирий loopback/tailnet URL, який обходить заголовки ідентичності Tailscale. + - Режим trusted-proxy: переконайтеся, що ви заходите через налаштований identity-aware proxy не-loopback, а не через proxy loopback на тому самому хості чи напряму через URL gateway. + - Якщо невідповідність зберігається після однієї повторної спроби, виконайте ротацію/повторне схвалення токена спареного пристрою: - `openclaw devices list` - `openclaw devices rotate --device --role operator` - - Якщо ця команда rotate каже, що дію відхилено, перевірте дві речі: - - paired-device sessions можуть перевидати лише **власний** пристрій, якщо тільки вони також не мають `operator.admin` - - явні значення `--scope` не можуть перевищувати поточні operator scopes виклику - - Усе ще не вдається? Виконайте `openclaw status --all` і дотримуйтесь [Усунення несправностей](/uk/gateway/troubleshooting). Деталі auth див. у [Dashboard](/web/dashboard). + - Якщо цей виклик ротації повідомляє, що його відхилено, перевірте дві речі: + - сесії спарених пристроїв можуть обертати лише **власний** пристрій, якщо тільки вони також не мають `operator.admin` + - явні значення `--scope` не можуть перевищувати поточні scopes оператора викликача + - Усе ще застрягли? Виконайте `openclaw status --all` і дотримуйтеся [Усунення несправностей](/uk/gateway/troubleshooting). Подробиці автентифікації див. у [Dashboard](/web/dashboard). - - Прив’язка `tailnet` вибирає IP Tailscale з мережевих інтерфейсів вашої машини (100.64.0.0/10). Якщо машина не підключена до Tailscale (або інтерфейс неактивний), прив’язуватися нема до чого. + + Bind `tailnet` вибирає IP-адресу Tailscale з ваших мережевих інтерфейсів (100.64.0.0/10). Якщо машина не підключена до Tailscale (або інтерфейс вимкнено), прив’язуватися нема до чого. Виправлення: - Запустіть Tailscale на цьому хості (щоб він мав адресу 100.x), або - Перемкніться на `gateway.bind: "loopback"` / `"lan"`. - Примітка: `tailnet` є явним режимом. `auto` надає перевагу loopback; використовуйте `gateway.bind: "tailnet"`, коли вам потрібна прив’язка лише до tailnet. + Примітка: `tailnet` задається явно. `auto` віддає перевагу loopback; використовуйте `gateway.bind: "tailnet"`, коли хочете прив’язку лише до tailnet. - Зазвичай ні — один Gateway може обслуговувати кілька messaging channels і agents. Використовуйте кілька Gateway лише тоді, коли вам потрібна надлишковість (наприклад, rescue bot) або жорстка ізоляція. + Зазвичай ні — один Gateway може обслуговувати кілька каналів обміну повідомленнями та агентів. Використовуйте кілька Gateway лише тоді, коли вам потрібна надлишковість (наприклад, rescue bot) або жорстка ізоляція. - Так, але потрібно ізолювати: + Так, але вам потрібно ізолювати: - - `OPENCLAW_CONFIG_PATH` (config для кожного екземпляра) - - `OPENCLAW_STATE_DIR` (state для кожного екземпляра) + - `OPENCLAW_CONFIG_PATH` (окрема конфігурація для кожного екземпляра) + - `OPENCLAW_STATE_DIR` (окремий стан для кожного екземпляра) - `agents.defaults.workspace` (ізоляція workspace) - - `gateway.port` (унікальні ports) + - `gateway.port` (унікальні порти) Швидке налаштування (рекомендовано): - Використовуйте `openclaw --profile ...` для кожного екземпляра (автоматично створює `~/.openclaw-`). - - Задайте унікальний `gateway.port` у config кожного профілю (або передавайте `--port` для ручних запусків). - - Встановіть сервіс для кожного профілю: `openclaw --profile gateway install`. + - Установіть унікальний `gateway.port` у конфігурації кожного профілю (або передавайте `--port` для ручних запусків). + - Установіть сервіс для кожного профілю: `openclaw --profile gateway install`. - Профілі також додають суфікси до назв сервісів (`ai.openclaw.`; legacy `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). - Повний посібник: [Кілька Gateway](/uk/gateway/multiple-gateways). + Профілі також додають суфікси до назв сервісів (`ai.openclaw.`; застарілі `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). + Повний посібник: [Кілька gateway](/uk/gateway/multiple-gateways). - Gateway — це **сервер WebSocket**, і він очікує, що найперше повідомлення - буде фреймом `connect`. Якщо він отримує щось інше, то закриває з’єднання - з **code 1008** (порушення політики). + Gateway — це **сервер WebSocket**, і він очікує, що першим повідомленням + буде кадр `connect`. Якщо він отримує щось інше, то закриває з’єднання + з **кодом 1008** (порушення політики). Поширені причини: - - Ви відкрили URL **HTTP** у браузері (`http://...`) замість клієнта WS. - - Ви використали неправильний port або path. - - Proxy або tunnel видалив заголовки auth або надіслав запит не до Gateway. + - Ви відкрили URL-адресу **HTTP** у браузері (`http://...`) замість клієнта WS. + - Ви використали неправильний порт або шлях. + - Proxy або тунель прибрав заголовки автентифікації чи надіслав запит, що не належить Gateway. Швидкі виправлення: - 1. Використовуйте URL WS: `ws://:18789` (або `wss://...`, якщо HTTPS). - 2. Не відкривайте port WS у звичайній вкладці браузера. - 3. Якщо auth увімкнено, включіть token/password у фрейм `connect`. + 1. Використовуйте URL-адресу WS: `ws://:18789` (або `wss://...`, якщо HTTPS). + 2. Не відкривайте порт WS у звичайній вкладці браузера. + 3. Якщо автентифікацію ввімкнено, передайте токен/пароль у кадрі `connect`. Якщо ви використовуєте CLI або TUI, URL має виглядати так: @@ -2873,36 +2875,36 @@ x-i18n: openclaw tui --url ws://:18789 --token ``` - Деталі протоколу: [Протокол Gateway](/uk/gateway/protocol). + Подробиці протоколу: [Протокол Gateway](/uk/gateway/protocol). -## Журналювання та налагодження +## Логування та налагодження - + Файлові журнали (структуровані): ``` /tmp/openclaw/openclaw-YYYY-MM-DD.log ``` - Ви можете задати стабільний path через `logging.file`. Рівнем файлів журналу керує `logging.level`. Детальністю консолі керують `--verbose` і `logging.consoleLevel`. + Ви можете задати стабільний шлях через `logging.file`. Рівень файлового журналу керується `logging.level`. Докладність консолі керується `--verbose` і `logging.consoleLevel`. - Найшвидший перегляд хвоста журналу: + Найшвидший перегляд журналу в реальному часі: ```bash openclaw logs --follow ``` - Журнали сервісу/supervisor (коли gateway запущено через launchd/systemd): + Журнали сервісу/supervisor (коли gateway працює через launchd/systemd): - macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` і `gateway.err.log` (типово: `~/.openclaw/logs/...`; профілі використовують `~/.openclaw-/logs/...`) - Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` - Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` - Див. [Усунення несправностей](/uk/gateway/troubleshooting) для додаткової інформації. + Додатково див. [Усунення несправностей](/uk/gateway/troubleshooting). @@ -2914,12 +2916,12 @@ x-i18n: openclaw gateway restart ``` - Якщо ви запускаєте gateway вручну, `openclaw gateway --force` може повторно захопити port. Див. [Gateway](/uk/gateway). + Якщо ви запускаєте gateway вручну, `openclaw gateway --force` може повернути собі порт. Див. [Gateway](/uk/gateway). - Є **два режими встановлення для Windows**: + У Windows є **два режими встановлення**: **1) WSL2 (рекомендовано):** Gateway працює всередині Linux. @@ -2952,11 +2954,11 @@ x-i18n: openclaw gateway run ``` - Документація: [Windows (WSL2)](/uk/platforms/windows), [Операційний посібник із сервісу Gateway](/uk/gateway). + Документація: [Windows (WSL2)](/uk/platforms/windows), [Операційний посібник сервісу Gateway](/uk/gateway). - + Почніть із швидкої перевірки стану: ```bash @@ -2968,26 +2970,26 @@ x-i18n: Поширені причини: - - Auth моделі не завантажено на **хості gateway** (перевірте `models status`). - - Pairing/allowlist channel блокує відповіді (перевірте config channel + журнали). - - WebChat/Dashboard відкрито без правильного token. + - Автентифікація моделі не завантажена на **хості gateway** (перевірте `models status`). + - Сполучення каналу/allowlist блокує відповіді (перевірте конфігурацію каналу + журнали). + - WebChat/Dashboard відкрито без правильного токена. - Якщо ви працюєте віддалено, переконайтеся, що tunnel/Tailscale-з’єднання активне і + Якщо ви працюєте віддалено, переконайтеся, що тунель/Tailscale-з’єднання працює і що Gateway WebSocket доступний. Документація: [Channels](/uk/channels), [Усунення несправностей](/uk/gateway/troubleshooting), [Віддалений доступ](/uk/gateway/remote). - + Зазвичай це означає, що UI втратив з’єднання WebSocket. Перевірте: - 1. Gateway працює? `openclaw gateway status` - 2. Gateway у нормальному стані? `openclaw status` - 3. UI має правильний token? `openclaw dashboard` - 4. Якщо це remote, чи активне з’єднання tunnel/Tailscale? + 1. Gateway запущено? `openclaw gateway status` + 2. Gateway справний? `openclaw status` + 3. UI має правильний токен? `openclaw dashboard` + 4. Якщо віддалено, чи працює тунель/Tailscale-з’єднання? - Потім перегляньте хвіст журналів: + Потім перегляньте журнали в реальному часі: ```bash openclaw logs --follow @@ -2997,18 +2999,18 @@ x-i18n: - - Почніть із журналів і статусу channel: + + Почніть із журналів і стану каналу: ```bash openclaw channels status openclaw channels logs --channel telegram ``` - Далі зіставте помилку: + Потім зіставте з помилкою: - - `BOT_COMMANDS_TOO_MUCH`: меню Telegram містить надто багато записів. OpenClaw уже обрізає список до ліміту Telegram і повторює спробу з меншою кількістю команд, але деякі пункти меню все одно потрібно прибрати. Скоротіть plugin/skill/custom commands або вимкніть `channels.telegram.commands.native`, якщо меню вам не потрібне. - - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` або подібні мережеві помилки: якщо ви на VPS або за proxy, переконайтеся, що вихідний HTTPS дозволений і DNS працює для `api.telegram.org`. + - `BOT_COMMANDS_TOO_MUCH`: у меню Telegram забагато записів. OpenClaw уже обрізає список до ліміту Telegram і повторює спробу з меншою кількістю команд, але деякі записи меню все одно потрібно прибрати. Зменште кількість команд plugin/skill/custom або вимкніть `channels.telegram.commands.native`, якщо меню вам не потрібне. + - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` або подібні мережеві помилки: якщо ви на VPS або за proxy, переконайтеся, що вихідний HTTPS дозволено і DNS працює для `api.telegram.org`. Якщо Gateway віддалений, переконайтеся, що ви дивитеся журнали на хості Gateway. @@ -3016,8 +3018,8 @@ x-i18n: - - Спочатку переконайтеся, що Gateway доступний і agent може працювати: + + Спочатку переконайтеся, що Gateway доступний і агент може працювати: ```bash openclaw status @@ -3025,10 +3027,10 @@ x-i18n: openclaw logs --follow ``` - У TUI використовуйте `/status`, щоб побачити поточний стан. Якщо ви очікуєте відповіді в chat - channel, переконайтеся, що доставку ввімкнено (`/deliver on`). + У TUI використовуйте `/status`, щоб побачити поточний стан. Якщо ви очікуєте відповіді в чаті + каналу, переконайтеся, що доставку ввімкнено (`/deliver on`). - Документація: [TUI](/web/tui), [Slash commands](/uk/tools/slash-commands). + Документація: [TUI](/web/tui), [Slash-команди](/uk/tools/slash-commands). @@ -3040,8 +3042,8 @@ x-i18n: openclaw gateway start ``` - Це зупиняє/запускає **сервіс під керуванням supervisor** (launchd на macOS, systemd на Linux). - Використовуйте це, коли Gateway працює у фоновому режимі як daemon. + Це зупиняє/запускає **керований сервіс** (launchd у macOS, systemd у Linux). + Використовуйте це, коли Gateway працює у фоновому режимі як демон. Якщо ви запускаєте у foreground, зупиніть через Ctrl-C, а потім: @@ -3049,21 +3051,21 @@ x-i18n: openclaw gateway run ``` - Документація: [Операційний посібник із сервісу Gateway](/uk/gateway). + Документація: [Операційний посібник сервісу Gateway](/uk/gateway). - + - `openclaw gateway restart`: перезапускає **фоновий сервіс** (launchd/systemd). - - `openclaw gateway`: запускає gateway **у foreground** для цього сеансу термінала. + - `openclaw gateway`: запускає gateway **у foreground** для цієї сесії термінала. Якщо ви встановили сервіс, використовуйте команди gateway. Використовуйте `openclaw gateway`, коли вам потрібен одноразовий запуск у foreground. - - Запустіть Gateway з `--verbose`, щоб отримати більше деталей у консолі. Потім перевірте файл журналу на наявність помилок auth channel, routing моделі та RPC. + + Запустіть Gateway з `--verbose`, щоб отримати більше подробиць у консолі. Потім перевірте файл журналу на предмет автентифікації каналу, маршрутизації моделей і помилок RPC. @@ -3071,7 +3073,7 @@ x-i18n: - Вихідні вкладення від agent мають містити рядок `MEDIA:` (в окремому рядку). Див. [Налаштування assistant OpenClaw](/uk/start/openclaw) і [Надсилання Agent](/uk/tools/agent-send). + Вихідні вкладення від агента мають містити рядок `MEDIA:` (в окремому рядку). Див. [Налаштування асистента OpenClaw](/uk/start/openclaw) і [Надсилання агентом](/uk/tools/agent-send). Надсилання через CLI: @@ -3081,10 +3083,10 @@ x-i18n: Також перевірте: - - Цільовий channel підтримує вихідні медіа й не блокується allowlist. - - Файл не перевищує обмеження розміру provider (зображення змінюються до максимуму 2048px). + - Цільовий channel підтримує вихідні медіа і не блокується allowlist. + - Файл не перевищує обмеження розміру провайдера (зображення змінюють розмір максимум до 2048 px). - `tools.fs.workspaceOnly=true` обмежує надсилання локальних шляхів workspace, temp/media-store і файлами, перевіреними sandbox. - - `tools.fs.workspaceOnly=false` дозволяє `MEDIA:` надсилати локальні файли хоста, які agent уже може читати, але лише для медіа та безпечних типів документів (зображення, аудіо, відео, PDF і документи Office). Звичайний текст і файли, схожі на secrets, усе одно блокуються. + - `tools.fs.workspaceOnly=false` дозволяє `MEDIA:` надсилати локальні файли хоста, які агент уже може читати, але лише для медіа і безпечних типів документів (зображення, аудіо, відео, PDF і документи Office). Звичайний текст і файли, схожі на секрети, усе одно блокуються. Див. [Зображення](/uk/nodes/images). @@ -3095,109 +3097,109 @@ x-i18n: - Ставтеся до вхідних DM як до недовіреного input. Типові налаштування розроблено для зниження ризику: + Ставтеся до вхідних DM як до недовіреного вводу. Значення за замовчуванням розроблено так, щоб зменшувати ризик: - - Типова поведінка на channels із підтримкою DM — **pairing**: + - Типова поведінка в каналах із підтримкою DM — **pairing**: - Невідомі відправники отримують код pairing; бот не обробляє їхнє повідомлення. - - Схвалення виконується так: `openclaw pairing approve --channel [--account ] ` - - Кількість очікуваних запитів обмежена до **3 на channel**; перевіряйте `openclaw pairing list --channel [--account ]`, якщо код не надійшов. - - Публічне відкриття DM вимагає явної згоди (`dmPolicy: "open"` і allowlist `"*"`). + - Підтвердження через: `openclaw pairing approve --channel [--account ] ` + - Кількість pending-запитів обмежена до **3 на channel**; перевіряйте `openclaw pairing list --channel [--account ]`, якщо код не надійшов. + - Відкриття DM публічно вимагає явного opt-in (`dmPolicy: "open"` і allowlist `"*"`). Запустіть `openclaw doctor`, щоб виявити ризиковані політики DM. - + Ні. Prompt injection стосується **недовіреного контенту**, а не лише того, хто може написати боту в DM. - Якщо ваш assistant читає зовнішній контент (web search/fetch, сторінки браузера, email, - документи, вкладення, вставлені журнали), цей контент може містити інструкції, які намагаються - перехопити керування моделлю. Це може трапитися, навіть якщо **єдиний відправник — ви**. + Якщо ваш асистент читає зовнішній контент (вебпошук/fetch, сторінки браузера, листи, + документи, вкладення, вставлені журнали), цей контент може містити інструкції, які + намагаються перехопити керування моделлю. Це може статися, навіть якщо **ви єдиний відправник**. - Найбільший ризик виникає, коли ввімкнено інструменти: модель можна змусити - ексфільтрувати context або викликати інструменти від вашого імені. Зменшуйте радіус ураження: + Найбільший ризик виникає, коли увімкнено інструменти: модель можна обманом змусити + витягти контекст або викликати інструменти від вашого імені. Зменште радіус ураження: - - використовуйте agent "читач" лише для читання або без інструментів, щоб підсумовувати недовірений контент - - тримайте `web_search` / `web_fetch` / `browser` вимкненими для agents з увімкненими інструментами - - ставтеся до декодованого тексту файлів/документів також як до недовіреного: OpenResponses - `input_file` і витягування тексту з медіавкладень обгортають витягнутий текст у - явні маркери меж зовнішнього контенту замість передавання сирого тексту файла + - використовуйте агента-"читача" лише для читання або без інструментів, щоб підсумовувати недовірений контент + - тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів з увімкненими інструментами + - також ставтеся до декодованого тексту файлів/документів як до недовіреного: OpenResponses + `input_file` і видобування з медіавкладень обгортають витягнутий текст + у явні маркери меж зовнішнього контенту замість передавання сирого тексту файла - використовуйте sandboxing і суворі allowlist інструментів - Деталі: [Безпека](/uk/gateway/security). + Подробиці: [Безпека](/uk/gateway/security). - - Так, для більшості конфігурацій. Ізоляція бота за допомогою окремих облікових записів і номерів телефону - зменшує радіус ураження, якщо щось піде не так. Також це полегшує перевипуск + + Так, для більшості сценаріїв. Ізоляція бота окремими обліковими записами й номерами телефонів + зменшує радіус ураження, якщо щось піде не так. Це також полегшує ротацію облікових даних або відкликання доступу без впливу на ваші особисті облікові записи. Починайте з малого. Надавайте доступ лише до тих інструментів і облікових записів, які вам справді потрібні, і розширюйте - його пізніше за потреби. + пізніше, якщо це знадобиться. Документація: [Безпека](/uk/gateway/security), [Pairing](/uk/channels/pairing). - - Ми **не** рекомендуємо повну автономність над вашими особистими повідомленнями. Найбезпечніший шаблон: + + Ми **не** рекомендуємо повну автономію над вашими особистими повідомленнями. Найбезпечніший шаблон: - - Тримайте DM у **режимі pairing** або з жорстким allowlist. + - Тримайте DM у режимі **pairing** або з жорстким allowlist. - Використовуйте **окремий номер або обліковий запис**, якщо хочете, щоб він надсилав повідомлення від вашого імені. - - Дозвольте йому створювати чернетки, а потім **схвалюйте перед надсиланням**. + - Нехай він готує чернетку, а ви **погоджуйте перед надсиланням**. - Якщо хочете поекспериментувати, робіть це на окремому обліковому записі й тримайте його ізольованим. Див. + Якщо хочете експериментувати, робіть це на окремому обліковому записі та зберігайте ізоляцію. Див. [Безпека](/uk/gateway/security). - - Так, **якщо** agent використовується лише для чату і input є довіреним. Менші рівні - більш схильні до викрадення інструкціями, тому уникайте їх для agents з увімкненими інструментами - або під час читання недовіреного контенту. Якщо все ж потрібно використовувати меншу модель, жорстко обмежте + + Так, **якщо** агент працює лише в чаті, а вхідні дані довірені. Менші рівні + більш схильні до перехоплення інструкціями, тому уникайте їх для агентів з увімкненими інструментами + або під час читання недовіреного контенту. Якщо вам усе ж потрібна менша модель, жорстко обмежте інструменти і запускайте всередині sandbox. Див. [Безпека](/uk/gateway/security). - - Коди pairing надсилаються **лише** тоді, коли невідомий відправник пише боту і - `dmPolicy: "pairing"` увімкнено. Сам по собі `/start` не генерує код. + + Коди pairing надсилаються **лише** коли невідомий відправник пише боту і + ввімкнено `dmPolicy: "pairing"`. Сам по собі `/start` не генерує код. - Перевірте очікувані запити: + Перевірте pending-запити: ```bash openclaw pairing list telegram ``` - Якщо вам потрібен негайний доступ, додайте свій sender id до allowlist або задайте `dmPolicy: "open"` + Якщо вам потрібен негайний доступ, додайте свій ID відправника до allowlist або задайте `dmPolicy: "open"` для цього облікового запису. - Ні. Типова політика DM у WhatsApp — **pairing**. Невідомі відправники отримують лише код pairing, а їхнє повідомлення **не обробляється**. OpenClaw відповідає лише в чатах, які отримує, або на явні надсилання, які ви ініціюєте. + Ні. Типова політика WhatsApp DM — **pairing**. Невідомі відправники отримують лише код pairing, а їхнє повідомлення **не обробляється**. OpenClaw відповідає лише на чати, які він отримує, або на явні надсилання, які ви запускаєте. - Схваліть pairing так: + Підтвердьте pairing через: ```bash openclaw pairing approve whatsapp ``` - Перелічіть очікувані запити: + Перелік pending-запитів: ```bash openclaw pairing list whatsapp ``` - Запит майстра на номер телефону: він використовується для встановлення вашого **allowlist/owner**, щоб ваші власні DM були дозволені. Він не використовується для автоматичного надсилання. Якщо ви запускаєте на своєму особистому номері WhatsApp, використовуйте цей номер і ввімкніть `channels.whatsapp.selfChatMode`. + Запит номера телефону в майстрі: він використовується для налаштування вашого **allowlist/власника**, щоб ваші власні DM були дозволені. Він не використовується для автоматичного надсилання. Якщо ви запускаєте на своєму особистому номері WhatsApp, використовуйте цей номер і ввімкніть `channels.whatsapp.selfChatMode`. -## Команди чату, переривання задач і "він не зупиняється" +## Команди чату, переривання завдань і "він не зупиняється" - Більшість внутрішніх повідомлень або повідомлень інструментів з’являються лише тоді, коли для цього session увімкнено **verbose**, **trace** або **reasoning**. + Більшість внутрішніх або інструментальних повідомлень з’являються лише тоді, коли для цієї сесії увімкнено **verbose**, **trace** або **reasoning**. Виправлення в чаті, де ви це бачите: @@ -3207,16 +3209,16 @@ x-i18n: /reasoning off ``` - Якщо все ще надто шумно, перевірте налаштування session у Control UI і встановіть verbose - на **inherit**. Також переконайтеся, що ви не використовуєте profile бота з `verboseDefault`, встановленим - у `on` у config. + Якщо все ще занадто шумно, перевірте налаштування сесії в Control UI і встановіть verbose + на **inherit**. Також переконайтеся, що ви не використовуєте профіль бота з `verboseDefault`, установленим + у `on` у конфігурації. Документація: [Thinking і verbose](/uk/tools/thinking), [Безпека](/uk/gateway/security#reasoning-verbose-output-in-groups). - - Надішліть будь-який із цих варіантів **як окреме повідомлення** (без slash): + + Надішліть будь-який із цих варіантів **як окреме повідомлення** (без слеша): ``` stop @@ -3242,23 +3244,23 @@ x-i18n: Це тригери переривання, а не slash-команди. - Для фонових процесів (з інструмента exec) ви можете попросити agent виконати: + Для фонових процесів (з інструмента exec) ви можете попросити агента виконати: ``` process action:kill sessionId:XXX ``` - Огляд slash-команд: див. [Slash commands](/uk/tools/slash-commands). + Огляд slash-команд: див. [Slash-команди](/uk/tools/slash-commands). - Більшість команд мають надсилатися як **окреме** повідомлення, що починається з `/`, але кілька скорочень (як-от `/status`) також працюють inline для відправників з allowlist. + Більшість команд треба надсилати як **окреме** повідомлення, що починається з `/`, але кілька скорочень (наприклад, `/status`) також працюють inline для відправників з allowlist. - OpenClaw типово блокує обмін повідомленнями **між різними providers**. Якщо виклик інструмента прив’язаний - до Telegram, він не надсилатиме в Discord, якщо ви явно цього не дозволите. + OpenClaw за замовчуванням блокує повідомлення **між різними провайдерами**. Якщо виклик інструмента прив’язаний + до Telegram, він не надсилатиме в Discord, якщо ви явно це не дозволите. - Увімкніть міжprovider-обмін повідомленнями для agent: + Увімкніть міжпровайдерний обмін повідомленнями для агента: ```json5 { @@ -3273,20 +3275,20 @@ x-i18n: } ``` - Після редагування config перезапустіть gateway. + Після редагування конфігурації перезапустіть gateway. - - Режим queue визначає, як нові повідомлення взаємодіють із поточним запущеним run. Використовуйте `/queue`, щоб змінити режими: + + Режим черги керує тим, як нові повідомлення взаємодіють із поточним виконанням. Використовуйте `/queue`, щоб змінити режими: - - `steer` — нові повідомлення перенаправляють поточну задачу - - `followup` — повідомлення виконуються по одному - - `collect` — пакетування повідомлень і одна відповідь (типово) - - `steer-backlog` — перенаправити зараз, а потім обробити backlog - - `interrupt` — перервати поточний run і почати заново + - `steer` - нові повідомлення перенаправляють поточне завдання + - `followup` - повідомлення виконуються по одному + - `collect` - групує повідомлення і відповідає один раз (типово) + - `steer-backlog` - перенаправляє зараз, а потім обробляє backlog + - `interrupt` - перериває поточне виконання і починає заново - Ви можете додавати параметри на кшталт `debounce:2s cap:25 drop:summarize` для режимів followup. + Ви можете додати параметри на кшталт `debounce:2s cap:25 drop:summarize` для режимів followup. @@ -3294,11 +3296,11 @@ x-i18n: ## Різне - - В OpenClaw облікові дані та вибір моделі розділено. Встановлення `ANTHROPIC_API_KEY` (або збереження Anthropic API key в auth profiles) вмикає автентифікацію, але фактична типова модель — це те, що ви налаштували в `agents.defaults.model.primary` (наприклад, `anthropic/claude-sonnet-4-6` або `anthropic/claude-opus-4-6`). Якщо ви бачите `No credentials found for profile "anthropic:default"`, це означає, що Gateway не зміг знайти облікові дані Anthropic в очікуваному `auth-profiles.json` для agent, який зараз працює. + + В OpenClaw облікові дані та вибір моделі — це окремі речі. Задання `ANTHROPIC_API_KEY` (або збереження API-ключа Anthropic у профілях автентифікації) вмикає автентифікацію, але фактична модель за замовчуванням — це те, що ви налаштували в `agents.defaults.model.primary` (наприклад, `anthropic/claude-sonnet-4-6` або `anthropic/claude-opus-4-6`). Якщо ви бачите `No credentials found for profile "anthropic:default"`, це означає, що Gateway не зміг знайти облікові дані Anthropic в очікуваному `auth-profiles.json` для агента, який виконується. --- -Усе ще застрягли? Запитайте в [Discord](https://discord.com/invite/clawd) або відкрийте [обговорення на GitHub](https://github.com/openclaw/openclaw/discussions). +Усе ще застрягли? Запитайте в [Discord](https://discord.com/invite/clawd) або відкрийте [обговорення GitHub](https://github.com/openclaw/openclaw/discussions). diff --git a/docs/uk/tools/browser.md b/docs/uk/tools/browser.md index 5976cc6ae..1d5d5ed1f 100644 --- a/docs/uk/tools/browser.md +++ b/docs/uk/tools/browser.md @@ -1,15 +1,15 @@ --- read_when: - - Додавання автоматизації браузера під керуванням агента - - Налагодження, чому openclaw втручається у ваш власний Chrome - - Реалізація налаштувань браузера та життєвого циклу в застосунку macOS -summary: Інтегрована служба керування браузером + команди дій + - Додавання автоматизації браузера, керованої агентом + - Налагодження того, чому openclaw заважає вашому власному Chrome + - Реалізація налаштувань браузера та його життєвого циклу в застосунку macOS +summary: Інтегрований сервіс керування браузером + команди дій title: Браузер (керований OpenClaw) x-i18n: - generated_at: "2026-04-19T09:45:12Z" + generated_at: "2026-04-19T10:22:58Z" model: gpt-5.4 provider: openai - source_hash: dac051a4e963545af045f97e2222777595c1a0865170dcc15407932f21703fd0 + source_hash: 3f7d37b34ba48dc7c38f8c2e77f8bb97af987eac6a874ebfc921f950fb59de4b source_path: tools/browser.md workflow: 15 --- @@ -23,18 +23,18 @@ OpenClaw може запускати **окремий профіль Chrome/Brav Погляд для початківців: - Думайте про це як про **окремий браузер лише для агента**. -- Профіль `openclaw` **не** торкається профілю вашого особистого браузера. +- Профіль `openclaw` **не** торкається вашого особистого профілю браузера. - Агент може **відкривати вкладки, читати сторінки, натискати та вводити текст** у безпечному середовищі. -- Вбудований профіль `user` під’єднується до вашої справжньої сесії Chrome із входом через Chrome MCP. +- Вбудований профіль `user` підключається до вашої справжньої сесії Chrome, у якій ви вже ввійшли, через Chrome MCP. ## Що ви отримуєте -- Окремий профіль браузера з назвою **openclaw** (помаранчевий акцент за замовчуванням). -- Детерміноване керування вкладками (перелік/відкриття/фокус/закриття). -- Дії агента (натискання/введення/перетягування/вибір), знімки стану, скриншоти, PDF. +- Окремий профіль браузера з назвою **openclaw** (типово з помаранчевим акцентом). +- Детерміноване керування вкладками (список/відкрити/фокус/закрити). +- Дії агента (натискання/введення/перетягування/вибір), знімки, скриншоти, PDF. - Необов’язкова підтримка кількох профілів (`openclaw`, `work`, `remote`, ...). -Цей браузер **не** є вашим щоденним основним браузером. Це безпечне, ізольоване середовище для +Цей браузер **не** призначений для вашого щоденного використання. Це безпечна, ізольована поверхня для автоматизації та перевірки агентом. ## Швидкий старт @@ -49,14 +49,14 @@ openclaw browser --browser-profile openclaw snapshot Якщо ви отримуєте “Browser disabled”, увімкніть його в конфігурації (див. нижче) і перезапустіть Gateway. -Якщо `openclaw browser` повністю відсутній або агент каже, що інструмент браузера -недоступний, перейдіть до [Відсутня команда або інструмент browser](/uk/tools/browser#missing-browser-command-or-tool). +Якщо `openclaw browser` повністю відсутня або агент каже, що інструмент браузера +недоступний, перейдіть до [Відсутня команда браузера або інструмент](/uk/tools/browser#missing-browser-command-or-tool). ## Керування Plugin -Типовий інструмент `browser` тепер є вбудованим Plugin, який постачається -увімкненим за замовчуванням. Це означає, що ви можете вимкнути або замінити його, не видаляючи решту -системи Plugin OpenClaw: +Типовий інструмент `browser` тепер є вбудованим Plugin, який постачається увімкненим +типово. Це означає, що ви можете вимкнути або замінити його, не видаляючи решту +системи Plugin у OpenClaw: ```json5 { @@ -71,30 +71,29 @@ Gateway. ``` Вимкніть вбудований Plugin перед встановленням іншого Plugin, який надає -те саме ім’я інструмента `browser`. Типова робота браузера потребує обох умов: +те саме ім’я інструмента `browser`. Типовому режиму браузера потрібні обидва параметри: - `plugins.entries.browser.enabled` не вимкнено - `browser.enabled=true` -Якщо ви вимкнете лише Plugin, тоді вбудований CLI браузера (`openclaw browser`), +Якщо ви вимкнете лише Plugin, вбудований CLI браузера (`openclaw browser`), метод gateway (`browser.request`), інструмент агента та типовий сервіс керування браузером -усі зникнуть одночасно. Ваш конфіг `browser.*` залишиться незмінним, щоб -його міг повторно використати замінний Plugin. +усі зникнуть разом. Ваша конфігурація `browser.*` залишиться недоторканою, щоб її міг повторно використати +Plugin-замінник. -Вбудований Plugin браузера тепер також володіє реалізацією середовища виконання браузера. -У ядрі залишаються лише спільні допоміжні засоби Plugin SDK та сумісні повторні експорти для -старих внутрішніх шляхів імпорту. На практиці це означає, що видалення або заміна пакета Plugin браузера -прибирає функціональність браузера замість того, щоб залишати другу реалізацію середовища виконання, -якою володіє ядро. +Вбудований Plugin браузера тепер також володіє реалізацією runtime браузера. +У core залишаються лише спільні допоміжні компоненти Plugin SDK плюс сумісні повторні експорти для +старих внутрішніх шляхів імпорту. На практиці видалення або заміна пакета Plugin браузера +прибирає функціональність браузера, а не залишає позаду другу runtime-реалізацію, що належить core. -Зміни конфігурації браузера, як і раніше, потребують перезапуску Gateway, щоб вбудований Plugin +Зміни конфігурації браузера все ще потребують перезапуску Gateway, щоб вбудований Plugin міг повторно зареєструвати свій сервіс браузера з новими налаштуваннями. -## Відсутня команда або інструмент browser +## Відсутня команда браузера або інструмент -Якщо після оновлення `openclaw browser` раптово стає невідомою командою або -агент повідомляє, що інструмент браузера відсутній, найпоширеніша причина — це -обмежувальний список `plugins.allow`, у якому немає `browser`. +Якщо `openclaw browser` раптово стає невідомою командою після оновлення або +агент повідомляє, що інструмент браузера відсутній, найпоширенішою причиною є +обмежувальний список `plugins.allow`, який не містить `browser`. Приклад зламаної конфігурації: @@ -106,7 +105,7 @@ Gateway. } ``` -Виправлення — додати `browser` до списку дозволених Plugin: +Виправте це, додавши `browser` до списку дозволених Plugin: ```json5 { @@ -118,9 +117,9 @@ Gateway. Важливі примітки: -- Самого `browser.enabled=true` недостатньо, якщо задано `plugins.allow`. -- Самого `plugins.entries.browser.enabled=true` також недостатньо, якщо задано `plugins.allow`. -- `tools.alsoAllow: ["browser"]` **не** завантажує вбудований Plugin браузера. Це лише коригує політику інструментів після того, як Plugin уже завантажено. +- Самого `browser.enabled=true` недостатньо, якщо встановлено `plugins.allow`. +- Самого `plugins.entries.browser.enabled=true` також недостатньо, якщо встановлено `plugins.allow`. +- `tools.alsoAllow: ["browser"]` **не** завантажує вбудований Plugin браузера. Він лише коригує політику інструментів після того, як Plugin уже завантажено. - Якщо вам не потрібен обмежувальний список дозволених Plugin, видалення `plugins.allow` також відновлює типову поведінку вбудованого браузера. Типові симптоми: @@ -129,37 +128,38 @@ Gateway. - `browser.request` відсутній. - Агент повідомляє, що інструмент браузера недоступний або відсутній. -## Профілі: `openclaw` проти `user` +## Профілі: `openclaw` vs `user` - `openclaw`: керований, ізольований браузер (розширення не потрібне). -- `user`: вбудований профіль підключення Chrome MCP до вашої **справжньої сесії Chrome із входом**. +- `user`: вбудований профіль підключення Chrome MCP до вашої **справжньої сесії Chrome** + із виконаним входом. Для викликів інструмента браузера агентом: -- За замовчуванням: використовується ізольований браузер `openclaw`. +- Типово: використовується ізольований браузер `openclaw`. - Надавайте перевагу `profile="user"`, коли важливі наявні сесії з виконаним входом і користувач перебуває за комп’ютером, щоб натиснути/підтвердити будь-який запит на підключення. -- `profile` — це явне перевизначення, коли вам потрібен конкретний режим браузера. +- `profile` — це явний спосіб перевизначення, коли вам потрібен конкретний режим браузера. -Установіть `browser.defaultProfile: "openclaw"`, якщо хочете, щоб керований режим був типовим. +Установіть `browser.defaultProfile: "openclaw"`, якщо хочете, щоб типово використовувався керований режим. ## Конфігурація -Налаштування браузера розташовані в `~/.openclaw/openclaw.json`. +Налаштування браузера зберігаються в `~/.openclaw/openclaw.json`. ```json5 { browser: { - enabled: true, // default: true + enabled: true, // типово: true ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access - // allowPrivateNetwork: true, // legacy alias + // dangerouslyAllowPrivateNetwork: true, // вмикайте лише для довіреного доступу до приватної мережі + // allowPrivateNetwork: true, // застарілий псевдонім // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, - // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override - remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms) - remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms) + // cdpUrl: "http://127.0.0.1:18792", // застаріле перевизначення одного профілю + remoteCdpTimeoutMs: 1500, // тайм-аут HTTP віддаленого CDP (мс) + remoteCdpHandshakeTimeoutMs: 3000, // тайм-аут рукостискання WebSocket віддаленого CDP (мс) defaultProfile: "openclaw", color: "#FF4500", headless: false, @@ -189,31 +189,31 @@ Gateway. Примітки: - Сервіс керування браузером прив’язується до loopback на порту, похідному від `gateway.port` - (за замовчуванням: `18791`, тобто gateway + 2). -- Якщо ви перевизначите порт Gateway (`gateway.port` або `OPENCLAW_GATEWAY_PORT`), - похідні порти браузера змістяться, щоб залишатися в тій самій «родині». -- `cdpUrl` за замовчуванням відповідає локальному керованому порту CDP, якщо не задано. -- `remoteCdpTimeoutMs` застосовується до перевірок доступності віддаленого CDP (не-loopback). -- `remoteCdpHandshakeTimeoutMs` застосовується до перевірок доступності WebSocket-з’єднання віддаленого CDP. -- Навігація браузера/відкриття вкладки захищені від SSRF перед переходом, а після переходу виконується повторна перевірка найкращими зусиллями для фінальної `http(s)` URL-адреси. -- У суворому режимі SSRF також перевіряються виявлення/зондування віддалених кінцевих точок CDP (`cdpUrl`, включно з пошуками `/json/version`). -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` за замовчуванням вимкнено. Установлюйте `true` лише тоді, коли ви свідомо довіряєте доступу браузера до приватної мережі. + (типово: `18791`, тобто gateway + 2). +- Якщо ви перевизначаєте порт Gateway (`gateway.port` або `OPENCLAW_GATEWAY_PORT`), + похідні порти браузера зміщуються, щоб залишатися в тій самій “сім’ї”. +- `cdpUrl` типово вказує на керований локальний CDP-порт, якщо його не задано. +- `remoteCdpTimeoutMs` застосовується до перевірок доступності віддаленого (не-loopback) CDP. +- `remoteCdpHandshakeTimeoutMs` застосовується до перевірок доступності рукостискання WebSocket віддаленого CDP. +- Навігація браузера/відкриття вкладок захищені SSRF-перевіркою до навігації та за можливості повторно перевіряються для фінального URL `http(s)` після навігації. +- У строгому режимі SSRF перевіряються також виявлення/проби віддалених кінцевих точок CDP (`cdpUrl`, включно з пошуками `/json/version`). +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` типово вимкнений. Установлюйте його в `true` лише тоді, коли ви навмисно довіряєте доступу браузера до приватної мережі. - `browser.ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як застарілий псевдонім для сумісності. -- `attachOnly: true` означає «ніколи не запускати локальний браузер; лише під’єднуватися, якщо він уже запущений». -- `color` та `color` для окремого профілю тонують інтерфейс браузера, щоб ви могли бачити, який профіль активний. -- Профіль за замовчуванням — `openclaw` (окремий браузер під керуванням OpenClaw). Використовуйте `defaultProfile: "user"`, щоб вибрати браузер користувача з виконаним входом. -- Порядок авто-виявлення: системний браузер за замовчуванням, якщо він базується на Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary. +- `attachOnly: true` означає “ніколи не запускати локальний браузер; лише підключатися, якщо він уже запущений”. +- `color` та `color` для кожного профілю тонують інтерфейс браузера, щоб ви могли бачити, який профіль активний. +- Типовий профіль — `openclaw` (окремий браузер, керований OpenClaw). Використовуйте `defaultProfile: "user"`, щоб перейти на браузер користувача з виконаним входом. +- Порядок автовизначення: системний браузер за замовчуванням, якщо він на базі Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary. - Локальні профілі `openclaw` автоматично призначають `cdpPort`/`cdpUrl` — задавайте їх лише для віддаленого CDP. - `driver: "existing-session"` використовує Chrome DevTools MCP замість сирого CDP. Не - задавайте `cdpUrl` для цього драйвера. + встановлюйте `cdpUrl` для цього драйвера. - Установіть `browser.profiles..userDataDir`, коли профіль existing-session - має підключатися до нестандартного користувацького профілю Chromium, такого як Brave або Edge. + має підключатися до нестандартного профілю користувача Chromium, наприклад Brave або Edge. ## Використання Brave (або іншого браузера на базі Chromium) -Якщо вашим **системним браузером за замовчуванням** є браузер на базі Chromium (Chrome/Brave/Edge тощо), +Якщо ваш **системний браузер за замовчуванням** базується на Chromium (Chrome/Brave/Edge тощо), OpenClaw використовує його автоматично. Установіть `browser.executablePath`, щоб перевизначити -авто-виявлення: +автовизначення: Приклад CLI: @@ -246,51 +246,51 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## Локальне та віддалене керування -- **Локальне керування (за замовчуванням):** Gateway запускає сервіс керування loopback і може запускати локальний браузер. +- **Локальне керування (типово):** Gateway запускає loopback-сервіс керування та може запускати локальний браузер. - **Віддалене керування (вузол-хост):** запустіть вузол-хост на машині, де є браузер; Gateway проксуватиме до нього дії браузера. - **Віддалений CDP:** установіть `browser.profiles..cdpUrl` (або `browser.cdpUrl`), щоб - підключитися до віддаленого браузера на базі Chromium. У цьому випадку OpenClaw не запускатиме локальний браузер. + підключитися до віддаленого браузера на базі Chromium. У такому разі OpenClaw не запускатиме локальний браузер. Поведінка під час зупинки відрізняється залежно від режиму профілю: - локальні керовані профілі: `openclaw browser stop` зупиняє процес браузера, який запустив OpenClaw -- профілі лише з підключенням і профілі віддаленого CDP: `openclaw browser stop` закриває активну +- профілі лише з підключенням та профілі віддаленого CDP: `openclaw browser stop` закриває активну сесію керування та скидає перевизначення емуляції Playwright/CDP (viewport, колірну схему, локаль, часовий пояс, офлайн-режим та подібний стан), навіть якщо OpenClaw не запускав жодного процесу браузера -URL віддаленого CDP можуть містити автентифікацію: +Віддалені URL CDP можуть містити автентифікацію: -- Токени запиту (наприклад, `https://provider.example?token=`) +- Токени в параметрах запиту (наприклад, `https://provider.example?token=`) - HTTP Basic auth (наприклад, `https://user:pass@provider.example`) OpenClaw зберігає автентифікацію під час виклику кінцевих точок `/json/*` і під час підключення -до WebSocket CDP. Віддавайте перевагу змінним середовища або менеджерам секретів для -токенів замість збереження їх у файлах конфігурації. +до WebSocket CDP. Для токенів краще використовувати змінні середовища або менеджери секретів, +а не зберігати їх у файлах конфігурації. -## Проксі браузера вузла (zero-config за замовчуванням) +## Проксі браузера Node (нульова конфігурація типово) Якщо ви запускаєте **вузол-хост** на машині, де є ваш браузер, OpenClaw може -автоматично маршрутизувати виклики інструмента браузера до цього вузла без будь-якої додаткової конфігурації браузера. -Це типовий шлях для віддалених gateway. +автоматично маршрутизувати виклики інструмента браузера до цього вузла без жодної додаткової конфігурації браузера. +Це типовий шлях для віддалених Gateway. Примітки: -- Вузол-хост надає свій локальний сервер керування браузером через **proxy command**. +- Вузол-хост надає свій локальний сервер керування браузером через **проксі-команду**. - Профілі беруться з власної конфігурації вузла `browser.profiles` (так само, як локально). - `nodeHost.browserProxy.allowProfiles` є необов’язковим. Залиште його порожнім для застарілої/типової поведінки: усі налаштовані профілі залишаються доступними через проксі, включно з маршрутами створення/видалення профілів. -- Якщо ви задаєте `nodeHost.browserProxy.allowProfiles`, OpenClaw сприймає це як межу найменших привілеїв: можна звертатися лише до профілів зі списку дозволених, а маршрути створення/видалення постійних профілів блокуються на поверхні проксі. -- Вимкніть це, якщо не хочете використовувати: +- Якщо ви встановите `nodeHost.browserProxy.allowProfiles`, OpenClaw розглядатиме це як межу найменших привілеїв: можна буде звертатися лише до профілів зі списку дозволених, а маршрути створення/видалення постійних профілів будуть заблоковані на поверхні проксі. +- Вимкніть це, якщо воно вам не потрібне: - На вузлі: `nodeHost.browserProxy.enabled=false` - На gateway: `gateway.nodes.browser.mode="off"` -## Browserless (хостований віддалений CDP) +## Browserless (розміщений віддалений CDP) -[Browserless](https://browserless.io) — це хостований сервіс Chromium, який надає +[Browserless](https://browserless.io) — це розміщений сервіс Chromium, який надає URL підключення CDP через HTTPS і WebSocket. OpenClaw може використовувати будь-яку форму, але -для профілю віддаленого браузера найпростішим варіантом є прямий URL WebSocket -з документації Browserless щодо підключення. +для віддаленого профілю браузера найпростішим варіантом є прямий URL WebSocket +з документації підключення Browserless. Приклад: @@ -314,43 +314,43 @@ URL підключення CDP через HTTPS і WebSocket. OpenClaw може Примітки: - Замініть `` на ваш справжній токен Browserless. -- Виберіть кінцеву точку регіону, яка відповідає вашому обліковому запису Browserless (див. їхню документацію). -- Якщо Browserless надає вам базову URL-адресу HTTPS, ви можете або перетворити її на +- Виберіть кінцеву точку регіону, що відповідає вашому обліковому запису Browserless (див. їхню документацію). +- Якщо Browserless надає вам базовий URL HTTPS, ви можете або перетворити його на `wss://` для прямого підключення CDP, або залишити URL HTTPS і дозволити OpenClaw виявити `/json/version`. -## Провайдери прямого WebSocket CDP +## Прямі постачальники WebSocket CDP -Деякі хостовані сервіси браузерів надають **пряму кінцеву точку WebSocket** замість +Деякі розміщені сервіси браузерів надають **пряму** кінцеву точку WebSocket замість стандартного виявлення CDP на основі HTTP (`/json/version`). OpenClaw приймає три форми URL CDP і автоматично вибирає правильну стратегію підключення: -- **Виявлення HTTP(S)** — `http://host[:port]` або `https://host[:port]`. +- **Виявлення через HTTP(S)** — `http://host[:port]` або `https://host[:port]`. OpenClaw викликає `/json/version`, щоб виявити URL WebSocket debugger, а потім підключається. Резервного переходу на WebSocket немає. - **Прямі кінцеві точки WebSocket** — `ws://host[:port]/devtools//` або `wss://...` зі шляхом `/devtools/browser|page|worker|shared_worker|service_worker/`. - OpenClaw підключається напряму через WebSocket handshake і повністю пропускає + OpenClaw підключається напряму через рукостискання WebSocket і повністю пропускає `/json/version`. -- **Кореневі адреси WebSocket без шляху** — `ws://host[:port]` або `wss://host[:port]` без +- **Базові корені WebSocket** — `ws://host[:port]` або `wss://host[:port]` без шляху `/devtools/...` (наприклад, [Browserless](https://browserless.io), - [Browserbase](https://www.browserbase.com)). OpenClaw спочатку пробує HTTP - виявлення через `/json/version` (нормалізуючи схему до `http`/`https`); + [Browserbase](https://www.browserbase.com)). OpenClaw спочатку пробує виявлення через HTTP + `/json/version` (нормалізуючи схему до `http`/`https`); якщо виявлення повертає `webSocketDebuggerUrl`, він використовується, інакше OpenClaw - переходить до прямого WebSocket handshake на кореневій адресі без шляху. Це охоплює - як віддалені порти налагодження у стилі Chrome, так і провайдерів лише з WebSocket. + переходить до прямого рукостискання WebSocket на базовому корені. Це охоплює + як віддалені порти налагодження в стилі Chrome, так і постачальників лише з WebSocket. -Звичайні `ws://host:port` / `wss://host:port` без шляху `/devtools/...`, -спрямовані на локальний екземпляр Chrome, підтримуються через резервну -схему з пріоритетом виявлення — Chrome приймає WebSocket upgrade лише на конкретному -шляху для браузера або цілі, поверненому `/json/version`, тому handshake лише на корені +Звичайний `ws://host:port` / `wss://host:port` без шляху `/devtools/...`, +спрямований на локальний екземпляр Chrome, підтримується через резервний механізм +із пріоритетом виявлення — Chrome приймає оновлення до WebSocket лише на конкретному шляху +для браузера або цілі, який повертає `/json/version`, тому лише рукостискання на базовому корені завершиться невдачею. ### Browserbase [Browserbase](https://www.browserbase.com) — це хмарна платформа для запуску -headless-браузерів із вбудованим розв’язанням CAPTCHA, stealth mode та residential -proxy. +браузерів у режимі headless із вбудованим розв’язанням CAPTCHA, stealth mode та резидентними +проксі. ```json5 { @@ -372,52 +372,52 @@ proxy. Примітки: - [Зареєструйтеся](https://www.browserbase.com/sign-up) і скопіюйте свій **API Key** - з [панелі керування Overview](https://www.browserbase.com/overview). -- Замініть `` на ваш справжній API key Browserbase. + з [панелі Overview](https://www.browserbase.com/overview). +- Замініть `` на ваш справжній API-ключ Browserbase. - Browserbase автоматично створює сесію браузера під час підключення WebSocket, тому - ручний крок створення сесії не потрібен. + окремий ручний етап створення сесії не потрібен. - Безкоштовний тариф дозволяє одну одночасну сесію та одну годину браузера на місяць. - Обмеження платних тарифів дивіться в [pricing](https://www.browserbase.com/pricing). -- Повний довідник API, - посібники з SDK та приклади інтеграції дивіться в [документації Browserbase](https://docs.browserbase.com). + Ліміти платних планів дивіться в [pricing](https://www.browserbase.com/pricing). +- Дивіться [документацію Browserbase](https://docs.browserbase.com) для повного + довідника API, посібників з SDK та прикладів інтеграції. ## Безпека Ключові ідеї: - Керування браузером доступне лише через loopback; доступ проходить через автентифікацію Gateway або спарювання вузлів. -- Окремий loopback HTTP API браузера використовує **лише автентифікацію за спільним секретом**: - bearer auth через токен gateway, `x-openclaw-password` або HTTP Basic auth із +- Автономний loopback HTTP API браузера використовує **лише автентифікацію через спільний секрет**: + bearer-автентифікацію за токеном gateway, `x-openclaw-password` або HTTP Basic auth із налаштованим паролем gateway. - Заголовки ідентичності Tailscale Serve та `gateway.auth.mode: "trusted-proxy"` - **не** автентифікують цей окремий loopback API браузера. -- Якщо керування браузером увімкнено і не налаштовано жодної автентифікації за спільним секретом, OpenClaw + **не** автентифікують цей автономний loopback API браузера. +- Якщо керування браузером увімкнено й не налаштовано жодної автентифікації через спільний секрет, OpenClaw автоматично генерує `gateway.auth.token` під час запуску та зберігає його в конфігурації. - OpenClaw **не** генерує цей токен автоматично, якщо `gateway.auth.mode` уже має значення `password`, `none` або `trusted-proxy`. -- Тримайте Gateway і будь-які вузли-хости у приватній мережі (Tailscale); уникайте публічного доступу. -- Розглядайте URL/токени віддаленого CDP як секрети; віддавайте перевагу змінним середовища або менеджеру секретів. +- Тримайте Gateway та будь-які вузли-хости в приватній мережі (Tailscale); уникайте публічного доступу. +- Ставтеся до віддалених URL/tокенів CDP як до секретів; надавайте перевагу змінним середовища або менеджеру секретів. Поради щодо віддаленого CDP: -- За можливості віддавайте перевагу зашифрованим кінцевим точкам (HTTPS або WSS) і токенам із коротким строком дії. +- За можливості надавайте перевагу зашифрованим кінцевим точкам (HTTPS або WSS) і токенам із коротким строком життя. - Уникайте вбудовування довгоживучих токенів безпосередньо у файли конфігурації. ## Профілі (кілька браузерів) -OpenClaw підтримує кілька іменованих профілів (конфігурацій маршрутизації). Профілі можуть бути такими: +OpenClaw підтримує кілька іменованих профілів (конфігурацій маршрутизації). Профілі можуть бути: -- **керовані openclaw**: окремий екземпляр браузера на базі Chromium із власним каталогом користувацьких даних + портом CDP -- **віддалені**: явна URL-адреса CDP (браузер на базі Chromium працює десь в іншому місці) -- **наявна сесія**: ваш наявний профіль Chrome через автопідключення Chrome DevTools MCP +- **керовані openclaw**: окремий екземпляр браузера на базі Chromium із власним каталогом користувацьких даних та портом CDP +- **віддалені**: явно заданий URL CDP (браузер на базі Chromium, що працює деінде) +- **наявна сесія**: ваш наявний профіль Chrome через автоматичне підключення Chrome DevTools MCP -За замовчуванням: +Типові значення: -- Профіль `openclaw` створюється автоматично, якщо його немає. -- Профіль `user` є вбудованим для підключення до наявної сесії Chrome MCP. -- Профілі наявної сесії, окрім `user`, вмикаються явно; створюйте їх за допомогою `--driver existing-session`. -- Локальні порти CDP за замовчуванням виділяються з діапазону **18800–18899**. -- Видалення профілю переміщує його локальний каталог даних до Смітника. +- Профіль `openclaw` автоматично створюється, якщо відсутній. +- Профіль `user` вбудований для підключення наявної сесії Chrome MCP. +- Профілі existing-session, окрім `user`, є необов’язковими; створюйте їх за допомогою `--driver existing-session`. +- Локальні порти CDP типово виділяються з діапазону **18800–18899**. +- Видалення профілю переміщує його локальний каталог даних до Кошика. Усі кінцеві точки керування приймають `?profile=`; CLI використовує `--browser-profile`. @@ -427,21 +427,21 @@ OpenClaw також може підключатися до запущеного офіційний сервер Chrome DevTools MCP. Це повторно використовує вкладки та стан входу, які вже відкриті в цьому профілі браузера. -Офіційні довідкові матеріали та налаштування: +Офіційні довідкові матеріали та посилання з налаштування: -- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) -- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp) +- [Chrome for Developers: Використання Chrome DevTools MCP із вашою сесією браузера](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) +- [README Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) Вбудований профіль: - `user` -Необов’язково: створіть власний профіль existing-session, якщо хочете -іншу назву, колір або каталог даних браузера. +Необов’язково: створіть власний профіль existing-session, якщо вам потрібні +інша назва, колір або каталог даних браузера. Типова поведінка: -- Вбудований профіль `user` використовує автопідключення Chrome MCP, яке націлюється на +- Вбудований профіль `user` використовує автоматичне підключення Chrome MCP, яке націлюється на типовий локальний профіль Google Chrome. Використовуйте `userDataDir` для Brave, Edge, Chromium або нетипового профілю Chrome: @@ -465,7 +465,7 @@ OpenClaw також може підключатися до запущеного 1. Відкрийте сторінку inspect цього браузера для віддаленого налагодження. 2. Увімкніть віддалене налагодження. -3. Тримайте браузер запущеним і підтвердьте запит на підключення, коли OpenClaw під’єднається. +3. Залиште браузер запущеним і підтвердьте запит на підключення, коли OpenClaw під’єднається. Поширені сторінки inspect: @@ -473,7 +473,7 @@ OpenClaw також може підключатися до запущеного - Brave: `brave://inspect/#remote-debugging` - Edge: `edge://inspect/#remote-debugging` -Smoke test для живого підключення: +Live attach smoke test: ```bash openclaw browser --browser-profile user start @@ -482,68 +482,70 @@ openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot --format ai ``` -Ознаки успіху: +Як виглядає успіх: - `status` показує `driver: existing-session` - `status` показує `transport: chrome-mcp` - `status` показує `running: true` -- `tabs` показує перелік уже відкритих вкладок браузера -- `snapshot` повертає refs з вибраної активної вкладки +- `tabs` перелічує вже відкриті у вашому браузері вкладки +- `snapshot` повертає refs із вибраної live-вкладки Що перевірити, якщо підключення не працює: - цільовий браузер на базі Chromium має версію `144+` -- у сторінці inspect цього браузера увімкнено віддалене налагодження -- браузер показав запит на згоду підключення, і ви його підтвердили -- `openclaw doctor` мігрує стару конфігурацію браузера на основі розширення і перевіряє, - що Chrome локально встановлено для типових профілів автопідключення, але він не може - увімкнути віддалене налагодження на боці браузера за вас +- у сторінці inspect цього браузера ввімкнено віддалене налагодження +- браузер показав запит на підключення, і ви його прийняли +- `openclaw doctor` мігрує стару конфігурацію браузера на основі розширення та перевіряє, що + Chrome встановлено локально для типових профілів автоматичного підключення, але він не може + увімкнути віддалене налагодження в самому браузері за вас Використання агентом: - Використовуйте `profile="user"`, коли вам потрібен стан браузера користувача з виконаним входом. - Якщо ви використовуєте власний профіль existing-session, передайте явну назву цього профілю. -- Вибирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб підтвердити +- Обирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб підтвердити запит на підключення. - Gateway або вузол-хост можуть запускати `npx chrome-devtools-mcp@latest --autoConnect` Примітки: - Цей шлях має вищий ризик, ніж ізольований профіль `openclaw`, оскільки він може - діяти всередині вашої сесії браузера з виконаним входом. + виконувати дії у вашій сесії браузера, де вже виконано вхід. - OpenClaw не запускає браузер для цього драйвера; він підключається лише до наявної сесії. -- OpenClaw тут використовує офіційний потік `--autoConnect` Chrome DevTools MCP. Якщо - задано `userDataDir`, OpenClaw передає його далі, щоб націлитися на цей явний +- Тут OpenClaw використовує офіційний потік Chrome DevTools MCP `--autoConnect`. Якщо + встановлено `userDataDir`, OpenClaw передає його далі, щоб націлитися на цей явний каталог користувацьких даних Chromium. -- Скріншоти existing-session підтримують захоплення сторінки та захоплення елементів через `--ref` - зі знімків стану, але не підтримують CSS-селектори `--element`. -- Скріншоти сторінки existing-session працюють без Playwright через Chrome MCP. - Скріншоти елементів за ref (`--ref`) там теж працюють, але `--full-page` +- Скриншоти existing-session підтримують захоплення сторінки та захоплення елементів через `--ref` + зі знімків, але не CSS-селектори `--element`. +- Скриншоти сторінок existing-session працюють без Playwright через Chrome MCP. + Скриншоти елементів за ref (`--ref`) також працюють там, але `--full-page` не можна поєднувати з `--ref` або `--element`. -- Дії existing-session все ще обмеженіші, ніж у шляху керованого браузера: +- Дії existing-session усе ще більш обмежені, ніж у режимі + керованого браузера: - `click`, `type`, `hover`, `scrollIntoView`, `drag` і `select` потребують snapshot refs замість CSS-селекторів - - `click` підтримує лише ліву кнопку миші (без перевизначення кнопок або модифікаторів) + - `click` підтримує лише ліву кнопку (без перевизначення кнопки чи модифікаторів) - `type` не підтримує `slowly=true`; використовуйте `fill` або `press` - `press` не підтримує `delayMs` - `hover`, `scrollIntoView`, `drag`, `select`, `fill` і `evaluate` не - підтримують перевизначення timeout для окремого виклику + підтримують перевизначення тайм-ауту для окремого виклику - `select` наразі підтримує лише одне значення -- Existing-session `wait --url` підтримує точні, підрядкові та glob-шаблони, - як і інші драйвери браузера. `wait --load networkidle` поки не підтримується. -- Хуки завантаження файлів existing-session вимагають `ref` або `inputRef`, підтримують по одному файлу за раз і не підтримують CSS-націлювання через `element`. -- Хуки діалогів existing-session не підтримують перевизначення timeout. -- Деякі можливості все ще потребують шляху керованого браузера, зокрема пакетні +- Existing-session `wait --url` підтримує точні, підрядкові та glob-шаблони + так само, як і інші драйвери браузера. `wait --load networkidle` поки не підтримується. +- Хуки вивантаження в existing-session потребують `ref` або `inputRef`, підтримують по одному файлу за раз і не підтримують націлювання на CSS `element`. +- Хуки діалогів existing-session не підтримують перевизначення тайм-ауту. +- Деякі можливості все ще потребують керованого шляху браузера, зокрема пакетні дії, експорт PDF, перехоплення завантажень і `responsebody`. -- Existing-session є локальним для хоста. Якщо Chrome розташований на іншій машині або - в іншому просторі імен мережі, натомість використовуйте віддалений CDP або вузол-хост. +- Existing-session може підключатися на вибраному хості або через підключений + вузол браузера. Якщо Chrome розташований деінде й вузол браузера не підключений, використовуйте + віддалений CDP або вузол-хост. ## Гарантії ізоляції -- **Окремий каталог користувацьких даних**: ніколи не торкається профілю вашого особистого браузера. +- **Окремий каталог користувацьких даних**: ніколи не торкається вашого особистого профілю браузера. - **Окремі порти**: уникає `9222`, щоб запобігти конфліктам із робочими процесами розробки. -- **Детерміноване керування вкладками**: націлювання на вкладки за `targetId`, а не за принципом «остання вкладка». +- **Детерміноване керування вкладками**: націлення на вкладки за `targetId`, а не за принципом “остання вкладка”. ## Вибір браузера @@ -555,13 +557,13 @@ openclaw browser --browser-profile user snapshot --format ai 4. Chromium 5. Chrome Canary -Ви можете перевизначити це за допомогою `browser.executablePath`. +Ви можете перевизначити це через `browser.executablePath`. Платформи: -- macOS: перевіряються `/Applications` і `~/Applications`. +- macOS: перевіряє `/Applications` і `~/Applications`. - Linux: шукає `google-chrome`, `brave`, `microsoft-edge`, `chromium` тощо. -- Windows: перевіряє типові місця встановлення. +- Windows: перевіряє поширені каталоги встановлення. ## API керування (необов’язково) @@ -569,7 +571,7 @@ openclaw browser --browser-profile user snapshot --format ai - Стан/запуск/зупинка: `GET /`, `POST /start`, `POST /stop` - Вкладки: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId` -- Знімок стану/скриншот: `GET /snapshot`, `POST /screenshot` +- Знімок/скриншот: `GET /snapshot`, `POST /screenshot` - Дії: `POST /navigate`, `POST /act` - Хуки: `POST /hooks/file-chooser`, `POST /hooks/dialog` - Завантаження: `POST /download`, `POST /wait/download` @@ -582,22 +584,22 @@ openclaw browser --browser-profile user snapshot --format ai Усі кінцеві точки приймають `?profile=`. -Якщо налаштовано автентифікацію gateway за спільним секретом, маршрути браузера HTTP також вимагають автентифікації: +Якщо налаштовано автентифікацію gateway через спільний секрет, HTTP-маршрути браузера також потребують автентифікації: - `Authorization: Bearer ` - `x-openclaw-password: ` або HTTP Basic auth із цим паролем Примітки: -- Цей окремий loopback API браузера **не** використовує trusted-proxy або +- Цей автономний loopback API браузера **не** використовує trusted-proxy або заголовки ідентичності Tailscale Serve. - Якщо `gateway.auth.mode` має значення `none` або `trusted-proxy`, ці loopback-маршрути браузера - не успадковують ці режими з передаванням ідентичності; залишайте їх доступними лише через loopback. + не успадковують ці режими з перенесенням ідентичності; тримайте їх доступними лише через loopback. ### Контракт помилок `/act` -`POST /act` використовує структуровану відповідь про помилку для валідації на рівні маршруту та -збоїв політик: +`POST /act` використовує структуровану відповідь помилки для валідації на рівні маршруту та +збоїв політики: ```json { "error": "", "code": "ACT_*" } @@ -606,48 +608,48 @@ openclaw browser --browser-profile user snapshot --format ai Поточні значення `code`: - `ACT_KIND_REQUIRED` (HTTP 400): `kind` відсутній або не розпізнаний. -- `ACT_INVALID_REQUEST` (HTTP 400): корисне навантаження дії не пройшло нормалізацію або валідацію. -- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` було використано з непідтримуваним типом дії. +- `ACT_INVALID_REQUEST` (HTTP 400): payload дії не пройшов нормалізацію або валідацію. +- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` використано з непідтримуваним типом дії. - `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (або `wait --fn`) вимкнено в конфігурації. -- `ACT_TARGET_ID_MISMATCH` (HTTP 403): верхньорівневий або пакетний `targetId` конфліктує з ціллю запиту. +- `ACT_TARGET_ID_MISMATCH` (HTTP 403): top-level `targetId` або `targetId` у пакеті конфліктує з ціллю запиту. - `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): дія не підтримується для профілів existing-session. -Інші збої під час виконання все ще можуть повертати `{ "error": "" }` без +Інші збої runtime усе ще можуть повертати `{ "error": "" }` без поля `code`. ### Вимога Playwright -Деякі можливості (`navigate`/`act`/AI snapshot/role snapshot, скриншоти елементів, +Деякі можливості (navigate/act/AI snapshot/role snapshot, скриншоти елементів, PDF) потребують Playwright. Якщо Playwright не встановлено, ці кінцеві точки повертають зрозумілу помилку 501. Що все ще працює без Playwright: - ARIA snapshots -- Скріншоти сторінки для керованого браузера `openclaw`, коли доступний WebSocket - CDP для окремої вкладки -- Скріншоти сторінки для профілів `existing-session` / Chrome MCP -- Скріншоти `existing-session` на основі ref (`--ref`) з виводу snapshot +- Скриншоти сторінок для керованого браузера `openclaw`, коли для вкладки доступний CDP + WebSocket +- Скриншоти сторінок для профілів `existing-session` / Chrome MCP +- Скриншоти existing-session на основі ref (`--ref`) з виводу snapshot Що все ще потребує Playwright: - `navigate` - `act` - AI snapshots / role snapshots -- Скріншоти елементів за CSS-селектором (`--element`) +- Скриншоти елементів за CSS-селектором (`--element`) - Повний експорт PDF браузера -Скріншоти елементів також відхиляють `--full-page`; маршрут повертає `fullPage is +Скриншоти елементів також відхиляють `--full-page`; маршрут повертає `fullPage is not supported for element screenshots`. Якщо ви бачите `Playwright is not available in this gateway build`, установіть повний пакет Playwright (не `playwright-core`) і перезапустіть gateway або перевстановіть -OpenClaw з підтримкою браузера. +OpenClaw із підтримкою браузера. #### Установлення Playwright у Docker Якщо ваш Gateway працює в Docker, уникайте `npx playwright` (конфлікти npm override). -Натомість використовуйте вбудований CLI: +Замість цього використовуйте вбудований CLI: ```bash docker compose run --rm openclaw-cli \ @@ -660,7 +662,7 @@ docker compose run --rm openclaw-cli \ ## Як це працює (внутрішньо) -Потік верхнього рівня: +Потік високого рівня: - Невеликий **сервер керування** приймає HTTP-запити. - Він підключається до браузерів на базі Chromium (Chrome/Brave/Edge/Chromium) через **CDP**. @@ -668,15 +670,15 @@ docker compose run --rm openclaw-cli \ CDP. - Коли Playwright відсутній, доступні лише операції без Playwright. -Ця архітектура надає агенту стабільний, детермінований інтерфейс і водночас дозволяє -вам змінювати локальні/віддалені браузери та профілі. +Ця архітектура забезпечує для агента стабільний, детермінований інтерфейс, водночас дозволяючи +вам замінювати локальні/віддалені браузери та профілі. ## Короткий довідник CLI -Усі команди приймають `--browser-profile ` для націлювання на конкретний профіль. -Усі команди також приймають `--json` для машинозчитуваного виводу (стабільні корисні навантаження). +Усі команди приймають `--browser-profile ` для націлення на конкретний профіль. +Усі команди також приймають `--json` для машинозчитуваного виводу (стабільні payload). -Базові команди: +Основи: - `openclaw browser status` - `openclaw browser start` @@ -690,7 +692,7 @@ docker compose run --rm openclaw-cli \ - `openclaw browser focus abcd1234` - `openclaw browser close abcd1234` -Перевірка та огляд: +Перевірка: - `openclaw browser screenshot` - `openclaw browser screenshot --full-page` @@ -707,8 +709,8 @@ docker compose run --rm openclaw-cli \ Примітка щодо життєвого циклу: -- Для профілів лише з підключенням і профілів віддаленого CDP `openclaw browser stop` усе ще є - правильною командою очищення після тестів. Вона закриває активну сесію керування і +- Для профілів лише з підключенням і віддаленим CDP `openclaw browser stop` усе ще є + правильною командою очищення після тестів. Вона закриває активну сесію керування та очищає тимчасові перевизначення емуляції замість завершення базового браузера. - `openclaw browser errors --clear` @@ -761,24 +763,24 @@ docker compose run --rm openclaw-cli \ Примітки: -- `upload` і `dialog` — це виклики **попереднього озброєння**; запускайте їх перед click/press, - які запускають file chooser або dialog. -- Шляхи виводу download і trace обмежені тимчасовими кореневими каталогами OpenClaw: +- `upload` і `dialog` — це виклики **підготовки**; запускайте їх перед натисканням/клавішею, + що викликає chooser/dialog. +- Шляхи виводу для download і trace обмежені тимчасовими коренями OpenClaw: - traces: `/tmp/openclaw` (резервний варіант: `${os.tmpdir()}/openclaw`) - downloads: `/tmp/openclaw/downloads` (резервний варіант: `${os.tmpdir()}/openclaw/downloads`) -- Шляхи upload обмежені тимчасовим кореневим каталогом upload OpenClaw: +- Шляхи upload обмежені тимчасовим коренем завантажень OpenClaw: - uploads: `/tmp/openclaw/uploads` (резервний варіант: `${os.tmpdir()}/openclaw/uploads`) -- `upload` також може напряму задавати file inputs через `--input-ref` або `--element`. +- `upload` також може напряму встановлювати file input через `--input-ref` або `--element`. - `snapshot`: - `--format ai` (типово, коли встановлено Playwright): повертає AI snapshot із числовими refs (`aria-ref=""`). - - `--format aria`: повертає дерево accessibility (без refs; лише для огляду). - - `--efficient` (або `--mode efficient`): компактний preset role snapshot (interactive + compact + depth + менший maxChars). - - Типове значення конфігурації (лише для tool/CLI): установіть `browser.snapshotDefaults.mode: "efficient"`, щоб використовувати efficient snapshots, коли викликаюча сторона не передає режим (див. [Конфігурація Gateway](/uk/gateway/configuration-reference#browser)). - - Параметри role snapshot (`--interactive`, `--compact`, `--depth`, `--selector`) примусово використовують snapshot на основі ролей із refs на кшталт `ref=e12`. - - `--frame "