From a8898e4969f1ef2b358b443a445e6ddb682add75 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 12 Apr 2026 18:29:29 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/channels/group-messages.md | 52 +- docs/uk/concepts/active-memory.md | 426 +++-- docs/uk/concepts/agent-loop.md | 168 +- docs/uk/concepts/context.md | 167 +- docs/uk/gateway/security/index.md | 1135 ++++++------ docs/uk/help/debugging.md | 95 +- docs/uk/help/faq.md | 2648 ++++++++++++++++++++-------- docs/uk/tools/slash-commands.md | 287 +-- docs/uk/tools/thinking.md | 123 +- 9 files changed, 3150 insertions(+), 1951 deletions(-) diff --git a/docs/uk/channels/group-messages.md b/docs/uk/channels/group-messages.md index 444f7cec4..371b27304 100644 --- a/docs/uk/channels/group-messages.md +++ b/docs/uk/channels/group-messages.md @@ -1,36 +1,36 @@ --- read_when: - Зміна правил групових повідомлень або згадок -summary: Поведінка та конфігурація для обробки групових повідомлень WhatsApp (`mentionPatterns` є спільними для різних поверхонь) +summary: Поведінка та конфігурація для обробки групових повідомлень WhatsApp (mentionPatterns спільні для всіх поверхонь) title: Групові повідомлення x-i18n: - generated_at: "2026-04-05T17:57:38Z" + generated_at: "2026-04-12T18:22:01Z" model: gpt-5.4 provider: openai - source_hash: 2543be5bc4c6f188f955df580a6fef585ecbfc1be36ade5d34b1a9157e021bc5 + source_hash: 5d9484dd1de74d42f8dce4c3ac80d60c24864df30a7802e64893ef55506230fe source_path: channels/group-messages.md workflow: 15 --- -# Групові повідомлення (канал WhatsApp web) +# Групові повідомлення (веб-канал WhatsApp) -Мета: дати змогу Clawd бути в групах WhatsApp, прокидатися лише коли його згадують, і тримати цей тред окремо від особистої DM-сесії. +Мета: дозволити Clawd бути присутнім у групах WhatsApp, прокидатися лише коли його пінгують, і тримати цей потік окремо від особистої сесії в DM. -Примітка: `agents.list[].groupChat.mentionPatterns` тепер також використовується в Telegram/Discord/Slack/iMessage; цей документ зосереджений на поведінці, специфічній для WhatsApp. Для конфігурацій із кількома агентами задавайте `agents.list[].groupChat.mentionPatterns` для кожного агента окремо (або використовуйте `messages.groupChat.mentionPatterns` як глобальний резервний варіант). +Примітка: `agents.list[].groupChat.mentionPatterns` тепер також використовується для Telegram/Discord/Slack/iMessage; цей документ зосереджений на поведінці, специфічній для WhatsApp. Для конфігурацій із кількома агентами задавайте `agents.list[].groupChat.mentionPatterns` для кожного агента окремо (або використовуйте `messages.groupChat.mentionPatterns` як глобальний запасний варіант). ## Поточна реалізація (2025-12-03) -- Режими активації: `mention` (типово) або `always`. `mention` вимагає згадки (справжні @-згадки WhatsApp через `mentionedJids`, безпечні regex-шаблони або E.164 номер бота будь-де в тексті). `always` пробуджує агента на кожне повідомлення, але він має відповідати лише тоді, коли може додати справді корисну цінність; інакше він повертає точний тихий токен `NO_REPLY` / `no_reply`. Типові значення можна задати в конфігурації (`channels.whatsapp.groups`) і перевизначити для кожної групи через `/activation`. Якщо задано `channels.whatsapp.groups`, це також працює як allowlist груп (включіть `"*"` , щоб дозволити всі). -- Політика для груп: `channels.whatsapp.groupPolicy` визначає, чи приймаються групові повідомлення (`open|disabled|allowlist`). Для `allowlist` використовується `channels.whatsapp.groupAllowFrom` (резервно: явний `channels.whatsapp.allowFrom`). Типове значення — `allowlist` (заблоковано, доки ви не додасте відправників). -- Сесії для кожної групи: ключі сесій мають вигляд `agent::whatsapp:group:`, тому команди на кшталт `/verbose on` або `/think high` (надіслані як окремі повідомлення) застосовуються лише до цієї групи; стан особистих DM не змінюється. Heartbeat для групових тредів пропускаються. -- Ін’єкція контексту: групові повідомлення зі статусом **pending-only** (типово 50), які _не_ запустили виконання, додаються на початок у блоці `[Chat messages since your last reply - for context]`, а повідомлення-тригер — у блоці `[Current message - respond to this]`. Повідомлення, які вже є в сесії, не додаються повторно. -- Відображення відправника: кожна групова партія тепер завершується рядком `[from: Ім’я відправника (+E164)]`, щоб Pi знав, хто говорить. -- Ephemeral/view-once: ми розгортаємо їх перед витягуванням тексту/згадок, тож згадки всередині них теж запускають спрацювання. -- Системний промпт групи: на першому ході групової сесії (і щоразу, коли `/activation` змінює режим) ми додаємо короткий фрагмент до системного промпта, наприклад `You are replying inside the WhatsApp group "". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` Якщо метадані недоступні, ми все одно повідомляємо агенту, що це груповий чат. +- Режими активації: `mention` (типово) або `always`. `mention` вимагає пінг (справжні @-згадки WhatsApp через `mentionedJids`, безпечні regex-шаблони або E.164 номер бота будь-де в тексті). `always` пробуджує агента на кожне повідомлення, але він має відповідати лише тоді, коли може додати змістовну цінність; інакше він повертає точний тихий токен `NO_REPLY` / `no_reply`. Типові значення можна задати в конфігурації (`channels.whatsapp.groups`) і перевизначити для кожної групи через `/activation`. Коли задано `channels.whatsapp.groups`, це також працює як список дозволених груп (додайте `"*"` для дозволу всіх). +- Політика груп: `channels.whatsapp.groupPolicy` керує тим, чи приймаються групові повідомлення (`open|disabled|allowlist`). `allowlist` використовує `channels.whatsapp.groupAllowFrom` (запасний варіант: явний `channels.whatsapp.allowFrom`). Типове значення — `allowlist` (блокується, доки ви не додасте відправників). +- Сесії для кожної групи: ключі сесій мають вигляд `agent::whatsapp:group:`, тому такі команди, як `/verbose on`, `/trace on` або `/think high` (надіслані як окремі повідомлення), обмежуються цією групою; стан особистих DM не змінюється. Heartbeat для групових потоків пропускаються. +- Додавання контексту: групові повідомлення **лише в очікуванні** (типово 50), які _не_ запустили виконання, додаються на початку під `[Chat messages since your last reply - for context]`, а рядок, що спрацював як тригер, — під `[Current message - respond to this]`. Повідомлення, які вже є в сесії, не додаються повторно. +- Відображення відправника: кожен пакет групових повідомлень тепер завершується рядком `[from: Sender Name (+E164)]`, щоб Pi знав, хто говорить. +- Ephemeral/view-once: ми розгортаємо їх перед витягуванням тексту/згадок, тому пінги всередині них також спрацьовують. +- Системний prompt групи: на першому ході групової сесії (і щоразу, коли `/activation` змінює режим) ми додаємо короткий фрагмент у системний prompt, наприклад `You are replying inside the WhatsApp group "". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` Якщо метадані недоступні, ми все одно повідомляємо агенту, що це груповий чат. ## Приклад конфігурації (WhatsApp) -Додайте блок `groupChat` до `~/.openclaw/openclaw.json`, щоб згадки за відображуваним іменем працювали навіть тоді, коли WhatsApp прибирає візуальний `@` із тексту повідомлення: +Додайте блок `groupChat` до `~/.openclaw/openclaw.json`, щоб згадки за відображуваним іменем працювали навіть тоді, коли WhatsApp прибирає візуальний `@` з тексту повідомлення: ```json5 { @@ -57,8 +57,8 @@ x-i18n: Примітки: -- Ці regex нечутливі до регістру та використовують ті самі захисні обмеження safe-regex, що й інші поверхні конфігурації regex; недійсні шаблони та небезпечні вкладені повторення ігноруються. -- WhatsApp усе ще надсилає канонічні згадки через `mentionedJids`, коли хтось торкається контакту, тож резервний варіант із номером рідко потрібен, але є корисною страховкою. +- Ці regex є нечутливими до регістру та використовують ті самі захисні обмеження safe-regex, що й інші поверхні конфігурації regex; недійсні шаблони та небезпечні вкладені повторення ігноруються. +- WhatsApp усе ще надсилає канонічні згадки через `mentionedJids`, коли хтось торкається контакту, тож запасний варіант із номером рідко потрібен, але є корисною страховкою. ### Команда активації (лише для власника) @@ -67,25 +67,25 @@ x-i18n: - `/activation mention` - `/activation always` -Змінювати це може лише номер власника (з `channels.whatsapp.allowFrom`, або власний E.164 номер бота, якщо не задано). Надішліть `/status` як окреме повідомлення в групі, щоб побачити поточний режим активації. +Лише номер власника (з `channels.whatsapp.allowFrom`, або власний E.164 бота, якщо не задано) може це змінити. Надішліть `/status` як окреме повідомлення в групу, щоб побачити поточний режим активації. ## Як використовувати 1. Додайте свій обліковий запис WhatsApp (той, на якому працює OpenClaw) до групи. -2. Напишіть `@openclaw …` (або вкажіть номер). Лише відправники з allowlist можуть його запускати, якщо ви не встановили `groupPolicy: "open"`. -3. Промпт агента включатиме нещодавній груповий контекст і завершальний маркер `[from: …]`, щоб він міг звернутися до правильної людини. -4. Директиви рівня сесії (`/verbose on`, `/think high`, `/new` або `/reset`, `/compact`) застосовуються лише до сесії цієї групи; надсилайте їх як окремі повідомлення, щоб вони зареєструвалися. Ваша особиста DM-сесія залишається незалежною. +2. Скажіть `@openclaw …` (або вкажіть номер). Лише відправники зі списку дозволених можуть його запускати, якщо тільки ви не встановите `groupPolicy: "open"`. +3. Prompt агента міститиме нещодавній груповий контекст плюс кінцевий маркер `[from: …]`, щоб він міг звернутися до правильної людини. +4. Директиви рівня сесії (`/verbose on`, `/trace on`, `/think high`, `/new` або `/reset`, `/compact`) застосовуються лише до сесії цієї групи; надсилайте їх як окремі повідомлення, щоб вони зареєструвалися. Ваша особиста DM-сесія залишається незалежною. ## Тестування / перевірка -- Ручна перевірка: - - Надішліть згадку `@openclaw` у групі й переконайтеся, що відповідь посилається на ім’я відправника. - - Надішліть другу згадку й перевірте, що блок історії включається, а потім очищується на наступному ході. +- Ручний smoke-тест: + - Надішліть пінг `@openclaw` у групі та підтвердьте відповідь, яка посилається на ім’я відправника. + - Надішліть другий пінг і перевірте, що блок історії включається, а потім очищується на наступному ході. - Перевірте журнали gateway (запустіть із `--verbose`), щоб побачити записи `inbound web message`, які показують `from: ` і суфікс `[from: …]`. ## Відомі особливості - Heartbeat навмисно пропускаються для груп, щоб уникнути шумних широкомовних повідомлень. -- Придушення ехо використовує об’єднаний рядок партії; якщо ви двічі надсилаєте однаковий текст без згадок, відповідь буде лише на перше повідомлення. -- Записи в сховищі сесій матимуть вигляд `agent::whatsapp:group:` у сховищі сесій (типово `~/.openclaw/agents//sessions/sessions.json`); відсутній запис просто означає, що група ще не запускала виконання. -- Індикатори набору в групах дотримуються `agents.defaults.typingMode` (типово: `message`, коли немає згадки). +- Придушення ехо використовує об’єднаний рядок пакета; якщо ви двічі надішлете однаковий текст без згадок, відповідь буде лише на перший раз. +- Записи в сховищі сесій відображатимуться як `agent::whatsapp:group:` у сховищі сесій (`~/.openclaw/agents//sessions/sessions.json` типово); відсутній запис лише означає, що група ще не запускала виконання. +- Індикатори набору тексту в групах дотримуються `agents.defaults.typingMode` (типово: `message`, коли немає згадки). diff --git a/docs/uk/concepts/active-memory.md b/docs/uk/concepts/active-memory.md index ca82404de..1b4e2bac1 100644 --- a/docs/uk/concepts/active-memory.md +++ b/docs/uk/concepts/active-memory.md @@ -1,36 +1,36 @@ --- read_when: - - Ви хочете зрозуміти, для чого потрібна активна пам’ять - - Ви хочете ввімкнути активну пам’ять для розмовного агента - - Ви хочете налаштувати поведінку активної пам’яті, не вмикаючи її всюди -summary: Підлеглий агент блокувальної пам’яті, що належить плагіну, який впроваджує релевантну пам’ять в інтерактивні сеанси чату -title: Активна пам’ять + - Ви хочете зрозуміти, для чого потрібна Active Memory + - Ви хочете ввімкнути Active Memory для розмовного агента + - Ви хочете налаштувати поведінку Active Memory, не вмикаючи її всюди +summary: Керований Plugin блокувальний підагент пам’яті, який впроваджує релевантну пам’ять в інтерактивні сеанси чату +title: Active Memory x-i18n: - generated_at: "2026-04-12T04:23:29Z" + generated_at: "2026-04-12T18:22:02Z" model: gpt-5.4 provider: openai - source_hash: 59456805c28daaab394ba2a7f87e1104a1334a5cf32dbb961d5d232d9c471d84 + source_hash: dc15b2139618d9dbb0ba4d9951fb82a4d86076f7b8dc1a6bf2013bcce61878c4 source_path: concepts/active-memory.md workflow: 15 --- -# Активна пам’ять +# Active Memory -Активна пам’ять — це необов’язковий підлеглий агент блокувальної пам’яті, що належить плагіну й запускається -перед основною відповіддю для відповідних розмовних сеансів. +Active Memory — це необов’язковий керований Plugin блокувальний підагент пам’яті, який запускається +перед основною відповіддю для придатних розмовних сеансів. -Вона існує тому, що більшість систем пам’яті є потужними, але реактивними. Вони покладаються на -те, що основний агент сам вирішить, коли шукати в пам’яті, або на те, що користувач скаже щось -на кшталт «запам’ятай це» чи «пошукай у пам’яті». На той момент мить, коли пам’ять могла б -зробити відповідь природнішою, уже минула. +Він існує тому, що більшість систем пам’яті є потужними, але реактивними. Вони покладаються на те, +що головний агент вирішить, коли шукати в пам’яті, або на те, що користувач скаже щось на кшталт +«запам’ятай це» чи «пошукай у пам’яті». На той момент мить, коли пам’ять могла б зробити відповідь +природною, уже минула. -Активна пам’ять дає системі одну обмежену можливість підставити релевантну пам’ять +Active Memory дає системі одну обмежену можливість показати релевантну пам’ять до того, як буде згенеровано основну відповідь. -## Вставте це у свого агента +## Вставте це у свій агент -Вставте це у свого агента, якщо хочете ввімкнути Активну пам’ять із -самодостатнім налаштуванням із безпечними значеннями за замовчуванням: +Вставте це у свій агент, якщо хочете ввімкнути Active Memory із +самодостатнім і безпечним типово налаштуванням: ```json5 { @@ -56,30 +56,30 @@ x-i18n: } ``` -Це вмикає плагін для агента `main`, за замовчуванням обмежує його -сеансами у стилі прямих повідомлень, дає змогу спочатку успадкувати модель поточного сеансу -та використовує налаштовану резервну модель лише тоді, коли немає -явно заданої або успадкованої моделі. +Це вмикає Plugin для агента `main`, типово обмежує його сеансами +у стилі прямих повідомлень, дає йому змогу спочатку успадковувати модель поточного сеансу та +використовує налаштовану резервну модель лише якщо жодна явна або успадкована модель недоступна. -Після цього перезапустіть шлюз: +Після цього перезапустіть Gateway: ```bash openclaw gateway ``` -Щоб перевірити це наживо в розмові: +Щоб переглянути це наживо в розмові: ```text /verbose on +/trace on ``` -## Увімкнення активної пам’яті +## Увімкнення active memory -Найбезпечніше налаштування таке: +Найбезпечніше налаштування: -1. увімкнути плагін +1. увімкнути Plugin 2. націлити його на одного розмовного агента -3. залишити журналювання ввімкненим лише під час налаштування +3. залишати журналювання увімкненим лише під час налаштування Почніть із цього в `openclaw.json`: @@ -106,7 +106,7 @@ openclaw gateway } ``` -Потім перезапустіть шлюз: +Потім перезапустіть Gateway: ```bash openclaw gateway @@ -114,22 +114,22 @@ openclaw gateway Що це означає: -- `plugins.entries.active-memory.enabled: true` вмикає плагін -- `config.agents: ["main"]` підключає до активної пам’яті лише агента `main` -- `config.allowedChatTypes: ["direct"]` за замовчуванням залишає активну пам’ять увімкненою лише для сеансів у стилі прямих повідомлень -- якщо `config.model` не задано, активна пам’ять спочатку успадковує модель поточного сеансу -- `config.modelFallback` за бажанням надає власний резервний постачальник/модель для пригадування +- `plugins.entries.active-memory.enabled: true` вмикає Plugin +- `config.agents: ["main"]` підключає до active memory лише агента `main` +- `config.allowedChatTypes: ["direct"]` типово залишає active memory увімкненою лише для сеансів у стилі прямих повідомлень +- якщо `config.model` не задано, active memory спочатку успадковує модель поточного сеансу +- `config.modelFallback` за бажанням надає вашу резервну модель провайдера для відновлення пам’яті - `config.promptStyle: "balanced"` використовує типовий універсальний стиль підказки для режиму `recent` -- активна пам’ять усе одно запускається лише для відповідних інтерактивних постійних сеансів чату +- active memory однаково запускається лише в придатних інтерактивних постійних сеансах чату ## Як це побачити -Активна пам’ять підставляє прихований системний контекст для моделі. Вона не показує +Active Memory впроваджує прихований системний контекст для моделі. Вона не показує сирі теги `...` клієнту. ## Перемикач сеансу -Використовуйте команду плагіна, якщо хочете призупинити або відновити активну пам’ять для +Використовуйте команду Plugin, коли хочете призупинити або відновити active memory для поточного сеансу чату без редагування конфігурації: ```text @@ -138,11 +138,11 @@ openclaw gateway /active-memory on ``` -Це діє в межах сеансу. Воно не змінює -`plugins.entries.active-memory.enabled`, націлювання на агента чи іншу глобальну +Це має область дії сеансу. Це не змінює +`plugins.entries.active-memory.enabled`, націлення на агентів чи іншу глобальну конфігурацію. -Якщо ви хочете, щоб команда записувала конфігурацію та призупиняла або відновлювала активну пам’ять для +Якщо ви хочете, щоб команда записувала конфігурацію й призупиняла або відновлювала active memory для всіх сеансів, використовуйте явну глобальну форму: ```text @@ -152,32 +152,36 @@ openclaw gateway ``` Глобальна форма записує `plugins.entries.active-memory.config.enabled`. Вона залишає -`plugins.entries.active-memory.enabled` увімкненим, щоб команда й надалі була доступною для -повторного ввімкнення активної пам’яті пізніше. +`plugins.entries.active-memory.enabled` увімкненим, щоб команда залишалася доступною для +повторного ввімкнення active memory пізніше. -Якщо ви хочете побачити, що робить активна пам’ять у живому сеансі, увімкніть докладний режим -для цього сеансу: +Якщо ви хочете побачити, що active memory робить у живому сеансі, увімкніть +перемикачі сеансу, які відповідають потрібному вам виводу: ```text /verbose on +/trace on ``` -Коли докладний режим увімкнено, OpenClaw може показувати: +Коли вони ввімкнені, OpenClaw може показувати: -- рядок стану активної пам’яті, наприклад `Active Memory: ok 842ms recent 34 chars` -- читабельний підсумок налагодження, наприклад `Active Memory Debug: Lemon pepper wings with blue cheese.` +- рядок стану active memory на кшталт `Active Memory: ok 842ms recent 34 chars`, коли ввімкнено `/verbose on` +- зручне для читання підсумкове налагодження на кшталт `Active Memory Debug: Lemon pepper wings with blue cheese.`, коли ввімкнено `/trace on` -Ці рядки походять із того самого проходу активної пам’яті, який формує прихований -системний контекст, але відформатовані для людей замість показу сирої розмітки -підказки. +Ці рядки походять із того самого проходу active memory, який подає прихований +системний контекст, але вони відформатовані для людей замість показу сирої +розмітки підказки. Вони надсилаються як діагностичне повідомлення після +звичайної відповіді асистента, щоб клієнти каналів, як-от Telegram, не показували окрему +діагностичну бульбашку перед відповіддю. -За замовчуванням стенограма підлеглого агента блокувальної пам’яті є тимчасовою та видаляється -після завершення запуску. +Типово транскрипт блокувального підагента пам’яті є тимчасовим і видаляється +після завершення виконання. Приклад потоку: ```text /verbose on +/trace on what wings should i order? ``` @@ -190,37 +194,37 @@ what wings should i order? 🔎 Active Memory Debug: Lemon pepper wings with blue cheese. ``` -## Коли вона запускається +## Коли це запускається -Активна пам’ять використовує два бар’єри: +Active Memory використовує два шлюзи: -1. **Увімкнення в конфігурації** - Плагін має бути ввімкнений, а поточний ідентифікатор агента має бути присутній у +1. **Явне ввімкнення в конфігурації** + Plugin має бути ввімкнений, а ідентифікатор поточного агента має бути присутній у `plugins.entries.active-memory.config.agents`. -2. **Сувора відповідність під час виконання** - Навіть якщо її ввімкнено й націлено, активна пам’ять запускається лише для відповідних +2. **Сувора придатність під час виконання** + Навіть коли Active Memory ввімкнено й націлено, вона запускається лише для придатних інтерактивних постійних сеансів чату. Фактичне правило таке: ```text -плагін увімкнено +plugin enabled + -ідентифікатор агента націлено +agent id targeted + -дозволений тип чату +allowed chat type + -відповідний інтерактивний постійний сеанс чату +eligible interactive persistent chat session = -активна пам’ять запускається +active memory runs ``` -Якщо будь-яка з цих умов не виконується, активна пам’ять не запускається. +Якщо будь-яка з цих умов не виконується, active memory не запускається. ## Типи сеансів -`config.allowedChatTypes` визначає, у яких типах розмов узагалі може запускатися Активна -пам’ять. +`config.allowedChatTypes` керує тим, у яких типах розмов узагалі може запускатися Active +Memory. Типове значення: @@ -228,8 +232,8 @@ what wings should i order? allowedChatTypes: ["direct"] ``` -Це означає, що Активна пам’ять за замовчуванням запускається в сеансах у стилі прямих повідомлень, але -не в групових сеансах або сеансах каналів, якщо ви явно не ввімкнете їх. +Це означає, що Active Memory типово працює в сеансах у стилі прямих повідомлень, але +не в групових сеансах чи сеансах каналів, якщо ви не ввімкнете їх явно. Приклади: @@ -245,44 +249,44 @@ allowedChatTypes: ["direct", "group"] allowedChatTypes: ["direct", "group", "channel"] ``` -## Де вона запускається +## Де це працює -Активна пам’ять — це функція збагачення розмови, а не загальноплатформна +Active memory — це функція покращення розмов, а не загальноплатформна функція інференсу. -| Поверхня | Активна пам’ять запускається? | -| ------------------------------------------------------------------- | ------------------------------------------------------ | -| Постійні сеанси Control UI / вебчату | Так, якщо плагін увімкнений і агент націлений | -| Інші інтерактивні сеанси каналів на тому самому шляху постійного чату | Так, якщо плагін увімкнений і агент націлений | -| Безголові одноразові запуски | Ні | -| Запуски heartbeat/фонові запуски | Ні | -| Загальні внутрішні шляхи `agent-command` | Ні | -| Виконання підлеглих агентів/внутрішніх допоміжних засобів | Ні | +| Поверхня | Active memory запускається? | +| ------------------------------------------------------------------- | -------------------------------------------------------- | +| Постійні сеанси Control UI / вебчату | Так, якщо Plugin увімкнено та агент націлено | +| Інші інтерактивні сеанси каналів на тому самому шляху постійного чату | Так, якщо Plugin увімкнено та агент націлено | +| Headless одноразові запуски | Ні | +| Запуски Heartbeat/у фоновому режимі | Ні | +| Загальні внутрішні шляхи `agent-command` | Ні | +| Виконання підагента/внутрішнього допоміжного компонента | Ні | ## Навіщо це використовувати -Використовуйте активну пам’ять, коли: +Використовуйте active memory, коли: -- сеанс є постійним і орієнтованим на користувача +- сеанс є постійним і призначеним для користувача - агент має змістовну довготривалу пам’ять для пошуку -- безперервність і персоналізація важливіші за чисту детермінованість підказки +- безперервність і персоналізація важливіші за чистий детермінізм підказок -Вона особливо добре працює для: +Це особливо добре працює для: -- сталих уподобань +- стабільних уподобань - повторюваних звичок -- довготривалого користувацького контексту, який має природно проявлятися +- довготривалого контексту користувача, який має проявлятися природно -Вона погано підходить для: +Це погано підходить для: - автоматизації -- внутрішніх працівників +- внутрішніх воркерів - одноразових API-завдань - місць, де прихована персоналізація була б несподіваною ## Як це працює -Форма під час виконання така: +Форма виконання така: ```mermaid flowchart LR @@ -293,7 +297,7 @@ flowchart LR I --> M["Main Reply"] ``` -Підлеглий агент блокувальної пам’яті може використовувати лише: +Блокувальний підагент пам’яті може використовувати лише: - `memory_search` - `memory_get` @@ -302,21 +306,21 @@ flowchart LR ## Режими запиту -`config.queryMode` визначає, яку частину розмови бачить підлеглий агент блокувальної пам’яті. +`config.queryMode` керує тим, скільки розмови бачить блокувальний підагент пам’яті. ## Стилі підказок -`config.promptStyle` визначає, наскільки охоче чи суворо підлеглий агент блокувальної пам’яті +`config.promptStyle` керує тим, наскільки охоче чи суворо блокувальний підагент пам’яті вирішує, чи повертати пам’ять. Доступні стилі: -- `balanced`: універсальне типове значення для режиму `recent` -- `strict`: найменш охочий; найкраще, коли ви хочете мінімізувати проникнення сусіднього контексту -- `contextual`: найбільш дружній до безперервності; найкраще, коли історія розмови має більше значення +- `balanced`: типовий універсальний варіант для режиму `recent` +- `strict`: найменш охочий; найкраще, коли ви хочете мінімального впливу сусіднього контексту +- `contextual`: найкращий для безперервності; найкраще, коли історія розмови має більше значення - `recall-heavy`: охочіше показує пам’ять за м’якших, але все ще правдоподібних збігів - `precision-heavy`: агресивно віддає перевагу `NONE`, якщо збіг не є очевидним -- `preference-only`: оптимізовано для улюбленого, звичок, рутин, смаків і повторюваних особистих фактів +- `preference-only`: оптимізований для улюбленого, звичок, рутин, смаків і повторюваних особистих фактів Типове зіставлення, якщо `config.promptStyle` не задано: @@ -326,7 +330,7 @@ recent -> balanced full -> contextual ``` -Якщо ви явно задаєте `config.promptStyle`, цей пріоритет має перевагу. +Якщо ви явно задаєте `config.promptStyle`, саме це перевизначення і використовується. Приклад: @@ -336,13 +340,13 @@ promptStyle: "preference-only" ## Політика резервної моделі -Якщо `config.model` не задано, Активна пам’ять намагається визначити модель у такому порядку: +Якщо `config.model` не задано, Active Memory намагається визначити модель у такому порядку: ```text -явно задана модель плагіна --> модель поточного сеансу --> основна модель агента --> необов’язкова налаштована резервна модель +explicit plugin model +-> current session model +-> agent primary model +-> optional configured fallback model ``` `config.modelFallback` керує кроком налаштованої резервної моделі. @@ -353,17 +357,17 @@ promptStyle: "preference-only" modelFallback: "google/gemini-3-flash" ``` -Якщо не вдається визначити жодну явно задану, успадковану або налаштовану резервну модель, Активна пам’ять -пропускає пригадування для цього ходу. +Якщо не вдається визначити явну, успадковану чи налаштовану резервну модель, Active Memory +пропускає відновлення пам’яті для цього ходу. `config.modelFallbackPolicy` збережено лише як застаріле поле сумісності для старіших конфігурацій. Воно більше не змінює поведінку під час виконання. -## Розширені аварійні обходи +## Розширені аварійні опції Ці параметри навмисно не входять до рекомендованого налаштування. -`config.thinking` може перевизначити рівень мислення підлеглого агента блокувальної пам’яті: +`config.thinking` може перевизначати рівень thinking блокувального підагента пам’яті: ```json5 thinking: "medium" @@ -375,74 +379,74 @@ thinking: "medium" thinking: "off" ``` -Не вмикайте це за замовчуванням. Активна пам’ять запускається на шляху відповіді, тож додатковий -час на мислення безпосередньо збільшує видиму для користувача затримку. +Не вмикайте це типово. Active Memory запускається на шляху відповіді, тому додатковий +час thinking безпосередньо збільшує видиму для користувача затримку. -`config.promptAppend` додає додаткові інструкції оператора після типової підказки Активної -пам’яті та перед контекстом розмови: +`config.promptAppend` додає додаткові інструкції оператора після типової підказки Active +Memory і перед контекстом розмови: ```json5 promptAppend: "Prefer stable long-term preferences over one-off events." ``` -`config.promptOverride` замінює типову підказку Активної пам’яті. OpenClaw -усе одно додає контекст розмови після цього: +`config.promptOverride` замінює типову підказку Active Memory. OpenClaw +все одно додає контекст розмови після неї: ```json5 promptOverride: "You are a memory search agent. Return NONE or one compact user fact." ``` -Налаштування підказок не рекомендується, якщо ви не тестуєте навмисно -інший контракт пригадування. Типова підказка налаштована так, щоб повертати або `NONE`, -або компактний контекст користувацького факту для основної моделі. +Налаштування підказки не рекомендується, якщо тільки ви свідомо не тестуєте +інший контракт відновлення пам’яті. Типову підказку налаштовано так, щоб повертати або `NONE`, +або компактний контекст фактів про користувача для основної моделі. ### `message` Надсилається лише останнє повідомлення користувача. ```text -Тільки останнє повідомлення користувача +Latest user message only ``` Використовуйте це, коли: -- вам потрібна найшвидша поведінка -- вам потрібен найсильніший ухил у бік пригадування сталих уподобань -- наступні ходи не потребують розмовного контексту +- ви хочете найшвидшої поведінки +- ви хочете найсильнішого ухилу в бік відновлення стабільних уподобань +- наступні ходи не потребують контексту розмови -Рекомендований час очікування: +Рекомендований тайм-аут: - починайте приблизно з `3000` до `5000` мс ### `recent` -Надсилається останнє повідомлення користувача плюс невеликий хвіст недавньої розмови. +Надсилається останнє повідомлення користувача разом із невеликим хвостом недавньої розмови. ```text -Хвіст недавньої розмови: +Recent conversation tail: user: ... assistant: ... user: ... -Останнє повідомлення користувача: +Latest user message: ... ``` Використовуйте це, коли: -- вам потрібен кращий баланс між швидкістю та прив’язкою до розмови -- запитання в наступних ходах часто залежать від кількох останніх ходів +- ви хочете кращого балансу між швидкістю та прив’язкою до розмовного контексту +- уточнювальні запитання часто залежать від кількох останніх ходів -Рекомендований час очікування: +Рекомендований тайм-аут: - починайте приблизно з `15000` мс ### `full` -До підлеглого агента блокувальної пам’яті надсилається вся розмова. +До блокувального підагента пам’яті надсилається вся розмова. ```text -Повний контекст розмови: +Full conversation context: user: ... assistant: ... user: ... @@ -451,33 +455,33 @@ user: ... Використовуйте це, коли: -- найвища якість пригадування важливіша за затримку -- розмова містить важливі налаштування далеко вище в гілці +- найвища якість відновлення пам’яті важливіша за затримку +- розмова містить важливий вступний контекст далеко вище в гілці -Рекомендований час очікування: +Рекомендований тайм-аут: -- суттєво збільшіть його порівняно з `message` або `recent` +- суттєво збільшуйте його порівняно з `message` або `recent` - починайте приблизно з `15000` мс або вище залежно від розміру гілки -Загалом час очікування має зростати разом із розміром контексту: +Загалом тайм-аут має зростати разом із розміром контексту: ```text message < recent < full ``` -## Постійність стенограм +## Збереження транскриптів -Запуски підлеглого агента блокувальної пам’яті активної пам’яті створюють справжню -стенограму `session.jsonl` під час виклику підлеглого агента блокувальної пам’яті. +Запуски блокувального підагента пам’яті active memory створюють реальний +транскрипт `session.jsonl` під час виклику блокувального підагента пам’яті. -За замовчуванням ця стенограма є тимчасовою: +Типово цей транскрипт є тимчасовим: -- вона записується до тимчасового каталогу -- вона використовується лише для запуску підлеглого агента блокувальної пам’яті -- вона видаляється одразу після завершення запуску +- він записується до тимчасового каталогу +- він використовується лише для запуску блокувального підагента пам’яті +- він видаляється одразу після завершення запуску -Якщо ви хочете зберігати ці стенограми підлеглого агента блокувальної пам’яті на диску для налагодження або -перевірки, явно ввімкніть постійність: +Якщо ви хочете зберігати ці транскрипти блокувального підагента пам’яті на диску для налагодження або +перевірки, явно ввімкніть збереження: ```json5 { @@ -496,11 +500,11 @@ message < recent < full } ``` -Коли це ввімкнено, активна пам’ять зберігає стенограми в окремому каталозі в папці -сеансів цільового агента, а не в основному шляху стенограми користувацької -розмови. +Коли це ввімкнено, active memory зберігає транскрипти в окремому каталозі в +теці сеансів цільового агента, а не в основному шляху транскрипту +розмови користувача. -Типовий макет концептуально такий: +Типова структура концептуально виглядає так: ```text agents//sessions/active-memory/.jsonl @@ -510,13 +514,13 @@ agents//sessions/active-memory/.jso Використовуйте це обережно: -- стенограми підлеглого агента блокувальної пам’яті можуть швидко накопичуватися в активних сеансах -- режим запиту `full` може дублювати великий обсяг контексту розмови -- ці стенограми містять прихований контекст підказок і пригадані спогади +- транскрипти блокувального підагента пам’яті можуть швидко накопичуватися в активних сеансах +- режим запиту `full` може дублювати велику кількість контексту розмови +- ці транскрипти містять прихований контекст підказки та відновлені спогади ## Конфігурація -Уся конфігурація активної пам’яті міститься в: +Уся конфігурація active memory розміщується в: ```text plugins.entries.active-memory @@ -524,36 +528,36 @@ plugins.entries.active-memory Найважливіші поля: -| Key | Type | Значення | -| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | -| `enabled` | `boolean` | Вмикає сам плагін | -| `config.agents` | `string[]` | Ідентифікатори агентів, які можуть використовувати активну пам’ять | -| `config.model` | `string` | Необов’язкове посилання на модель підлеглого агента блокувальної пам’яті; якщо не задано, активна пам’ять використовує модель поточного сеансу | -| `config.queryMode` | `"message" \| "recent" \| "full"` | Керує тим, яку частину розмови бачить підлеглий агент блокувальної пам’яті | -| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Керує тим, наскільки охоче чи суворо підлеглий агент блокувальної пам’яті вирішує, чи повертати пам’ять | -| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Розширене перевизначення рівня мислення для підлеглого агента блокувальної пам’яті; типове значення `off` для швидкості | -| `config.promptOverride` | `string` | Розширена повна заміна підказки; не рекомендується для звичайного використання | -| `config.promptAppend` | `string` | Розширені додаткові інструкції, додані до типової або перевизначеної підказки | -| `config.timeoutMs` | `number` | Жорсткий час очікування для підлеглого агента блокувальної пам’яті | -| `config.maxSummaryChars` | `number` | Максимальна загальна кількість символів, дозволена в підсумку active-memory | -| `config.logging` | `boolean` | Виводить журнали активної пам’яті під час налаштування | -| `config.persistTranscripts` | `boolean` | Зберігає стенограми підлеглого агента блокувальної пам’яті на диску замість видалення тимчасових файлів | -| `config.transcriptDir` | `string` | Відносний каталог стенограм підлеглого агента блокувальної пам’яті в папці сеансів агента | +| Key | Type | Meaning | +| --------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `enabled` | `boolean` | Вмикає сам Plugin | +| `config.agents` | `string[]` | Ідентифікатори агентів, які можуть використовувати active memory | +| `config.model` | `string` | Необов’язкове посилання на модель блокувального підагента пам’яті; якщо не задано, active memory використовує модель поточного сеансу | +| `config.queryMode` | `"message" \| "recent" \| "full"` | Керує тим, скільки розмови бачить блокувальний підагент пам’яті | +| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Керує тим, наскільки охоче чи суворо блокувальний підагент пам’яті вирішує, чи повертати пам’ять | +| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Розширене перевизначення thinking для блокувального підагента пам’яті; типово `off` для швидкості | +| `config.promptOverride` | `string` | Розширена повна заміна підказки; не рекомендовано для звичайного використання | +| `config.promptAppend` | `string` | Розширені додаткові інструкції, додані в кінець типової або перевизначеної підказки | +| `config.timeoutMs` | `number` | Жорсткий тайм-аут для блокувального підагента пам’яті | +| `config.maxSummaryChars` | `number` | Максимальна загальна кількість символів, дозволена в підсумку active-memory | +| `config.logging` | `boolean` | Виводить журнали active memory під час налаштування | +| `config.persistTranscripts` | `boolean` | Зберігає транскрипти блокувального підагента пам’яті на диску замість видалення тимчасових файлів | +| `config.transcriptDir` | `string` | Відносний каталог транскриптів блокувального підагента пам’яті в теці сеансів агента | -Корисні поля для налаштування: +Корисні поля налаштування: -| Key | Type | Значення | -| ----------------------------- | -------- | ------------------------------------------------------------- | +| Key | Type | Meaning | +| ----------------------------- | -------- | ---------------------------------------------------------------- | | `config.maxSummaryChars` | `number` | Максимальна загальна кількість символів, дозволена в підсумку active-memory | -| `config.recentUserTurns` | `number` | Попередні ходи користувача, які слід включати, коли `queryMode` має значення `recent` | -| `config.recentAssistantTurns` | `number` | Попередні ходи асистента, які слід включати, коли `queryMode` має значення `recent` | -| `config.recentUserChars` | `number` | Максимальна кількість символів на один недавній хід користувача | -| `config.recentAssistantChars` | `number` | Максимальна кількість символів на один недавній хід асистента | -| `config.cacheTtlMs` | `number` | Повторне використання кешу для повторюваних однакових запитів | +| `config.recentUserTurns` | `number` | Попередні ходи користувача, які слід включити, коли `queryMode` дорівнює `recent` | +| `config.recentAssistantTurns` | `number` | Попередні ходи асистента, які слід включити, коли `queryMode` дорівнює `recent` | +| `config.recentUserChars` | `number` | Максимум символів на один нещодавній хід користувача | +| `config.recentAssistantChars` | `number` | Максимум символів на один нещодавній хід асистента | +| `config.cacheTtlMs` | `number` | Повторне використання кешу для повторюваних ідентичних запитів | ## Рекомендоване налаштування -Почніть із `recent`. +Починайте з `recent`. ```json5 { @@ -575,37 +579,91 @@ plugins.entries.active-memory } ``` -Якщо ви хочете перевіряти поведінку наживо під час налаштування, використовуйте `/verbose on` у -сеансі замість пошуку окремої команди налагодження active-memory. +Якщо ви хочете перевіряти поведінку наживо під час налаштування, використовуйте `/verbose on` для +звичайного рядка стану та `/trace on` для підсумку налагодження active-memory замість +пошуку окремої команди налагодження active-memory. У каналах чату ці +діагностичні рядки надсилаються після основної відповіді асистента, а не перед нею. Потім переходьте до: -- `message`, якщо хочете меншу затримку -- `full`, якщо вирішите, що додатковий контекст вартий повільнішого підлеглого агента блокувальної пам’яті +- `message`, якщо хочете меншої затримки +- `full`, якщо вирішите, що додатковий контекст вартий повільнішого блокувального підагента пам’яті ## Налагодження -Якщо активна пам’ять не з’являється там, де ви очікуєте: +Якщо active memory не з’являється там, де ви очікуєте: -1. Переконайтеся, що плагін увімкнений у `plugins.entries.active-memory.enabled`. -2. Переконайтеся, що поточний ідентифікатор агента вказаний у `config.agents`. +1. Переконайтеся, що Plugin увімкнено в `plugins.entries.active-memory.enabled`. +2. Переконайтеся, що ідентифікатор поточного агента вказано в `config.agents`. 3. Переконайтеся, що ви тестуєте через інтерактивний постійний сеанс чату. -4. Увімкніть `config.logging: true` і перегляньте журнали шлюзу. +4. Увімкніть `config.logging: true` і перегляньте журнали Gateway. 5. Перевірте, що сам пошук у пам’яті працює, за допомогою `openclaw memory status --deep`. -Якщо збіги пам’яті занадто шумні, зменште: +Якщо збіги в пам’яті шумні, зменште: - `maxSummaryChars` -Якщо активна пам’ять працює надто повільно: +Якщо active memory працює надто повільно: - зменште `queryMode` - зменште `timeoutMs` -- зменште кількість недавніх ходів +- зменште кількість нещодавніх ходів - зменште ліміти символів на хід +## Поширені проблеми + +### Провайдер вбудовувань неочікувано змінився + +Active Memory покладається на звичайний провайдер вбудовувань для пошуку в пам’яті в +`agents.defaults.memorySearch`. Якщо ви не задаєте цей провайдер явно, +OpenClaw автоматично виявляє перший доступний провайдер вбудовувань. + +Це може збивати з пантелику в реальних розгортаннях: + +- новий доступний API-ключ може змінити провайдера, який використовує пошук у пам’яті +- одна команда або поверхня діагностики може створювати враження, що вибраний провайдер + інший, ніж шлях, який ви фактично використовуєте під час живої синхронізації пам’яті або + ініціалізації пошуку +- хостовані провайдери можуть завершуватися помилками квоти або обмеження швидкості, які проявляються лише + коли Active Memory починає надсилати запити на відновлення пам’яті перед кожною відповіддю + +Якщо для вас важлива передбачувана поведінка, явно закріпіть провайдера вбудовувань для пам’яті +замість покладання на автовиявлення. + +Приклад: + +```json5 +{ + agents: { + defaults: { + memorySearch: { + provider: "ollama", + model: "nomic-embed-text", + }, + }, + }, +} +``` + +Або, якщо ви хочете вбудовування Gemini: + +```json5 +{ + agents: { + defaults: { + memorySearch: { + provider: "gemini", + }, + }, + }, +} +``` + +Після зміни провайдера перезапустіть Gateway і виконайте новий тест з +`/trace on`, щоб рядок налагодження Active Memory відображав новий шлях вбудовувань. + ## Пов’язані сторінки -- [Пошук у пам’яті](/uk/concepts/memory-search) +- [Memory Search](/uk/concepts/memory-search) - [Довідник із конфігурації пам’яті](/uk/reference/memory-config) - [Налаштування Plugin SDK](/uk/plugins/sdk-setup) diff --git a/docs/uk/concepts/agent-loop.md b/docs/uk/concepts/agent-loop.md index 60e787504..5d26a894f 100644 --- a/docs/uk/concepts/agent-loop.md +++ b/docs/uk/concepts/agent-loop.md @@ -4,10 +4,10 @@ read_when: summary: Життєвий цикл циклу агента, потоки та семантика очікування title: Цикл агента x-i18n: - generated_at: "2026-04-10T07:10:45Z" + generated_at: "2026-04-12T18:22:00Z" model: gpt-5.4 provider: openai - source_hash: b6831a5b11e9100e49f650feca51ab44a2bef242ce1b5db2766d0b3b5c5ba729 + source_hash: 3c2986708b444055340e0c91b8fce7d32225fcccf3d197b797665fd36b1991a5 source_path: concepts/agent-loop.md workflow: 15 --- @@ -16,161 +16,161 @@ x-i18n: Агентний цикл — це повний «реальний» запуск агента: прийом → збирання контексту → інференс моделі → виконання інструментів → потокові відповіді → збереження. Це авторитетний шлях, який перетворює повідомлення -на дії та фінальну відповідь, водночас підтримуючи узгоджений стан сесії. +на дії та фінальну відповідь, водночас зберігаючи узгоджений стан сесії. -У OpenClaw цикл — це один серіалізований запуск на сесію, який генерує події життєвого циклу та потокові події, -поки модель думає, викликає інструменти та передає вихідні дані потоком. У цьому документі пояснюється, як цей -автентичний цикл з'єднаний наскрізно. +В OpenClaw цикл — це один серіалізований запуск на сесію, який створює події життєвого циклу та потокові події, +поки модель думає, викликає інструменти й передає в потоці вихідні дані. У цьому документі пояснюється, як цей +автентичний цикл з’єднано наскрізно. ## Точки входу - Gateway RPC: `agent` і `agent.wait`. - CLI: команда `agent`. -## Як це працює (високий рівень) +## Як це працює (на високому рівні) -1. RPC `agent` перевіряє параметри, визначає сесію (sessionKey/sessionId), зберігає метадані сесії та одразу повертає `{ runId, acceptedAt }`. +1. RPC `agent` перевіряє параметри, визначає сесію (`sessionKey/sessionId`), зберігає метадані сесії та відразу повертає `{ runId, acceptedAt }`. 2. `agentCommand` запускає агента: - - визначає стандартні значення model + thinking/verbose + - визначає типові значення model + thinking/verbose/trace - завантажує знімок Skills - викликає `runEmbeddedPiAgent` (середовище виконання pi-agent-core) - - генерує **lifecycle end/error**, якщо вбудований цикл сам цього не згенерував + - створює **lifecycle end/error**, якщо вбудований цикл цього не створив 3. `runEmbeddedPiAgent`: - серіалізує запуски через черги для кожної сесії та глобальну чергу - - визначає model + профіль auth і будує pi session - - підписується на події pi та передає потоком assistant/tool deltas - - застосовує тайм-аут -> перериває запуск, якщо його перевищено - - повертає payloads + метадані usage -4. `subscribeEmbeddedPiSession` з'єднує події pi-agent-core з потоком OpenClaw `agent`: + - визначає профіль model + auth і будує pi-сесію + - підписується на події pi та передає assistant/tool deltas у потоці + - примусово застосовує timeout -> перериває запуск, якщо його перевищено + - повертає корисні навантаження та метадані usage +4. `subscribeEmbeddedPiSession` з’єднує події pi-agent-core з потоком OpenClaw `agent`: - події інструментів => `stream: "tool"` - assistant deltas => `stream: "assistant"` - події життєвого циклу => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`) 5. `agent.wait` використовує `waitForAgentRun`: - - очікує **lifecycle end/error** для `runId` + - чекає на **lifecycle end/error** для `runId` - повертає `{ status: ok|error|timeout, startedAt, endedAt, error? }` ## Черги + паралельність -- Запуски серіалізуються для кожного ключа сесії (лінія сесії) і, за потреби, через глобальну лінію. -- Це запобігає гонкам інструментів/сесій і підтримує узгоджену історію сесії. -- Канали обміну повідомленнями можуть вибирати режими черги (collect/steer/followup), які подають дані в цю систему ліній. +- Запуски серіалізуються для кожного ключа сесії (доріжка сесії) та, за потреби, через глобальну доріжку. +- Це запобігає конфліктам інструментів/сесій і підтримує узгодженість історії сесії. +- Канали обміну повідомленнями можуть вибирати режими черги (collect/steer/followup), які подаються в цю систему доріжок. Див. [Черга команд](/uk/concepts/queue). ## Підготовка сесії + робочого простору -- Робочий простір визначається та створюється; у sandbox-запусках він може бути перенаправлений до кореня робочого простору sandbox. +- Робочий простір визначається та створюється; ізольовані запуски можуть перенаправлятися до кореня ізольованого робочого простору. - Skills завантажуються (або повторно використовуються зі знімка) та впроваджуються в env і prompt. -- Bootstrap/context-файли визначаються та впроваджуються у звіт системного prompt. -- Отримується блокування запису сесії; перед початком потокової передачі відкривається та готується `SessionManager`. +- Bootstrap/context файли визначаються та впроваджуються у звіт системного prompt. +- Отримується блокування запису сесії; `SessionManager` відкривається та підготовлюється до потокової передачі. ## Збирання prompt + системний prompt - Системний prompt будується з базового prompt OpenClaw, prompt Skills, bootstrap-контексту та перевизначень для конкретного запуску. -- Застосовуються специфічні для моделі ліміти та резервні токени для compaction. -- Див. [Системний prompt](/uk/concepts/system-prompt), щоб зрозуміти, що бачить модель. +- Застосовуються обмеження, специфічні для моделі, і резервні токени для Compaction. +- Див. [Системний prompt](/uk/concepts/system-prompt), щоб побачити, що бачить модель. -## Точки hook (де можна перехопити) +## Точки перехоплення (де можна втрутитися) -OpenClaw має дві системи hook: +OpenClaw має дві системи хуків: -- **Внутрішні hooks** (Gateway hooks): скрипти, керовані подіями, для команд і подій життєвого циклу. -- **Plugin hooks**: точки розширення всередині життєвого циклу агента/інструмента та конвеєра gateway. +- **Внутрішні хуки** (хуки Gateway): скрипти на основі подій для команд і подій життєвого циклу. +- **Plugin hooks**: точки розширення всередині циклу агента/інструментів і конвеєра gateway. -### Внутрішні hooks (Gateway hooks) +### Внутрішні хуки (хуки Gateway) -- **`agent:bootstrap`**: виконується під час побудови bootstrap-файлів до остаточного формування системного prompt. - Використовуйте це, щоб додавати/видаляти bootstrap context-файли. -- **Command hooks**: `/new`, `/reset`, `/stop` та інші події команд (див. документацію про Hooks). +- **`agent:bootstrap`**: запускається під час побудови bootstrap-файлів до того, як буде фіналізовано системний prompt. + Використовуйте це, щоб додавати/видаляти bootstrap-файли контексту. +- **Хуки команд**: `/new`, `/reset`, `/stop` та інші події команд (див. документ про Hooks). -Див. [Hooks](/uk/automation/hooks) для налаштування та прикладів. +Див. [Hooks](/uk/automation/hooks), щоб переглянути налаштування та приклади. ### Plugin hooks (життєвий цикл агента + gateway) -Вони виконуються всередині циклу агента або конвеєра gateway: +Вони запускаються всередині циклу агента або конвеєра gateway: -- **`before_model_resolve`**: виконується до сесії (без `messages`), щоб детерміновано перевизначити provider/model до визначення моделі. -- **`before_prompt_build`**: виконується після завантаження сесії (з `messages`), щоб впровадити `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext` перед надсиланням prompt. Використовуйте `prependContext` для динамічного тексту на кожен хід, а поля системного контексту — для стабільних вказівок, які мають розміщуватися в просторі системного prompt. -- **`before_agent_start`**: застарілий hook сумісності, який може виконуватися в будь-якій фазі; віддавайте перевагу явним hooks вище. -- **`before_agent_reply`**: виконується після вбудованих дій і перед викликом LLM, дозволяючи plugin перехопити хід і повернути синтетичну відповідь або повністю приглушити хід. -- **`agent_end`**: перевіряє фінальний список повідомлень і метадані запуску після завершення. -- **`before_compaction` / `after_compaction`**: спостерігає або анотує цикли compaction. +- **`before_model_resolve`**: запускається до сесії (без `messages`), щоб детерміновано перевизначити provider/model до визначення моделі. +- **`before_prompt_build`**: запускається після завантаження сесії (з `messages`), щоб впровадити `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext` до надсилання prompt. Використовуйте `prependContext` для динамічного тексту на кожен хід, а поля системного контексту — для стабільних вказівок, які мають перебувати в просторі системного prompt. +- **`before_agent_start`**: застарілий хук сумісності, який може запускатися в будь-якій фазі; віддавайте перевагу наведеним вище явним хукам. +- **`before_agent_reply`**: запускається після вбудованих дій і перед викликом LLM, дозволяючи Plugin перехопити хід і повернути синтетичну відповідь або повністю приглушити хід. +- **`agent_end`**: дає змогу перевірити фінальний список повідомлень і метадані запуску після завершення. +- **`before_compaction` / `after_compaction`**: дає змогу спостерігати або анотувати цикли Compaction. - **`before_tool_call` / `after_tool_call`**: перехоплює параметри/результати інструментів. -- **`before_install`**: перевіряє результати вбудованого сканування та, за потреби, блокує встановлення skill або plugin. -- **`tool_result_persist`**: синхронно перетворює результати інструментів перед їх записом до транскрипту сесії. -- **`message_received` / `message_sending` / `message_sent`**: hooks вхідних і вихідних повідомлень. +- **`before_install`**: дає змогу перевірити результати вбудованого сканування й за потреби заблокувати встановлення Skill або Plugin. +- **`tool_result_persist`**: синхронно трансформує результати інструментів перед тим, як вони будуть записані до транскрипту сесії. +- **`message_received` / `message_sending` / `message_sent`**: вхідні та вихідні хуки повідомлень. - **`session_start` / `session_end`**: межі життєвого циклу сесії. - **`gateway_start` / `gateway_stop`**: події життєвого циклу gateway. -Правила рішень hook для вихідних повідомлень/захисту інструментів: +Правила рішень хуків для вихідних даних/запобіжників інструментів: - `before_tool_call`: `{ block: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. -- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує попереднє блокування. +- `before_tool_call`: `{ block: false }` не виконує жодної дії та не скасовує попереднє блокування. - `before_install`: `{ block: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. -- `before_install`: `{ block: false }` нічого не робить і не скасовує попереднє блокування. +- `before_install`: `{ block: false }` не виконує жодної дії та не скасовує попереднє блокування. - `message_sending`: `{ cancel: true }` є термінальним і зупиняє обробники з нижчим пріоритетом. -- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує попереднє скасування. +- `message_sending`: `{ cancel: false }` не виконує жодної дії та не скасовує попереднє скасування. -Див. [Plugin hooks](/uk/plugins/architecture#provider-runtime-hooks), щоб дізнатися про API hooks і подробиці реєстрації. +Див. [Plugin hooks](/uk/plugins/architecture#provider-runtime-hooks), щоб переглянути API хуків і деталі реєстрації. ## Потокова передача + часткові відповіді -- Assistant deltas передаються потоком із pi-agent-core та генеруються як події `assistant`. -- Block streaming може передавати часткові відповіді або на `text_end`, або на `message_end`. -- Потокова передача reasoning може генеруватися як окремий потік або як block replies. -- Див. [Потокова передача](/uk/concepts/streaming) для інформації про chunking і поведінку block reply. +- Assistant deltas передаються в потоці з pi-agent-core і створюються як події `assistant`. +- Потокова передача блоків може створювати часткові відповіді або на `text_end`, або на `message_end`. +- Потокова передача міркувань може створюватися як окремий потік або як блокові відповіді. +- Див. [Потокова передача](/uk/concepts/streaming), щоб дізнатися про розбиття на частини та поведінку блокових відповідей. -## Виконання інструментів + інструменти обміну повідомленнями +## Виконання інструментів + інструменти повідомлень -- Події початку/оновлення/завершення інструментів генеруються в потоці `tool`. -- Результати інструментів очищуються з урахуванням розміру та image payloads перед логуванням/генерацією. -- Надсилання через інструменти обміну повідомленнями відстежуються, щоб не дублювати підтвердження assistant. +- Події початку/оновлення/завершення інструментів створюються в потоці `tool`. +- Результати інструментів очищуються з урахуванням обмежень розміру та корисних навантажень зображень перед логуванням/створенням подій. +- Надсилання інструментів повідомлень відстежуються, щоб пригнічувати дубльовані підтвердження assistant. -## Формування відповіді + приглушення +## Формування відповіді + пригнічення -- Фінальні payloads збираються з: - - assistant text (і, за потреби, reasoning) - - вбудованих підсумків інструментів (коли verbose увімкнено та це дозволено) - - тексту помилки assistant, якщо модель завершується з помилкою -- Точний silent token `NO_REPLY` / `no_reply` відфільтровується з вихідних - payloads. -- Дублікати з інструментів обміну повідомленнями видаляються з фінального списку payload. -- Якщо не лишилося payloads для відображення, а інструмент завершився з помилкою, генерується резервна відповідь про помилку інструмента - (якщо тільки інструмент обміну повідомленнями вже не надіслав видиму для користувача відповідь). +- Фінальні корисні навантаження збираються з: + - тексту assistant (та, за потреби, reasoning) + - вбудованих зведень інструментів (коли verbose увімкнено + дозволено) + - тексту помилки assistant, якщо модель повернула помилку +- Точний маркер безмовності `NO_REPLY` / `no_reply` відфільтровується з вихідних + корисних навантажень. +- Дублікати інструментів повідомлень видаляються з фінального списку корисних навантажень. +- Якщо не лишилося жодних придатних до відображення корисних навантажень і інструмент повернув помилку, створюється резервна відповідь про помилку інструмента + (якщо тільки інструмент повідомлень ще не надіслав видиму для користувача відповідь). ## Compaction + повторні спроби -- Автоматичний compaction генерує потокові події `compaction` і може спричинити повторну спробу. -- Під час повторної спроби буфери в пам'яті та підсумки інструментів скидаються, щоб уникнути дубльованого виводу. -- Див. [Compaction](/uk/concepts/compaction), щоб дізнатися про конвеєр compaction. +- Автоматичний Compaction створює події потоку `compaction` і може ініціювати повторну спробу. +- Під час повторної спроби буфери в пам’яті та зведення інструментів скидаються, щоб уникнути дубльованого виводу. +- Див. [Compaction](/uk/concepts/compaction), щоб ознайомитися з конвеєром Compaction. ## Потоки подій (зараз) -- `lifecycle`: генерується `subscribeEmbeddedPiSession` (і як резервний варіант — `agentCommand`) -- `assistant`: потокові deltas із pi-agent-core +- `lifecycle`: створюється `subscribeEmbeddedPiSession` (і як резервний варіант — `agentCommand`) +- `assistant`: потокові deltas з pi-agent-core - `tool`: потокові події інструментів із pi-agent-core -## Обробка chat-каналу +## Обробка чат-каналу -- Assistant deltas буферизуються в chat-повідомлення `delta`. -- Chat `final` генерується на **lifecycle end/error**. +- Assistant deltas буферизуються в чат-повідомлення `delta`. +- Чат `final` створюється на **lifecycle end/error**. ## Тайм-аути -- Стандартне значення для `agent.wait`: 30 с (лише очікування). Перевизначається параметром `timeoutMs`. -- Час виконання агента: стандартне значення `agents.defaults.timeoutSeconds` — 172800 с (48 годин); застосовується в таймері переривання `runEmbeddedPiAgent`. -- Тайм-аут бездіяльності LLM: `agents.defaults.llm.idleTimeoutSeconds` перериває запит до моделі, якщо до завершення вікна бездіяльності не надходять жодні chunks відповіді. Установіть його явно для повільних локальних моделей або providers reasoning/tool-call; установіть 0, щоб вимкнути. Якщо його не встановлено, OpenClaw використовує `agents.defaults.timeoutSeconds`, якщо він налаштований, інакше — 120 с. Запуски, ініційовані cron, без явного LLM- або агентського тайм-ауту вимикають watchdog бездіяльності та покладаються на зовнішній тайм-аут cron. +- Типове значення `agent.wait`: 30 с (лише очікування). Параметр `timeoutMs` його перевизначає. +- Час виконання агента: типове значення `agents.defaults.timeoutSeconds` — 172800 с (48 годин); застосовується в таймері переривання `runEmbeddedPiAgent`. +- Тайм-аут бездіяльності LLM: `agents.defaults.llm.idleTimeoutSeconds` перериває запит до моделі, якщо жодні фрагменти відповіді не надходять до завершення вікна бездіяльності. Установіть його явно для повільних локальних моделей або provider-ів reasoning/tool-call; установіть 0, щоб вимкнути. Якщо його не задано, OpenClaw використовує `agents.defaults.timeoutSeconds`, якщо його налаштовано, інакше 120 с. Запуски, ініційовані Cron, без явного тайм-ауту LLM або агента вимикають watchdog бездіяльності й покладаються на зовнішній тайм-аут Cron. -## Де все може завершитися раніше +## Де все може завершитися завчасно - Тайм-аут агента (переривання) - AbortSignal (скасування) -- Відключення gateway або тайм-аут RPC +- Від’єднання Gateway або тайм-аут RPC - Тайм-аут `agent.wait` (лише очікування, не зупиняє агента) -## Пов'язане +## Пов’язані теми - [Інструменти](/uk/tools) — доступні інструменти агента -- [Hooks](/uk/automation/hooks) — скрипти, керовані подіями, які запускаються подіями життєвого циклу агента -- [Compaction](/uk/concepts/compaction) — як підсумовуються довгі розмови -- [Exec Approvals](/uk/tools/exec-approvals) — бар'єри погодження для shell-команд -- [Thinking](/uk/tools/thinking) — конфігурація рівня thinking/reasoning +- [Hooks](/uk/automation/hooks) — скрипти на основі подій, що спрацьовують на подіях життєвого циклу агента +- [Compaction](/uk/concepts/compaction) — як узагальнюються довгі розмови +- [Погодження Exec](/uk/tools/exec-approvals) — бар’єри погодження для shell-команд +- [Thinking](/uk/tools/thinking) — налаштування рівня thinking/reasoning diff --git a/docs/uk/concepts/context.md b/docs/uk/concepts/context.md index 0e1cb1356..d347d33d6 100644 --- a/docs/uk/concepts/context.md +++ b/docs/uk/concepts/context.md @@ -2,114 +2,114 @@ read_when: - Ви хочете зрозуміти, що означає «контекст» в OpenClaw - Ви налагоджуєте, чому модель «знає» щось (або забула це) - - Ви хочете зменшити накладні витрати контексту (`/context`, `/status`, `/compact`) -summary: 'Контекст: що бачить модель, як він формується та як його перевірити' + - Ви хочете зменшити накладні витрати контексту (/context, /status, /compact) +summary: 'Контекст: що бачить модель, як її побудовано та як її перевірити' title: Контекст x-i18n: - generated_at: "2026-04-06T12:42:54Z" + generated_at: "2026-04-12T18:22:02Z" model: gpt-5.4 provider: openai - source_hash: a75b4cd65bf6385d46265b9ce1643310bc99d220e35ec4b4924096bed3ca4aa0 + source_hash: 3620db1a8c1956d91a01328966df491388d3a32c4003dc4447197eb34316c77d source_path: concepts/context.md workflow: 15 --- # Контекст -«Контекст» — це **все, що OpenClaw надсилає моделі для запуску**. Він обмежений **вікном контексту** моделі (лімітом токенів). +«Контекст» — це **все, що OpenClaw надсилає моделі для одного запуску**. Його обмежує **вікно контексту** моделі (ліміт токенів). -Проста ментальна модель для початківців: +Ментальна модель для початківців: -- **Системний prompt** (збудований OpenClaw): правила, інструменти, список Skills, час/середовище виконання та вбудовані файли робочого простору. -- **Історія розмови**: ваші повідомлення + повідомлення асистента для цієї сесії. +- **Системний промпт** (побудований OpenClaw): правила, інструменти, список Skills, час/середовище виконання та впроваджені файли робочого простору. +- **Історія розмови**: ваші повідомлення + повідомлення помічника в цій сесії. - **Виклики/результати інструментів + вкладення**: вивід команд, читання файлів, зображення/аудіо тощо. -Контекст _це не те саме_, що «пам’ять»: пам’ять може зберігатися на диску та повторно завантажуватися пізніше; контекст — це те, що знаходиться всередині поточного вікна моделі. +Контекст _не є тим самим_, що й «пам’ять»: пам’ять може зберігатися на диску та повторно завантажуватися пізніше; контекст — це те, що знаходиться всередині поточного вікна моделі. ## Швидкий старт (перевірка контексту) - `/status` → швидкий перегляд «наскільки заповнене моє вікно?» + налаштування сесії. -- `/context list` → що вбудовано + приблизні розміри (для кожного файла + загалом). -- `/context detail` → детальніший розподіл: пофайлово, розміри схем кожного інструмента, розміри записів кожного skill та розмір системного prompt. -- `/usage tokens` → додає нижній колонтитул із використанням до звичайних відповідей. +- `/context list` → що впроваджується + приблизні розміри (для кожного файлу + підсумки). +- `/context detail` → глибший розбір: розміри для кожного файлу, для кожної схеми інструмента, для кожного запису Skills і розмір системного промпту. +- `/usage tokens` → додає виноску з використанням токенів до звичайних відповідей. - `/compact` → підсумовує старішу історію в компактний запис, щоб звільнити місце у вікні. -Див. також: [Slash commands](/uk/tools/slash-commands), [Використання токенів і витрати](/uk/reference/token-use), [Стиснення](/uk/concepts/compaction). +Див. також: [Косі команди](/uk/tools/slash-commands), [Використання токенів і вартість](/uk/reference/token-use), [Compaction](/uk/concepts/compaction). ## Приклад виводу -Значення відрізняються залежно від моделі, провайдера, політики інструментів і вмісту вашого робочого простору. +Значення відрізняються залежно від моделі, провайдера, політики інструментів і того, що є у вашому робочому просторі. ### `/context list` ``` -🧠 Розподіл контексту -Робочий простір: -Максимум bootstrap на файл: 20,000 символів -Пісочниця: mode=non-main sandboxed=false -Системний prompt (запуск): 38,412 символів (~9,603 ток) (Контекст проєкту 23,901 символів (~5,976 ток)) +🧠 Розбір контексту +Workspace: +Bootstrap max/file: 20,000 chars +Sandbox: mode=non-main sandboxed=false +System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok)) -Вбудовані файли робочого простору: -- AGENTS.md: OK | raw 1,742 символів (~436 ток) | injected 1,742 символів (~436 ток) -- SOUL.md: OK | raw 912 символів (~228 ток) | injected 912 символів (~228 ток) -- TOOLS.md: TRUNCATED | raw 54,210 символів (~13,553 ток) | injected 20,962 символів (~5,241 ток) -- IDENTITY.md: OK | raw 211 символів (~53 ток) | injected 211 символів (~53 ток) -- USER.md: OK | raw 388 символів (~97 ток) | injected 388 символів (~97 ток) +Injected workspace files: +- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok) +- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok) +- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok) +- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok) +- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok) - HEARTBEAT.md: MISSING | raw 0 | injected 0 -- BOOTSTRAP.md: OK | raw 0 символів (~0 ток) | injected 0 символів (~0 ток) +- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok) -Список Skills (текст системного prompt): 2,184 символів (~546 ток) (12 skills) -Інструменти: read, edit, write, exec, process, browser, message, sessions_send, … -Список інструментів (текст системного prompt): 1,032 символів (~258 ток) -Схеми інструментів (JSON): 31,988 символів (~7,997 ток) (враховуються в контексті; не показані як текст) -Інструменти: (ті самі, що вище) +Skills list (system prompt text): 2,184 chars (~546 tok) (12 skills) +Tools: read, edit, write, exec, process, browser, message, sessions_send, … +Tool list (system prompt text): 1,032 chars (~258 tok) +Tool schemas (JSON): 31,988 chars (~7,997 tok) (counts toward context; not shown as text) +Tools: (same as above) -Токени сесії (кешовані): 14,250 усього / ctx=32,000 +Session tokens (cached): 14,250 total / ctx=32,000 ``` ### `/context detail` ``` -🧠 Розподіл контексту (детально) +🧠 Детальний розбір контексту … -Найбільші skills (розмір запису в prompt): -- frontend-design: 412 символів (~103 ток) -- oracle: 401 символ (~101 ток) +Top skills (prompt entry size): +- frontend-design: 412 chars (~103 tok) +- oracle: 401 chars (~101 tok) … (+10 more skills) -Найбільші інструменти (розмір схеми): -- browser: 9,812 символів (~2,453 ток) -- exec: 6,240 символів (~1,560 ток) +Top tools (schema size): +- browser: 9,812 chars (~2,453 tok) +- exec: 6,240 chars (~1,560 tok) … (+N more tools) ``` -## Що враховується у вікні контексту +## Що зараховується до вікна контексту -Усе, що отримує модель, враховується, зокрема: +Зараховується все, що отримує модель, зокрема: -- Системний prompt (усі розділи). +- Системний промпт (усі розділи). - Історія розмови. - Виклики інструментів + результати інструментів. - Вкладення/транскрипти (зображення/аудіо/файли). -- Підсумки стиснення та артефакти обрізання. -- «Обгортки» провайдера або приховані заголовки (не видимі, але все одно враховуються). +- Підсумки Compaction і артефакти обрізання. +- «Обгортки» провайдера або приховані заголовки (не видно, але все одно зараховуються). -## Як OpenClaw будує системний prompt +## Як OpenClaw будує системний промпт -Системний prompt **належить OpenClaw** і перебудовується для кожного запуску. Він містить: +Системний промпт **належить OpenClaw** і перебудовується для кожного запуску. Він містить: - Список інструментів + короткі описи. - Список Skills (лише метадані; див. нижче). - Розташування робочого простору. - Час (UTC + перетворений час користувача, якщо налаштовано). -- Метадані середовища виконання (хост/ОС/модель/thinking). -- Вбудовані bootstrap-файли робочого простору в розділі **Контекст проєкту**. +- Метадані середовища виконання (хост/ОС/модель/мислення). +- Впроваджені файли bootstrap робочого простору в розділі **Project Context**. -Повний розбір: [System Prompt](/uk/concepts/system-prompt). +Повний розбір: [Системний промпт](/uk/concepts/system-prompt). -## Вбудовані файли робочого простору (Контекст проєкту) +## Впроваджені файли робочого простору (Project Context) -Типово OpenClaw вбудовує фіксований набір файлів робочого простору (якщо вони є): +Типово OpenClaw впроваджує фіксований набір файлів робочого простору (якщо вони є): - `AGENTS.md` - `SOUL.md` @@ -119,69 +119,68 @@ x-i18n: - `HEARTBEAT.md` - `BOOTSTRAP.md` (лише під час першого запуску) -Великі файли обрізаються для кожного файла окремо за допомогою `agents.defaults.bootstrapMaxChars` (типове значення `20000` символів). OpenClaw також застосовує загальне обмеження на вбудовування bootstrap для всіх файлів через `agents.defaults.bootstrapTotalMaxChars` (типове значення `150000` символів). `/context` показує розміри **raw vs injected** і те, чи відбулося обрізання. +Великі файли обрізаються для кожного файлу окремо за допомогою `agents.defaults.bootstrapMaxChars` (типово `20000` символів). OpenClaw також застосовує загальне обмеження на сумарний обсяг впровадження bootstrap для всіх файлів через `agents.defaults.bootstrapTotalMaxChars` (типово `150000` символів). `/context` показує розміри **raw vs injected** і те, чи відбулося обрізання. -Коли відбувається обрізання, середовище виконання може вставити в prompt блок попередження в розділі Контекст проєкту. Це налаштовується через `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; типове значення `once`). +Коли відбувається обрізання, середовище виконання може впровадити попереджувальний блок прямо в промпт у розділі Project Context. Налаштуйте це через `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; типово `once`). -## Skills: вбудовані чи завантажувані на вимогу +## Skills: впроваджуються чи завантажуються на вимогу -Системний prompt містить компактний **список Skills** (назва + опис + розташування). Цей список має реальні накладні витрати. +Системний промпт містить компактний **список Skills** (назва + опис + розташування). Цей список має реальні накладні витрати. -Інструкції skill _не_ включаються типово. Очікується, що модель прочитає `SKILL.md` відповідного skill через `read` **лише за потреби**. +Інструкції Skills _типово не включаються_. Очікується, що модель викличе `read` для `SKILL.md` цього Skills **лише за потреби**. -## Інструменти: є дві складові витрат +## Інструменти: є дві складові вартості Інструменти впливають на контекст двома способами: -1. **Текст списку інструментів** у системному prompt (те, що ви бачите як «Інструменти»). -2. **Схеми інструментів** (JSON). Вони надсилаються моделі, щоб вона могла викликати інструменти. Вони враховуються в контексті, хоча ви не бачите їх як звичайний текст. +1. **Текст списку інструментів** у системному промпті (те, що ви бачите як «Tooling»). +2. **Схеми інструментів** (JSON). Вони надсилаються моделі, щоб вона могла викликати інструменти. Вони зараховуються до контексту, навіть якщо ви не бачите їх як звичайний текст. `/context detail` розбиває найбільші схеми інструментів, щоб ви могли побачити, що домінує. ## Команди, директиви та "вбудовані скорочення" -Slash-команди обробляються Gateway. Є кілька різних варіантів поведінки: +Косі команди обробляє Gateway. Є кілька різних варіантів поведінки: -- **Окремі команди**: повідомлення, що складається лише з `/...`, виконується як команда. -- **Директиви**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/model`, `/queue` видаляються до того, як модель побачить повідомлення. +- **Окремі команди**: повідомлення, яке складається лише з `/...`, виконується як команда. +- **Директиви**: `/think`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/model`, `/queue` видаляються до того, як модель побачить повідомлення. - Повідомлення, що містять лише директиви, зберігають налаштування сесії. - - Вбудовані директиви у звичайному повідомленні діють як підказки для конкретного повідомлення. -- **Вбудовані скорочення** (лише для відправників із allowlist): певні токени `/...` всередині звичайного повідомлення можуть виконуватися негайно (наприклад: «hey /status»), і видаляються до того, як модель побачить решту тексту. + - Вбудовані директиви у звичайному повідомленні діють як підказки лише для цього повідомлення. +- **Вбудовані скорочення** (лише для відправників із allowlist): певні токени `/...` усередині звичайного повідомлення можуть виконуватися негайно (наприклад: “hey /status”), і видаляються до того, як модель побачить решту тексту. -Докладніше: [Slash commands](/uk/tools/slash-commands). +Докладніше: [Косі команди](/uk/tools/slash-commands). -## Сесії, стиснення та обрізання (що зберігається) +## Сесії, Compaction та обрізання (що зберігається) -Що саме зберігається між повідомленнями, залежить від механізму: +Що зберігається між повідомленнями, залежить від механізму: - **Звичайна історія** зберігається в транскрипті сесії, доки не буде стиснена/обрізана згідно з політикою. -- **Стиснення** зберігає підсумок у транскрипті та залишає недоторканими нещодавні повідомлення. -- **Обрізання** видаляє старі результати інструментів із prompt _у пам’яті_ для запуску, але не переписує транскрипт. +- **Compaction** зберігає підсумок у транскрипті й залишає недавні повідомлення недоторканими. +- **Pruning** видаляє старі результати інструментів із _внутрішньопам’ятного_ промпту для запуску, але не переписує транскрипт. -Документація: [Сесія](/uk/concepts/session), [Стиснення](/uk/concepts/compaction), [Обрізання сесії](/uk/concepts/session-pruning). +Документація: [Сесія](/uk/concepts/session), [Compaction](/uk/concepts/compaction), [Обрізання сесії](/uk/concepts/session-pruning). -Типово OpenClaw використовує вбудований рушій контексту `legacy` для складання -та стиснення. Якщо ви встановите plugin, який надає `kind: "context-engine"`, і +Типово OpenClaw використовує вбудований рушій контексту `legacy` для збирання +та compaction. Якщо ви встановите Plugin, який надає `kind: "context-engine"` і виберете його через `plugins.slots.contextEngine`, OpenClaw натомість делегує -складання контексту, `/compact` і пов’язані гачки життєвого циклу контексту -підлеглого агента цьому рушію. `ownsCompaction: false` не викликає -автоматичного повернення до рушія `legacy`; активний рушій усе одно має -коректно реалізовувати `compact()`. Див. +збирання контексту, `/compact` і пов’язані хуки життєвого циклу контексту +субагента цьому рушію. `ownsCompaction: false` не викликає автоматичного +повернення до рушія legacy; активний рушій усе одно має правильно реалізовувати `compact()`. Див. [Context Engine](/uk/concepts/context-engine), щоб ознайомитися з повним -підключуваним інтерфейсом, гачками життєвого циклу та конфігурацією. +підключуваним інтерфейсом, хуками життєвого циклу та конфігурацією. ## Що насправді показує `/context` -`/context` за можливості віддає перевагу найновішому звіту про системний prompt, **побудований під час запуску**: +`/context` надає перевагу найновішому звіту про системний промпт, **побудованому під час запуску**, якщо він доступний: -- `System prompt (run)` = захоплений з останнього вбудованого запуску (із підтримкою інструментів) і збережений у сховищі сесії. -- `System prompt (estimate)` = обчислений на льоту, коли звіт про запуск відсутній (або під час роботи через бекенд CLI, який не генерує цей звіт). +- `System prompt (run)` = захоплено з останнього вбудованого запуску (з підтримкою інструментів) і збережено в сховищі сесії. +- `System prompt (estimate)` = обчислено на льоту, коли звіт про запуск відсутній (або під час запуску через бекенд CLI, який не генерує цей звіт). -У будь-якому разі він повідомляє розміри та найбільші складові; він **не** виводить повний системний prompt або схеми інструментів. +У будь-якому разі він повідомляє про розміри та найбільших учасників; він **не** виводить повний системний промпт або схеми інструментів. ## Пов’язане -- [Context Engine](/uk/concepts/context-engine) — користувацьке вбудовування контексту через plugins -- [Стиснення](/uk/concepts/compaction) — підсумовування довгих розмов -- [System Prompt](/uk/concepts/system-prompt) — як будується системний prompt +- [Context Engine](/uk/concepts/context-engine) — власне впровадження контексту через plugins +- [Compaction](/uk/concepts/compaction) — підсумовування довгих розмов +- [Системний промпт](/uk/concepts/system-prompt) — як будується системний промпт - [Цикл агента](/uk/concepts/agent-loop) — повний цикл виконання агента diff --git a/docs/uk/gateway/security/index.md b/docs/uk/gateway/security/index.md index 790169fdd..4b1fb902c 100644 --- a/docs/uk/gateway/security/index.md +++ b/docs/uk/gateway/security/index.md @@ -1,13 +1,13 @@ --- read_when: - - Додавання функцій, які розширюють доступ або автоматизацію -summary: Міркування безпеки та модель загроз для запуску AI-шлюзу з доступом до оболонки + - Додавання функцій, що розширюють доступ або автоматизацію +summary: Міркування щодо безпеки та модель загроз для запуску AI Gateway із доступом до оболонки title: Безпека x-i18n: - generated_at: "2026-04-10T20:41:23Z" + generated_at: "2026-04-12T18:22:01Z" model: gpt-5.4 provider: openai - source_hash: 770407f64b2ce27221ebd9756b2f8490a249c416064186e64edb663526f9d6b5 + source_hash: 7f3ef693813b696be2e24bcc333c8ee177fa56c3cb06c5fac12a0bd220a29917 source_path: gateway/security/index.md workflow: 15 --- @@ -15,29 +15,29 @@ x-i18n: # Безпека -**Модель довіри для персонального асистента:** ці рекомендації виходять із припущення про одну межу довіри оператора на шлюз (модель одного користувача / персонального асистента). -OpenClaw **не** є безпечною межею для ворожого багатокористувацького середовища, де кілька недовірених користувачів ділять одного агента/шлюз. -Якщо вам потрібна робота зі змішаним рівнем довіри або ворожими користувачами, розділіть межі довіри (окремий шлюз + облікові дані, бажано також окремі користувачі ОС/хости). +**Модель довіри персонального асистента:** ці рекомендації виходять із припущення про одну межу довіри оператора на один Gateway (модель одного користувача / персонального асистента). +OpenClaw **не** є безпечною межею для ворожого багатокористувацького середовища, у якому кілька зловмисних користувачів ділять одного агента/Gateway. +Якщо вам потрібна робота зі змішаною довірою або в умовах ворожих користувачів, розділіть межі довіри (окремий Gateway + облікові дані, в ідеалі також окремі користувачі ОС/хости). -**На цій сторінці:** [Модель довіри](#scope-first-personal-assistant-security-model) | [Швидкий аудит](#quick-check-openclaw-security-audit) | [Посилена базова конфігурація](#hardened-baseline-in-60-seconds) | [Модель доступу через DM](#dm-access-model-pairing-allowlist-open-disabled) | [Посилення конфігурації](#configuration-hardening-examples) | [Реагування на інциденти](#incident-response) +**На цій сторінці:** [Модель довіри](#scope-first-personal-assistant-security-model) | [Швидкий аудит](#quick-check-openclaw-security-audit) | [Посилений базовий захист](#hardened-baseline-in-60-seconds) | [Модель доступу DM](#dm-access-model-pairing-allowlist-open-disabled) | [Посилення конфігурації](#configuration-hardening-examples) | [Реагування на інциденти](#incident-response) ## Спочатку про межі: модель безпеки персонального асистента -Рекомендації OpenClaw щодо безпеки припускають розгортання **персонального асистента**: одна межа довіри оператора, потенційно багато агентів. +Рекомендації з безпеки OpenClaw ґрунтуються на розгортанні **персонального асистента**: одна межа довіри оператора, потенційно багато агентів. -- Підтримувана модель безпеки: один користувач / одна межа довіри на шлюз (бажано один користувач ОС/хост/VPS на межу). -- Непідтримувана межа безпеки: один спільний шлюз/агент, яким користуються взаємно недовірені або ворожі користувачі. -- Якщо потрібна ізоляція від ворожих користувачів, розділяйте за межами довіри (окремий шлюз + облікові дані, а бажано також окремі користувачі ОС/хости). -- Якщо кілька недовірених користувачів можуть надсилати повідомлення одному агенту з увімкненими інструментами, вважайте, що всі вони спільно використовують ті самі делеговані повноваження цього агента. +- Підтримувана модель безпеки: один користувач/межа довіри на Gateway (бажано один користувач ОС/хост/VPS на межу). +- Модель, яка не підтримується як межа безпеки: один спільний Gateway/агент, яким користуються взаємно недовірені або ворожі користувачі. +- Якщо потрібна ізоляція від ворожих користувачів, розділіть за межами довіри (окремий Gateway + облікові дані, а в ідеалі також окремі користувачі ОС/хости). +- Якщо кілька недовірених користувачів можуть надсилати повідомлення одному агенту з увімкненими інструментами, вважайте, що всі вони спільно використовують однакові делеговані повноваження цього агента щодо інструментів. -Ця сторінка пояснює посилення захисту **в межах цієї моделі**. Вона не стверджує наявність ізоляції для ворожого багатокористувацького середовища на одному спільному шлюзі. +Ця сторінка пояснює посилення захисту **в межах цієї моделі**. Вона не стверджує наявність ворожої багатокористувацької ізоляції в одному спільному Gateway. ## Швидка перевірка: `openclaw security audit` Див. також: [Формальна верифікація (моделі безпеки)](/uk/security/formal-verification) -Запускайте це регулярно (особливо після зміни конфігурації або відкриття мережевих поверхонь): +Регулярно запускайте це (особливо після змін конфігурації або відкриття мережевих поверхонь): ```bash openclaw security audit @@ -46,103 +46,103 @@ openclaw security audit --fix openclaw security audit --json ``` -`security audit --fix` навмисно має вузьку дію: він переводить типові відкриті групові політики на allowlist, відновлює `logging.redactSensitive: "tools"`, посилює дозволи для state/config/include-файлів і використовує скидання Windows ACL замість POSIX `chmod` під час роботи у Windows. +`security audit --fix` навмисно залишається вузько спрямованою командою: вона перемикає поширені відкриті групові політики на allowlist, відновлює `logging.redactSensitive: "tools"`, посилює дозволи для state/config/include-file і використовує скидання ACL Windows замість POSIX `chmod` під час роботи у Windows. -Він виявляє типові небезпечні конфігурації (відкритий доступ до автентифікації Gateway, відкритий доступ до керування браузером, підвищені allowlist, дозволи файлової системи, надто поблажливі схвалення exec і відкритий доступ інструментів у каналах). +Команда позначає типові небезпечні конфігурації (відкритий доступ до автентифікації Gateway, відкритий доступ до керування браузером, розширені allowlist, дозволи файлової системи, надто поблажливі схвалення exec і відкритий доступ до інструментів через канали). -OpenClaw — це і продукт, і експеримент: ви підключаєте поведінку frontier-моделей до реальних поверхонь обміну повідомленнями та реальних інструментів. **Ідеально безпечної конфігурації не існує.** Мета — свідомо контролювати: +OpenClaw — це і продукт, і експеримент: ви підключаєте поведінку frontier-моделей до реальних поверхонь обміну повідомленнями та реальних інструментів. **Ідеально безпечної конфігурації не існує.** Мета — усвідомлено визначити: -- хто може взаємодіяти з вашим ботом -- де бот має право діяти -- до чого бот може мати доступ +- хто може спілкуватися з вашим ботом; +- де боту дозволено діяти; +- до чого бот може торкатися. -Починайте з мінімального доступу, якого достатньо для роботи, і розширюйте його лише тоді, коли зростає ваша впевненість. +Починайте з мінімального доступу, який ще дозволяє працювати, і розширюйте його лише в міру зростання впевненості. ### Розгортання та довіра до хоста -OpenClaw виходить із довіри до хоста та межі конфігурації: +OpenClaw припускає, що хост і межа конфігурації є довіреними: -- Якщо хтось може змінювати стан/конфігурацію Gateway на хості (`~/.openclaw`, включно з `openclaw.json`), вважайте цю людину довіреним оператором. -- Запуск одного Gateway для кількох взаємно недовірених/ворожих операторів **не є рекомендованим сценарієм**. -- Для команд зі змішаним рівнем довіри розділяйте межі довіри окремими шлюзами (або щонайменше окремими користувачами ОС/хостами). -- Рекомендоване типове налаштування: один користувач на машину/хост (або VPS), один gateway для цього користувача та один або кілька агентів у цьому gateway. -- У межах одного екземпляра Gateway автентифікований доступ оператора — це роль довіреної control plane, а не роль окремого користувача-орендаря. -- Ідентифікатори сесії (`sessionKey`, ID сесій, мітки) — це селектори маршрутизації, а не токени авторизації. -- Якщо кілька людей можуть надсилати повідомлення одному агенту з увімкненими інструментами, кожен із них може керувати тим самим набором дозволів. Ізоляція сесій/пам’яті на рівні користувача допомагає конфіденційності, але не перетворює спільного агента на авторизацію хоста на рівні окремого користувача. +- Якщо хтось може змінювати стан/конфігурацію хоста Gateway (`~/.openclaw`, включно з `openclaw.json`), вважайте його довіреним оператором. +- Запуск одного Gateway для кількох взаємно недовірених/ворожих операторів **не є рекомендованою конфігурацією**. +- Для команд зі змішаним рівнем довіри розділяйте межі довіри за допомогою окремих Gateway (або щонайменше окремих користувачів ОС/хостів). +- Рекомендований типовий варіант: один користувач на машину/хост (або VPS), один gateway для цього користувача та один або кілька агентів у цьому gateway. +- У межах одного екземпляра Gateway автентифікований операторський доступ — це довірена роль площини керування, а не роль окремого користувача-орендаря. +- Ідентифікатори сеансу (`sessionKey`, session IDs, labels) — це селектори маршрутизації, а не токени авторизації. +- Якщо кілька людей можуть надсилати повідомлення одному агенту з увімкненими інструментами, кожен із них може керувати однаковим набором дозволів. Ізоляція сеансів/пам’яті на рівні користувача допомагає приватності, але не перетворює спільного агента на авторизацію хоста на рівні окремого користувача. -### Спільний робочий простір Slack: реальний ризик +### Спільний Slack workspace: реальний ризик -Якщо «будь-хто у Slack може написати боту», основний ризик — це делеговані повноваження інструментів: +Якщо «будь-хто в Slack може написати боту», основний ризик — це делеговані повноваження інструментів: -- будь-який дозволений відправник може спричинити виклики інструментів (`exec`, браузер, мережеві/файлові інструменти) в межах політик агента; -- ін’єкція підказок/вмісту від одного відправника може викликати дії, що впливають на спільний стан, пристрої або результати; -- якщо один спільний агент має доступ до чутливих облікових даних/файлів, будь-який дозволений відправник потенційно може спричинити витік через використання інструментів. +- будь-який дозволений відправник може ініціювати виклики інструментів (`exec`, браузер, мережеві/файлові інструменти) у межах політики агента; +- ін’єкція підказок/вмісту від одного відправника може спричинити дії, що впливають на спільний стан, пристрої або результати; +- якщо один спільний агент має доступ до чутливих облікових даних/файлів, будь-який дозволений відправник потенційно може ініціювати їх ексфільтрацію через використання інструментів. -Для командних сценаріїв використовуйте окремих агентів/шлюзи з мінімальним набором інструментів; агентів із персональними даними тримайте приватними. +Для командних робочих процесів використовуйте окремі агенти/Gateway з мінімальним набором інструментів; агентів із персональними даними тримайте приватними. -### Спільний агент компанії: прийнятний шаблон +### Спільний агент у компанії: прийнятний шаблон -Це прийнятно, якщо всі, хто користується цим агентом, перебувають у межах однієї довіри (наприклад, одна команда в компанії) і агент суворо обмежений робочими завданнями. +Це прийнятно, коли всі користувачі такого агента належать до однієї межі довіри (наприклад, одна команда в компанії), а сам агент суворо обмежений бізнес-контекстом. - запускайте його на виділеній машині/VM/контейнері; -- використовуйте окремого користувача ОС + окремий браузер/профіль/акаунти для цього runtime; -- не входьте в цьому runtime у персональні облікові записи Apple/Google чи особисті профілі браузера/менеджера паролів. +- використовуйте виділеного користувача ОС + окремий браузер/профіль/акаунти для цього середовища; +- не входьте в цьому середовищі до особистих Apple/Google-акаунтів чи особистих профілів браузера/менеджера паролів. -Якщо ви змішуєте особисті та корпоративні ідентичності в одному runtime, ви руйнуєте поділ і підвищуєте ризик витоку персональних даних. +Якщо ви змішуєте особисті й корпоративні ідентичності в одному середовищі, ви руйнуєте розділення та підвищуєте ризик витоку персональних даних. -## Концепція довіри між Gateway і node +## Концепція довіри між Gateway і Node -Розглядайте Gateway і node як одну доменну область довіри оператора, але з різними ролями: +Розглядайте Gateway і Node як єдиний домен довіри оператора, але з різними ролями: -- **Gateway** — це control plane і поверхня політик (`gateway.auth`, політика інструментів, маршрутизація). -- **Node** — це поверхня віддаленого виконання, пов’язана з цим Gateway (команди, дії з пристроями, можливості хоста на цьому вузлі). -- Викликаючий, автентифікований у Gateway, є довіреним у межах Gateway. Після pairing дії node вважаються діями довіреного оператора на цьому node. -- `sessionKey` — це вибір маршрутизації/контексту, а не автентифікація на рівні користувача. -- Схвалення exec (allowlist + ask) — це запобіжники для наміру оператора, а не ізоляція від ворожих багатокористувацьких сценаріїв. -- Типова поведінка продукту OpenClaw для довірених конфігурацій з одним оператором полягає в тому, що host exec на `gateway`/`node` дозволений без запитів на схвалення (`security="full"`, `ask="off"`, якщо ви самі не посилите політику). Цей типовий режим — свідоме UX-рішення, а не вразливість сам по собі. -- Схвалення exec прив’язані до точного контексту запиту та, наскільки можливо, до прямих локальних файлових операндів; вони не моделюють семантично всі шляхи завантаження під час виконання/інтерпретації. Для сильних меж використовуйте sandboxing та ізоляцію хоста. +- **Gateway** — це площина керування та поверхня політик (`gateway.auth`, політика інструментів, маршрутизація). +- **Node** — це поверхня віддаленого виконання, пов’язана з цим Gateway (команди, дії на пристрої, локальні можливості хоста). +- Викликач, автентифікований у Gateway, є довіреним у межах Gateway. Після pairing дії Node вважаються довіреними операторськими діями на цьому Node. +- `sessionKey` — це вибір маршрутизації/контексту, а не автентифікація окремого користувача. +- Схвалення exec (allowlist + ask) — це запобіжники для намірів оператора, а не ізоляція від ворожих багатокористувацьких сценаріїв. +- Типова поведінка OpenClaw для довірених конфігурацій з одним оператором полягає в тому, що виконання на хості через `gateway`/`node` дозволене без запитів на схвалення (`security="full"`, `ask="off"`, якщо ви не посилите політику). Це навмисне UX-рішення, а не вразливість саме по собі. +- Схвалення exec прив’язуються до точного контексту запиту та, наскільки можливо, до прямих локальних файлових операндів; вони не моделюють семантично кожен шлях завантаження runtime/інтерпретатора. Для сильних меж використовуйте sandboxing та ізоляцію хоста. -Якщо вам потрібна ізоляція від ворожих користувачів, розділяйте межі довіри за користувачами ОС/хостами й запускайте окремі шлюзи. +Якщо вам потрібна ізоляція від ворожих користувачів, розділяйте межі довіри за користувачем ОС/хостом і запускайте окремі Gateway. ## Матриця меж довіри -Використовуйте це як швидку модель під час оцінювання ризику: +Використовуйте це як швидку модель під час оцінки ризику: | Межа або контроль | Що це означає | Типове хибне тлумачення | | -------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------- | -| `gateway.auth` (token/password/trusted-proxy/device auth) | Автентифікує виклики до API шлюзу | «Щоб було безпечно, потрібні підписи кожного повідомлення в кожному кадрі» | -| `sessionKey` | Ключ маршрутизації для вибору контексту/сесії | «Ключ сесії — це межа автентифікації користувача» | -| Запобіжники для prompt/content | Знижують ризик зловживання моделлю | «Одна лише prompt injection уже доводить обхід автентифікації» | -| `canvas.eval` / browser evaluate | Навмисна можливість оператора, коли увімкнено | «Будь-який примітив JS eval автоматично є вразливістю в цій моделі довіри» | -| Локальна TUI-команда `!` shell | Явний локальний запуск, ініційований оператором | «Зручна локальна shell-команда — це віддалена ін’єкція» | -| Pairing node і команди node | Віддалене виконання на рівні оператора на paired-пристроях | «Керування віддаленим пристроєм за замовчуванням слід вважати доступом недовіреного користувача» | +| `gateway.auth` (token/password/trusted-proxy/device auth) | Автентифікує викликачів до API Gateway | «Щоб бути безпечною, система потребує підпису кожного повідомлення в кожному кадрі» | +| `sessionKey` | Ключ маршрутизації для вибору контексту/сеансу | «Ключ сеансу — це межа автентифікації користувача» | +| Запобіжники для prompt/content | Зменшують ризик зловживання моделлю | «Одна лише prompt injection уже доводить обхід автентифікації» | +| `canvas.eval` / browser evaluate | Навмисна операторська можливість, коли увімкнена | «Будь-який примітив JS eval автоматично є вразливістю в цій моделі довіри» | +| Локальна TUI-оболонка `!` | Явно ініційоване оператором локальне виконання | «Локальна зручна shell-команда — це віддалена ін’єкція» | +| Pairing Node і команди Node | Віддалене виконання на рівні оператора на пов’язаних пристроях | «Керування віддаленим пристроєм слід за замовчуванням трактувати як доступ недовіреного користувача» | -## За задумом не є вразливостями +## Не є вразливостями за задумом -Ці шаблони часто повідомляють як проблеми, але зазвичай їх закривають без дій, якщо не показано реальний обхід межі: +Про ці шаблони часто повідомляють, але зазвичай їх закривають без дій, якщо не показано реальний обхід межі: -- Ланцюжки, що ґрунтуються лише на prompt injection без обходу політик/автентифікації/sandbox. -- Твердження, які припускають ворожий багатокористувацький сценарій на одному спільному хості/конфігурації. -- Твердження, які класифікують нормальний операторський доступ на читання (наприклад, `sessions.list`/`sessions.preview`/`chat.history`) як IDOR у конфігурації спільного gateway. -- Знахідки, релевантні лише для localhost-розгортання (наприклад, HSTS на шлюзі, доступному тільки через loopback). -- Знахідки щодо підпису вхідних webhook Discord для вхідних шляхів, яких у цьому репозиторії не існує. -- Звіти, які трактують метадані pairing node як прихований другий шар схвалення для кожної команди `system.run`, хоча реальна межа виконання — це глобальна політика команд node на шлюзі плюс власні схвалення exec на node. -- Знахідки про «відсутність авторизації на рівні користувача», які трактують `sessionKey` як токен автентифікації. +- Ланцюги, що складаються лише з prompt injection, без обходу політики/автентифікації/sandbox. +- Твердження, що припускають вороже багатокористувацьке використання на одному спільному хості/конфігурації. +- Твердження, які класифікують звичайний операторський доступ на читання (наприклад `sessions.list`/`sessions.preview`/`chat.history`) як IDOR у конфігурації зі спільним gateway. +- Висновки щодо розгортань лише на localhost (наприклад HSTS для gateway, доступного лише через loopback). +- Повідомлення про підпис вхідних webhook Discord для вхідних шляхів, яких немає в цьому репозиторії. +- Повідомлення, які трактують метадані pairing Node як прихований другий рівень схвалення кожної команди для `system.run`, хоча реальною межею виконання все ще є глобальна політика команд Node у gateway плюс власні схвалення exec самого Node. +- Повідомлення про «відсутність авторизації на рівні користувача», які трактують `sessionKey` як токен автентифікації. -## Контрольний список дослідника перед поданням +## Контрольний список для дослідника перед відкриттям GHSA -Перш ніж відкривати GHSA, перевірте все з цього списку: +Перш ніж відкривати GHSA, перевірте все з наведеного нижче: -1. Відтворення досі працює на останньому `main` або останньому релізі. -2. Звіт містить точний шлях у коді (`file`, function, line range) і протестовану версію/коміт. -3. Вплив перетинає задокументовану межу довіри, а не лише prompt injection. -4. Твердження не входить до списку [Out of Scope](https://github.com/openclaw/openclaw/blob/main/SECURITY.md#out-of-scope). -5. Наявні advisory вже перевірено на дублікати (за потреби використовуйте канонічний GHSA повторно). -6. Припущення щодо розгортання явно вказані (loopback/local чи exposed, довірені чи недовірені оператори). +1. Відтворення все ще працює на останньому `main` або в останньому релізі. +2. Повідомлення містить точний шлях у коді (`file`, function, line range) і перевірену версію/коміт. +3. Вплив перетинає задокументовану межу довіри (а не лише prompt injection). +4. Заявлена проблема не входить до [Out of Scope](https://github.com/openclaw/openclaw/blob/main/SECURITY.md#out-of-scope). +5. Наявні advisory уже перевірені на дублікати (за потреби використовуйте канонічний GHSA повторно). +6. Припущення щодо розгортання явно описані (loopback/local чи exposed, довірені чи недовірені оператори). -## Посилена базова конфігурація за 60 секунд +## Посилений базовий захист за 60 секунд -Спочатку використовуйте цю базову конфігурацію, а потім вибірково знову вмикайте інструменти для довірених агентів: +Спочатку використовуйте цей базовий профіль, а потім вибірково знову вмикайте інструменти для довірених агентів: ```json5 { @@ -167,216 +167,210 @@ OpenClaw виходить із довіри до хоста та межі кон } ``` -Це залишає Gateway доступним лише локально, ізолює DM і за замовчуванням вимикає інструменти control-plane/runtime. +Це залишає Gateway доступним лише локально, ізолює DM і за замовчуванням вимикає інструменти площини керування/runtime. -## Швидке правило для спільної скриньки вхідних +## Швидке правило для спільної вхідної скриньки Якщо більше ніж одна людина може надсилати DM вашому боту: -- Встановіть `session.dmScope: "per-channel-peer"` (або `"per-account-channel-peer"` для багатoакаунтних каналів). -- Залишайте `dmPolicy: "pairing"` або використовуйте суворі allowlist. +- Установіть `session.dmScope: "per-channel-peer"` (або `"per-account-channel-peer"` для каналів із кількома акаунтами). +- Використовуйте `dmPolicy: "pairing"` або суворі allowlist. - Ніколи не поєднуйте спільні DM із широким доступом до інструментів. -- Це посилює захист для кооперативних/спільних вхідних, але не призначене для ворожої ізоляції співкористувачів, якщо вони мають спільний доступ на запис до хоста/конфігурації. +- Це посилює захист кооперативних/спільних вхідних скриньок, але не призначене для ворожої коорендної ізоляції, коли користувачі мають спільний доступ на запис до хоста/конфігурації. ## Модель видимості контексту OpenClaw розділяє два поняття: -- **Авторизація запуску**: хто може активувати агента (`dmPolicy`, `groupPolicy`, allowlist, вимоги щодо згадки). -- **Видимість контексту**: який додатковий контекст інжектується у вхід моделі (тіло відповіді, процитований текст, історія треду, метадані пересилання). +- **Авторизація запуску**: хто може запускати агента (`dmPolicy`, `groupPolicy`, allowlist, обмеження згадуваннями). +- **Видимість контексту**: який додатковий контекст вбудовується у вхід моделі (тіло відповіді, процитований текст, історія гілки, метадані пересилання). -Allowlists керують запуском і авторизацією команд. Налаштування `contextVisibility` визначає, як фільтрується додатковий контекст (цитовані відповіді, кореневі повідомлення треду, витягнута історія): +Allowlist контролюють запуск і авторизацію команд. Налаштування `contextVisibility` визначає, як фільтрується додатковий контекст (процитовані відповіді, корені гілок, отримана історія): -- `contextVisibility: "all"` (типово) залишає додатковий контекст у тому вигляді, як він був отриманий. -- `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників, дозволених активними перевірками allowlist. -- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все одно зберігає одну явно процитовану відповідь. +- `contextVisibility: "all"` (типове значення) зберігає додатковий контекст у тому вигляді, у якому його отримано. +- `contextVisibility: "allowlist"` фільтрує додатковий контекст за відправниками, дозволеними активними перевірками allowlist. +- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все ж зберігає одну явну процитовану відповідь. -Встановлюйте `contextVisibility` на рівні каналу або кімнати/розмови. Докладніше див. у [Групові чати](/uk/channels/groups#context-visibility-and-allowlists). +Установлюйте `contextVisibility` для каналу або для кімнати/розмови. Докладніше про налаштування див. у [Групові чати](/uk/channels/groups#context-visibility-and-allowlists). Рекомендації для triage advisory: -- Твердження, які лише показують, що «модель може бачити процитований або історичний текст від відправників поза allowlist», є hardening-знахідками, які можна усунути через `contextVisibility`, але самі по собі не є обходом меж автентифікації чи sandbox. -- Щоб вважатися суттєвими для безпеки, звіти все одно мають демонструвати обхід межі довіри (автентифікація, політика, sandbox, схвалення або інша задокументована межа). +- Твердження, які лише показують, що «модель може бачити процитований або історичний текст від відправників поза allowlist», є висновками щодо посилення захисту, які можна усунути за допомогою `contextVisibility`, а не самі по собі обходом межі автентифікації чи sandbox. +- Щоб мати безпековий вплив, повідомлення все одно повинні демонструвати обхід межі довіри (автентифікація, політика, sandbox, схвалення або інша задокументована межа). ## Що перевіряє аудит (на високому рівні) -- **Вхідний доступ** (політики DM, групові політики, allowlist): чи можуть сторонні користувачі активувати бота? -- **Радіус ураження інструментів** (підвищені інструменти + відкриті кімнати): чи може prompt injection перетворитися на дії в оболонці/файловій системі/мережі? -- **Зсув схвалення exec** (`security=full`, `autoAllowSkills`, allowlist інтерпретаторів без `strictInlineEval`): чи й далі запобіжники host-exec працюють так, як ви очікуєте? - - `security="full"` — це широке попередження про рівень ризику, а не доказ помилки. Це свідомо обраний типовий режим для довірених конфігурацій персонального асистента; посилюйте його лише тоді, коли ваша модель загроз вимагає схвалення або запобіжників allowlist. -- **Відкритість мережі** (bind/auth Gateway, Tailscale Serve/Funnel, слабкі/короткі токени автентифікації). -- **Відкритість керування браузером** (віддалені nodes, relay-порти, віддалені CDP endpoints). -- **Гігієна локального диска** (дозволи, symlink, include конфігурації, шляхи «synced folder»). -- **Plugins** (розширення існують без явного allowlist). -- **Зсув політик/помилки конфігурації** (налаштовано sandbox docker settings, але режим sandbox вимкнений; неефективні шаблони `gateway.nodes.denyCommands`, бо зіставлення виконується лише за точною назвою команди (наприклад, `system.run`) і не аналізує текст оболонки; небезпечні записи `gateway.nodes.allowCommands`; глобальний `tools.profile="minimal"` перевизначено профілями на рівні агента; інструменти extension plugin доступні через поблажливу політику інструментів). -- **Зсув очікувань runtime** (наприклад, припущення, що неявний exec усе ще означає `sandbox`, хоча `tools.exec.host` тепер типово має значення `auto`, або явне встановлення `tools.exec.host="sandbox"` при вимкненому режимі sandbox). -- **Гігієна моделей** (попереджає, якщо налаштовані моделі виглядають застарілими; це не жорстке блокування). +- **Вхідний доступ** (політики DM, групові політики, allowlist): чи можуть сторонні люди запускати бота? +- **Радіус ураження інструментів** (розширені інструменти + відкриті кімнати): чи може prompt injection перетворитися на дії в оболонці/з файлами/мережею? +- **Дрейф схвалення exec** (`security=full`, `autoAllowSkills`, allowlist інтерпретаторів без `strictInlineEval`): чи запобіжники host-exec усе ще працюють так, як ви очікуєте? + - `security="full"` — це широке попередження про режим безпеки, а не доказ помилки. Це обраний варіант за замовчуванням для довірених конфігурацій персонального асистента; посилюйте його лише тоді, коли ваша модель загроз вимагає схвалення або запобіжників allowlist. +- **Мережевий доступ** (bind/auth Gateway, Tailscale Serve/Funnel, слабкі/короткі токени автентифікації). +- **Доступ до керування браузером** (віддалені Node, relay-порти, віддалені кінцеві точки CDP). +- **Гігієна локального диска** (дозволи, symlink, include конфігурації, шляхи «синхронізованих папок»). +- **Плагіни** (розширення існують без явного allowlist). +- **Дрейф політик/помилки конфігурації** (налаштування sandbox docker задані, але режим sandbox вимкнений; неефективні шаблони `gateway.nodes.denyCommands`, тому що зіставлення виконується лише за точною назвою команди (наприклад `system.run`) і не аналізує текст оболонки; небезпечні записи `gateway.nodes.allowCommands`; глобальний `tools.profile="minimal"` перевизначено профілями окремих агентів; інструменти розширень Plugin доступні через надто поблажливу політику інструментів). +- **Дрейф очікувань runtime** (наприклад, припущення, що неявний exec і далі означає `sandbox`, хоча `tools.exec.host` тепер за замовчуванням має значення `auto`, або явне встановлення `tools.exec.host="sandbox"` при вимкненому режимі sandbox). +- **Гігієна моделей** (попередження, якщо налаштовані моделі виглядають застарілими; не є жорстким блокуванням). -Якщо ви запускаєте `--deep`, OpenClaw також виконує best-effort live probe Gateway. +Якщо ви запускаєте `--deep`, OpenClaw також намагається виконати best-effort live-перевірку Gateway. ## Карта зберігання облікових даних -Використовуйте це під час аудиту доступу або коли вирішуєте, що саме резервно копіювати: +Використовуйте це під час аудиту доступу або коли вирішуєте, що резервувати: - **WhatsApp**: `~/.openclaw/credentials/whatsapp//creds.json` -- **Telegram bot token**: config/env або `channels.telegram.tokenFile` (лише звичайний файл; symlink відхиляються) -- **Discord bot token**: config/env або SecretRef (провайдери env/file/exec) -- **Slack tokens**: config/env (`channels.slack.*`) -- **Pairing allowlist**: +- **Токен Telegram-бота**: config/env або `channels.telegram.tokenFile` (лише звичайний файл; symlink відхиляються) +- **Токен Discord-бота**: config/env або SecretRef (постачальники env/file/exec) +- **Токени Slack**: config/env (`channels.slack.*`) +- **Allowlist pairing**: - `~/.openclaw/credentials/-allowFrom.json` (типовий акаунт) - `~/.openclaw/credentials/--allowFrom.json` (нетипові акаунти) - **Профілі автентифікації моделей**: `~/.openclaw/agents//agent/auth-profiles.json` -- **Payload секретів на основі файлу (необов’язково)**: `~/.openclaw/secrets.json` +- **Файл із payload секретів (необов’язково)**: `~/.openclaw/secrets.json` - **Імпорт застарілого OAuth**: `~/.openclaw/credentials/oauth.json` ## Контрольний список аудиту безпеки -Коли аудит виводить результати, сприймайте це як порядок пріоритетів: +Коли аудит виводить висновки, дотримуйтеся такого порядку пріоритетів: -1. **Будь-що “open” + увімкнені інструменти**: спочатку обмежте DM/групи (pairing/allowlist), потім посильте політику інструментів/sandboxing. -2. **Публічна мережева відкритість** (bind у LAN, Funnel, відсутня автентифікація): виправляйте негайно. -3. **Віддалена відкритість керування браузером**: ставтеся до цього як до операторського доступу (лише tailnet, pairing nodes навмисно, уникайте публічної відкритості). -4. **Дозволи**: переконайтеся, що state/config/credentials/auth не доступні на читання групі або всім. -5. **Plugins/extensions**: завантажуйте лише те, чому явно довіряєте. -6. **Вибір моделі**: для будь-якого бота з інструментами надавайте перевагу сучасним, стійким до інструкцій моделям. +1. **Усе, що є “open” + увімкнені інструменти**: спочатку обмежте DM/групи (pairing/allowlist), потім посильте політику інструментів/sandboxing. +2. **Публічний мережевий доступ** (bind у LAN, Funnel, відсутність auth): виправляйте негайно. +3. **Віддалений доступ до керування браузером**: ставтеся до цього як до операторського доступу (лише tailnet, навмисне pair Node, уникайте публічного доступу). +4. **Дозволи**: переконайтеся, що state/config/credentials/auth недоступні для читання групою або всіма. +5. **Плагіни/розширення**: завантажуйте лише те, чому ви явно довіряєте. +6. **Вибір моделі**: для будь-якого бота з інструментами віддавайте перевагу сучасним моделям, загартованим проти інструкційних атак. ## Глосарій аудиту безпеки -`checkId` з високим сигналом, які ви найімовірніше побачите в реальних розгортаннях (не вичерпний список): +Найбільш показові значення `checkId`, які ви, найімовірніше, побачите в реальних розгортаннях (список не є вичерпним): -| `checkId` | Серйозність | Чому це важливо | Основний ключ/шлях для виправлення | Авто-виправлення | -| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ---------------- | -| `fs.state_dir.perms_world_writable` | critical | Інші користувачі/процеси можуть змінювати весь стан OpenClaw | дозволи файлової системи для `~/.openclaw` | так | -| `fs.state_dir.perms_group_writable` | warn | Користувачі групи можуть змінювати весь стан OpenClaw | дозволи файлової системи для `~/.openclaw` | так | -| `fs.state_dir.perms_readable` | warn | Каталог стану доступний для читання іншими | дозволи файлової системи для `~/.openclaw` | так | -| `fs.state_dir.symlink` | warn | Ціль каталогу стану стає іншою межею довіри | схема файлової системи каталогу стану | ні | -| `fs.config.perms_writable` | critical | Інші можуть змінювати політики auth/tool/config | дозволи файлової системи для `~/.openclaw/openclaw.json` | так | -| `fs.config.symlink` | warn | Ціль файлу конфігурації стає іншою межею довіри | схема файлової системи файлу конфігурації | ні | -| `fs.config.perms_group_readable` | warn | Користувачі групи можуть читати токени/налаштування з конфігурації | дозволи файлової системи для файлу конфігурації | так | -| `fs.config.perms_world_readable` | critical | Конфігурація може розкривати токени/налаштування | дозволи файлової системи для файлу конфігурації | так | -| `fs.config_include.perms_writable` | critical | Include-файл конфігурації може бути змінений іншими | дозволи include-файлу, на який посилається `openclaw.json` | так | -| `fs.config_include.perms_group_readable` | warn | Користувачі групи можуть читати включені секрети/налаштування | дозволи include-файлу, на який посилається `openclaw.json` | так | -| `fs.config_include.perms_world_readable` | critical | Включені секрети/налаштування доступні для читання всім | дозволи include-файлу, на який посилається `openclaw.json` | так | -| `fs.auth_profiles.perms_writable` | critical | Інші можуть підмінити або замінити збережені облікові дані моделі | дозволи для `agents//agent/auth-profiles.json` | так | -| `fs.auth_profiles.perms_readable` | warn | Інші можуть читати API-ключі та OAuth-токени | дозволи для `agents//agent/auth-profiles.json` | так | -| `fs.credentials_dir.perms_writable` | critical | Інші можуть змінювати стан pairing/облікових даних каналів | дозволи файлової системи для `~/.openclaw/credentials` | так | -| `fs.credentials_dir.perms_readable` | warn | Інші можуть читати стан облікових даних каналів | дозволи файлової системи для `~/.openclaw/credentials` | так | -| `fs.sessions_store.perms_readable` | warn | Інші можуть читати транскрипти/метадані сесій | дозволи сховища сесій | так | -| `fs.log_file.perms_readable` | warn | Інші можуть читати журнали, що хоч і редаговані, але все ще містять чутливі дані | дозволи для файла журналу gateway | так | -| `fs.synced_dir` | warn | Стан/конфігурація в iCloud/Dropbox/Drive розширюють доступ до токенів/транскриптів | перемістіть конфігурацію/стан поза межі синхронізованих папок | ні | -| `gateway.bind_no_auth` | critical | Віддалений bind без спільного секрету | `gateway.bind`, `gateway.auth.*` | ні | -| `gateway.loopback_no_auth` | critical | Loopback за reverse proxy може стати неавтентифікованим | `gateway.auth.*`, налаштування proxy | ні | -| `gateway.trusted_proxies_missing` | warn | Заголовки reverse proxy присутні, але proxy не позначені як довірені | `gateway.trustedProxies` | ні | -| `gateway.http.no_auth` | warn/critical | HTTP API gateway доступні з `auth.mode="none"` | `gateway.auth.mode`, `gateway.http.endpoints.*` | ні | -| `gateway.http.session_key_override_enabled` | info | Клієнти HTTP API можуть перевизначати `sessionKey` | `gateway.http.allowSessionKeyOverride` | ні | -| `gateway.tools_invoke_http.dangerous_allow` | warn/critical | Повторно вмикає небезпечні інструменти через HTTP API | `gateway.tools.allow` | ні | -| `gateway.nodes.allow_commands_dangerous` | warn/critical | Вмикає високоризикові команди node (камера/екран/контакти/календар/SMS) | `gateway.nodes.allowCommands` | ні | -| `gateway.nodes.deny_commands_ineffective` | warn | Записи deny у стилі шаблонів не зіставляються з текстом оболонки або групами | `gateway.nodes.denyCommands` | ні | -| `gateway.tailscale_funnel` | critical | Публічна доступність з інтернету | `gateway.tailscale.mode` | ні | -| `gateway.tailscale_serve` | info | Доступність у tailnet увімкнена через Serve | `gateway.tailscale.mode` | ні | -| `gateway.control_ui.allowed_origins_required` | critical | Control UI поза loopback без явного allowlist джерел браузера | `gateway.controlUi.allowedOrigins` | ні | -| `gateway.control_ui.allowed_origins_wildcard` | warn/critical | `allowedOrigins=["*"]` вимикає allowlist джерел браузера | `gateway.controlUi.allowedOrigins` | ні | -| `gateway.control_ui.host_header_origin_fallback` | warn/critical | Вмикає fallback походження через Host-header (послаблення захисту від DNS rebinding) | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | ні | -| `gateway.control_ui.insecure_auth` | warn | Увімкнено compatibility toggle для небезпечної автентифікації | `gateway.controlUi.allowInsecureAuth` | ні | -| `gateway.control_ui.device_auth_disabled` | critical | Вимикає перевірку ідентичності пристрою | `gateway.controlUi.dangerouslyDisableDeviceAuth` | ні | -| `gateway.real_ip_fallback_enabled` | warn/critical | Довіра до fallback `X-Real-IP` може дозволити підміну source IP через помилку proxy | `gateway.allowRealIpFallback`, `gateway.trustedProxies` | ні | -| `gateway.token_too_short` | warn | Короткий спільний токен легше підібрати перебором | `gateway.auth.token` | ні | -| `gateway.auth_no_rate_limit` | warn | Відкрита автентифікація без rate limiting підвищує ризик brute force | `gateway.auth.rateLimit` | ні | -| `gateway.trusted_proxy_auth` | critical | Ідентичність proxy тепер стає межею автентифікації | `gateway.auth.mode="trusted-proxy"` | ні | -| `gateway.trusted_proxy_no_proxies` | critical | Автентифікація trusted-proxy без IP довірених proxy є небезпечною | `gateway.trustedProxies` | ні | -| `gateway.trusted_proxy_no_user_header` | critical | Автентифікація trusted-proxy не може безпечно визначити ідентичність користувача | `gateway.auth.trustedProxy.userHeader` | ні | -| `gateway.trusted_proxy_no_allowlist` | warn | Автентифікація trusted-proxy приймає будь-якого автентифікованого користувача зверху | `gateway.auth.trustedProxy.allowUsers` | ні | -| `checkId` | Серйозність | Чому це важливо | Основний ключ/шлях для виправлення | Авто-виправлення | -| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ---------------- | -| `gateway.probe_auth_secretref_unavailable` | warn | Deep probe не зміг визначити auth SecretRef у цьому шляху виконання команди | джерело auth для deep probe / доступність SecretRef | ні | -| `gateway.probe_failed` | warn/critical | Live probe Gateway завершився невдачею | доступність gateway / auth | ні | +| `checkId` | Серйозність | Чому це важливо | Основний ключ/шлях для виправлення | Авто-виправлення | +| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ---------------- | +| `fs.state_dir.perms_world_writable` | critical | Інші користувачі/процеси можуть змінювати весь стан OpenClaw | дозволи файлової системи для `~/.openclaw` | так | +| `fs.state_dir.perms_group_writable` | warn | Користувачі групи можуть змінювати весь стан OpenClaw | дозволи файлової системи для `~/.openclaw` | так | +| `fs.state_dir.perms_readable` | warn | Каталог стану доступний для читання іншими | дозволи файлової системи для `~/.openclaw` | так | +| `fs.state_dir.symlink` | warn | Ціль каталогу стану стає іншою межею довіри | структура файлової системи каталогу стану | ні | +| `fs.config.perms_writable` | critical | Інші можуть змінювати політику auth/tool/config | дозволи файлової системи для `~/.openclaw/openclaw.json` | так | +| `fs.config.symlink` | warn | Ціль файлу конфігурації стає іншою межею довіри | структура файлової системи файлу конфігурації | ні | +| `fs.config.perms_group_readable` | warn | Користувачі групи можуть читати токени/налаштування з конфігурації | дозволи файлової системи для файлу конфігурації | так | +| `fs.config.perms_world_readable` | critical | Конфігурація може розкривати токени/налаштування | дозволи файлової системи для файлу конфігурації | так | +| `fs.config_include.perms_writable` | critical | Файл include конфігурації може бути змінений іншими | дозволи для include-файлу, на який посилається `openclaw.json` | так | +| `fs.config_include.perms_group_readable` | warn | Користувачі групи можуть читати включені секрети/налаштування | дозволи для include-файлу, на який посилається `openclaw.json` | так | +| `fs.config_include.perms_world_readable` | critical | Включені секрети/налаштування доступні для читання всім | дозволи для include-файлу, на який посилається `openclaw.json` | так | +| `fs.auth_profiles.perms_writable` | critical | Інші можуть впроваджувати або підміняти збережені облікові дані моделей | дозволи для `agents//agent/auth-profiles.json` | так | +| `fs.auth_profiles.perms_readable` | warn | Інші можуть читати API-ключі та OAuth-токени | дозволи для `agents//agent/auth-profiles.json` | так | +| `fs.credentials_dir.perms_writable` | critical | Інші можуть змінювати стан pairing/облікових даних каналів | дозволи файлової системи для `~/.openclaw/credentials` | так | +| `fs.credentials_dir.perms_readable` | warn | Інші можуть читати стан облікових даних каналів | дозволи файлової системи для `~/.openclaw/credentials` | так | +| `fs.sessions_store.perms_readable` | warn | Інші можуть читати транскрипти/метадані сеансів | дозволи сховища сеансів | так | +| `fs.log_file.perms_readable` | warn | Інші можуть читати журнали, де дані замасковані, але все ще чутливі | дозволи для файлу журналу gateway | так | +| `fs.synced_dir` | warn | Стан/конфігурація в iCloud/Dropbox/Drive розширюють ризик витоку токенів/транскриптів | перенесіть конфігурацію/стан із синхронізованих папок | ні | +| `gateway.bind_no_auth` | critical | Віддалений bind без спільного секрету | `gateway.bind`, `gateway.auth.*` | ні | +| `gateway.loopback_no_auth` | critical | Loopback за reverse proxy може стати неавтентифікованим | `gateway.auth.*`, налаштування proxy | ні | +| `gateway.trusted_proxies_missing` | warn | Заголовки reverse proxy присутні, але не позначені як trusted | `gateway.trustedProxies` | ні | +| `gateway.http.no_auth` | warn/critical | HTTP API Gateway доступні з `auth.mode="none"` | `gateway.auth.mode`, `gateway.http.endpoints.*` | ні | +| `gateway.http.session_key_override_enabled` | info | Викликачі HTTP API можуть перевизначати `sessionKey` | `gateway.http.allowSessionKeyOverride` | ні | +| `gateway.tools_invoke_http.dangerous_allow` | warn/critical | Повторно вмикає небезпечні інструменти через HTTP API | `gateway.tools.allow` | ні | +| `gateway.nodes.allow_commands_dangerous` | warn/critical | Вмикає команди Node з високим впливом (camera/screen/contacts/calendar/SMS) | `gateway.nodes.allowCommands` | ні | +| `gateway.nodes.deny_commands_ineffective` | warn | Записи deny, схожі на шаблони, не зіставляються з текстом оболонки або групами | `gateway.nodes.denyCommands` | ні | +| `gateway.tailscale_funnel` | critical | Публічний доступ з інтернету | `gateway.tailscale.mode` | ні | +| `gateway.tailscale_serve` | info | Доступ через tailnet увімкнено через Serve | `gateway.tailscale.mode` | ні | +| `gateway.control_ui.allowed_origins_required` | critical | Control UI поза loopback без явного allowlist джерел браузера | `gateway.controlUi.allowedOrigins` | ні | +| `gateway.control_ui.allowed_origins_wildcard` | warn/critical | `allowedOrigins=["*"]` вимикає allowlist джерел браузера | `gateway.controlUi.allowedOrigins` | ні | +| `gateway.control_ui.host_header_origin_fallback` | warn/critical | Вмикає fallback походження через заголовок Host (послаблення захисту від DNS rebinding) | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | ні | +| `gateway.control_ui.insecure_auth` | warn | Увімкнено перемикач сумісності insecure-auth | `gateway.controlUi.allowInsecureAuth` | ні | +| `gateway.control_ui.device_auth_disabled` | critical | Вимикає перевірку ідентичності пристрою | `gateway.controlUi.dangerouslyDisableDeviceAuth` | ні | +| `gateway.real_ip_fallback_enabled` | warn/critical | Довіра до fallback `X-Real-IP` може дозволити підробку source-IP через помилкову конфігурацію proxy | `gateway.allowRealIpFallback`, `gateway.trustedProxies` | ні | +| `gateway.token_too_short` | warn | Короткий спільний токен легше підібрати перебором | `gateway.auth.token` | ні | +| `gateway.auth_no_rate_limit` | warn | Відкрита auth без rate limiting підвищує ризик brute-force | `gateway.auth.rateLimit` | ні | +| `gateway.trusted_proxy_auth` | critical | Ідентичність proxy тепер стає межею auth | `gateway.auth.mode="trusted-proxy"` | ні | +| `gateway.trusted_proxy_no_proxies` | critical | Автентифікація trusted-proxy без IP-адрес trusted proxy є небезпечною | `gateway.trustedProxies` | ні | +| `gateway.trusted_proxy_no_user_header` | critical | Автентифікація trusted-proxy не може безпечно визначити ідентичність користувача | `gateway.auth.trustedProxy.userHeader` | ні | +| `gateway.trusted_proxy_no_allowlist` | warn | Автентифікація trusted-proxy приймає будь-якого автентифікованого користувача upstream | `gateway.auth.trustedProxy.allowUsers` | ні | +| `gateway.probe_auth_secretref_unavailable` | warn | Глибока перевірка не змогла розв’язати auth SecretRef у цьому шляху команди | джерело auth для deep-probe / доступність SecretRef | ні | +| `gateway.probe_failed` | warn/critical | Live-перевірка Gateway завершилася невдачею | доступність/автентифікація gateway | ні | | `discovery.mdns_full_mode` | warn/critical | Повний режим mDNS рекламує метадані `cliPath`/`sshPort` у локальній мережі | `discovery.mdns.mode`, `gateway.bind` | ні | -| `config.insecure_or_dangerous_flags` | warn | Увімкнено будь-які небезпечні/ризиковані debug-прапорці | кілька ключів (див. деталі у finding) | ні | +| `config.insecure_or_dangerous_flags` | warn | Увімкнено будь-які небезпечні/незахищені debug-прапори | кілька ключів (див. деталі висновку) | ні | | `config.secrets.gateway_password_in_config` | warn | Пароль Gateway зберігається безпосередньо в конфігурації | `gateway.auth.password` | ні | -| `config.secrets.hooks_token_in_config` | warn | Bearer-токен hooks зберігається безпосередньо в конфігурації | `hooks.token` | ні | -| `hooks.token_reuse_gateway_token` | critical | Токен входу hooks також відкриває auth Gateway | `hooks.token`, `gateway.auth.token` | ні | -| `hooks.token_too_short` | warn | Полегшує brute force для входу hooks | `hooks.token` | ні | -| `hooks.default_session_key_unset` | warn | Агент hooks виконує fan out у згенеровані сесії для кожного запиту | `hooks.defaultSessionKey` | ні | -| `hooks.allowed_agent_ids_unrestricted` | warn/critical | Автентифіковані виклики hooks можуть маршрутизуватися до будь-якого налаштованого агента | `hooks.allowedAgentIds` | ні | -| `hooks.request_session_key_enabled` | warn/critical | Зовнішній викликаючий може вибирати `sessionKey` | `hooks.allowRequestSessionKey` | ні | -| `hooks.request_session_key_prefixes_missing` | warn/critical | Немає обмеження на форму зовнішніх ключів сесії | `hooks.allowedSessionKeyPrefixes` | ні | -| `hooks.path_root` | critical | Шлях hooks дорівнює `/`, що спрощує колізії або помилкову маршрутизацію входу | `hooks.path` | ні | -| `hooks.installs_unpinned_npm_specs` | warn | Записи встановлення hooks не закріплені за незмінними npm-специфікаціями | метадані встановлення hook | ні | -| `hooks.installs_missing_integrity` | warn | У записах встановлення hooks відсутні метадані integrity | метадані встановлення hook | ні | -| `hooks.installs_version_drift` | warn | Записи встановлення hooks розходяться з установленими пакетами | метадані встановлення hook | ні | -| `logging.redact_off` | warn | Чутливі значення потрапляють у журнали/статус | `logging.redactSensitive` | так | -| `browser.control_invalid_config` | warn | Конфігурація керування браузером некоректна ще до runtime | `browser.*` | ні | -| `browser.control_no_auth` | critical | Керування браузером відкрите без auth через токен/пароль | `gateway.auth.*` | ні | -| `browser.remote_cdp_http` | warn | Віддалений CDP через звичайний HTTP не має шифрування транспорту | профіль браузера `cdpUrl` | ні | -| `browser.remote_cdp_private_host` | warn | Віддалений CDP спрямовано на приватний/внутрішній хост | профіль браузера `cdpUrl`, `browser.ssrfPolicy.*` | ні | +| `config.secrets.hooks_token_in_config` | warn | Bearer-токен hook зберігається безпосередньо в конфігурації | `hooks.token` | ні | +| `hooks.token_reuse_gateway_token` | critical | Токен входу hook також відкриває доступ до auth Gateway | `hooks.token`, `gateway.auth.token` | ні | +| `hooks.token_too_short` | warn | Полегшує brute force для входу hook | `hooks.token` | ні | +| `hooks.default_session_key_unset` | warn | Агент hook виконує fan out у згенеровані сеанси для кожного запиту | `hooks.defaultSessionKey` | ні | +| `hooks.allowed_agent_ids_unrestricted` | warn/critical | Автентифіковані викликачі hook можуть маршрутизувати до будь-якого налаштованого агента | `hooks.allowedAgentIds` | ні | +| `hooks.request_session_key_enabled` | warn/critical | Зовнішній викликач може вибирати `sessionKey` | `hooks.allowRequestSessionKey` | ні | +| `hooks.request_session_key_prefixes_missing` | warn/critical | Немає обмеження на форму зовнішніх ключів сеансу | `hooks.allowedSessionKeyPrefixes` | ні | +| `hooks.path_root` | critical | Шлях hook — `/`, що полегшує колізії або помилкову маршрутизацію входу | `hooks.path` | ні | +| `hooks.installs_unpinned_npm_specs` | warn | Записи встановлення hook не прив’язані до незмінних npm-специфікацій | метадані встановлення hook | ні | +| `hooks.installs_missing_integrity` | warn | У записах встановлення hook відсутні метадані integrity | метадані встановлення hook | ні | +| `hooks.installs_version_drift` | warn | Записи встановлення hook розходяться зі встановленими пакетами | метадані встановлення hook | ні | +| `logging.redact_off` | warn | Чутливі значення витікають у журнали/статус | `logging.redactSensitive` | так | +| `browser.control_invalid_config` | warn | Конфігурація керування браузером недійсна ще до runtime | `browser.*` | ні | +| `browser.control_no_auth` | critical | Керування браузером відкрите без auth через token/password | `gateway.auth.*` | ні | +| `browser.remote_cdp_http` | warn | Віддалений CDP через звичайний HTTP не має транспортного шифрування | профіль браузера `cdpUrl` | ні | +| `browser.remote_cdp_private_host` | warn | Віддалений CDP націлений на приватний/внутрішній хост | профіль браузера `cdpUrl`, `browser.ssrfPolicy.*` | ні | | `sandbox.docker_config_mode_off` | warn | Конфігурація Docker sandbox присутня, але неактивна | `agents.*.sandbox.mode` | ні | | `sandbox.bind_mount_non_absolute` | warn | Відносні bind mount можуть розв’язуватися непередбачувано | `agents.*.sandbox.docker.binds[]` | ні | -| `sandbox.dangerous_bind_mount` | critical | Bind mount у sandbox спрямовано на заблоковані системні шляхи, шляхи облікових даних або Docker socket | `agents.*.sandbox.docker.binds[]` | ні | -| `sandbox.dangerous_network_mode` | critical | Мережа Docker sandbox використовує `host` або режим приєднання до простору імен `container:*` | `agents.*.sandbox.docker.network` | ні | -| `sandbox.dangerous_seccomp_profile` | critical | Профіль seccomp для sandbox послаблює ізоляцію контейнера | `agents.*.sandbox.docker.securityOpt` | ні | -| `sandbox.dangerous_apparmor_profile` | critical | Профіль AppArmor для sandbox послаблює ізоляцію контейнера | `agents.*.sandbox.docker.securityOpt` | ні | +| `sandbox.dangerous_bind_mount` | critical | Ціль bind mount sandbox вказує на заблоковані системні шляхи, облікові дані або шляхи сокета Docker | `agents.*.sandbox.docker.binds[]` | ні | +| `sandbox.dangerous_network_mode` | critical | Мережа Docker sandbox використовує режим `host` або `container:*` із приєднанням до простору імен | `agents.*.sandbox.docker.network` | ні | +| `sandbox.dangerous_seccomp_profile` | critical | Профіль seccomp sandbox послаблює ізоляцію контейнера | `agents.*.sandbox.docker.securityOpt` | ні | +| `sandbox.dangerous_apparmor_profile` | critical | Профіль AppArmor sandbox послаблює ізоляцію контейнера | `agents.*.sandbox.docker.securityOpt` | ні | | `sandbox.browser_cdp_bridge_unrestricted` | warn | Міст CDP браузера в sandbox відкритий без обмеження діапазону джерел | `sandbox.browser.cdpSourceRange` | ні | -| `sandbox.browser_container.non_loopback_publish` | critical | Наявний контейнер браузера публікує CDP на інтерфейсах, відмінних від loopback | конфігурація публікації контейнера браузера sandbox | ні | +| `sandbox.browser_container.non_loopback_publish` | critical | Наявний контейнер браузера публікує CDP на інтерфейсах поза loopback | конфігурація publish контейнера браузера sandbox | ні | | `sandbox.browser_container.hash_label_missing` | warn | Наявний контейнер браузера створено до поточних міток хеша конфігурації | `openclaw sandbox recreate --browser --all` | ні | | `sandbox.browser_container.hash_epoch_stale` | warn | Наявний контейнер браузера створено до поточної епохи конфігурації браузера | `openclaw sandbox recreate --browser --all` | ні | -| `tools.exec.host_sandbox_no_sandbox_defaults` | warn | `exec host=sandbox` безпечно блокується, якщо sandbox вимкнений | `tools.exec.host`, `agents.defaults.sandbox.mode` | ні | -| `tools.exec.host_sandbox_no_sandbox_agents` | warn | `exec host=sandbox` на рівні агента безпечно блокується, якщо sandbox вимкнений | `agents.list[].tools.exec.host`, `agents.list[].sandbox.mode` | ні | +| `tools.exec.host_sandbox_no_sandbox_defaults` | warn | `exec host=sandbox` безпечно завершується відмовою, якщо sandbox вимкнено | `tools.exec.host`, `agents.defaults.sandbox.mode` | ні | +| `tools.exec.host_sandbox_no_sandbox_agents` | warn | Для агента `exec host=sandbox` безпечно завершується відмовою, якщо sandbox вимкнено | `agents.list[].tools.exec.host`, `agents.list[].sandbox.mode` | ні | | `tools.exec.security_full_configured` | warn/critical | Host exec працює з `security="full"` | `tools.exec.security`, `agents.list[].tools.exec.security` | ні | -| `tools.exec.auto_allow_skills_enabled` | warn | Схвалення exec неявно довіряють skill bins | `~/.openclaw/exec-approvals.json` | ні | -| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | warn | Allowlists інтерпретаторів дозволяють inline eval без примусового повторного схвалення | `tools.exec.strictInlineEval`, `agents.list[].tools.exec.strictInlineEval`, allowlist схвалень exec | ні | -| `tools.exec.safe_bins_interpreter_unprofiled` | warn | Бінарники інтерпретаторів/runtime у `safeBins` без явних профілів розширюють ризик exec | `tools.exec.safeBins`, `tools.exec.safeBinProfiles`, `agents.list[].tools.exec.*` | ні | -| `tools.exec.safe_bins_broad_behavior` | warn | Інструменти широкої поведінки в `safeBins` послаблюють модель довіри з низьким ризиком для stdin-фільтра | `tools.exec.safeBins`, `agents.list[].tools.exec.safeBins` | ні | -| `tools.exec.safe_bin_trusted_dirs_risky` | warn | `safeBinTrustedDirs` містить змінювані або ризиковані каталоги | `tools.exec.safeBinTrustedDirs`, `agents.list[].tools.exec.safeBinTrustedDirs` | ні | -| `skills.workspace.symlink_escape` | warn | `skills/**/SKILL.md` у workspace розв’язується за межі кореня workspace (зсув через ланцюг symlink) | стан файлової системи `skills/**` у workspace | ні | -| `plugins.extensions_no_allowlist` | warn | Extensions встановлені без явного allowlist plugins | `plugins.allowlist` | ні | -| `plugins.installs_unpinned_npm_specs` | warn | Записи встановлення plugins не закріплені за незмінними npm-специфікаціями | метадані встановлення plugin | ні | -| `checkId` | Серйозність | Чому це важливо | Основний ключ/шлях для виправлення | Авто-виправлення | -| ------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ---------------- | -| `plugins.installs_missing_integrity` | warn | У записах встановлення plugin відсутні метадані integrity | метадані встановлення plugin | ні | -| `plugins.installs_version_drift` | warn | Записи встановлення plugin розходяться з установленими пакетами | метадані встановлення plugin | ні | -| `plugins.code_safety` | warn/critical | Сканування коду plugin виявило підозрілі або небезпечні шаблони | код plugin / джерело встановлення | ні | -| `plugins.code_safety.entry_path` | warn | Шлях входу plugin вказує на приховані каталоги або розташування в `node_modules` | `entry` у маніфесті plugin | ні | -| `plugins.code_safety.entry_escape` | critical | Точка входу plugin виходить за межі каталогу plugin | `entry` у маніфесті plugin | ні | -| `plugins.code_safety.scan_failed` | warn | Сканування коду plugin не вдалося завершити | шлях extension plugin / середовище сканування | ні | -| `skills.code_safety` | warn/critical | Метадані інсталятора/code для skill містять підозрілі або небезпечні шаблони | джерело встановлення skill | ні | -| `skills.code_safety.scan_failed` | warn | Сканування коду skill не вдалося завершити | середовище сканування skill | ні | -| `security.exposure.open_channels_with_exec` | warn/critical | Спільні/публічні кімнати можуть звертатися до агентів з увімкненим exec | `channels.*.dmPolicy`, `channels.*.groupPolicy`, `tools.exec.*`, `agents.list[].tools.exec.*` | ні | -| `security.exposure.open_groups_with_elevated` | critical | Відкриті групи + підвищені інструменти створюють високоризикові шляхи prompt injection | `channels.*.groupPolicy`, `tools.elevated.*` | ні | -| `security.exposure.open_groups_with_runtime_or_fs` | critical/warn | Відкриті групи можуть отримати доступ до командних/файлових інструментів без sandbox/workspace-запобіжників | `channels.*.groupPolicy`, `tools.profile/deny`, `tools.fs.workspaceOnly`, `agents.*.sandbox.mode` | ні | -| `security.trust_model.multi_user_heuristic` | warn | Конфігурація виглядає багатокористувацькою, хоча модель довіри gateway — персональний асистент | розділіть межі довіри або посильте спільний доступ (`sandbox.mode`, deny інструментів / обмеження workspace) | ні | -| `tools.profile_minimal_overridden` | warn | Перевизначення на рівні агента обходять глобальний профіль minimal | `agents.list[].tools.profile` | ні | -| `plugins.tools_reachable_permissive_policy` | warn | Інструменти extension доступні в поблажливих контекстах | `tools.profile` + allow/deny інструментів | ні | -| `models.legacy` | warn | Досі налаштовані застарілі сімейства моделей | вибір моделі | ні | +| `tools.exec.auto_allow_skills_enabled` | warn | Схвалення exec неявно довіряють skill bins | `~/.openclaw/exec-approvals.json` | ні | +| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | warn | Allowlist інтерпретаторів дозволяють inline eval без примусового повторного схвалення | `tools.exec.strictInlineEval`, `agents.list[].tools.exec.strictInlineEval`, allowlist схвалень exec | ні | +| `tools.exec.safe_bins_interpreter_unprofiled` | warn | Біни інтерпретаторів/runtime у `safeBins` без явних профілів розширюють ризик exec | `tools.exec.safeBins`, `tools.exec.safeBinProfiles`, `agents.list[].tools.exec.*` | ні | +| `tools.exec.safe_bins_broad_behavior` | warn | Інструменти з широкою поведінкою в `safeBins` послаблюють модель довіри низького ризику для фільтра stdin | `tools.exec.safeBins`, `agents.list[].tools.exec.safeBins` | ні | +| `tools.exec.safe_bin_trusted_dirs_risky` | warn | `safeBinTrustedDirs` містить змінювані або ризикові каталоги | `tools.exec.safeBinTrustedDirs`, `agents.list[].tools.exec.safeBinTrustedDirs` | ні | +| `skills.workspace.symlink_escape` | warn | `skills/**/SKILL.md` у workspace розв’язується поза коренем workspace (дрейф ланцюжка symlink) | стан файлової системи `skills/**` у workspace | ні | +| `plugins.extensions_no_allowlist` | warn | Розширення встановлені без явного allowlist Plugin | `plugins.allowlist` | ні | +| `plugins.installs_unpinned_npm_specs` | warn | Записи встановлення Plugin не прив’язані до незмінних npm-специфікацій | метадані встановлення Plugin | ні | +| `plugins.installs_missing_integrity` | warn | У записах встановлення Plugin відсутні метадані integrity | метадані встановлення Plugin | ні | +| `plugins.installs_version_drift` | warn | Записи встановлення Plugin розходяться зі встановленими пакетами | метадані встановлення Plugin | ні | +| `plugins.code_safety` | warn/critical | Сканування коду Plugin виявило підозрілі або небезпечні шаблони | код Plugin / джерело встановлення | ні | +| `plugins.code_safety.entry_path` | warn | Шлях входу Plugin вказує на приховані розташування або `node_modules` | `entry` у маніфесті Plugin | ні | +| `plugins.code_safety.entry_escape` | critical | Точка входу Plugin виходить за межі каталогу Plugin | `entry` у маніфесті Plugin | ні | +| `plugins.code_safety.scan_failed` | warn | Сканування коду Plugin не вдалося завершити | шлях розширення Plugin / середовище сканування | ні | +| `skills.code_safety` | warn/critical | Метадані/код інсталятора Skills містять підозрілі або небезпечні шаблони | джерело встановлення Skills | ні | +| `skills.code_safety.scan_failed` | warn | Сканування коду Skills не вдалося завершити | середовище сканування Skills | ні | +| `security.exposure.open_channels_with_exec` | warn/critical | Спільні/публічні кімнати можуть звертатися до агентів із увімкненим exec | `channels.*.dmPolicy`, `channels.*.groupPolicy`, `tools.exec.*`, `agents.list[].tools.exec.*` | ні | +| `security.exposure.open_groups_with_elevated` | critical | Відкриті групи + розширені інструменти створюють шляхи prompt injection з високим впливом | `channels.*.groupPolicy`, `tools.elevated.*` | ні | +| `security.exposure.open_groups_with_runtime_or_fs` | critical/warn | Відкриті групи можуть отримати доступ до командних/файлових інструментів без sandbox/обмежень workspace | `channels.*.groupPolicy`, `tools.profile/deny`, `tools.fs.workspaceOnly`, `agents.*.sandbox.mode` | ні | +| `security.trust_model.multi_user_heuristic` | warn | Конфігурація виглядає багатокористувацькою, хоча модель довіри gateway — персональний асистент | розділіть межі довіри або посильте захист для спільного використання (`sandbox.mode`, deny інструментів / обмеження workspace) | ні | +| `tools.profile_minimal_overridden` | warn | Перевизначення агента обходять глобальний профіль minimal | `agents.list[].tools.profile` | ні | +| `plugins.tools_reachable_permissive_policy` | warn | Інструменти розширень доступні в надто поблажливих контекстах | `tools.profile` + allow/deny інструментів | ні | +| `models.legacy` | warn | Досі налаштовано застарілі сімейства моделей | вибір моделі | ні | | `models.weak_tier` | warn | Налаштовані моделі нижчі за поточно рекомендовані рівні | вибір моделі | ні | -| `models.small_params` | critical/info | Малі моделі + небезпечні поверхні інструментів підвищують ризик ін’єкцій | вибір моделі + sandbox/політика інструментів | ні | -| `summary.attack_surface` | info | Зведений підсумок про стан auth, каналів, інструментів і рівень відкритості | кілька ключів (див. деталі у finding) | ні | +| `models.small_params` | critical/info | Малі моделі + небезпечні поверхні інструментів підвищують ризик ін’єкцій | вибір моделі + політика sandbox/інструментів | ні | +| `summary.attack_surface` | info | Підсумкове зведення щодо auth, каналів, інструментів і рівня доступності | кілька ключів (див. деталі висновку) | ні | ## Control UI через HTTP -Для створення ідентичності пристрою Control UI потребує **безпечного контексту** (HTTPS або localhost). -`gateway.controlUi.allowInsecureAuth` — це локальний compatibility toggle: +Control UI потребує **безпечного контексту** (HTTPS або localhost), щоб генерувати ідентичність пристрою. `gateway.controlUi.allowInsecureAuth` — це локальний перемикач сумісності: -- На localhost він дозволяє автентифікацію Control UI без ідентичності пристрою, якщо сторінку завантажено через небезпечний HTTP. +- На localhost він дозволяє автентифікацію Control UI без ідентичності пристрою, коли сторінку відкрито через небезпечний HTTP. - Він не обходить перевірки pairing. - Він не послаблює вимоги до ідентичності пристрою для віддалених (не localhost) підключень. Надавайте перевагу HTTPS (Tailscale Serve) або відкривайте UI на `127.0.0.1`. Лише для аварійних сценаріїв `gateway.controlUi.dangerouslyDisableDeviceAuth` -повністю вимикає перевірки ідентичності пристрою. Це серйозне послаблення безпеки; -тримайте цей параметр вимкненим, якщо тільки ви не займаєтеся активним налагодженням і не можете швидко все повернути назад. +повністю вимикає перевірки ідентичності пристрою. Це серйозне послаблення безпеки; тримайте його вимкненим, якщо тільки ви активно не налагоджуєте проблему і не можете швидко повернути все назад. -Окремо від цих небезпечних прапорців, успішний режим `gateway.auth.mode: "trusted-proxy"` +Окремо від цих небезпечних прапорів, успішний режим `gateway.auth.mode: "trusted-proxy"` може допускати **операторські** сесії Control UI без ідентичності пристрою. Це -свідома поведінка режиму auth, а не скорочений шлях через `allowInsecureAuth`, і вона -все одно не поширюється на сесії Control UI з роллю node. +навмисна поведінка режиму auth, а не обхід через `allowInsecureAuth`, і вона все +одно не поширюється на сесії Control UI ролі Node. -`openclaw security audit` попереджає, коли цей параметр увімкнено. +`openclaw security audit` попереджає, коли це налаштування увімкнено. -## Підсумок небезпечних або ризикованих прапорців +## Підсумок небезпечних або незахищених прапорів `openclaw security audit` включає `config.insecure_or_dangerous_flags`, коли -відомі небезпечні/ризиковані debug-перемикачі увімкнені. Наразі ця перевірка +увімкнено відомі незахищені/небезпечні debug-перемикачі. Наразі ця перевірка агрегує: - `gateway.controlUi.allowInsecureAuth=true` @@ -387,7 +381,7 @@ Allowlists керують запуском і авторизацією кома - `tools.exec.applyPatch.workspaceOnly=false` - `plugins.entries.acpx.config.permissionMode=approve-all` -Повний перелік ключів конфігурації `dangerous*` / `dangerously*`, визначених у schema конфігурації OpenClaw: +Повний список ключів конфігурації `dangerous*` / `dangerously*`, визначених у схемі конфігурації OpenClaw: - `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` - `gateway.controlUi.dangerouslyDisableDeviceAuth` @@ -399,15 +393,15 @@ Allowlists керують запуском і авторизацією кома - `channels.googlechat.dangerouslyAllowNameMatching` - `channels.googlechat.accounts..dangerouslyAllowNameMatching` - `channels.msteams.dangerouslyAllowNameMatching` -- `channels.synology-chat.dangerouslyAllowNameMatching` (канал extension) -- `channels.synology-chat.accounts..dangerouslyAllowNameMatching` (канал extension) -- `channels.synology-chat.dangerouslyAllowInheritedWebhookPath` (канал extension) -- `channels.zalouser.dangerouslyAllowNameMatching` (канал extension) -- `channels.zalouser.accounts..dangerouslyAllowNameMatching` (канал extension) -- `channels.irc.dangerouslyAllowNameMatching` (канал extension) -- `channels.irc.accounts..dangerouslyAllowNameMatching` (канал extension) -- `channels.mattermost.dangerouslyAllowNameMatching` (канал extension) -- `channels.mattermost.accounts..dangerouslyAllowNameMatching` (канал extension) +- `channels.synology-chat.dangerouslyAllowNameMatching` (канал розширення) +- `channels.synology-chat.accounts..dangerouslyAllowNameMatching` (канал розширення) +- `channels.synology-chat.dangerouslyAllowInheritedWebhookPath` (канал розширення) +- `channels.zalouser.dangerouslyAllowNameMatching` (канал розширення) +- `channels.zalouser.accounts..dangerouslyAllowNameMatching` (канал розширення) +- `channels.irc.dangerouslyAllowNameMatching` (канал розширення) +- `channels.irc.accounts..dangerouslyAllowNameMatching` (канал розширення) +- `channels.mattermost.dangerouslyAllowNameMatching` (канал розширення) +- `channels.mattermost.accounts..dangerouslyAllowNameMatching` (канал розширення) - `channels.telegram.network.dangerouslyAllowPrivateNetwork` - `channels.telegram.accounts..network.dangerouslyAllowPrivateNetwork` - `agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets` @@ -420,38 +414,38 @@ Allowlists керують запуском і авторизацією кома ## Конфігурація reverse proxy Якщо ви запускаєте Gateway за reverse proxy (nginx, Caddy, Traefik тощо), налаштуйте -`gateway.trustedProxies` для коректної обробки пересланої IP-адреси клієнта. +`gateway.trustedProxies` для коректної обробки IP-адрес клієнтів із forwarded-заголовків. -Коли Gateway виявляє заголовки proxy від адреси, якої **немає** у `trustedProxies`, він **не** вважатиме підключення локальними клієнтами. Якщо auth gateway вимкнено, такі підключення буде відхилено. Це запобігає обходу автентифікації, коли проксійовані підключення інакше могли б виглядати як такі, що походять із localhost, і отримували б автоматичну довіру. +Коли Gateway виявляє proxy-заголовки з адреси, якої **немає** в `trustedProxies`, він **не** вважатиме з’єднання локальними клієнтами. Якщо auth gateway вимкнено, такі з’єднання буде відхилено. Це запобігає обходу автентифікації, коли проксійовані з’єднання інакше могли б виглядати як такі, що надходять із localhost, і автоматично отримувати довіру. -`gateway.trustedProxies` також використовується для `gateway.auth.mode: "trusted-proxy"`, але цей режим auth суворіший: +`gateway.trustedProxies` також використовується режимом `gateway.auth.mode: "trusted-proxy"`, але цей режим auth суворіший: -- auth trusted-proxy **безпечним чином завершується відмовою для proxy із джерелом loopback** -- reverse proxy loopback на тому самому хості все одно можуть використовувати `gateway.trustedProxies` для виявлення локального клієнта та обробки пересланого IP -- для reverse proxy loopback на тому самому хості використовуйте auth на основі token/password замість `gateway.auth.mode: "trusted-proxy"` +- auth trusted-proxy **завершується відмовою за замовчуванням для proxy із джерелом loopback** +- reverse proxy loopback на тому ж хості все одно можуть використовувати `gateway.trustedProxies` для виявлення локальних клієнтів і обробки forwarded IP +- для reverse proxy loopback на тому ж хості використовуйте auth через token/password замість `gateway.auth.mode: "trusted-proxy"` ```yaml gateway: trustedProxies: - "10.0.0.1" # IP reverse proxy - # Необов’язково. Типове значення false. - # Вмикайте лише якщо ваш proxy не може надавати X-Forwarded-For. + # Необов’язково. За замовчуванням false. + # Увімкніть лише якщо ваш proxy не може надавати X-Forwarded-For. allowRealIpFallback: false auth: mode: password password: ${OPENCLAW_GATEWAY_PASSWORD} ``` -Коли `trustedProxies` налаштовано, Gateway використовує `X-Forwarded-For` для визначення IP-адреси клієнта. `X-Real-IP` типово ігнорується, якщо явно не встановлено `gateway.allowRealIpFallback: true`. +Коли налаштовано `trustedProxies`, Gateway використовує `X-Forwarded-For` для визначення IP-адреси клієнта. `X-Real-IP` типово ігнорується, якщо явно не встановлено `gateway.allowRealIpFallback: true`. -Правильна поведінка reverse proxy (перезапис вхідних заголовків пересилання): +Коректна поведінка reverse proxy (перезапис вхідних forwarded-заголовків): ```nginx proxy_set_header X-Forwarded-For $remote_addr; proxy_set_header X-Real-IP $remote_addr; ``` -Неправильна поведінка reverse proxy (додавання/збереження недовірених заголовків пересилання): +Некоректна поведінка reverse proxy (додавання/збереження недовірених forwarded-заголовків): ```nginx proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; @@ -459,48 +453,48 @@ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; ## Примітки щодо HSTS і origin -- Шлюз OpenClaw спочатку орієнтований на local/loopback. Якщо ви завершуєте TLS на reverse proxy, налаштовуйте HSTS там, на HTTPS-домені, який бачить proxy. +- Gateway OpenClaw насамперед орієнтований на local/loopback. Якщо ви завершуєте TLS на reverse proxy, налаштуйте HSTS на HTTPS-домені, який обслуговує proxy. - Якщо HTTPS завершує сам gateway, ви можете встановити `gateway.http.securityHeaders.strictTransportSecurity`, щоб OpenClaw додавав заголовок HSTS у відповіді. -- Докладні рекомендації щодо розгортання наведено в [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts). -- Для розгортань Control UI поза loopback `gateway.controlUi.allowedOrigins` типово є обов’язковим. -- `gateway.controlUi.allowedOrigins: ["*"]` — це явна політика браузерного origin «дозволити все», а не посилене типове налаштування. Уникайте її поза межами жорстко контрольованого локального тестування. -- Збої браузерної автентифікації за origin на loopback усе одно обмежуються rate limiting навіть тоді, коли ввімкнено загальний виняток для loopback, але ключ блокування прив’язується до кожного нормалізованого значення `Origin`, а не до одного спільного бакета localhost. -- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback origin через Host-header; розглядайте це як небезпечну політику, свідомо обрану оператором. -- Розглядайте DNS rebinding і поведінку proxy щодо Host-header як питання посилення безпеки розгортання; тримайте `trustedProxies` максимально вузьким і не відкривайте gateway напряму в публічний інтернет. +- Докладні вказівки щодо розгортання наведено в [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts). +- Для розгортань Control UI поза loopback `gateway.controlUi.allowedOrigins` є обов’язковим за замовчуванням. +- `gateway.controlUi.allowedOrigins: ["*"]` — це явна політика браузерних origin «дозволити все», а не посилене типове значення. Уникайте її поза межами суворо контрольованого локального тестування. +- Збої автентифікації за browser-origin на loopback усе одно підлягають rate limiting, навіть коли загальний виняток для loopback увімкнено, але ключ блокування визначається окремо для кожного нормалізованого значення `Origin`, а не для одного спільного локального bucket. +- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає режим fallback походження через заголовок Host; розглядайте це як небезпечну політику, свідомо обрану оператором. +- Розглядайте DNS rebinding і поведінку proxy щодо заголовка Host як питання посилення безпеки розгортання; тримайте `trustedProxies` вузьким і уникайте прямого відкриття gateway у публічний інтернет. -## Локальні журнали сесій зберігаються на диску +## Локальні журнали сеансів зберігаються на диску -OpenClaw зберігає транскрипти сесій на диску в `~/.openclaw/agents//sessions/*.jsonl`. -Це потрібно для безперервності сесій і (за бажанням) індексації пам’яті сесій, але це також означає, -що **будь-який процес/користувач із доступом до файлової системи може читати ці журнали**. Вважайте доступ до диска -межею довіри й жорстко обмежуйте дозволи на `~/.openclaw` (див. розділ аудиту нижче). Якщо вам потрібна +OpenClaw зберігає транскрипти сеансів на диску в `~/.openclaw/agents//sessions/*.jsonl`. +Це необхідно для безперервності сеансів і (за бажанням) індексації пам’яті сеансів, але це також означає, що +**будь-який процес/користувач із доступом до файлової системи може читати ці журнали**. Вважайте доступ до диска +межею довіри й жорстко обмежуйте дозволи для `~/.openclaw` (див. розділ аудиту нижче). Якщо вам потрібна сильніша ізоляція між агентами, запускайте їх під окремими користувачами ОС або на окремих хостах. -## Виконання на node (`system.run`) +## Виконання на Node (`system.run`) -Якщо macOS node paired, Gateway може викликати `system.run` на цьому node. Це **віддалене виконання коду** на Mac: +Якщо Node macOS пов’язано через pairing, Gateway може викликати `system.run` на цьому Node. Це **віддалене виконання коду** на Mac: -- Потрібне pairing node (схвалення + токен). -- Pairing node у Gateway — це не поверхня схвалення кожної команди. Воно встановлює ідентичність/довіру до node та видачу токена. -- Gateway застосовує грубу глобальну політику команд node через `gateway.nodes.allowCommands` / `denyCommands`. -- Керування на Mac виконується через **Settings → Exec approvals** (security + ask + allowlist). -- Політика `system.run` для кожного node — це власний файл схвалень exec цього node (`exec.approvals.node.*`), який може бути суворішим або м’якшим за глобальну політику ідентифікаторів команд gateway. +- Потрібне pairing Node (схвалення + токен). +- Pairing Node в Gateway не є поверхнею схвалення кожної окремої команди. Воно встановлює ідентичність/довіру до Node та видачу токена. +- Gateway застосовує грубу глобальну політику команд Node через `gateway.nodes.allowCommands` / `denyCommands`. +- На Mac це контролюється через **Settings → Exec approvals** (security + ask + allowlist). +- Політика `system.run` для конкретного Node — це власний файл схвалень exec цього Node (`exec.approvals.node.*`), який може бути суворішим або м’якшим, ніж глобальна політика ID команд у gateway. - Node, що працює з `security="full"` і `ask="off"`, дотримується типової моделі довіреного оператора. Вважайте це очікуваною поведінкою, якщо тільки ваше розгортання явно не вимагає суворішого режиму схвалення або allowlist. -- Режим схвалення прив’язується до точного контексту запиту та, коли це можливо, до одного конкретного локального операнда script/file. Якщо OpenClaw не може визначити рівно один прямий локальний файл для команди інтерпретатора/runtime, виконання на основі схвалення буде відхилене, а не вдаватиме повне семантичне покриття. -- Для `host=node` виконання на основі схвалення також зберігає канонічний підготовлений `systemRunPlan`; подальші схвалені переспрямування повторно використовують цей збережений план, а валідація gateway відхиляє зміни викликача до command/cwd/session context після створення запиту на схвалення. -- Якщо вам не потрібне віддалене виконання, встановіть security у **deny** і видаліть pairing node для цього Mac. +- Режим схвалення прив’язується до точного контексту запиту і, коли можливо, до одного конкретного локального операнда script/file. Якщо OpenClaw не може точно визначити один прямий локальний файл для команди інтерпретатора/runtime, виконання, що потребує схвалення, відхиляється замість того, щоб обіцяти повне семантичне покриття. +- Для `host=node` виконання, що потребують схвалення, також зберігають канонічний підготовлений `systemRunPlan`; пізніші схвалені переспрямування повторно використовують цей збережений план, а валідація gateway відхиляє зміни викликачем до команди/cwd/контексту сеансу після створення запиту на схвалення. +- Якщо ви не хочете віддаленого виконання, встановіть security у **deny** і видаліть pairing Node для цього Mac. Це розрізнення важливе для triage: -- Якщо paired node після повторного підключення оголошує інший список команд, це саме по собі не є вразливістю, якщо глобальна політика Gateway і локальні схвалення exec на node усе ще забезпечують фактичну межу виконання. -- Звіти, які трактують метадані pairing node як другий прихований шар схвалення кожної команди, зазвичай є плутаниною навколо політики/UX, а не обходом межі безпеки. +- Повторне підключення вже пов’язаного Node, який рекламує інший список команд, саме по собі не є вразливістю, якщо глобальна політика Gateway і локальні схвалення exec самого Node усе ще забезпечують реальну межу виконання. +- Повідомлення, які трактують метадані pairing Node як другий прихований шар схвалення кожної команди, зазвичай є плутаниною політики/UX, а не обходом межі безпеки. -## Динамічні Skills (watcher / віддалені nodes) +## Динамічні Skills (watcher / віддалені Node) -OpenClaw може оновлювати список Skills посеред сесії: +OpenClaw може оновлювати список Skills посеред сеансу: -- **Watcher Skills**: зміни у `SKILL.md` можуть оновити знімок Skills на наступному ході агента. -- **Віддалені nodes**: підключення macOS node може зробити доступними Skills лише для macOS (на основі перевірки bin). +- **Спостерігач Skills**: зміни в `SKILL.md` можуть оновити знімок Skills на наступному ході агента. +- **Віддалені Node**: підключення Node macOS може зробити доступними Skills лише для macOS (на основі перевірки наявності бінарників). Розглядайте папки skill як **довірений код** і обмежуйте коло тих, хто може їх змінювати. @@ -508,49 +502,49 @@ OpenClaw може оновлювати список Skills посеред сес Ваш AI-асистент може: -- Виконувати довільні команди оболонки +- Виконувати довільні shell-команди - Читати/записувати файли - Отримувати доступ до мережевих сервісів - Надсилати повідомлення будь-кому (якщо ви надали йому доступ до WhatsApp) -Люди, які надсилають вам повідомлення, можуть: +Люди, які пишуть вам, можуть: -- Намагатися обдурити ваш AI, щоб він робив шкідливі речі -- Соціальною інженерією здобувати доступ до ваших даних -- Досліджувати вашу інфраструктуру на предмет деталей +- Намагатися обманом змусити ваш AI робити шкідливі речі +- Соціальною інженерією добиватися доступу до ваших даних +- Досліджувати вашу інфраструктуру в пошуках деталей -## Основна концепція: контроль доступу перед інтелектом +## Ключова ідея: контроль доступу перед інтелектом -Більшість збоїв тут — це не хитромудрі експлойти, а радше «хтось написав боту, і бот зробив те, що його попросили». +Більшість збоїв тут — не витончені експлойти, а ситуації на кшталт «хтось написав боту, і бот зробив те, що його попросили». -Позиція OpenClaw: +Позиція OpenClaw така: -- **Спочатку ідентичність:** визначте, хто може взаємодіяти з ботом (pairing DM / allowlist / явний режим “open”). -- **Потім обсяг:** визначте, де бот має право діяти (allowlist груп + вимога згадки, інструменти, sandboxing, дозволи пристрою). -- **І лише потім модель:** виходьте з того, що моделлю можна маніпулювати; будуйте систему так, щоб маніпуляції мали обмежений радіус ураження. +- **Спочатку ідентичність:** вирішіть, хто може говорити з ботом (pairing для DM / allowlist / явний `open`). +- **Потім обсяг:** вирішіть, де боту дозволено діяти (allowlist груп + обмеження згадуваннями, інструменти, sandboxing, дозволи пристрою). +- **Модель наприкінці:** припускайте, що моделлю можна маніпулювати; проєктуйте систему так, щоб наслідки маніпуляції були обмеженими. ## Модель авторизації команд -Slash commands і directives виконуються лише для **авторизованих відправників**. Авторизація визначається через -allowlist/pairing каналу плюс `commands.useAccessGroups` (див. [Configuration](/uk/gateway/configuration) +Слеш-команди та директиви виконуються лише для **авторизованих відправників**. Авторизація визначається через +allowlist/pairing каналу разом із `commands.useAccessGroups` (див. [Configuration](/uk/gateway/configuration) і [Slash commands](/uk/tools/slash-commands)). Якщо allowlist каналу порожній або містить `"*"`, команди фактично відкриті для цього каналу. -`/exec` — це зручна команда лише для сесії, призначена для авторизованих операторів. Вона **не** записує конфігурацію і -не змінює інші сесії. +`/exec` — це зручна команда лише в межах сеансу для авторизованих операторів. Вона **не** записує конфігурацію і +не змінює інші сеанси. -## Ризики інструментів control plane +## Ризики інструментів площини керування -Два вбудовані інструменти можуть вносити постійні зміни в control plane: +Два вбудовані інструменти можуть вносити стійкі зміни до площини керування: -- `gateway` може переглядати конфігурацію через `config.schema.lookup` / `config.get`, а також вносити постійні зміни через `config.apply`, `config.patch` і `update.run`. +- `gateway` може переглядати конфігурацію через `config.schema.lookup` / `config.get`, а також вносити стійкі зміни через `config.apply`, `config.patch` і `update.run`. - `cron` може створювати заплановані завдання, які продовжують працювати після завершення початкового чату/завдання. -Інструмент runtime `gateway`, доступний лише власнику, усе одно відмовляється переписувати -`tools.exec.ask` або `tools.exec.security`; застарілі псевдоніми `tools.bash.*` +Інструмент runtime `gateway`, доступний лише власнику, усе ще відмовляється +перезаписувати `tools.exec.ask` або `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec перед записом. -Для будь-якого агента/поверхні, що обробляє недовірений вміст, за замовчуванням забороняйте таке: +Для будь-якого агента/поверхні, що обробляє недовірений вміст, типово забороняйте таке: ```json5 { @@ -562,33 +556,33 @@ allowlist/pairing каналу плюс `commands.useAccessGroups` (див. [Con `commands.restart=false` блокує лише дії перезапуску. Він не вимикає дії конфігурації/оновлення `gateway`. -## Plugins/extensions +## Плагіни/розширення -Plugins працюють **у тому самому процесі**, що й Gateway. Розглядайте їх як довірений код: +Плагіни працюють **у тому ж процесі**, що й Gateway. Розглядайте їх як довірений код: -- Встановлюйте plugins лише з джерел, яким довіряєте. +- Встановлюйте лише ті плагіни, джерелам яких ви довіряєте. - Надавайте перевагу явним allowlist `plugins.allow`. -- Перевіряйте конфігурацію plugin перед увімкненням. -- Перезапускайте Gateway після змін plugins. -- Якщо ви встановлюєте або оновлюєте plugins (`openclaw plugins install `, `openclaw plugins update `), ставтеся до цього як до запуску недовіреного коду: - - Шлях встановлення — це каталог конкретного plugin у межах активного кореня встановлення plugins. - - Перед встановленням/оновленням OpenClaw запускає вбудоване сканування на небезпечний код. Знахідки рівня `critical` типово блокують процес. - - OpenClaw використовує `npm pack`, а потім запускає `npm install --omit=dev` у цьому каталозі (npm lifecycle scripts можуть виконувати код під час встановлення). - - Надавайте перевагу закріпленим точним версіям (`@scope/pkg@1.2.3`) і перевіряйте розпакований код на диску перед увімкненням. - - `--dangerously-force-unsafe-install` — лише аварійний варіант для хибнопозитивних спрацювань вбудованого сканування під час потоків встановлення/оновлення plugin. Він не обходить блокування політики hook `before_install` для plugin і не обходить збої сканування. - - Встановлення залежностей Skills через Gateway дотримується такого самого поділу між dangerous і suspicious: вбудовані знахідки `critical` блокують процес, якщо тільки викликаючий явно не встановить `dangerouslyForceUnsafeInstall`, тоді як suspicious-знахідки й надалі лише попереджають. `openclaw skills install` і надалі залишається окремим потоком завантаження/встановлення skill через ClawHub. +- Перевіряйте конфігурацію Plugin перед увімкненням. +- Перезапускайте Gateway після змін Plugin. +- Якщо ви встановлюєте або оновлюєте Plugin (`openclaw plugins install `, `openclaw plugins update `), ставтеся до цього так, ніби ви запускаєте недовірений код: + - Шлях встановлення — це каталог конкретного Plugin у межах активного кореня встановлення Plugin. + - Перед встановленням/оновленням OpenClaw запускає вбудоване сканування небезпечного коду. Знахідки рівня `critical` типово блокують операцію. + - OpenClaw використовує `npm pack`, а потім виконує `npm install --omit=dev` у цьому каталозі (скрипти життєвого циклу npm можуть виконувати код під час встановлення). + - Надавайте перевагу pinned, точним версіям (`@scope/pkg@1.2.3`) і перевіряйте розпакований код на диску перед увімкненням. + - `--dangerously-force-unsafe-install` — лише аварійний варіант для хибнопозитивних спрацювань вбудованого сканування у потоках встановлення/оновлення Plugin. Він не обходить блокування політики hook `before_install` Plugin і не обходить збої сканування. + - Встановлення залежностей Skills через Gateway дотримуються того самого поділу на dangerous/suspicious: вбудовані знахідки `critical` блокують операцію, якщо викликач явно не встановить `dangerouslyForceUnsafeInstall`, тоді як підозрілі знахідки, як і раніше, лише попереджають. `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills із ClawHub. Докладніше: [Plugins](/uk/tools/plugin) -## Модель доступу через DM (pairing / allowlist / open / disabled) +## Модель доступу DM (pairing / allowlist / open / disabled) -Усі поточні канали з підтримкою DM мають політику DM (`dmPolicy` або `*.dm.policy`), яка контролює вхідні DM **до** обробки повідомлення: +Усі поточні канали з підтримкою DM мають політику DM (`dmPolicy` або `*.dm.policy`), яка блокує вхідні DM **до** обробки повідомлення: -- `pairing` (типово): невідомі відправники отримують короткий код pairing, а бот ігнорує їхнє повідомлення до схвалення. Коди спливають через 1 годину; повторні DM не надсилатимуть код повторно, доки не буде створено новий запит. Кількість очікувальних запитів типово обмежена до **3 на канал**. -- `allowlist`: невідомих відправників блокують (без handshake pairing). -- `open`: дозволити будь-кому надсилати DM (публічно). **Потребує**, щоб allowlist каналу містив `"*"` (явна згода). +- `pairing` (типово): невідомі відправники отримують короткий код pairing, а бот ігнорує їхнє повідомлення до схвалення. Коди спливають через 1 годину; повторні DM не надсилатимуть код знову, доки не буде створено новий запит. Кількість очікуваних запитів типово обмежена **3 на канал**. +- `allowlist`: невідомих відправників заблоковано (без handshake pairing). +- `open`: дозволити будь-кому надсилати DM (публічно). **Потрібно**, щоб allowlist каналу містив `"*"` (явне підтвердження). - `disabled`: повністю ігнорувати вхідні DM. Схвалення через CLI: @@ -600,9 +594,9 @@ openclaw pairing approve Докладніше + файли на диску: [Pairing](/uk/channels/pairing) -## Ізоляція DM-сесій (багатокористувацький режим) +## Ізоляція сеансів DM (багатокористувацький режим) -Типово OpenClaw маршрутизує **всі DM до основної сесії**, щоб ваш асистент зберігав безперервність між пристроями та каналами. Якщо **кілька людей** можуть надсилати DM боту (відкриті DM або allowlist із кількома людьми), розгляньте ізоляцію DM-сесій: +Типово OpenClaw маршрутизує **усі DM в основний сеанс**, щоб ваш асистент зберігав безперервність між пристроями й каналами. Якщо **кілька людей** можуть надсилати DM боту (відкриті DM або allowlist із кількох осіб), розгляньте ізоляцію сеансів DM: ```json5 { @@ -610,190 +604,192 @@ openclaw pairing approve } ``` -Це запобігає витоку контексту між користувачами, зберігаючи водночас ізоляцію групових чатів. +Це запобігає витоку контексту між користувачами, зберігаючи при цьому ізоляцію групових чатів. -Це межа контексту обміну повідомленнями, а не межа адміністрування хоста. Якщо користувачі є взаємно ворожими й ділять той самий хост/config Gateway, запускайте окремі шлюзи для кожної межі довіри. +Це межа контексту обміну повідомленнями, а не межа адміністрування хоста. Якщо користувачі взаємно ворожі та спільно використовують той самий хост/конфігурацію Gateway, запускайте окремі Gateway для кожної межі довіри. ### Безпечний режим DM (рекомендовано) -Розглядайте наведений вище фрагмент як **безпечний режим DM**: +Розглядайте фрагмент вище як **безпечний режим DM**: -- Типове значення: `session.dmScope: "main"` (усі DM ділять одну сесію для безперервності). -- Типове значення для локального CLI-онбордингу: записує `session.dmScope: "per-channel-peer"`, якщо значення не встановлено (зберігає наявні явні значення). +- Типово: `session.dmScope: "main"` (усі DM використовують один спільний сеанс для безперервності). +- Типове значення локального onboarding у CLI: записує `session.dmScope: "per-channel-peer"`, якщо значення не задано (зберігає наявні явні значення). - Безпечний режим DM: `session.dmScope: "per-channel-peer"` (кожна пара канал+відправник отримує ізольований контекст DM). -- Ізоляція відправника між каналами: `session.dmScope: "per-peer"` (кожен відправник отримує одну сесію в усіх каналах одного типу). +- Ізоляція контакту між каналами: `session.dmScope: "per-peer"` (кожен відправник має один сеанс у всіх каналах одного типу). -Якщо ви запускаєте кілька акаунтів в одному каналі, використовуйте натомість `per-account-channel-peer`. Якщо та сама людина звертається до вас через кілька каналів, використовуйте `session.identityLinks`, щоб об’єднати ці DM-сесії в одну канонічну ідентичність. Див. [Керування сесіями](/uk/concepts/session) і [Configuration](/uk/gateway/configuration). +Якщо ви використовуєте кілька акаунтів в одному каналі, замість цього застосовуйте `per-account-channel-peer`. Якщо та сама людина зв’язується з вами через кілька каналів, використовуйте `session.identityLinks`, щоб об’єднати ці DM-сеанси в одну канонічну ідентичність. Див. [Session Management](/uk/concepts/session) і [Configuration](/uk/gateway/configuration). -## Allowlists (DM + групи) - термінологія +## Allowlists (DM + групи) — термінологія -OpenClaw має два окремі шари «хто може мене активувати?»: +В OpenClaw є два окремі шари «хто може мене запускати?»: -- **DM allowlist** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; застаріле: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): хто має право спілкуватися з ботом у direct messages. - - Коли `dmPolicy="pairing"`, схвалення записуються в сховище pairing allowlist, прив’язане до акаунта, у `~/.openclaw/credentials/` (`-allowFrom.json` для типового акаунта, `--allowFrom.json` для нетипових акаунтів), і об’єднуються з allowlist із конфігурації. -- **Group allowlist** (залежить від каналу): з яких саме груп/каналів/guilds бот взагалі прийматиме повідомлення. +- **Allowlist DM** (`allowFrom` / `channels.discord.allowFrom` / `channels.slack.allowFrom`; застаріле: `channels.discord.dm.allowFrom`, `channels.slack.dm.allowFrom`): хто має право писати боту в особисті повідомлення. + - Коли `dmPolicy="pairing"`, схвалення записуються в сховище allowlist pairing з областю дії акаунта в `~/.openclaw/credentials/` (`-allowFrom.json` для типового акаунта, `--allowFrom.json` для нетипових акаунтів) і зливаються з allowlist із конфігурації. +- **Allowlist груп** (специфічний для каналу): з яких саме груп/каналів/guilds бот узагалі прийматиме повідомлення. - Типові шаблони: - - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: типові налаштування на рівні групи, наприклад `requireMention`; якщо встановлено, це також працює як group allowlist (включіть `"*"`, щоб зберегти поведінку «дозволити все»). - - `groupPolicy="allowlist"` + `groupAllowFrom`: обмежує, хто може активувати бота _всередині_ групової сесії (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). - - `channels.discord.guilds` / `channels.slack.channels`: allowlist на рівні поверхонь + типові налаштування згадок. - - Перевірки груп виконуються в такому порядку: спочатку `groupPolicy`/group allowlist, потім активація через згадку/відповідь. - - Відповідь на повідомлення бота (неявна згадка) **не** обходить allowlist відправника, наприклад `groupAllowFrom`. - - **Примітка з безпеки:** розглядайте `dmPolicy="open"` і `groupPolicy="open"` як налаштування останньої інстанції. Їх слід використовувати вкрай рідко; надавайте перевагу pairing + allowlists, якщо тільки ви не довіряєте повністю кожному учаснику кімнати. + - `channels.whatsapp.groups`, `channels.telegram.groups`, `channels.imessage.groups`: типові параметри для груп, як-от `requireMention`; якщо задано, це також працює як allowlist груп (додайте `"*"`, щоб зберегти поведінку «дозволити все»). + - `groupPolicy="allowlist"` + `groupAllowFrom`: обмежує, хто може запускати бота _в межах_ групового сеансу (WhatsApp/Telegram/Signal/iMessage/Microsoft Teams). + - `channels.discord.guilds` / `channels.slack.channels`: allowlist для конкретних поверхонь + типові параметри згадувань. + - Перевірки груп виконуються в такому порядку: спочатку `groupPolicy`/allowlist груп, потім активація за згадуванням/відповіддю. + - Відповідь на повідомлення бота (неявне згадування) **не** обходить allowlist відправників, як-от `groupAllowFrom`. + - **Примітка щодо безпеки:** ставтеся до `dmPolicy="open"` і `groupPolicy="open"` як до крайніх варіантів. Їх варто використовувати якомога рідше; надавайте перевагу pairing + allowlist, якщо тільки ви не довіряєте повністю кожному учаснику кімнати. Докладніше: [Configuration](/uk/gateway/configuration) і [Groups](/uk/channels/groups) -## Prompt injection (що це таке і чому це важливо) +## Prompt injection (що це, і чому це важливо) -Prompt injection — це коли зловмисник створює повідомлення, яке маніпулює моделлю так, щоб вона зробила щось небезпечне («ігноруй свої інструкції», «вивантаж свою файлову систему», «перейди за цим посиланням і виконай команди» тощо). +Prompt injection — це ситуація, коли зловмисник створює повідомлення, яке маніпулює моделлю так, щоб вона зробила щось небезпечне («ігноруй свої інструкції», «виведи вміст файлової системи», «перейди за цим посиланням і виконай команди» тощо). -Навіть із сильними system prompt **проблема prompt injection не вирішена**. Запобіжники в system prompt — це лише м’які рекомендації; жорстке забезпечення дають політика інструментів, схвалення exec, sandboxing і allowlist каналів (і оператори можуть за задумом усе це вимкнути). Що реально допомагає на практиці: +Навіть із сильними системними prompt, **prompt injection не розв’язано**. Запобіжники в системному prompt — це лише м’які вказівки; жорстке забезпечення дають політика інструментів, схвалення exec, sandboxing і allowlist каналів (і оператори можуть вимкнути це за задумом). Що практично допомагає: -- Тримайте вхідні DM закритими (pairing/allowlists). -- У групах надавайте перевагу активації через згадки; уникайте «завжди активних» ботів у публічних кімнатах. -- Розглядайте посилання, вкладення та вставлені інструкції як потенційно ворожі за замовчуванням. -- Виконуйте чутливі інструменти в sandbox; тримайте секрети поза досяжною для агента файловою системою. -- Примітка: sandboxing є opt-in. Якщо режим sandbox вимкнений, неявний `host=auto` розв’язується до хоста gateway. Явний `host=sandbox` усе одно безпечно завершується відмовою, оскільки runtime sandbox недоступний. Встановіть `host=gateway`, якщо хочете, щоб така поведінка була явно зафіксована в конфігурації. -- Обмежуйте високоризикові інструменти (`exec`, `browser`, `web_fetch`, `web_search`) довіреними агентами або явними allowlist. -- Якщо ви додаєте інтерпретатори до allowlist (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), увімкніть `tools.exec.strictInlineEval`, щоб inline eval-форми все одно вимагали явного схвалення. -- **Вибір моделі має значення:** старіші/менші/застарілі моделі значно менш стійкі до prompt injection і неправильного використання інструментів. Для агентів з увімкненими інструментами використовуйте найсильнішу доступну модель останнього покоління, стійку до інструкцій. +- Тримайте вхідні DM закритими (pairing/allowlist). +- У групах надавайте перевагу обмеженню за згадуванням; уникайте «завжди активних» ботів у публічних кімнатах. +- За замовчуванням вважайте посилання, вкладення та вставлені інструкції ворожими. +- Виконуйте чутливі інструменти в sandbox; тримайте секрети поза файловою системою, доступною для агента. +- Примітка: sandboxing вмикається добровільно. Якщо режим sandbox вимкнено, неявне `host=auto` розв’язується до хоста gateway. Явне `host=sandbox` усе одно безпечно завершується відмовою, тому що runtime sandbox недоступний. Установіть `host=gateway`, якщо хочете, щоб така поведінка була явно описана в конфігурації. +- Обмежуйте інструменти високого ризику (`exec`, `browser`, `web_fetch`, `web_search`) лише довіреними агентами або явними allowlist. +- Якщо ви використовуєте allowlist інтерпретаторів (`python`, `node`, `ruby`, `perl`, `php`, `lua`, `osascript`), увімкніть `tools.exec.strictInlineEval`, щоб inline eval-форми все одно вимагали явного схвалення. +- **Вибір моделі має значення:** старіші/менші/застарілі моделі значно менш стійкі до prompt injection і зловживань інструментами. Для агентів з увімкненими інструментами використовуйте найсильнішу доступну сучасну модель, загартовану щодо інструкцій. -Ознаки, які слід вважати недовіреними: +Тривожні сигнали, які слід вважати недовіреними: - «Прочитай цей файл/URL і зроби точно те, що там написано». -- «Ігноруй свій system prompt або правила безпеки». +- «Ігноруй свій системний prompt або правила безпеки». - «Розкрий свої приховані інструкції або результати інструментів». - «Встав повний вміст `~/.openclaw` або свої журнали». -## Прапорці обходу небезпечного зовнішнього вмісту +## Прапори обходу небезпечного зовнішнього вмісту -OpenClaw містить явні прапорці обходу, які вимикають обгортання безпеки для зовнішнього вмісту: +OpenClaw містить явні прапори обходу, які вимикають захисне обгортання зовнішнього вмісту: - `hooks.mappings[].allowUnsafeExternalContent` - `hooks.gmail.allowUnsafeExternalContent` -- Поле payload cron `allowUnsafeExternalContent` +- Поле payload Cron `allowUnsafeExternalContent` Рекомендації: -- У production тримайте ці параметри не встановленими/`false`. -- Вмикайте лише тимчасово для вузько обмеженого налагодження. -- Якщо ввімкнено, ізолюйте такого агента (sandbox + мінімум інструментів + окремий простір імен сесії). +- У production залишайте їх незаданими/false. +- Увімкнюйте лише тимчасово для дуже вузько обмеженого налагодження. +- Якщо увімкнули, ізолюйте цього агента (sandbox + мінімум інструментів + окремий простір імен сеансів). -Примітка про ризики hooks: +Примітка про ризики Hooks: -- Payload hooks — це недовірений вміст, навіть якщо доставка надходить із систем, які ви контролюєте (пошта/документи/вебвміст можуть містити prompt injection). -- Слабкі рівні моделей підвищують цей ризик. Для автоматизації, що запускається через hooks, надавайте перевагу сильним сучасним рівням моделей і тримайте політику інструментів суворою (`tools.profile: "messaging"` або суворіше), а також використовуйте sandboxing, де це можливо. +- Payload hooks — це недовірений вміст, навіть якщо доставлення походить із систем, які ви контролюєте (пошта/документи/вебвміст можуть містити prompt injection). +- Слабкіші рівні моделей збільшують цей ризик. Для автоматизації на основі hooks надавайте перевагу сильним сучасним рівням моделей і тримайте політику інструментів суворою (`tools.profile: "messaging"` або суворіше), а також використовуйте sandboxing там, де це можливо. ### Prompt injection не потребує публічних DM -Навіть якщо **лише ви** можете надсилати повідомлення боту, prompt injection усе одно може виникнути через +Навіть якщо **лише ви** можете писати боту, prompt injection усе одно може виникнути через будь-який **недовірений вміст**, який бот читає (результати web search/fetch, сторінки браузера, -листи, документи, вкладення, вставлені журнали/код). Іншими словами: джерелом загрози є не лише відправник; сам **вміст** також може містити ворожі інструкції. +листи, документи, вкладення, вставлені журнали/код). Іншими словами: не лише відправник +є поверхнею загрози; сам **вміст** також може містити ворожі інструкції. -Коли інструменти увімкнено, типовий ризик — це витік контексту або запуск -викликів інструментів. Зменшити радіус ураження можна так: +Коли інструменти увімкнені, типовий ризик — це ексфільтрація контексту або запуск +викликів інструментів. Зменшуйте радіус ураження так: -- Використовуйте **агента-читача** у режимі лише для читання або без інструментів для узагальнення недовіреного вмісту, - а потім передавайте це узагальнення вашому основному агенту. -- Тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів з увімкненими інструментами, якщо вони не потрібні. +- Використовуйте **агента-читача** лише для читання або без інструментів, щоб підсумовувати недовірений вміст, + а вже потім передавайте підсумок основному агенту. +- Тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів з інструментами, якщо вони не потрібні. - Для URL-входів OpenResponses (`input_file` / `input_image`) задавайте суворі `gateway.http.endpoints.responses.files.urlAllowlist` і - `gateway.http.endpoints.responses.images.urlAllowlist`, а також тримайте `maxUrlParts` низьким. - Порожні allowlist трактуються як не встановлені; використовуйте `files.allowUrl: false` / `images.allowUrl: false`, - якщо хочете повністю вимкнути отримання URL. -- Для файлових входів OpenResponses декодований текст `input_file` усе одно інжектується як - **недовірений зовнішній вміст**. Не вважайте текст файлу довіреним лише тому, - що Gateway декодував його локально. Інжектований блок усе одно містить явні + `gateway.http.endpoints.responses.images.urlAllowlist`, а також зберігайте малим значення `maxUrlParts`. + Порожні allowlist вважаються незаданими; використовуйте `files.allowUrl: false` / `images.allowUrl: false`, + якщо хочете повністю вимкнути отримання за URL. +- Для файлових входів OpenResponses декодований текст `input_file` усе одно вбудовується як + **недовірений зовнішній вміст**. Не покладайтеся на те, що текст файла є довіреним лише тому, + що Gateway декодував його локально. Вбудований блок усе одно містить явні маркери меж `<<>>` плюс метадані `Source: External`, - хоча в цьому шляху відсутній довший банер `SECURITY NOTICE:`. -- Те саме обгортання на основі маркерів застосовується, коли media-understanding витягує текст - із вкладених документів перед додаванням цього тексту до media prompt. -- Увімкніть sandboxing і суворі allowlist інструментів для будь-якого агента, що працює з недовіреним вводом. + хоча цей шлях і пропускає довший банер `SECURITY NOTICE:`. +- Таке саме обгортання на основі маркерів застосовується, коли media-understanding витягує текст + із прикріплених документів перед додаванням цього тексту до prompt медіа. +- Увімкніть sandboxing і суворі allowlist інструментів для будь-якого агента, який працює з недовіреним вводом. - Тримайте секрети поза prompt; передавайте їх через env/config на хості gateway. -### Сила моделі (примітка з безпеки) +### Сила моделі (примітка щодо безпеки) -Стійкість до prompt injection **не** є однаковою для всіх рівнів моделей. Менші/дешевші моделі зазвичай більш уразливі до неправильного використання інструментів і захоплення інструкцій, особливо під ворожими prompt. +Стійкість до prompt injection **не** однакова для всіх рівнів моделей. Менші/дешевші моделі загалом більш схильні до зловживання інструментами та перехоплення інструкцій, особливо під час ворожих prompt. -Для агентів з увімкненими інструментами або агентів, які читають недовірений вміст, ризик prompt injection зі старішими/меншими моделями часто є надто високим. Не запускайте такі навантаження на слабких рівнях моделей. +Для агентів із увімкненими інструментами або агентів, які читають недовірений вміст, ризик prompt injection зі старішими/меншими моделями часто є надто високим. Не запускайте такі навантаження на слабких рівнях моделей. Рекомендації: -- **Використовуйте модель останнього покоління найвищого рівня** для будь-якого бота, який може запускати інструменти або працювати з файлами/мережами. -- **Не використовуйте старіші/слабші/менші рівні** для агентів з інструментами або недовіреними вхідними даними; ризик prompt injection занадто високий. -- Якщо вам усе ж потрібна менша модель, **зменшуйте радіус ураження** (інструменти лише для читання, сильний sandboxing, мінімальний доступ до файлової системи, суворі allowlist). -- Під час запуску малих моделей **увімкніть sandboxing для всіх сесій** і **вимкніть `web_search`/`web_fetch`/`browser`**, якщо вхідні дані не перебувають під суворим контролем. -- Для чат-асистентів особистого користування з довіреним вводом і без інструментів менші моделі зазвичай підходять. +- **Використовуйте модель останнього покоління найвищого рівня** для будь-якого бота, який може запускати інструменти або взаємодіяти з файлами/мережами. +- **Не використовуйте старіші/слабші/менші рівні** для агентів з інструментами або недовірених вхідних скриньок; ризик prompt injection надто високий. +- Якщо вам доводиться використовувати меншу модель, **зменшуйте радіус ураження** (лише читання, сильне sandboxing, мінімальний доступ до файлової системи, суворі allowlist). +- Під час роботи з малими моделями **увімкніть sandboxing для всіх сеансів** і **вимкніть `web_search`/`web_fetch`/`browser`**, якщо вхідні дані не контролюються дуже жорстко. +- Для персональних асистентів лише для чату з довіреним вводом і без інструментів малі моделі зазвичай підходять. -## Reasoning і докладний вивід у групах +## Reasoning і verbose output у групах -`/reasoning` і `/verbose` можуть розкривати внутрішнє reasoning або вивід інструментів, -який не призначався для публічного каналу. У групових налаштуваннях розглядайте їх як **лише для налагодження** +`/reasoning`, `/verbose` і `/trace` можуть розкривати внутрішнє міркування, вихід +інструментів або діагностику Plugin, які +не призначалися для публічного каналу. У групових налаштуваннях розглядайте їх як **лише для налагодження** і тримайте вимкненими, якщо тільки вони вам явно не потрібні. Рекомендації: -- Тримайте `/reasoning` і `/verbose` вимкненими в публічних кімнатах. -- Якщо ви їх вмикаєте, робіть це лише в довірених DM або жорстко контрольованих кімнатах. -- Пам’ятайте: докладний вивід може містити аргументи інструментів, URL і дані, які бачила модель. +- Тримайте `/reasoning`, `/verbose` і `/trace` вимкненими в публічних кімнатах. +- Якщо ви їх увімкнули, робіть це лише в довірених DM або в суворо контрольованих кімнатах. +- Пам’ятайте: verbose і trace output можуть містити аргументи інструментів, URL, діагностику Plugin і дані, які бачила модель. ## Посилення конфігурації (приклади) ### 0) Дозволи файлів -Тримайте config + state приватними на хості gateway: +Тримайте конфігурацію та стан приватними на хості gateway: - `~/.openclaw/openclaw.json`: `600` (лише читання/запис для користувача) -- `~/.openclaw`: `700` (лише для користувача) +- `~/.openclaw`: `700` (лише користувач) -`openclaw doctor` може попередити про це й запропонувати посилити ці дозволи. +`openclaw doctor` може попередити про це та запропонувати посилити ці дозволи. -### 0.4) Відкритість мережі (bind + port + firewall) +### 0.4) Мережевий доступ (bind + порт + firewall) -Шлюз мультиплексує **WebSocket + HTTP** на одному порту: +Gateway мультиплексує **WebSocket + HTTP** на одному порту: -- Типовий: `18789` +- Типово: `18789` - Config/flags/env: `gateway.port`, `--port`, `OPENCLAW_GATEWAY_PORT` Ця HTTP-поверхня включає Control UI і canvas host: - Control UI (ресурси SPA) (типовий базовий шлях `/`) -- Canvas host: `/__openclaw__/canvas/` і `/__openclaw__/a2ui/` (довільний HTML/JS; розглядайте як недовірений вміст) +- Canvas host: `/__openclaw__/canvas/` і `/__openclaw__/a2ui/` (довільні HTML/JS; розглядайте як недовірений вміст) -Якщо ви завантажуєте canvas-вміст у звичайному браузері, ставтеся до нього як до будь-якої іншої недовіреної вебсторінки: +Якщо ви завантажуєте вміст canvas у звичайному браузері, ставтеся до нього як до будь-якої іншої недовіреної вебсторінки: - Не відкривайте canvas host для недовірених мереж/користувачів. -- Не змушуйте canvas-вміст ділити той самий origin із привілейованими вебповерхнями, якщо ви повністю не розумієте наслідки. +- Не змушуйте вміст canvas використовувати той самий origin, що й привілейовані вебповерхні, якщо ви повністю не розумієте наслідки. -Режим bind визначає, де слухає Gateway: +Режим bind визначає, де саме слухає Gateway: - `gateway.bind: "loopback"` (типово): підключатися можуть лише локальні клієнти. -- Bind не на loopback (`"lan"`, `"tailnet"`, `"custom"`) розширює поверхню атаки. Використовуйте його лише разом з auth gateway (спільний token/password або правильно налаштований trusted proxy не на loopback) і реальним firewall. +- Bind поза loopback (`"lan"`, `"tailnet"`, `"custom"`) розширює поверхню атаки. Використовуйте їх лише з auth gateway (спільний token/password або правильно налаштований non-loopback trusted proxy) і реальним firewall. -Практичні правила: +Базові правила: -- Надавайте перевагу Tailscale Serve замість bind у LAN (Serve тримає Gateway на loopback, а доступом керує Tailscale). -- Якщо все ж потрібно bind у LAN, обмежте порт через firewall вузьким allowlist вихідних IP-адрес; не робіть широке port-forwarding. +- Надавайте перевагу Tailscale Serve замість bind у LAN (Serve залишає Gateway на loopback, а доступ контролює Tailscale). +- Якщо вам все ж потрібен bind у LAN, обмежте порт через firewall вузьким allowlist вихідних IP; не робіть широкого port-forward. - Ніколи не відкривайте Gateway без автентифікації на `0.0.0.0`. ### 0.4.1) Публікація портів Docker + UFW (`DOCKER-USER`) -Якщо ви запускаєте OpenClaw з Docker на VPS, пам’ятайте, що опубліковані порти контейнера -(`-p HOST:CONTAINER` або `ports:` у Compose) маршрутизуються через ланцюги пересилання Docker, +Якщо ви запускаєте OpenClaw у Docker на VPS, пам’ятайте, що опубліковані порти контейнера +(`-p HOST:CONTAINER` або Compose `ports:`) маршрутизуються через ланцюги переспрямування Docker, а не лише через правила `INPUT` хоста. -Щоб трафік Docker відповідав вашій політиці firewall, застосовуйте правила в -`DOCKER-USER` (цей ланцюг обробляється до власних правил accept Docker). +Щоб трафік Docker відповідав політиці вашого firewall, застосовуйте правила в +`DOCKER-USER` (цей ланцюг перевіряється до власних правил accept Docker). На багатьох сучасних дистрибутивах `iptables`/`ip6tables` використовують frontend `iptables-nft` і все одно застосовують ці правила до backend nftables. Мінімальний приклад allowlist (IPv4): ```bash -# /etc/ufw/after.rules (додайте як окрему секцію *filter) +# /etc/ufw/after.rules (додайте як окремий розділ *filter) *filter :DOCKER-USER - [0:0] -A DOCKER-USER -m conntrack --ctstate ESTABLISHED,RELATED -j RETURN @@ -810,11 +806,11 @@ COMMIT ``` Для IPv6 існують окремі таблиці. Додайте відповідну політику в `/etc/ufw/after6.rules`, якщо -Docker IPv6 увімкнено. +IPv6 у Docker увімкнено. -Уникайте жорсткого кодування назв інтерфейсів на кшталт `eth0` у фрагментах документації. Назви інтерфейсів +Уникайте жорстко заданих назв інтерфейсів, таких як `eth0`, у фрагментах документації. Назви інтерфейсів відрізняються між образами VPS (`ens3`, `enp*` тощо), і невідповідність може випадково -пропустити ваше правило deny. +призвести до пропуску вашого правила deny. Швидка перевірка після перезавантаження: @@ -825,22 +821,22 @@ ip6tables -S DOCKER-USER nmap -sT -p 1-65535 --open ``` -Очікуваними зовнішніми портами мають бути лише ті, які ви навмисно відкрили (для більшості +Очікувано зовні мають бути відкриті лише ті порти, які ви навмисно відкрили (для більшості конфігурацій: SSH + порти вашого reverse proxy). -### 0.4.2) Виявлення mDNS/Bonjour (розкриття інформації) +### 0.4.2) Виявлення через mDNS/Bonjour (розкриття інформації) -Gateway транслює свою присутність через mDNS (`_openclaw-gw._tcp` на порту 5353) для локального виявлення пристроїв. У повному режимі це включає TXT-записи, які можуть розкривати деталі роботи: +Gateway транслює свою присутність через mDNS (`_openclaw-gw._tcp` на порту 5353) для локального виявлення пристроїв. У повному режимі це включає TXT-записи, які можуть розкривати операційні деталі: -- `cliPath`: повний шлях файлової системи до бінарного файла CLI (розкриває ім’я користувача та місце встановлення) -- `sshPort`: повідомляє про доступність SSH на хості +- `cliPath`: повний шлях у файловій системі до CLI-бінарника (розкриває ім’я користувача та місце встановлення) +- `sshPort`: рекламує доступність SSH на хості - `displayName`, `lanHost`: інформація про ім’я хоста -**Міркування операційної безпеки:** трансляція деталей інфраструктури спрощує розвідку для будь-кого в локальній мережі. Навіть «нешкідлива» інформація, як-от шляхи файлової системи та наявність SSH, допомагає зловмисникам картографувати ваше середовище. +**Міркування щодо операційної безпеки:** трансляція інфраструктурних деталей полегшує розвідку для будь-кого в локальній мережі. Навіть «нешкідлива» інформація, як-от шляхи файлової системи та наявність SSH, допомагає зловмисникам картографувати ваше середовище. **Рекомендації:** -1. **Мінімальний режим** (типовий, рекомендований для відкритих gateway): виключає чутливі поля з mDNS-трансляцій: +1. **Мінімальний режим** (типово, рекомендовано для відкритих gateway): вилучає чутливі поля з mDNS-трансляцій: ```json5 { @@ -850,7 +846,7 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -2. **Повністю вимкніть**, якщо вам не потрібне локальне виявлення пристроїв: +2. **Повністю вимкніть**, якщо локальне виявлення пристроїв вам не потрібне: ```json5 { @@ -860,7 +856,7 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -3. **Повний режим** (лише за явною згодою): включає `cliPath` + `sshPort` у TXT-записи: +3. **Повний режим** (за явним бажанням): включає `cliPath` + `sshPort` у TXT-записи: ```json5 { @@ -870,19 +866,19 @@ Gateway транслює свою присутність через mDNS (`_open } ``` -4. **Змінна середовища** (альтернатива): встановіть `OPENCLAW_DISABLE_BONJOUR=1`, щоб вимкнути mDNS без змін у конфігурації. +4. **Змінна середовища** (альтернатива): установіть `OPENCLAW_DISABLE_BONJOUR=1`, щоб вимкнути mDNS без змін конфігурації. -У мінімальному режимі Gateway все одно транслює достатньо даних для виявлення пристроїв (`role`, `gatewayPort`, `transport`), але не включає `cliPath` і `sshPort`. Програми, яким потрібна інформація про шлях до CLI, можуть отримати її через автентифіковане підключення WebSocket. +У мінімальному режимі Gateway все одно транслює достатньо даних для виявлення пристроїв (`role`, `gatewayPort`, `transport`), але не включає `cliPath` і `sshPort`. Програми, яким потрібна інформація про шлях до CLI, можуть отримати її через автентифіковане з’єднання WebSocket. ### 0.5) Захистіть WebSocket Gateway (локальна auth) -Auth gateway **є обов’язковою за замовчуванням**. Якщо не налаштовано -жодного коректного шляху auth gateway, Gateway відмовляє у підключеннях WebSocket (безпечна відмова за замовчуванням). +Auth Gateway **потрібна за замовчуванням**. Якщо не налаштовано +жодного коректного шляху auth gateway, Gateway відмовляє у WebSocket-з’єднаннях (fail‑closed). -Онбординг типово генерує token (навіть для loopback), тому +Onboarding типово генерує токен (навіть для loopback), тому локальні клієнти повинні проходити автентифікацію. -Встановіть token, щоб **усі** клієнти WS проходили автентифікацію: +Установіть токен, щоб **усі** WS-клієнти мусили автентифікуватися: ```json5 { @@ -892,135 +888,134 @@ Auth gateway **є обов’язковою за замовчуванням**. } ``` -Doctor може згенерувати його для вас: `openclaw doctor --generate-gateway-token`. +Doctor може згенерувати його за вас: `openclaw doctor --generate-gateway-token`. -Примітка: `gateway.remote.token` / `.password` — це джерела клієнтських облікових даних. Вони -самі по собі **не** захищають локальний доступ WS. -Локальні шляхи виклику можуть використовувати `gateway.remote.*` як fallback лише тоді, коли `gateway.auth.*` -не встановлено. -Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не вдається визначити значення, -визначення завершується безпечним блокуванням (без маскування через fallback на remote). -Необов’язково: закріпіть віддалений TLS через `gateway.remote.tlsFingerprint`, якщо використовуєте `wss://`. -Нешифрований `ws://` типово дозволений лише для loopback. Для довірених шляхів у приватній мережі +Примітка: `gateway.remote.token` / `.password` — це джерела облікових даних клієнта. +Самі по собі вони **не** захищають локальний доступ WS. +Локальні шляхи виклику можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` +не задано. +Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і його не вдається розв’язати, розв’язання завершується fail closed (жоден резервний шлях remote не маскує проблему). +Необов’язково: закріпіть віддалений TLS через `gateway.remote.tlsFingerprint` під час використання `wss://`. +Нешифрований `ws://` типово дозволено лише для loopback. Для довірених шляхів у приватній мережі встановіть `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` у процесі клієнта як аварійний варіант. -Локальне pairing пристрою: +Локальний pairing пристроїв: - Pairing пристрою автоматично схвалюється для прямих локальних loopback-підключень, щоб - same-host клієнти працювали без зайвих перешкод. -- OpenClaw також має вузький backend/container-local шлях самопідключення для - довірених helper-потоків зі спільним секретом. + взаємодія клієнтів на тому самому хості була зручною. +- OpenClaw також має вузький шлях backend/container-local self-connect для + довірених потоків із допоміжними засобами зі спільним секретом. - Підключення через tailnet і LAN, включно з bind через tailnet на тому ж хості, вважаються - віддаленими з погляду pairing і все одно потребують схвалення. + віддаленими для pairing і все одно потребують схвалення. Режими auth: - `gateway.auth.mode: "token"`: спільний bearer token (рекомендовано для більшості конфігурацій). -- `gateway.auth.mode: "password"`: автентифікація за паролем (краще задавати через env: `OPENCLAW_GATEWAY_PASSWORD`). -- `gateway.auth.mode: "trusted-proxy"`: довіряти reverse proxy з підтримкою identity, який автентифікує користувачів і передає ідентичність через заголовки (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). +- `gateway.auth.mode: "password"`: автентифікація паролем (краще задавати через env: `OPENCLAW_GATEWAY_PASSWORD`). +- `gateway.auth.mode: "trusted-proxy"`: довіряти reverse proxy з урахуванням ідентичності, який автентифікує користувачів і передає ідентичність у заголовках (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Контрольний список ротації (token/password): 1. Згенеруйте/встановіть новий секрет (`gateway.auth.token` або `OPENCLAW_GATEWAY_PASSWORD`). 2. Перезапустіть Gateway (або перезапустіть застосунок macOS, якщо він керує Gateway). -3. Оновіть усі віддалені клієнти (`gateway.remote.token` / `.password` на машинах, які викликають Gateway). -4. Перевірте, що зі старими обліковими даними підключитися вже не можна. +3. Оновіть усі віддалені клієнти (`gateway.remote.token` / `.password` на машинах, які звертаються до Gateway). +4. Переконайтеся, що зі старими обліковими даними підключитися більше не можна. ### 0.6) Заголовки ідентичності Tailscale Serve Коли `gateway.auth.allowTailscale` має значення `true` (типово для Serve), OpenClaw приймає заголовки ідентичності Tailscale Serve (`tailscale-user-login`) для автентифікації -Control UI/WebSocket. OpenClaw перевіряє ідентичність, визначаючи адресу +Control UI/WebSocket. OpenClaw перевіряє ідентичність, розв’язуючи адресу `x-forwarded-for` через локальний демон Tailscale (`tailscale whois`) і зіставляючи її із заголовком. Це спрацьовує лише для запитів, що потрапляють на loopback і містять `x-forwarded-for`, `x-forwarded-proto` та `x-forwarded-host`, як -їх додає Tailscale. +інжектує Tailscale. Для цього асинхронного шляху перевірки ідентичності невдалі спроби для того самого `{scope, ip}` -серіалізуються до того, як лімітатор зафіксує помилку. Тому паралельні невдалі повторні спроби -від одного клієнта Serve можуть одразу заблокувати другу спробу, замість того щоб -пройти як дві звичайні незалежні невідповідності. +серіалізуються до того, як обмежувач зафіксує збій. Тому конкурентні невдалі повтори +від одного клієнта Serve можуть заблокувати другу спробу негайно, замість того щоб +проскочити як дві звичайні невідповідності. Кінцеві точки HTTP API (наприклад `/v1/*`, `/tools/invoke` і `/api/channels/*`) -**не** використовують auth через заголовки ідентичності Tailscale. Вони й далі дотримуються -налаштованого режиму HTTP auth gateway. +**не** використовують автентифікацію заголовками ідентичності Tailscale. Вони, як і раніше, дотримуються +налаштованого в gateway режиму HTTP auth. -Важлива примітка про межі: +Важлива примітка щодо меж: -- Bearer auth HTTP Gateway фактично дає повний або нульовий операторський доступ. -- Облікові дані, які можуть викликати `/v1/chat/completions`, `/v1/responses` або `/api/channels/*`, слід вважати секретами оператора з повним доступом для цього gateway. -- На HTTP-поверхні, сумісній з OpenAI, bearer auth зі спільним секретом відновлює повний типовий набір операторських scope (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) і семантику owner для ходів агента; вужчі значення `x-openclaw-scopes` не зменшують цей шлях зі спільним секретом. -- Семантика scope на HTTP на рівні окремого запиту застосовується лише тоді, коли запит надходить із режиму, що несе ідентичність, такого як auth trusted proxy або `gateway.auth.mode="none"` на приватному ingress. -- У таких режимах, що несуть ідентичність, пропуск `x-openclaw-scopes` повертає типовий набір операторських scope; надсилайте цей заголовок явно, якщо хочете вужчий набір scope. -- `/tools/invoke` дотримується того самого правила спільного секрету: bearer auth через token/password і тут розглядається як повний операторський доступ, тоді як режими з ідентичністю все ще враховують оголошені scope. -- Не діліться цими обліковими даними з недовіреними викликаючими; для кожної межі довіри краще використовувати окремі gateway. +- Bearer auth HTTP Gateway фактично дає повний операторський доступ без тонкого поділу. +- Ставтеся до облікових даних, які можуть викликати `/v1/chat/completions`, `/v1/responses` або `/api/channels/*`, як до повноцінних операторських секретів доступу до цього gateway. +- На сумісній з OpenAI HTTP-поверхні bearer auth зі спільним секретом відновлює повний типовий набір операторських scope (`operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write`) і семантику власника для ходів агента; вужчі значення `x-openclaw-scopes` не звужують цей шлях зі спільним секретом. +- Семантика scope на HTTP на рівні окремого запиту застосовується лише тоді, коли запит надходить із режиму, що несе ідентичність, як-от auth через trusted proxy або `gateway.auth.mode="none"` на приватному вході. +- У таких режимах, що несуть ідентичність, якщо не вказано `x-openclaw-scopes`, використовується звичайний типовий набір операторських scope; надсилайте заголовок явно, коли хочете вужчий набір scope. +- `/tools/invoke` дотримується того самого правила спільного секрету: bearer auth через token/password там також розглядається як повний операторський доступ, тоді як режими, що несуть ідентичність, як і раніше, поважають задекларовані scope. +- Не передавайте ці облікові дані недовіреним викликачам; краще використовуйте окремі Gateway для кожної межі довіри. -**Припущення довіри:** auth Serve без token виходить із довіри до хоста gateway. -Не вважайте це захистом від ворожих процесів на тому самому хості. Якщо на хості gateway +**Припущення довіри:** auth Serve без токена виходить із того, що хост gateway є довіреним. +Не розглядайте це як захист від ворожих процесів на тому самому хості. Якщо на хості gateway може виконуватися недовірений локальний код, вимкніть `gateway.auth.allowTailscale` -і вимагайте явної auth зі спільним секретом через `gateway.auth.mode: "token"` або +і вимагайте явної auth через спільний секрет із `gateway.auth.mode: "token"` або `"password"`. **Правило безпеки:** не пересилайте ці заголовки зі свого reverse proxy. Якщо -ви завершуєте TLS або ставите proxy перед gateway, вимкніть -`gateway.auth.allowTailscale` і використовуйте auth зі спільним секретом (`gateway.auth.mode: -"token"` або `"password"`) чи [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth) +ви завершуєте TLS або проксіюєте запити перед gateway, вимкніть +`gateway.auth.allowTailscale` і використовуйте auth через спільний секрет (`gateway.auth.mode: +"token"` або `"password"`) або [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth) замість цього. Довірені proxy: -- Якщо ви завершуєте TLS перед Gateway, вкажіть IP-адреси proxy у `gateway.trustedProxies`. -- OpenClaw довірятиме `x-forwarded-for` (або `x-real-ip`) від цих IP для визначення IP-адреси клієнта під час локальних перевірок pairing і HTTP auth/local-перевірок. +- Якщо ви завершуєте TLS перед Gateway, установіть `gateway.trustedProxies` на IP-адреси вашого proxy. +- OpenClaw довірятиме `x-forwarded-for` (або `x-real-ip`) від цих IP для визначення IP клієнта під час перевірок локального pairing і HTTP auth/local. - Переконайтеся, що ваш proxy **перезаписує** `x-forwarded-for` і блокує прямий доступ до порту Gateway. -Див. [Tailscale](/uk/gateway/tailscale) і [Огляд web](/web). +Див. [Tailscale](/uk/gateway/tailscale) і [Огляд Web](/web). -### 0.6.1) Керування браузером через хост node (рекомендовано) +### 0.6.1) Керування браузером через host Node (рекомендовано) -Якщо ваш Gateway віддалений, але браузер працює на іншій машині, запустіть **хост node** -на машині з браузером і дозвольте Gateway проксіювати дії браузера (див. [Інструмент browser](/uk/tools/browser)). -Розглядайте pairing node як адміндоступ. +Якщо ваш Gateway віддалений, але браузер працює на іншій машині, запустіть **host Node** +на машині з браузером і дозвольте Gateway проксувати дії браузера (див. [Інструмент browser](/uk/tools/browser)). +Ставтеся до pairing Node як до адміністративного доступу. Рекомендований шаблон: -- Тримайте Gateway і хост node в одному tailnet (Tailscale). -- Pairing node виконуйте свідомо; вимикайте proxy routing браузера, якщо він вам не потрібен. +- Тримайте Gateway і host Node в одній tailnet (Tailscale). +- Навмисно виконайте pairing Node; вимикайте proxy-маршрутизацію браузера, якщо вона вам не потрібна. Уникайте: - Відкриття relay/control-портів у LAN або публічному інтернеті. -- Tailscale Funnel для кінцевих точок керування браузером (публічна відкритість). +- Tailscale Funnel для кінцевих точок керування браузером (публічний доступ). ### 0.7) Секрети на диску (чутливі дані) -Виходьте з того, що будь-що в `~/.openclaw/` (або `$OPENCLAW_STATE_DIR/`) може містити секрети або приватні дані: +Вважайте, що все в `~/.openclaw/` (або `$OPENCLAW_STATE_DIR/`) може містити секрети або приватні дані: -- `openclaw.json`: конфігурація може містити токени (gateway, remote gateway), налаштування провайдерів і allowlist. -- `credentials/**`: облікові дані каналів (наприклад, WhatsApp creds), pairing allowlist, імпорт застарілого OAuth. -- `agents//agent/auth-profiles.json`: API-ключі, профілі токенів, OAuth-токени та необов’язкові `keyRef`/`tokenRef`. -- `secrets.json` (необов’язково): payload секретів на основі файлу, що використовується провайдерами `file` SecretRef (`secrets.providers`). -- `agents//agent/auth.json`: застарілий файл сумісності. Статичні записи `api_key` очищаються після виявлення. -- `agents//sessions/**`: транскрипти сесій (`*.jsonl`) + метадані маршрутизації (`sessions.json`), які можуть містити приватні повідомлення і вивід інструментів. -- пакети bundled plugin: встановлені plugins (разом із їхніми `node_modules/`). -- `sandboxes/**`: робочі простори sandbox для інструментів; можуть накопичувати копії файлів, які ви читаєте/записуєте всередині sandbox. +- `openclaw.json`: конфігурація може містити токени (gateway, віддалений gateway), налаштування постачальників і allowlist. +- `credentials/**`: облікові дані каналів (наприклад, облікові дані WhatsApp), allowlist pairing, імпорт застарілого OAuth. +- `agents//agent/auth-profiles.json`: API-ключі, профілі токенів, OAuth-токени, а також необов’язкові `keyRef`/`tokenRef`. +- `secrets.json` (необов’язково): файл із payload секретів, який використовується постачальниками SecretRef типу `file` (`secrets.providers`). +- `agents//agent/auth.json`: застарілий файл сумісності. Статичні записи `api_key` очищаються під час виявлення. +- `agents//sessions/**`: транскрипти сеансів (`*.jsonl`) + метадані маршрутизації (`sessions.json`), які можуть містити приватні повідомлення та результати інструментів. +- пакети bundled Plugin: установлені Plugin (разом із їхніми `node_modules/`). +- `sandboxes/**`: робочі простори sandbox інструментів; у них можуть накопичуватися копії файлів, які ви читали/записували всередині sandbox. Поради щодо посилення захисту: -- Тримайте жорсткі дозволи (`700` для каталогів, `600` для файлів). -- Використовуйте повнодискове шифрування на хості gateway. -- Якщо хост спільний, надавайте перевагу окремому користувацькому акаунту ОС для Gateway. +- Тримайте дозволи суворими (`700` для каталогів, `600` для файлів). +- Використовуйте повне шифрування диска на хості gateway. +- Якщо хост спільний, надавайте перевагу окремому обліковому запису користувача ОС для Gateway. -### 0.8) Журнали й транскрипти (редагування + зберігання) +### 0.8) Журнали + транскрипти (редагування + зберігання) -Журнали й транскрипти можуть призводити до витоку чутливої інформації, навіть якщо контроль доступу налаштовано правильно: +Журнали й транскрипти можуть призвести до витоку чутливої інформації навіть тоді, коли контроль доступу налаштовано правильно: - Журнали Gateway можуть містити зведення інструментів, помилки та URL. -- Транскрипти сесій можуть містити вставлені секрети, вміст файлів, вивід команд і посилання. +- Транскрипти сеансів можуть містити вставлені секрети, вміст файлів, вихід команд і посилання. Рекомендації: -- Тримайте редагування зведень інструментів увімкненим (`logging.redactSensitive: "tools"`; типово). -- Додавайте власні шаблони для вашого середовища через `logging.redactPatterns` (токени, імена хостів, внутрішні URL). -- Під час поширення діагностики надавайте перевагу `openclaw status --all` (зручно для вставлення, секрети відредаговано) замість сирих журналів. -- Видаляйте старі транскрипти сесій і файли журналів, якщо вам не потрібне довготривале зберігання. +- Тримайте редагування зведень інструментів увімкненим (`logging.redactSensitive: "tools"`; типове значення). +- Додавайте власні шаблони для свого середовища через `logging.redactPatterns` (токени, імена хостів, внутрішні URL). +- Коли ділитеся діагностикою, надавайте перевагу `openclaw status --all` (зручно вставляти, секрети відредаговані), а не сирим журналам. +- Видаляйте старі транскрипти сеансів і файли журналів, якщо вам не потрібне тривале зберігання. Докладніше: [Logging](/uk/gateway/logging) @@ -1032,7 +1027,7 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ви } ``` -### 2) Групи: вимагайте згадку всюди +### 2) Групи: вимагайте згадування всюди ```json { @@ -1054,31 +1049,31 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ви } ``` -У групових чатах відповідайте лише тоді, коли вас явно згадали. +У групових чатах відповідайте лише за явного згадування. ### 3) Окремі номери (WhatsApp, Signal, Telegram) -Для каналів на основі номера телефону варто розглянути запуск вашого AI на окремому номері телефону, відмінному від особистого: +Для каналів на основі телефонних номерів розгляньте запуск вашого AI на окремому номері телефону, а не на вашому особистому: - Особистий номер: ваші розмови залишаються приватними -- Номер бота: AI обробляє саме їх, у відповідних межах +- Номер бота: їх обробляє AI, з відповідними межами -### 4) Режим лише для читання (через sandbox + tools) +### 4) Режим лише для читання (через sandbox + інструменти) Ви можете побудувати профіль лише для читання, поєднавши: -- `agents.defaults.sandbox.workspaceAccess: "ro"` (або `"none"` без доступу до workspace) +- `agents.defaults.sandbox.workspaceAccess: "ro"` (або `"none"` для повної відсутності доступу до workspace) - списки allow/deny інструментів, які блокують `write`, `edit`, `apply_patch`, `exec`, `process` тощо Додаткові варіанти посилення захисту: -- `tools.exec.applyPatch.workspaceOnly: true` (типово): гарантує, що `apply_patch` не може записувати/видаляти файли поза каталогом workspace, навіть якщо sandboxing вимкнено. Встановлюйте `false` лише якщо свідомо хочете, щоб `apply_patch` працював із файлами поза workspace. -- `tools.fs.workspaceOnly: true` (необов’язково): обмежує шляхи `read`/`write`/`edit`/`apply_patch` і шляхи автозавантаження зображень native prompt каталогом workspace (корисно, якщо зараз ви дозволяєте абсолютні шляхи й хочете один спільний запобіжник). -- Тримайте корені файлової системи вузькими: уникайте широких коренів на кшталт домашнього каталогу для workspace агента/sandbox workspace. Широкі корені можуть відкрити інструментам файлової системи доступ до чутливих локальних файлів (наприклад, state/config у `~/.openclaw`). +- `tools.exec.applyPatch.workspaceOnly: true` (типово): гарантує, що `apply_patch` не може записувати/видаляти за межами каталогу workspace, навіть якщо sandboxing вимкнено. Установлюйте `false` лише тоді, коли ви свідомо хочете дозволити `apply_patch` працювати з файлами поза workspace. +- `tools.fs.workspaceOnly: true` (необов’язково): обмежує шляхи `read`/`write`/`edit`/`apply_patch` і нативні шляхи автозавантаження зображень у prompt лише каталогом workspace (корисно, якщо сьогодні ви дозволяєте абсолютні шляхи й хочете мати єдиний запобіжник). +- Тримайте корені файлової системи вузькими: уникайте широких коренів, як-от ваш домашній каталог, для workspace агента/workspace sandbox. Широкі корені можуть відкривати файловим інструментам доступ до чутливих локальних файлів (наприклад, state/config у `~/.openclaw`). -### 5) Безпечна базова конфігурація (копіювати/вставити) +### 5) Безпечний базовий профіль (копіювати/вставити) -Одна «безпечна за замовчуванням» конфігурація, яка тримає Gateway приватним, вимагає DM pairing і уникає завжди активних ботів у групах: +Одна «безпечна типова» конфігурація, яка тримає Gateway приватним, вимагає pairing для DM і уникає завжди активних ботів у групах: ```json5 { @@ -1097,9 +1092,9 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ви } ``` -Якщо ви також хочете «безпечніше за замовчуванням» виконання інструментів, додайте sandbox + заборону небезпечних інструментів для будь-якого агента, що не є owner (приклад нижче в розділі «Профілі доступу на рівні агента»). +Якщо ви хочете також «типово безпечніше» виконання інструментів, додайте sandbox + deny небезпечних інструментів для будь-якого агента, який не є власником (див. приклад нижче в розділі «Профілі доступу для кожного агента»). -Вбудована базова політика для ходів агента, керованих через чат: відправники, які не є owner, не можуть використовувати інструменти `cron` або `gateway`. +Вбудований базовий профіль для chat-driven ходів агента: відправники, які не є власниками, не можуть використовувати інструменти `cron` або `gateway`. ## Sandboxing (рекомендовано) @@ -1108,58 +1103,58 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ви Два взаємодоповнювальні підходи: - **Запускати весь Gateway у Docker** (межа контейнера): [Docker](/uk/install/docker) -- **Інструментальний sandbox** (`agents.defaults.sandbox`, хостовий gateway + інструменти, ізольовані через Docker): [Sandboxing](/uk/gateway/sandboxing) +- **Інструментальний sandbox** (`agents.defaults.sandbox`, host gateway + інструменти, ізольовані Docker): [Sandboxing](/uk/gateway/sandboxing) -Примітка: щоб запобігти доступу між агентами, тримайте `agents.defaults.sandbox.scope` на значенні `"agent"` (типово) -або `"session"` для суворішої ізоляції на рівні сесій. `scope: "shared"` використовує -один контейнер/workspace. +Примітка: щоб запобігти доступу між агентами, залишайте `agents.defaults.sandbox.scope` зі значенням `"agent"` (типово) +або використовуйте `"session"` для суворішої ізоляції на рівні сеансу. `scope: "shared"` використовує +один спільний контейнер/workspace. -Також враховуйте доступ агента до workspace всередині sandbox: +Також врахуйте доступ агента до workspace всередині sandbox: -- `agents.defaults.sandbox.workspaceAccess: "none"` (типово) не дає доступу до workspace агента; інструменти працюють із sandbox workspace у `~/.openclaw/sandboxes` +- `agents.defaults.sandbox.workspaceAccess: "none"` (типово) залишає workspace агента недоступним; інструменти працюють із workspace sandbox у `~/.openclaw/sandboxes` - `agents.defaults.sandbox.workspaceAccess: "ro"` монтує workspace агента лише для читання в `/agent` (вимикає `write`/`edit`/`apply_patch`) - `agents.defaults.sandbox.workspaceAccess: "rw"` монтує workspace агента для читання/запису в `/workspace` -- Додаткові `sandbox.docker.binds` перевіряються відносно нормалізованих і канонізованих вихідних шляхів. Хитрощі з symlink батьківського каталогу та канонічними псевдонімами домашнього каталогу все одно безпечно блокуються, якщо вони розв’язуються в заблоковані корені, такі як `/etc`, `/var/run` або каталоги облікових даних у home каталозі ОС. +- Додаткові `sandbox.docker.binds` перевіряються за нормалізованими й канонізованими шляхами джерела. Хитрощі з symlink батьківських каталогів і канонічними псевдонімами home усе одно завершуються fail closed, якщо вони розв’язуються в заблоковані корені, такі як `/etc`, `/var/run` або каталоги облікових даних у home ОС. -Важливо: `tools.elevated` — це глобальний аварійний вихід із базової політики, який запускає exec поза sandbox. Ефективним хостом типово є `gateway`, або `node`, якщо ціль exec налаштована як `node`. Тримайте `tools.elevated.allowFrom` суворо обмеженим і не вмикайте його для сторонніх користувачів. Ви можете додатково обмежити elevated на рівні агента через `agents.list[].tools.elevated`. Див. [Elevated Mode](/uk/tools/elevated). +Важливо: `tools.elevated` — це глобальний аварійний обхід базового захисту, який запускає exec поза sandbox. Ефективний host типово має значення `gateway`, або `node`, якщо ціль exec налаштована на `node`. Тримайте `tools.elevated.allowFrom` вузьким і не вмикайте це для сторонніх. Ви також можете додатково обмежити elevated для конкретного агента через `agents.list[].tools.elevated`. Див. [Elevated Mode](/uk/tools/elevated). -### Запобіжник делегування субагентам +### Запобіжник делегування підлеглих агентів -Якщо ви дозволяєте інструменти сесій, розглядайте делеговані запуски субагентів як окреме рішення щодо меж: +Якщо ви дозволяєте інструменти сеансів, розглядайте делеговані запуски підлеглих агентів як ще одне рішення щодо меж: - Забороняйте `sessions_spawn`, якщо агенту справді не потрібне делегування. -- Тримайте `agents.defaults.subagents.allowAgents` і будь-які перевизначення `agents.list[].subagents.allowAgents` на рівні агента обмеженими відомо безпечними цільовими агентами. -- Для будь-якого workflow, який має залишатися в sandbox, викликайте `sessions_spawn` із `sandbox: "require"` (типове значення — `inherit`). -- `sandbox: "require"` негайно завершується помилкою, якщо дочірній runtime цільового агента не працює в sandbox. +- Тримайте `agents.defaults.subagents.allowAgents` і будь-які перевизначення `agents.list[].subagents.allowAgents` для окремих агентів обмеженими відомими безпечними цільовими агентами. +- Для будь-якого робочого процесу, який має залишатися в sandbox, викликайте `sessions_spawn` із `sandbox: "require"` (типове значення — `inherit`). +- `sandbox: "require"` швидко завершується помилкою, якщо цільовий дочірній runtime не працює в sandbox. ## Ризики керування браузером Увімкнення керування браузером дає моделі можливість керувати реальним браузером. -Якщо в цьому профілі браузера вже є активні сесії входу, модель може +Якщо в цьому профілі браузера вже є активні сеанси входу, модель може отримати доступ до цих акаунтів і даних. Розглядайте профілі браузера як **чутливий стан**: - Надавайте перевагу окремому профілю для агента (типовий профіль `openclaw`). -- Уникайте спрямування агента на ваш особистий щоденний профіль. -- Тримайте керування браузером на хості вимкненим для sandboxed-агентів, якщо ви їм не довіряєте. -- Окремий loopback API керування браузером підтримує лише auth зі спільним секретом - (bearer auth через token gateway або пароль gateway). Він не використовує +- Уникайте спрямування агента на ваш особистий повсякденний профіль. +- Тримайте керування браузером на host вимкненим для агентів у sandbox, якщо ви їм не довіряєте. +- Автономний loopback API керування браузером приймає лише auth через спільний секрет + (bearer auth токеном gateway або паролем gateway). Він не використовує заголовки ідентичності trusted-proxy або Tailscale Serve. -- Розглядайте завантаження браузером як недовірений вхід; надавайте перевагу ізольованому каталогу завантажень. +- Ставтеся до завантажень браузера як до недовіреного вводу; надавайте перевагу ізольованому каталогу завантажень. - Якщо можливо, вимикайте синхронізацію браузера/менеджери паролів у профілі агента (це зменшує радіус ураження). -- Для віддалених gateway виходьте з того, що «керування браузером» еквівалентне «операторському доступу» до всього, до чого має доступ цей профіль. -- Тримайте Gateway і хости node лише в tailnet; уникайте відкриття портів керування браузером у LAN або публічному інтернеті. -- Вимикайте proxy routing браузера, якщо він вам не потрібен (`gateway.nodes.browser.mode="off"`). -- Режим наявної сесії Chrome MCP **не** є «безпечнішим»; він може діяти від вашого імені в усьому, до чого має доступ той профіль Chrome на хості. +- Для віддалених gateway виходьте з того, що «керування браузером» еквівалентне «операторському доступу» до всього, чого може досягти цей профіль. +- Тримайте Gateway і host Node доступними лише через tailnet; уникайте відкриття портів керування браузером у LAN або публічному інтернеті. +- Вимикайте proxy-маршрутизацію браузера, коли вона не потрібна (`gateway.nodes.browser.mode="off"`). +- Режим існуючого сеансу Chrome MCP **не** є «безпечнішим»; він може діяти від вашого імені в межах усього, до чого має доступ цей профіль Chrome на host. ### Політика SSRF браузера (сувора за замовчуванням) -Політика навігації браузера в OpenClaw за замовчуванням сувора: приватні/внутрішні адресати залишаються заблокованими, якщо ви явно не дозволите їх. +Політика навігації браузера в OpenClaw сувора за замовчуванням: приватні/внутрішні адресати залишаються заблокованими, якщо ви явно не дозволите їх. -- Типова поведінка: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` не встановлено, тому навігація браузера й далі блокує приватні/внутрішні/special-use адресати. +- Типово: `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` не встановлено, тому навігація браузера блокує приватні/внутрішні/special-use адресати. - Застарілий псевдонім: `browser.ssrfPolicy.allowPrivateNetwork` і далі приймається для сумісності. -- Режим з явною згодою: встановіть `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, щоб дозволити приватні/внутрішні/special-use адресати. -- У суворому режимі використовуйте `hostnameAllowlist` (шаблони на кшталт `*.example.com`) і `allowedHostnames` (точні винятки хостів, включно із заблокованими іменами на кшталт `localhost`) для явних винятків. -- Навігація перевіряється до запиту та повторно перевіряється best-effort на фінальному URL `http(s)` після навігації, щоб зменшити ризик переходів через редиректи. +- Режим за явною згодою: установіть `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, щоб дозволити приватні/внутрішні/special-use адресати. +- У суворому режимі використовуйте `hostnameAllowlist` (шаблони на кшталт `*.example.com`) і `allowedHostnames` (точні винятки для host, включно із заблокованими іменами, як-от `localhost`) для явних винятків. +- Навігація перевіряється перед запитом і повторно перевіряється best-effort на фінальному URL `http(s)` після навігації, щоб зменшити ризик pivot через редиректи. Приклад суворої політики: @@ -1175,17 +1170,17 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ви } ``` -## Профілі доступу на рівні агента (multi-agent) +## Профілі доступу для кожного агента (багатоагентність) -У multi-agent-маршрутизації кожен агент може мати власну політику sandbox + tools: -використовуйте це, щоб надавати **повний доступ**, **лише читання** або **без доступу** на рівні агента. +За багатoагентної маршрутизації кожен агент може мати власний sandbox + політику інструментів: +використовуйте це, щоб надавати **повний доступ**, **лише читання** або **без доступу** для кожного агента. Повні подробиці та правила пріоритету див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). Типові сценарії: - Особистий агент: повний доступ, без sandbox - Сімейний/робочий агент: sandbox + інструменти лише для читання -- Публічний агент: sandbox + без інструментів файлової системи/оболонки +- Публічний агент: sandbox + без доступу до файлової системи/оболонки ### Приклад: повний доступ (без sandbox) @@ -1227,7 +1222,7 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ви } ``` -### Приклад: без доступу до файлової системи/оболонки (дозволені provider messaging) +### Приклад: без доступу до файлової системи/оболонки (дозволено обмін повідомленнями через постачальника) ```json5 { @@ -1241,9 +1236,9 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ви scope: "agent", workspaceAccess: "none", }, - // Session tools can reveal sensitive data from transcripts. By default OpenClaw limits these tools - // to the current session + spawned subagent sessions, but you can clamp further if needed. - // See `tools.sessions.visibility` in the configuration reference. + // Інструменти сеансів можуть розкривати чутливі дані з транскриптів. Типово OpenClaw обмежує ці інструменти + // поточним сеансом + сеансами запущених підлеглих агентів, але за потреби можна обмежити їх ще сильніше. + // Див. `tools.sessions.visibility` у довіднику конфігурації. tools: { sessions: { visibility: "tree" }, // self | tree | agent | all allow: [ @@ -1280,7 +1275,7 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ви ## Що сказати вашому AI -Включіть рекомендації з безпеки до system prompt вашого агента: +Додайте рекомендації з безпеки до системного prompt вашого агента: ``` ## Security Rules @@ -1293,42 +1288,42 @@ Control UI/WebSocket. OpenClaw перевіряє ідентичність, ви ## Реагування на інциденти -Якщо ваш AI зробив щось небажане: +Якщо ваш AI зробив щось погане: -### Стримування +### Стримайте ситуацію -1. **Зупиніть це:** зупиніть застосунок macOS (якщо він керує Gateway) або завершіть процес `openclaw gateway`. -2. **Закрийте відкритість:** встановіть `gateway.bind: "loopback"` (або вимкніть Tailscale Funnel/Serve), доки не зрозумієте, що сталося. -3. **Заморозьте доступ:** переключіть ризиковані DM/групи на `dmPolicy: "disabled"` / вимогу згадки та видаліть записи `"*"`, що дозволяють усіх, якщо вони у вас були. +1. **Зупиніть його:** зупиніть застосунок macOS (якщо він керує Gateway) або завершіть процес `openclaw gateway`. +2. **Закрийте доступ:** установіть `gateway.bind: "loopback"` (або вимкніть Tailscale Funnel/Serve), доки не зрозумієте, що сталося. +3. **Заморозьте доступ:** перемкніть ризиковані DM/групи на `dmPolicy: "disabled"` / вимогу згадувань і видаліть записи `"*"`, що дозволяють усіх, якщо вони були. -### Ротація (вважайте, що стався компроміс, якщо секрети витекли) +### Проведіть ротацію (припускайте компрометацію, якщо секрети витекли) -1. Замініть auth Gateway (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) і перезапустіть. -2. Замініть секрети віддалених клієнтів (`gateway.remote.token` / `.password`) на всіх машинах, які можуть викликати Gateway. -3. Замініть облікові дані провайдерів/API (WhatsApp creds, токени Slack/Discord, ключі моделей/API в `auth-profiles.json` і значення payload зашифрованих секретів, якщо вони використовуються). +1. Змініть auth Gateway (`gateway.auth.token` / `OPENCLAW_GATEWAY_PASSWORD`) і перезапустіть систему. +2. Змініть секрети віддалених клієнтів (`gateway.remote.token` / `.password`) на кожній машині, яка може викликати Gateway. +3. Змініть облікові дані постачальників/API (облікові дані WhatsApp, токени Slack/Discord, ключі моделей/API в `auth-profiles.json` і значення зашифрованого payload секретів, якщо вони використовуються). ### Аудит 1. Перевірте журнали Gateway: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` (або `logging.file`). 2. Перегляньте відповідні транскрипти: `~/.openclaw/agents//sessions/*.jsonl`. -3. Перегляньте недавні зміни конфігурації (усе, що могло розширити доступ: `gateway.bind`, `gateway.auth`, політики dm/group, `tools.elevated`, зміни plugins). -4. Повторно запустіть `openclaw security audit --deep` і переконайтеся, що критичні знахідки усунуто. +3. Перегляньте нещодавні зміни конфігурації (усе, що могло розширити доступ: `gateway.bind`, `gateway.auth`, політики dm/group, `tools.elevated`, зміни Plugin). +4. Повторно запустіть `openclaw security audit --deep` і переконайтеся, що критичні висновки усунено. -### Зберіть дані для звіту +### Зберіть для звіту -- Часова мітка, ОС хоста gateway + версія OpenClaw -- Транскрипти сесії(й) + короткий хвіст журналу (після редагування) -- Що надіслав зловмисник + що зробив агент -- Чи був Gateway відкритий за межі loopback (LAN/Tailscale Funnel/Serve) +- Часову позначку, ОС хоста gateway + версію OpenClaw +- Транскрипти сеансів + короткий tail журналу (після редагування) +- Що надіслав атакувальник + що зробив агент +- Чи був Gateway відкритий поза loopback (LAN/Tailscale Funnel/Serve) ## Сканування секретів (detect-secrets) CI запускає pre-commit hook `detect-secrets` у job `secrets`. Push у `main` завжди запускають сканування всіх файлів. Pull request використовують -швидкий шлях для змінених файлів, коли доступний базовий коміт, і повертаються до -сканування всіх файлів в іншому випадку. Якщо перевірка не проходить, з’явилися нові кандидати, яких ще немає в baseline. +швидкий шлях лише для змінених файлів, коли доступний базовий коміт, і повертаються +до повного сканування інакше. Якщо перевірка завершується невдачею, це означає, що є нові кандидати, яких ще немає в baseline. -### Якщо CI не проходить +### Якщо CI падає 1. Відтворіть локально: @@ -1337,25 +1332,27 @@ Push у `main` завжди запускають сканування всіх ``` 2. Зрозумійте інструменти: - - `detect-secrets` у pre-commit запускає `detect-secrets-hook` з baseline та exclude цього репозиторію. - - `detect-secrets audit` відкриває інтерактивний перегляд, де можна позначити кожен елемент baseline як справжній секрет або хибнопозитивне спрацювання. -3. Якщо це справжні секрети: замініть/видаліть їх, а потім повторно запустіть сканування, щоб оновити baseline. -4. Якщо це хибнопозитивні спрацювання: запустіть інтерактивний аудит і позначте їх як хибні: + - `detect-secrets` у pre-commit запускає `detect-secrets-hook` із baseline + та виключеннями репозиторію. + - `detect-secrets audit` відкриває інтерактивний перегляд, щоб позначити кожен елемент baseline + як справжній секрет або хибнопозитивне спрацювання. +3. Для справжніх секретів: змініть/видаліть їх, а потім повторно запустіть сканування, щоб оновити baseline. +4. Для хибнопозитивних спрацювань: запустіть інтерактивний audit і позначте їх як хибні: ```bash detect-secrets audit .secrets.baseline ``` -5. Якщо вам потрібні нові exclude, додайте їх до `.detect-secrets.cfg` і заново згенеруйте - baseline з відповідними прапорцями `--exclude-files` / `--exclude-lines` (файл конфігурації - є лише довідковим; detect-secrets не читає його автоматично). +5. Якщо вам потрібні нові виключення, додайте їх до `.detect-secrets.cfg` і заново згенеруйте + baseline з відповідними прапорами `--exclude-files` / `--exclude-lines` (файл config + наведено лише для довідки; detect-secrets не читає його автоматично). -Закомітьте оновлений `.secrets.baseline`, щойно він відображатиме запланований стан. +Закомітьте оновлений `.secrets.baseline`, коли він відображатиме задуманий стан. ## Повідомлення про проблеми безпеки Знайшли вразливість в OpenClaw? Будь ласка, повідомте відповідально: 1. Email: [security@openclaw.ai](mailto:security@openclaw.ai) -2. Не публікуйте інформацію публічно, доки проблему не буде виправлено -3. Ми зазначимо вашу заслугу (якщо ви не віддаєте перевагу анонімності) +2. Не публікуйте публічно, доки проблему не буде виправлено +3. Ми вкажемо вас у подяках (якщо ви не віддаєте перевагу анонімності) diff --git a/docs/uk/help/debugging.md b/docs/uk/help/debugging.md index 498b4efe8..d8b764717 100644 --- a/docs/uk/help/debugging.md +++ b/docs/uk/help/debugging.md @@ -1,15 +1,15 @@ --- read_when: - - Вам потрібно перевірити сирий вивід моделі на витік міркувань - - Ви хочете запускати Gateway у режимі watch під час ітерацій + - Вам потрібно перевірити сирий вивід моделі на наявність витоку міркувань + - Ви хочете запускати Gateway у режимі спостереження під час ітерації - Вам потрібен відтворюваний робочий процес налагодження -summary: 'Інструменти налагодження: режим watch, сирі потоки моделі та відстеження витоку міркувань' +summary: 'Інструменти налагодження: режим спостереження, сирі потоки моделі та трасування витоку міркувань' title: Налагодження x-i18n: - generated_at: "2026-04-05T22:36:52Z" + generated_at: "2026-04-12T18:22:02Z" model: gpt-5.4 provider: openai - source_hash: 4bc72e8d6cad3a1acaad066f381c82309583fabf304c589e63885f2685dc704e + source_hash: bc31ce9b41e92a14c4309f32df569b7050b18024f83280930e53714d3bfcd5cc source_path: help/debugging.md workflow: 15 --- @@ -21,9 +21,9 @@ x-i18n: ## Перевизначення налагодження під час виконання -Використовуйте `/debug` у чаті, щоб задавати перевизначення конфігурації **лише на час виконання** (у пам’яті, не на диску). -`/debug` вимкнено за замовчуванням; увімкніть його за допомогою `commands.debug: true`. -Це зручно, коли потрібно перемкнути маловідомі налаштування без редагування `openclaw.json`. +Використовуйте `/debug` у чаті, щоб установити перевизначення конфігурації **лише для поточного виконання** (у пам’яті, не на диску). +`/debug` за замовчуванням вимкнено; увімкніть його за допомогою `commands.debug: true`. +Це зручно, коли потрібно перемикати малопомітні налаштування без редагування `openclaw.json`. Приклади: @@ -34,43 +34,60 @@ x-i18n: /debug reset ``` -`/debug reset` очищує всі перевизначення та повертає конфігурацію з диска. +`/debug reset` очищає всі перевизначення та повертає конфігурацію з диска. -## Режим watch для Gateway +## Вивід трасування сесії -Для швидких ітерацій запускайте gateway під наглядом засобу відстеження файлів: +Використовуйте `/trace`, коли хочете бачити рядки trace/debug, що належать plugin, в одній сесії +без увімкнення повного режиму verbose. + +Приклади: + +```text +/trace +/trace on +/trace off +``` + +Використовуйте `/trace` для діагностики plugin, наприклад зведень налагодження Active Memory. +Продовжуйте використовувати `/verbose` для звичайного виводу статусу/інструментів у режимі verbose, а також +продовжуйте використовувати `/debug` для перевизначень конфігурації лише під час виконання. + +## Режим спостереження Gateway + +Для швидкої ітерації запускайте Gateway під файловим спостерігачем: ```bash pnpm gateway:watch ``` -Це відповідає такому: +Це відповідає: ```bash node scripts/watch-node.mjs gateway --force ``` -Засіб відстеження перезапускається при змінах у важливих для збірки файлах у `src/`, вихідних файлах розширень, -метаданих розширень `package.json` і `openclaw.plugin.json`, `tsconfig.json`, -`package.json` і `tsdown.config.ts`. Зміни в метаданих розширень перезапускають -gateway без примусового перебудування `tsdown`; зміни у вихідних файлах і конфігурації, як і раніше, +Спостерігач перезапускається при змінах у файлах, важливих для збірки, у `src/`, вихідних файлах extension, +метаданих extension `package.json` і `openclaw.plugin.json`, `tsconfig.json`, +`package.json` і `tsdown.config.ts`. Зміни метаданих extension перезапускають +Gateway без примусового `tsdown`-перезбирання; зміни у вихідному коді та конфігурації, як і раніше, спочатку перебудовують `dist`. -Додайте будь-які прапорці CLI для gateway після `gateway:watch`, і вони передаватимуться під час -кожного перезапуску. Повторний запуск тієї самої команди watch для того самого репозиторію/набору прапорців тепер -замінює старіший засіб відстеження, замість того щоб залишати дубльовані батьківські процеси спостерігача. +Додайте будь-які прапорці CLI Gateway після `gateway:watch`, і вони передаватимуться далі +під час кожного перезапуску. Повторний запуск тієї самої команди watch для того самого набору repo/прапорців +тепер замінює старіший спостерігач замість того, щоб залишати дубльовані батьківські процеси спостерігача. ## Профіль dev + dev gateway (--dev) Використовуйте профіль dev, щоб ізолювати стан і підняти безпечне, тимчасове середовище для -налагодження. Існує **два** прапорці `--dev`: +налагодження. Є **два** прапорці `--dev`: - **Глобальний `--dev` (профіль):** ізолює стан у `~/.openclaw-dev` і - за замовчуванням встановлює порт gateway на `19001` (похідні порти зміщуються разом із ним). + за замовчуванням встановлює порт Gateway на `19001` (пов’язані порти зміщуються разом із ним). - **`gateway --dev`:** вказує Gateway автоматично створити типову конфігурацію + - робочу область, якщо вони відсутні (і пропустити BOOTSTRAP.md). + workspace, якщо їх немає (і пропустити BOOTSTRAP.md). -Рекомендований процес (профіль dev + dev bootstrap): +Рекомендований сценарій (профіль dev + dev bootstrap): ```bash pnpm gateway:dev @@ -88,31 +105,31 @@ OPENCLAW_PROFILE=dev openclaw tui - `OPENCLAW_GATEWAY_PORT=19001` (порти browser/canvas відповідно зміщуються) 2. **Dev bootstrap** (`gateway --dev`) - - Записує мінімальну конфігурацію, якщо її немає (`gateway.mode=local`, прив’язка до loopback). - - Встановлює `agent.workspace` на dev-робочу область. - - Встановлює `agent.skipBootstrap=true` (без BOOTSTRAP.md). - - Ініціалізує файли робочої області, якщо їх немає: + - Записує мінімальну конфігурацію, якщо її немає (`gateway.mode=local`, bind loopback). + - Установлює `agent.workspace` на dev workspace. + - Установлює `agent.skipBootstrap=true` (без BOOTSTRAP.md). + - Заповнює файли workspace, якщо їх немає: `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`. - Типова ідентичність: **C3‑PO** (протокольний дроїд). - - Пропускає провайдери каналів у режимі dev (`OPENCLAW_SKIP_CHANNELS=1`). + - У режимі dev пропускає канальні провайдери (`OPENCLAW_SKIP_CHANNELS=1`). -Процес скидання (чистий старт): +Сценарій скидання (чистий старт): ```bash pnpm gateway:dev:reset ``` -Примітка: `--dev` — це **глобальний** прапорець профілю, і деякі засоби запуску його поглинають. +Примітка: `--dev` — це **глобальний** прапорець профілю, і деякі раннери його поглинають. Якщо потрібно вказати його явно, використовуйте форму зі змінною середовища: ```bash OPENCLAW_PROFILE=dev openclaw gateway --dev --reset ``` -`--reset` очищує конфігурацію, облікові дані, сесії та dev-робочу область (з використанням +`--reset` очищає конфігурацію, облікові дані, сесії та dev workspace (за допомогою `trash`, а не `rm`), а потім заново створює типове dev-середовище. -Порада: якщо вже запущено gateway не в режимі dev (launchd/systemd), спочатку зупиніть його: +Порада: якщо вже запущено не-dev Gateway (launchd/systemd), спочатку зупиніть його: ```bash openclaw gateway stop @@ -120,7 +137,7 @@ openclaw gateway stop ## Логування сирого потоку (OpenClaw) -OpenClaw може журналювати **сирий потік помічника** до будь-якої фільтрації/форматування. +OpenClaw може журналювати **сирий потік асистента** до будь-якої фільтрації/форматування. Це найкращий спосіб побачити, чи надходять міркування як звичайні текстові дельти (або як окремі блоки thinking). @@ -149,8 +166,8 @@ OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl ## Логування сирих чанків (pi-mono) -Щоб захопити **сирі OpenAI-сумісні чанки** до того, як вони буде розібрано на блоки, -pi-mono надає окремий журналювальник: +Щоб захопити **сирі OpenAI-сумісні чанки** до того, як їх буде розібрано на блоки, +pi-mono надає окремий журналювач: ```bash PI_RAW_STREAM=1 @@ -166,11 +183,11 @@ PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl `~/.pi-mono/logs/raw-openai-completions.jsonl` -> Примітка: це виводиться лише процесами, які використовують провайдер -> `openai-completions` у pi-mono. +> Примітка: це виводиться лише процесами, які використовують провайдер pi-mono +> `openai-completions`. ## Примітки щодо безпеки -- Журнали сирого потоку можуть містити повні запити, вивід інструментів і дані користувача. +- Журнали сирого потоку можуть містити повні підказки, вивід інструментів і дані користувача. - Зберігайте журнали локально та видаляйте їх після налагодження. -- Якщо ви ділитеся журналами, спочатку очистьте з них секрети та персональні дані. +- Якщо ділитеся журналами, спочатку очищуйте з них секрети та PII. diff --git a/docs/uk/help/faq.md b/docs/uk/help/faq.md index c62c56e7a..1b4fdc0e6 100644 --- a/docs/uk/help/faq.md +++ b/docs/uk/help/faq.md @@ -1,21 +1,21 @@ --- read_when: - - Відповідь на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки під час виконання + - Відповіді на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки під час виконання - Тріаж проблем, про які повідомляють користувачі, перед глибшим налагодженням summary: Часті запитання про налаштування, конфігурацію та використання OpenClaw -title: ЧаПи +title: Часті запитання x-i18n: - generated_at: "2026-04-07T19:00:28Z" + generated_at: "2026-04-12T18:22:02Z" model: gpt-5.4 provider: openai - source_hash: 001b4605966b45b08108606f76ae937ec348c2179b04cf6fb34fef94833705e6 + source_hash: d2a78d0fea9596625cc2753e6dc8cc42c2379a3a0c91729265eee0261fe53eaa source_path: help/faq.md workflow: 15 --- -# ЧаПи +# Часті запитання -Швидкі відповіді та глибше усунення несправностей для реальних сценаріїв (локальна розробка, VPS, мультиагентність, OAuth/API-ключі, перемикання моделей при збоях). Для діагностики під час виконання див. [Усунення несправностей](/uk/gateway/troubleshooting). Повний довідник конфігурації див. у [Конфігурація](/uk/gateway/configuration). +Швидкі відповіді плюс глибше усунення проблем для реальних сценаріїв налаштування (локальна розробка, VPS, multi-agent, OAuth/API-ключі, резервне перемикання моделей). Для діагностики під час виконання див. [Усунення проблем](/uk/gateway/troubleshooting). Повний довідник із конфігурації див. у [Конфігурація](/uk/gateway/configuration). ## Перші 60 секунд, якщо щось зламалося @@ -25,15 +25,15 @@ x-i18n: openclaw status ``` - Швидкий локальний підсумок: ОС + оновлення, доступність gateway/сервісу, агенти/сесії, конфігурація провайдера + проблеми під час виконання (коли gateway доступний). + Швидке локальне зведення: ОС + оновлення, доступність gateway/сервісу, agents/sessions, конфігурація провайдера + проблеми під час виконання (коли gateway доступний). -2. **Звіт, який можна вставити та поширити** +2. **Звіт, який можна вставити та поділитися ним** ```bash openclaw status --all ``` - Діагностика лише для читання з хвостом журналу (токени замасковані). + Діагностика в режимі лише читання з хвостом логу (токени замасковано). 3. **Стан демона + порту** @@ -41,7 +41,7 @@ x-i18n: openclaw gateway status ``` - Показує стан supervisor під час виконання проти доступності RPC, цільовий URL для probe та яку конфігурацію сервіс, імовірно, використав. + Показує runtime supervisor порівняно з досяжністю RPC, цільову URL-адресу probe і те, яку конфігурацію сервіс, імовірно, використовував. 4. **Глибокі probe-перевірки** @@ -49,22 +49,22 @@ x-i18n: openclaw status --deep ``` - Виконує живу probe-перевірку стану gateway, включно з probe-перевірками каналів, коли це підтримується - (потрібен доступний gateway). Див. [Стан](/uk/gateway/health). + Запускає live probe-перевірку стану gateway, зокрема перевірки channel, якщо це підтримується + (потрібен доступний gateway). Див. [Health](/uk/gateway/health). -5. **Переглянути хвіст останнього журналу** +5. **Переглянути хвіст останнього логу** ```bash openclaw logs --follow ``` - Якщо RPC недоступний, використайте запасний варіант: + Якщо RPC недоступний, використайте як запасний варіант: ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - Файлові журнали відокремлені від журналів сервісу; див. [Журналювання](/uk/logging) та [Усунення несправностей](/uk/gateway/troubleshooting). + Файлові логи відокремлені від сервісних логів; див. [Logging](/uk/logging) і [Усунення проблем](/uk/gateway/troubleshooting). 6. **Запустити doctor (виправлення)** @@ -72,44 +72,44 @@ x-i18n: openclaw doctor ``` - Виправляє/мігрує конфігурацію/стан + запускає перевірки справності. Див. [Doctor](/uk/gateway/doctor). + Виправляє/мігрує config/state + запускає перевірки стану. Див. [Doctor](/uk/gateway/doctor). 7. **Знімок gateway** ```bash openclaw health --json - openclaw health --verbose # показує цільовий URL + шлях до конфігурації при помилках + openclaw health --verbose # показує цільову URL-адресу + шлях до config у разі помилок ``` - Запитує в запущеного gateway повний знімок стану (лише WS). Див. [Стан](/uk/gateway/health). + Запитує повний знімок у запущеного gateway (лише WS). Див. [Health](/uk/gateway/health). ## Швидкий старт і початкове налаштування - - Використайте локального AI-агента, який може **бачити вашу машину**. Це набагато ефективніше, ніж питати - в 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, сервіси, дозволи, файли auth). Надайте їм **повну checkout-копію вихідного коду** через - hackable (git) встановлення: + Ці інструменти можуть читати репозиторій, виконувати команди, перевіряти логи й допомагати виправити + налаштування на рівні машини (PATH, сервіси, дозволи, файли автентифікації). Дайте їм **повну checkout-копію вихідного коду** + через hackable (git) install: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` Це встановлює OpenClaw **із git checkout**, тож агент може читати код + документацію та - міркувати про точну версію, яку ви запускаєте. Ви завжди можете повернутися на stable пізніше, + міркувати на основі точної версії, яку ви використовуєте. Ви завжди можете пізніше повернутися до stable, повторно запустивши інсталятор без `--install-method git`. - Порада: попросіть агента **спланувати та контролювати** виправлення (крок за кроком), а потім виконати лише - потрібні команди. Це робить зміни меншими та простішими для аудиту. + Порада: попросіть агента **спланувати й контролювати** виправлення (крок за кроком), а потім виконати лише + потрібні команди. Це зберігає зміни невеликими й полегшує аудит. - Якщо ви виявили справжній баг або виправлення, будь ласка, створіть GitHub issue або надішліть 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) @@ -123,44 +123,44 @@ x-i18n: Що вони роблять: - - `openclaw status`: швидкий знімок стану gateway/агента + базової конфігурації. - - `openclaw models status`: перевіряє auth провайдерів + доступність моделей. - - `openclaw doctor`: перевіряє та виправляє поширені проблеми конфігурації/стану. + - `openclaw status`: швидкий знімок стану gateway/agent + базова config. + - `openclaw models status`: перевіряє auth провайдера + доступність моделей. + - `openclaw doctor`: перевіряє та виправляє поширені проблеми config/state. Інші корисні перевірки CLI: `openclaw status --all`, `openclaw logs --follow`, `openclaw gateway status`, `openclaw health --verbose`. Швидкий цикл налагодження: [Перші 60 секунд, якщо щось зламалося](#перші-60-секунд-якщо-щось-зламалося). - Документація зі встановлення: [Встановлення](/uk/install), [Прапорці інсталятора](/uk/install/installer), [Оновлення](/uk/install/updating). + Документація зі встановлення: [Install](/uk/install), [Прапорці інсталятора](/uk/install/installer), [Оновлення](/uk/install/updating). - Поширені причини пропуску heartbeat: + Поширені причини пропуску Heartbeat: - `quiet-hours`: поза налаштованим вікном active-hours - - `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожній каркас/заголовки - - `no-tasks-due`: активний режим задач `HEARTBEAT.md`, але жоден інтервал задачі ще не настав - - `alerts-disabled`: усю видимість heartbeat вимкнено (`showOk`, `showAlerts` і `useIndicator` вимкнені) + - `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). - Репозиторій рекомендує запуск із сирців і використання онбордингу: + Репозиторій рекомендує запуск із вихідного коду та використання onboarding: ```bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-daemon ``` - Майстер також може автоматично зібрати UI-ресурси. Після онбордингу ви зазвичай запускаєте Gateway на порту **18789**. + Майстер також може автоматично зібрати ресурси UI. Після onboarding зазвичай Gateway запускається на порту **18789**. - Із сирців (для учасників/розробників): + Із вихідного коду (contributors/dev): ```bash git clone https://github.com/openclaw/openclaw.git @@ -175,86 +175,86 @@ x-i18n: - - Майстер відкриває ваш браузер із чистим URL dashboard (без токенів) одразу після онбордингу, а також виводить посилання у підсумку. Тримайте цю вкладку відкритою; якщо вона не запустилася, скопіюйте/вставте надрукований URL на тій самій машині. + + Майстер відкриває браузер із чистою URL-адресою dashboard (без токенів) одразу після onboarding, а також виводить посилання в підсумку. Залиште цю вкладку відкритою; якщо вона не запустилася, скопіюйте й вставте надруковану URL-адресу на тій самій машині. **Localhost (та сама машина):** - Відкрийте `http://127.0.0.1:18789/`. - - Якщо запитується auth через shared secret, вставте налаштований 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`. + - Якщо запитується автентифікація shared secret, вставте налаштований токен або пароль у налаштуваннях Control UI. + - Джерело токена: `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`). + - Джерело пароля: `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). + - Якщо shared secret ще не налаштовано, згенеруйте токен командою `openclaw doctor --generate-gateway-token`. **Не на localhost:** - - **Tailscale Serve** (рекомендовано): залиште bind loopback, запустіть `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` дорівнює `true`, заголовки ідентичності задовольняють auth для Control UI/WebSocket (без вставляння shared secret, за умови довіреного gateway host); HTTP API усе одно потребують auth через shared secret, якщо ви свідомо не використовуєте `none` для private-ingress або HTTP auth довіреного proxy. - Невдалі одночасні спроби Serve auth від того самого клієнта серіалізуються до того, як limiter невдалої auth зафіксує їх, тому друга невдала повторна спроба вже може показати `retry later`. - - **Tailnet bind**: запустіть `openclaw gateway --bind tailnet --token ""` (або налаштуйте auth через password), відкрийте `http://:18789/`, потім вставте відповідний shared secret у налаштування dashboard. - - **Identity-aware reverse 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/`. Auth через shared secret усе ще діє поверх тунелю; вставте налаштований token або password, якщо буде запит. + - **Tailscale Serve** (рекомендовано): залиште прив’язку до loopback, виконайте `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` має значення `true`, заголовки ідентичності задовольняють автентифікацію Control UI/WebSocket (без вставляння shared secret, за умови довіреного хоста gateway); HTTP API усе одно вимагають автентифікацію shared secret, якщо ви навмисно не використовуєте private-ingress `none` або trusted-proxy HTTP auth. + Некоректні одночасні спроби автентифікації Serve від одного клієнта серіалізуються до того, як обмежувач failed-auth їх зафіксує, тому друга невдала повторна спроба вже може показати `retry later`. + - **Прив’язка до tailnet**: виконайте `openclaw gateway --bind tailnet --token ""` (або налаштуйте автентифікацію паролем), відкрийте `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 усе ще застосовується через tunnel; якщо буде запит, вставте налаштований токен або пароль. - Див. [Dashboard](/web/dashboard) і [Web surfaces](/web) щодо режимів bind і деталей auth. + Див. [Dashboard](/web/dashboard) і [Веб-поверхні](/web) для режимів прив’язки та деталей автентифікації. - - Вони керують різними шарами: + + Вони керують різними рівнями: - - `approvals.exec`: пересилає запити на схвалення в chat-призначення - - `channels..execApprovals`: робить цей канал нативним клієнтом схвалення для exec approvals + - `approvals.exec`: пересилає запити на затвердження до chat destinations + - `channels..execApprovals`: робить цей channel нативним approval-клієнтом для exec approvals - Політика exec на host усе ще є справжнім бар’єром схвалення. Конфігурація chat лише керує тим, де - з’являються запити на схвалення і як люди можуть на них відповідати. + Політика host exec все одно залишається справжнім бар’єром затвердження. Конфігурація чату лише визначає, куди + надходять запити на затвердження і як люди можуть на них відповідати. - У більшості сценаріїв вам **не** потрібні обидві: + У більшості налаштувань вам **не** потрібні обидві: - - Якщо chat уже підтримує команди й відповіді, `/approve` у тому ж chat працює через спільний шлях. - - Якщо підтримуваний нативний канал може безпечно визначати approver-ів, OpenClaw тепер автоматично вмикає DM-first нативні approvals, коли `channels..execApprovals.enabled` не встановлено або дорівнює `"auto"`. - - Коли доступні нативні картки/кнопки схвалення, цей нативний UI є основним шляхом; агент має включати ручну команду `/approve`, лише якщо результат інструмента каже, що chat approvals недоступні або ручне схвалення — єдиний шлях. - - Використовуйте `approvals.exec` лише коли запити також треба пересилати в інші chat-и або явні ops-room. - - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише коли ви явно хочете, щоб запити на схвалення поверталися в початкову кімнату/тему. - - Plugin approvals знову окремі: вони за замовчуванням використовують `/approve` у тому ж chat, необов’язкове пересилання `approvals.plugin`, і лише деякі нативні канали додатково зберігають нативну обробку схвалення plugin. + - Якщо chat уже підтримує команди й відповіді, `/approve` у тому самому чаті працює через спільний шлях. + - Якщо підтримуваний нативний channel може безпечно визначити осіб, які затверджують, OpenClaw тепер автоматично вмикає нативні approvals із пріоритетом DM, коли `channels..execApprovals.enabled` не задано або має значення `"auto"`. + - Коли доступні нативні approval cards/buttons, цей нативний UI є основним шляхом; агент має включати ручну команду `/approve`, лише якщо результат інструмента каже, що chat approvals недоступні або ручне затвердження — єдиний шлях. + - Використовуйте `approvals.exec` лише тоді, коли запити також потрібно пересилати до інших чатів або явних ops rooms. + - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише тоді, коли ви явно хочете, щоб запити на затвердження публікувалися назад у вихідну room/topic. + - Затвердження Plugin знову ж окремі: за замовчуванням вони використовують `/approve` у тому самому чаті, необов’язкове пересилання `approvals.plugin`, і лише деякі нативні channels додатково зберігають нативну обробку затверджень Plugin. - Коротко: пересилання — для маршрутизації, конфігурація нативного клієнта — для багатшого UX, специфічного для каналу. + Коротко: пересилання — для маршрутизації, конфігурація нативного клієнта — для більш зручного channel-specific UX. Див. [Exec Approvals](/uk/tools/exec-approvals). - - Потрібен Node **>= 22**. Рекомендовано `pnpm`. Bun **не рекомендований** для Gateway. + + Потрібен Node **>= 22**. Рекомендується `pnpm`. Bun **не рекомендується** для Gateway. - Так. Gateway легкий — документація вказує, що для особистого використання достатньо **512MB-1GB RAM**, **1 ядра** і близько **500MB** - диска, а також зазначає, що **Raspberry Pi 4 може це запускати**. + Так. Gateway легкий — у документації вказано, що для персонального використання достатньо **512MB-1GB RAM**, **1 core** і приблизно **500MB** + дискового простору, а також зазначено, що **Raspberry Pi 4 може його запускати**. - Якщо вам потрібен додатковий запас (журнали, медіа, інші сервіси), **рекомендовано 2GB**, але це + Якщо вам потрібен додатковий запас (логи, медіа, інші сервіси), **рекомендується 2GB**, але це не жорсткий мінімум. - Порада: невеликий Pi/VPS може хостити Gateway, а ви можете під’єднувати **nodes** на своєму ноутбуці/телефоні для + Порада: невеликий Pi/VPS може хостити Gateway, а ви можете під’єднати **nodes** на ноутбуці/телефоні для локального екрана/камери/canvas або виконання команд. Див. [Nodes](/uk/nodes). - - Коротко: працює, але очікуйте шорсткі краї. + + Коротко: це працює, але очікуйте шорсткостей. - - Використовуйте **64-бітну** ОС і тримайте Node >= 22. - - Віддавайте перевагу **hackable (git) install**, щоб бачити журнали й швидко оновлюватися. - - Починайте без каналів/Skills, а потім додавайте їх по одному. - - Якщо натрапите на дивні проблеми з бінарниками, зазвичай це проблема **сумісності ARM**. + - Використовуйте **64-bit** ОС і Node >= 22. + - Віддавайте перевагу **hackable (git) install**, щоб бачити логи й швидко оновлюватися. + - Починайте без channels/skills, а потім додавайте їх по одному. + - Якщо натрапите на дивні проблеми з бінарниками, зазвичай це проблема **ARM compatibility**. - Документація: [Linux](/uk/platforms/linux), [Встановлення](/uk/install). + Документація: [Linux](/uk/platforms/linux), [Install](/uk/install). - - Цей екран залежить від доступності Gateway та успішної auth. TUI також автоматично надсилає + + Цей екран залежить від того, чи доступний і автентифікований Gateway. TUI також автоматично надсилає "Wake up, my friend!" під час першого hatch. Якщо ви бачите цей рядок **без відповіді** - і токени залишаються на 0, агент так і не запустився. + і токени залишаються на 0, agent так і не запустився. 1. Перезапустіть Gateway: @@ -276,50 +276,50 @@ x-i18n: openclaw doctor ``` - Якщо Gateway віддалений, переконайтеся, що tunnel/Tailscale-з’єднання активне і UI - спрямований на правильний Gateway. Див. [Віддалений доступ](/uk/gateway/remote). + Якщо Gateway віддалений, переконайтеся, що tunnel/Tailscale-з’єднання активне і що UI + вказує на правильний Gateway. Див. [Віддалений доступ](/uk/gateway/remote). - - Так. Скопіюйте **каталог стану** і **workspace**, а потім один раз запустіть Doctor. Це - збереже вашого бота «точно таким самим» (memory, історію сесій, auth і стан - каналів), якщо ви скопіюєте **обидва** місця: + + Так. Скопіюйте **каталог state** і **workspace**, а потім один раз запустіть Doctor. Це + збереже вашого бота **точно таким самим** (memory, історія session, auth і + стан channel), якщо ви скопіюєте **обидва** розташування: 1. Встановіть OpenClaw на нову машину. 2. Скопіюйте `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`) зі старої машини. - 3. Скопіюйте свій workspace (типово: `~/.openclaw/workspace`). - 4. Запустіть `openclaw doctor` і перезапустіть сервіс Gateway. + 3. Скопіюйте ваш workspace (типово: `~/.openclaw/workspace`). + 4. Виконайте `openclaw doctor` і перезапустіть сервіс Gateway. - Це збереже конфігурацію, профілі auth, облікові дані WhatsApp, сесії та memory. Якщо ви в - remote mode, пам’ятайте: gateway host володіє сховищем сесій і workspace. + Це зберігає config, профілі auth, облікові дані WhatsApp, sessions і memory. Якщо ви працюєте + у віддаленому режимі, пам’ятайте, що session store і workspace належать хосту gateway. - **Важливо:** якщо ви лише commit/push-ите свій workspace у GitHub, ви створюєте резервну - копію **memory + bootstrap-файлів**, але **не** історії сесій або auth. Вони живуть - у `~/.openclaw/` (наприклад `~/.openclaw/agents//sessions/`). + **Важливо:** якщо ви лише commit/push свій workspace до GitHub, ви створюєте + резервну копію **memory + bootstrap-файлів**, але **не** історії session чи auth. Вони зберігаються + у `~/.openclaw/` (наприклад, `~/.openclaw/agents//sessions/`). - Пов’язане: [Міграція](/uk/install/migrating), [Де що лежить на диску](#де-що-лежить-на-диску), - [Workspace агента](/uk/concepts/agent-workspace), [Doctor](/uk/gateway/doctor), + Пов’язане: [Міграція](/uk/install/migrating), [Де що зберігається на диску](#де-що-зберігається-на-диску), + [Робочий простір agent](/uk/concepts/agent-workspace), [Doctor](/uk/gateway/doctor), [Віддалений режим](/uk/gateway/remote). - Перегляньте changelog у GitHub: + Перегляньте changelog на GitHub: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Найновіші записи — зверху. Якщо верхню секцію позначено як **Unreleased**, наступна датована - секція — це остання випущена версія. Записи згруповано за **Highlights**, **Changes** і - **Fixes** (а також документація/інші секції за потреби). + Найновіші записи — угорі. Якщо верхній розділ позначено як **Unreleased**, наступний датований + розділ — це остання випущена версія. Записи згруповано за **Highlights**, **Changes** і + **Fixes** (плюс розділи з документацією/інші за потреби). - Деякі підключення Comcast/Xfinity помилково блокують `docs.openclaw.ai` через Xfinity + Деякі з’єднання Comcast/Xfinity помилково блокують `docs.openclaw.ai` через Xfinity Advanced Security. Вимкніть її або додайте `docs.openclaw.ai` до allowlist, а потім повторіть спробу. - Будь ласка, допоможіть нам розблокувати це, повідомивши тут: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). + Будь ласка, допоможіть нам розблокувати сайт, повідомивши тут: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). - Якщо ви все ще не можете відкрити сайт, документація дзеркалиться на GitHub: + Якщо ви все ще не можете відкрити сайт, документація дзеркально доступна на GitHub: [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) @@ -330,21 +330,21 @@ x-i18n: - `latest` = stable - `beta` = рання збірка для тестування - Зазвичай stable-реліз спочатку потрапляє в **beta**, а потім окремий крок - просування переміщує цю ж версію в `latest`. Супровідники також можуть за потреби - публікувати одразу в `latest`. Саме тому beta і stable після просування можуть - вказувати на **ту саму версію**. + Зазвичай stable-реліз спочатку потрапляє в **beta**, а потім явний + крок просування переміщує цю саму версію до `latest`. Maintainers також можуть + за потреби публікувати одразу в `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 див. в accordion нижче. - - **Beta** — це npm dist-tag `beta` (може збігатися з `latest` після просування). - **Dev** — це рухома голова `main` (git); коли публікується, використовує npm dist-tag `dev`. + + **Beta** — це npm dist-tag `beta` (після просування може збігатися з `latest`). + **Dev** — це рухома вершина `main` (git); під час публікації використовується npm dist-tag `dev`. Однорядкові команди (macOS/Linux): @@ -359,20 +359,20 @@ x-i18n: Інсталятор для Windows (PowerShell): [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) - Більше деталей: [Канали розробки](/uk/install/development-channels) і [Прапорці інсталятора](/uk/install/installer). + Докладніше: [Канали розробки](/uk/install/development-channels) і [Прапорці інсталятора](/uk/install/installer). - + Є два варіанти: - 1. **Канал dev (git checkout):** + 1. **Dev channel (git checkout):** ```bash openclaw update --channel dev ``` - Це перемикає на гілку `main` і оновлює з сирців. + Це перемикає вас на гілку `main` і оновлює з вихідного коду. 2. **Hackable install (із сайту інсталятора):** @@ -382,7 +382,7 @@ x-i18n: Це дає вам локальний репозиторій, який можна редагувати, а потім оновлювати через git. - Якщо віддаєте перевагу чистому ручному clone, використайте: + Якщо ви віддаєте перевагу чистому ручному clone, використайте: ```bash git clone https://github.com/openclaw/openclaw.git @@ -391,30 +391,30 @@ x-i18n: pnpm build ``` - Документація: [Оновлення](/cli/update), [Канали розробки](/uk/install/development-channels), - [Встановлення](/uk/install). + Документація: [Update](/cli/update), [Канали розробки](/uk/install/development-channels), + [Install](/uk/install). - - Приблизно: + + Приблизний орієнтир: - - **Встановлення:** 2-5 хвилин - - **Онбординг:** 5-15 хвилин залежно від того, скільки каналів/моделей ви налаштовуєте + - **Встановлення:** 2–5 хвилин + - **Onboarding:** 5–15 хвилин залежно від того, скільки channels/models ви налаштовуєте - Якщо зависає, використайте [Інсталятор завис?](#швидкий-старт-і-початкове-налаштування) + Якщо все зависає, див. [Інсталятор завис?](#швидкий-старт-і-початкове-налаштування) і швидкий цикл налагодження в [Я застряг](#швидкий-старт-і-початкове-налаштування). - Повторно запустіть інсталятор із **детальним виводом**: + Повторно запустіть інсталятор із **докладним виводом**: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` - Встановлення beta з verbose: + Установлення beta з докладним виводом: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose @@ -429,7 +429,7 @@ x-i18n: Еквівалент для Windows (PowerShell): ```powershell - # install.ps1 ще не має окремого прапорця -Verbose. + # install.ps1 поки що не має окремого прапорця -Verbose. Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0 @@ -439,38 +439,38 @@ x-i18n: - + Дві поширені проблеми у Windows: **1) помилка npm spawn git / git not found** - - Встановіть **Git for Windows** і переконайтеся, що `git` є у вашому PATH. + - Установіть **Git for Windows** і переконайтеся, що `git` є у вашому PATH. - Закрийте й знову відкрийте PowerShell, а потім повторно запустіть інсталятор. - **2) openclaw is not recognized після встановлення** + **2) після встановлення `openclaw` not recognized** - - Ваш глобальний npm bin-каталог відсутній у PATH. + - Ваш глобальний каталог npm bin відсутній у PATH. - Перевірте шлях: ```powershell npm config get prefix ``` - - Додайте цей каталог до свого user PATH (суфікс `\bin` у Windows не потрібен; на більшості систем це `%AppData%\npm`). - - Закрийте й знову відкрийте PowerShell після оновлення PATH. + - Додайте цей каталог до вашого користувацького PATH (у Windows суфікс `\bin` не потрібен; у більшості систем це `%AppData%\npm`). + - Після оновлення PATH закрийте й знову відкрийте PowerShell. - Якщо вам потрібне найплавніше налаштування у Windows, використовуйте **WSL2** замість нативного Windows. + Якщо ви хочете максимально плавне налаштування у Windows, використовуйте **WSL2** замість нативного Windows. Документація: [Windows](/uk/platforms/windows). - Зазвичай це невідповідність code page консолі в нативних оболонках Windows. + Зазвичай це невідповідність кодової сторінки консолі в нативних оболонках Windows. Симптоми: - - вивід `system.run`/`exec` показує китайську як mojibake - - та сама команда нормально виглядає в іншому профілі термінала + - вивід `system.run`/`exec` показує китайський текст як mojibake + - та сама команда виглядає нормально в іншому профілі термінала Швидкий обхідний шлях у PowerShell: @@ -481,72 +481,72 @@ x-i18n: $OutputEncoding = [System.Text.UTF8Encoding]::new($false) ``` - Потім перезапустіть Gateway і повторіть вашу команду: + Потім перезапустіть Gateway і повторіть команду: ```powershell openclaw gateway restart ``` - Якщо ви все ще відтворюєте це в останньому OpenClaw, відстежуйте/повідомляйте тут: + Якщо це все ще відтворюється в останній версії OpenClaw, відстежуйте/повідомляйте тут: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - Використайте **hackable (git) install**, щоб мати повні сирці та документацію локально, а тоді запитайте - свого бота (або Claude/Codex) _з цієї папки_, щоб він міг прочитати репозиторій і точно відповісти. + Використайте **hackable (git) install**, щоб мати локально повний вихідний код і документацію, а потім запитайте + свого бота (або Claude/Codex) _з цієї папки_, щоб він міг читати репозиторій і точно відповісти. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Більше деталей: [Встановлення](/uk/install) і [Прапорці інсталятора](/uk/install/installer). + Докладніше: [Install](/uk/install) і [Прапорці інсталятора](/uk/install/installer). - - Коротка відповідь: дотримуйтеся інструкції для Linux, а потім запустіть онбординг. + + Коротка відповідь: дотримуйтеся інструкції для Linux, а потім запустіть onboarding. - Швидкий шлях для Linux + встановлення сервісу: [Linux](/uk/platforms/linux). - - Повний покроковий гайд: [Початок роботи](/uk/start/getting-started). + - Повний покроковий посібник: [Початок роботи](/uk/start/getting-started). - Інсталятор + оновлення: [Встановлення й оновлення](/uk/install/updating). - - Підійде будь-який 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). + Посібники: [exe.dev](/uk/install/exe-dev), [Hetzner](/uk/install/hetzner), [Fly.io](/uk/install/fly). + Віддалений доступ: [Gateway remote](/uk/gateway/remote). - - Ми підтримуємо **хаб хостингу** з поширеними провайдерами. Оберіть одного й дотримуйтеся інструкції: + + У нас є **хаб хостингу** з поширеними провайдерами. Виберіть один і дотримуйтеся інструкції: - - [VPS-хостинг](/uk/vps) (усі провайдери в одному місці) + - [VPS hosting](/uk/vps) (усі провайдери в одному місці) - [Fly.io](/uk/install/fly) - [Hetzner](/uk/install/hetzner) - [exe.dev](/uk/install/exe-dev) - Як це працює в хмарі: **Gateway працює на сервері**, а ви отримуєте до нього доступ - зі свого ноутбука/телефона через Control UI (або Tailscale/SSH). Ваші state + workspace - живуть на сервері, тож сприймайте host як джерело істини й робіть його резервні копії. + Як це працює в хмарі: **Gateway працює на сервері**, а ви звертаєтеся до нього + з ноутбука/телефона через Control UI (або Tailscale/SSH). Ваші state + workspace + зберігаються на сервері, тож вважайте хост джерелом істини та робіть його резервні копії. - Ви можете під’єднувати **nodes** (Mac/iOS/Android/headless) до цього хмарного Gateway, щоб отримати - локальний екран/камеру/canvas або запускати команди на своєму ноутбуці, залишаючи - Gateway у хмарі. + Ви можете під’єднувати **nodes** (Mac/iOS/Android/headless) до цього хмарного Gateway, щоб отримувати доступ до + локального екрана/камери/canvas або запускати команди на ноутбуці, водночас + тримаючи Gateway у хмарі. - Хаб: [Платформи](/uk/platforms). Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). - Nodes: [Nodes](/uk/nodes), [CLI для Nodes](/cli/nodes). + Хаб: [Platforms](/uk/platforms). Віддалений доступ: [Gateway remote](/uk/gateway/remote). + Nodes: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes). - Коротко: **можливо, але не рекомендовано**. Процес оновлення може перезапустити - Gateway (що розірве активну сесію), може потребувати чистого git checkout і - може запитувати підтвердження. Безпечніше запускати оновлення з оболонки як оператор. + Коротка відповідь: **можливо, але не рекомендується**. Під час оновлення може перезапуститися + Gateway (що розірве активну session), може знадобитися чистий git checkout, а також + може з’явитися запит на підтвердження. Безпечніше запускати оновлення з оболонки як оператор. Використовуйте CLI: @@ -558,66 +558,66 @@ x-i18n: openclaw update --no-restart ``` - Якщо вам обов’язково треба автоматизувати це через агента: + Якщо автоматизація через agent все ж потрібна: ```bash openclaw update --yes --no-restart openclaw gateway restart ``` - Документація: [Оновлення](/cli/update), [Оновлення](/uk/install/updating). + Документація: [Update](/cli/update), [Оновлення](/uk/install/updating). - + `openclaw onboard` — рекомендований шлях налаштування. У **локальному режимі** він проводить вас через: - - **Налаштування моделі/auth** (OAuth провайдера, API-ключі, Anthropic setup-token, а також локальні варіанти моделей, як-от LM Studio) + - **Налаштування model/auth** (OAuth провайдера, API-ключі, токен налаштування Anthropic, а також варіанти локальних моделей, як-от LM Studio) - Розташування **workspace** + bootstrap-файли - **Налаштування Gateway** (bind/port/auth/tailscale) - - **Канали** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також bundled channel plugins, як-от QQ Bot) - - **Встановлення демона** (LaunchAgent у macOS; systemd user unit у Linux/WSL2) - - **Перевірки справності** та вибір **Skills** + - **Channels** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також bundled channel plugins, як-от QQ Bot) + - **Встановлення демона** (LaunchAgent на macOS; user unit systemd на Linux/WSL2) + - **Перевірки стану** і вибір **Skills** - Також він попереджає, якщо ваша налаштована модель невідома або для неї відсутня auth. + Він також попереджає, якщо налаштована model невідома або для неї відсутня auth. - + Ні. Ви можете запускати OpenClaw з **API-ключами** (Anthropic/OpenAI/інші) або з - **лише локальними моделями**, щоб ваші дані лишалися на вашому пристрої. Підписки (Claude - Pro/Max або OpenAI Codex) — це необов’язкові способи автентифікації в цих провайдерів. + **лише локальними моделями**, щоб ваші дані залишалися на вашому пристрої. Підписки (Claude + Pro/Max або OpenAI Codex) — це необов’язкові способи автентифікації цих провайдерів. Для Anthropic в OpenClaw практичний поділ такий: - - **Anthropic API key**: звичайна оплата Anthropic API - - **Claude CLI / auth підписки Claude в OpenClaw**: співробітники Anthropic - повідомили нам, що таке використання знову дозволено, і OpenClaw розглядає використання `claude -p` + - **API-ключ Anthropic**: звичайна оплата Anthropic API + - **Автентифікація Claude CLI / підпискою Claude в OpenClaw**: співробітники Anthropic + повідомили нам, що таке використання знову дозволене, і OpenClaw розглядає використання `claude -p` як санкціоноване для цієї інтеграції, якщо Anthropic не опублікує нову політику - Для довготривалих gateway host-ів Anthropic API keys усе ще є більш - передбачуваним налаштуванням. OpenAI Codex OAuth явно підтримується для зовнішніх + Для довготривалих хостів gateway API-ключі Anthropic усе ще є + більш передбачуваним варіантом. OAuth OpenAI Codex явно підтримується для зовнішніх інструментів на кшталт OpenClaw. - OpenClaw також підтримує інші хостингові варіанти на кшталт підписки, зокрема + OpenClaw також підтримує інші розміщені варіанти у стилі підписки, зокрема **Qwen Cloud Coding Plan**, **MiniMax Coding Plan** і **Z.AI / GLM Coding Plan**. Документація: [Anthropic](/uk/providers/anthropic), [OpenAI](/uk/providers/openai), [Qwen Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax), [GLM Models](/uk/providers/glm), - [Локальні моделі](/uk/gateway/local-models), [Моделі](/uk/concepts/models). + [Локальні моделі](/uk/gateway/local-models), [Models](/uk/concepts/models). - + Так. Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож OpenClaw вважає auth через підписку Claude та використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. Якщо вам потрібне - найпередбачуваніше серверне налаштування, використовуйте натомість Anthropic API key. + найпередбачуваніше налаштування на стороні сервера, натомість використовуйте API-ключ Anthropic. @@ -628,10 +628,10 @@ x-i18n: повторне використання Claude CLI та використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. - Anthropic setup-token усе ще доступний як підтримуваний шлях токена OpenClaw, але OpenClaw тепер віддає перевагу повторному використанню Claude CLI та `claude -p`, коли це доступно. - Для production або багатокористувацьких навантажень auth через Anthropic API key усе ще є - безпечнішим і передбачуванішим вибором. Якщо вам потрібні інші варіанти hosted auth у стилі підписки - в OpenClaw, див. [OpenAI](/uk/providers/openai), [Qwen / Model + Токен налаштування Anthropic все ще доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI та `claude -p`, коли це можливо. + Для production або multi-user навантажень auth через API-ключ Anthropic усе ще є + безпечнішим і передбачуванішим вибором. Якщо вас цікавлять інші розміщені варіанти + у стилі підписки в OpenClaw, див. [OpenAI](/uk/providers/openai), [Qwen / Model Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax) і [GLM Models](/uk/providers/glm). @@ -640,151 +640,151 @@ x-i18n: Це означає, що вашу **квоту/ліміт швидкості Anthropic** вичерпано для поточного вікна. Якщо ви -використовуєте **Claude CLI**, дочекайтеся скидання вікна або підвищте свій план. Якщо ви -використовуєте **Anthropic API key**, перевірте Anthropic Console -щодо використання/оплати та за потреби підвищте ліміти. +використовуєте **Claude CLI**, дочекайтеся скидання вікна або оновіть свій план. Якщо ви +використовуєте **API-ключ Anthropic**, перевірте Anthropic Console +щодо використання/білінгу та за потреби збільште ліміти. Якщо повідомлення конкретно таке: - `Extra usage is required for long context requests`, запит намагається використати - 1M context beta від Anthropic (`context1m: true`). Це працює лише тоді, коли ваші - облікові дані мають право на billing довгого контексту (billing за API key або - шлях входу Claude в OpenClaw із увімкненим Extra Usage). + `Extra usage is required for long context requests`, запит намагається використовувати + 1M context beta Anthropic (`context1m: true`). Це працює лише тоді, коли ваші + облікові дані мають право на білінг long-context (білінг за API-ключем або + шлях входу Claude в OpenClaw з увімкненим Extra Usage). - Порада: налаштуйте **fallback model**, щоб OpenClaw міг продовжувати відповідати, поки для провайдера діє rate limit. - Див. [Моделі](/cli/models), [OAuth](/uk/concepts/oauth) і + Порада: задайте **резервну model**, щоб 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 має bundled провайдер **Amazon Bedrock (Converse)**. Коли присутні AWS env marker-и, OpenClaw може автоматично виявити каталог потокових/текстових Bedrock і об’єднати його як неявний провайдер `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати запис провайдера вручну. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо ви віддаєте перевагу керованому потоку ключів, сумісний з OpenAI proxy перед Bedrock також залишається коректним варіантом. + Так. OpenClaw має bundled провайдер **Amazon Bedrock (Converse)**. За наявності AWS env markers OpenClaw може автоматично виявити потоковий/текстовий каталог Bedrock і об’єднати його як неявного провайдера `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати запис ручного провайдера. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Провайдери моделей](/uk/providers/models). Якщо ви віддаєте перевагу керованому потоку ключів, OpenAI-compatible 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). Onboarding може запустити OAuth-потік і за потреби встановить модель за замовчуванням `openai-codex/gpt-5.4`. Див. [Провайдери моделей](/uk/concepts/model-providers) і [Onboarding (CLI)](/uk/start/wizard). - + OpenClaw розглядає ці два шляхи окремо: - `openai-codex/gpt-5.4` = OAuth ChatGPT/Codex - - `openai/gpt-5.4` = прямий OpenAI Platform API + - `openai/gpt-5.4` = прямий API OpenAI Platform - В OpenClaw вхід через ChatGPT/Codex прив’язаний до шляху `openai-codex/*`, - а не до прямого шляху `openai/*`. Якщо ви хочете прямий API-шлях в - OpenClaw, встановіть `OPENAI_API_KEY` (або еквівалентну конфігурацію провайдера OpenAI). - Якщо ви хочете вхід через ChatGPT/Codex в OpenClaw, використовуйте `openai-codex/*`. + В OpenClaw вхід ChatGPT/Codex прив’язано до маршруту `openai-codex/*`, + а не до прямого маршруту `openai/*`. Якщо вам потрібен прямий API-шлях у + OpenClaw, задайте `OPENAI_API_KEY` (або еквівалентну config провайдера OpenAI). + Якщо вам потрібен вхід ChatGPT/Codex в OpenClaw, використовуйте `openai-codex/*`. - `openai-codex/*` використовує шлях Codex OAuth, і його доступні квотні вікна + `openai-codex/*` використовує маршрут Codex OAuth, і його доступні вікна квот керуються OpenAI та залежать від плану. На практиці ці ліміти можуть відрізнятися від - досвіду на сайті/в застосунку ChatGPT, навіть коли обидва пов’язані з тим самим обліковим записом. + досвіду використання сайту/застосунку ChatGPT, навіть якщо обидва прив’язані до одного облікового запису. - OpenClaw може показувати поточні видимі вікна використання/квот провайдера у - `openclaw models status`, але він не вигадує і не нормалізує привілеї ChatGPT-web - у прямий API-доступ. Якщо вам потрібен прямий шлях OpenAI Platform - billing/limit, використовуйте `openai/*` з API key. + OpenClaw може показувати поточні видимі вікна використання/квот провайдера в + `openclaw models status`, але не вигадує й не нормалізує + права доступу ChatGPT web до прямого доступу API. Якщо вам потрібен прямий шлях білінгу/лімітів OpenAI Platform, + використовуйте `openai/*` з API-ключем. Так. OpenClaw повністю підтримує **OAuth підписки OpenAI Code (Codex)**. - OpenAI явно дозволяє використання subscription OAuth у зовнішніх інструментах/робочих процесах - на кшталт OpenClaw. Онбординг може запустити потік OAuth за вас. + OpenAI явно дозволяє використання OAuth-підписки в зовнішніх інструментах/робочих процесах + на кшталт OpenClaw. Onboarding може запустити OAuth-потік за вас. - Див. [OAuth](/uk/concepts/oauth), [Провайдери моделей](/uk/concepts/model-providers), і [Онбординг (CLI)](/uk/start/wizard). + Див. [OAuth](/uk/concepts/oauth), [Провайдери моделей](/uk/concepts/model-providers) і [Onboarding (CLI)](/uk/start/wizard). - Gemini CLI використовує **plugin auth flow**, а не client id чи secret у `openclaw.json`. + Gemini CLI використовує **потік auth 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` + 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 host + 5. Якщо запити не працюють, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway - Це зберігає токени OAuth у профілях auth на gateway host. Деталі: [Провайдери моделей](/uk/concepts/model-providers). + Це зберігає OAuth-токени в auth profiles на хості gateway. Докладніше: [Провайдери моделей](/uk/concepts/model-providers). - - Зазвичай ні. OpenClaw потребує великого контексту + сильної безпеки; малі карти обрізають і протікають. Якщо вже мусите, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантизовані моделі підвищують ризик prompt injection — див. [Безпека](/uk/gateway/security). + + Зазвичай ні. OpenClaw потребує великого контексту + сильної безпеки; малі картки обрізають і допускають витоки. Якщо вже потрібно, запускайте **найбільшу** збірку model, яку можете локально (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантовані models підвищують ризик prompt injection — див. [Security](/uk/gateway/security). - - Обирайте endpoint-и, прив’язані до регіону. OpenRouter надає US-hosted варіанти для MiniMax, Kimi та GLM; оберіть US-hosted варіант, щоб тримати дані в регіоні. Ви все одно можете перелічити Anthropic/OpenAI поруч із ними, використовуючи `models.mode: "merge"`, щоб fallback лишалися доступними, водночас поважаючи обраного вами регіонального провайдера. + + Вибирайте endpoints, прив’язані до регіону. OpenRouter надає варіанти з хостингом у США для MiniMax, Kimi та GLM; вибирайте варіант із хостингом у США, щоб зберігати дані в межах регіону. Ви все одно можете вказувати Anthropic/OpenAI поруч із ними, використовуючи `models.mode: "merge"`, щоб резервні варіанти залишалися доступними, водночас дотримуючись вибраного провайдера з прив’язкою до регіону. - - Ні. OpenClaw працює на macOS або Linux (Windows через WSL2). Mac mini — необов’язковий: - дехто купує його як завжди ввімкнений host, але невеликий 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 або під’єднайте macOS node. + 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). + Документація: [BlueBubbles](/uk/channels/bluebubbles), [Nodes](/uk/nodes), [Mac remote mode](/uk/platforms/mac/remote). - - Вам потрібен **якийсь пристрій macOS**, у якому виконано вхід у Messages. Це **не обов’язково** має бути Mac mini — + + Вам потрібен **якийсь пристрій macOS**, на якому виконано вхід у Messages. Це **не обов’язково** має бути Mac mini — підійде будь-який Mac. **Використовуйте [BlueBubbles](/uk/channels/bluebubbles)** (рекомендовано) для iMessage — сервер 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 remote mode](/uk/platforms/mac/remote). - - Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може під’єднатися як + + Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може підключатися як **node** (супутній пристрій). Nodes не запускають Gateway — вони надають додаткові можливості, як-от screen/camera/canvas і `system.run` на цьому пристрої. - Типовий шаблон: + Поширений сценарій: - Gateway на Mac mini (завжди ввімкнений). - - MacBook Pro запускає застосунок macOS або host node й під’єднується до Gateway. - - Використовуйте `openclaw nodes status` / `openclaw nodes list`, щоб це побачити. + - MacBook Pro запускає macOS app або хост node і під’єднується до Gateway. + - Щоб побачити його, використовуйте `openclaw nodes status` / `openclaw nodes list`. - Документація: [Nodes](/uk/nodes), [CLI для Nodes](/cli/nodes). + Документація: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes). - - Bun **не рекомендований**. Ми спостерігаємо баги під час виконання, особливо з WhatsApp і Telegram. + + Bun **не рекомендується**. Ми бачимо помилки runtime, особливо з WhatsApp і Telegram. Для стабільних gateway використовуйте **Node**. - Якщо ви все ж хочете поекспериментувати з Bun, робіть це на непродукційному gateway + Якщо ви все ж хочете поекспериментувати з Bun, робіть це на неproduction gateway без WhatsApp/Telegram. - - `channels.telegram.allowFrom` — це **Telegram user ID людини-відправника** (числовий). Це не username бота. + + `channels.telegram.allowFrom` — це **Telegram user ID людини-відправника** (числовий). Це не ім’я користувача бота. - Онбординг приймає ввід `@username` і перетворює його на числовий ID, але авторизація OpenClaw використовує лише числові ID. + Onboarding приймає введення `@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`. @@ -792,12 +792,12 @@ x-i18n: - - Так, через **маршрутизацію мультиагентності**. Прив’яжіть **DM** WhatsApp кожного відправника (peer `kind: "direct"`, sender E.164 на кшталт `+15551234567`) до різного `agentId`, щоб кожна людина мала власний workspace і сховище сесій. Відповіді все одно надходитимуть з **того самого облікового запису WhatsApp**, а контроль доступу до DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для всього облікового запису WhatsApp. Див. [Маршрутизація мультиагентності](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp). + + Так, через **маршрутизацію 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). - - Так. Використовуйте маршрутизацію мультиагентності: надайте кожному агенту власну модель за замовчуванням, а потім прив’яжіть вхідні маршрути (обліковий запис провайдера або конкретні peer-и) до кожного агента. Приклад конфігурації наведено в [Маршрутизація мультиагентності](/uk/concepts/multi-agent). Див. також [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration). + + Так. Використовуйте маршрутизацію multi-agent: призначте кожному agent власну model за замовчуванням, а потім прив’яжіть вхідні маршрути (обліковий запис провайдера або конкретні peers) до кожного agent. Приклад config є в [Маршрутизація Multi-Agent](/uk/concepts/multi-agent). Див. також [Models](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration). @@ -810,15 +810,15 @@ x-i18n: brew install ``` - Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH сервісу містить `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб інструменти, встановлені через `brew`, знаходилися в non-login shell. - Останні збірки також додають поширені 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`, якщо вони встановлені. + Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH сервісу містить `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб інструменти, встановлені через `brew`, визначалися в оболонках без входу. + Останні збірки також додають попереду поширені каталоги 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`, якщо їх задано. - - **Hackable (git) install:** повний checkout сирців, редагований, найкраще для учасників. - Ви збираєте все локально і можете патчити код/документацію. - - **npm install:** глобальне встановлення CLI, без репозиторію, найкраще для «просто запустити». + - **Hackable (git) install:** повний checkout вихідного коду, можна редагувати, найкраще для contributors. + Ви локально запускаєте збірки й можете вносити зміни в код/документацію. + - **npm install:** глобальне встановлення CLI, без репозиторію, найкраще для сценарію "просто запустити". Оновлення надходять із npm dist-tags. Документація: [Початок роботи](/uk/start/getting-started), [Оновлення](/uk/install/updating). @@ -826,8 +826,8 @@ x-i18n: - Так. Встановіть інший варіант, а потім запустіть Doctor, щоб gateway service вказував на нову entrypoint. - Це **не видаляє ваші дані** — змінюється лише встановлений код OpenClaw. Ваші state + Так. Установіть інший варіант, а потім запустіть Doctor, щоб сервіс gateway вказував на нову точку входу. + Це **не видаляє ваші дані** — змінюється лише встановлений код OpenClaw. Ваш state (`~/.openclaw`) і workspace (`~/.openclaw/workspace`) залишаються недоторканими. З npm на git: @@ -849,67 +849,67 @@ x-i18n: openclaw gateway restart ``` - Doctor виявляє невідповідність entrypoint сервісу gateway і пропонує переписати конфігурацію сервісу так, щоб вона відповідала поточному встановленню (для автоматизації використовуйте `--repair`). + Doctor виявляє невідповідність точки входу сервісу gateway і пропонує переписати config сервісу відповідно до поточного встановлення (використовуйте `--repair` в автоматизації). - Поради щодо резервного копіювання: див. [Стратегія резервного копіювання](#де-що-лежить-на-диску). + Поради щодо резервного копіювання: див. [Стратегія резервного копіювання](#де-що-зберігається-на-диску). - - Коротко: **якщо вам потрібна надійність 24/7, використовуйте VPS**. Якщо вам потрібен + + Коротка відповідь: **якщо вам потрібна надійність 24/7, використовуйте VPS**. Якщо вам потрібен найменший тертя і вас влаштовують сон/перезапуски, запускайте локально. **Ноутбук (локальний Gateway)** - - **Плюси:** без витрат на сервер, прямий доступ до локальних файлів, видиме вікно браузера. - - **Мінуси:** сон/обриви мережі = розриви з’єднання, оновлення ОС/перезавантаження переривають роботу, машина має не засинати. + - **Переваги:** без витрат на сервер, прямий доступ до локальних файлів, видиме вікно браузера. + - **Недоліки:** сон/обриви мережі = роз’єднання, оновлення/перезавантаження ОС переривають роботу, машина має залишатися активною. **VPS / хмара** - - **Плюси:** завжди ввімкнений, стабільна мережа, без проблем зі сном ноутбука, простіше тримати в роботі. - - **Мінуси:** часто headless (використовуйте screenshot-и), доступ до файлів лише віддалений, для оновлень потрібен SSH. + - **Переваги:** завжди ввімкнений, стабільна мережа, немає проблем через сон ноутбука, легше підтримувати безперервну роботу. + - **Недоліки:** часто працює без GUI (використовуйте знімки екрана), доступ лише до віддалених файлів, для оновлень потрібен SSH. - **Примітка, специфічна для OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord чудово працюють із VPS. Єдиний справжній компроміс — **headless browser** проти видимого вікна. Див. [Browser](/uk/tools/browser). + **Примітка щодо OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord чудово працюють із VPS. Єдиний реальний компроміс — **headless browser** проти видимого вікна. Див. [Browser](/uk/tools/browser). - **Рекомендований варіант за замовчуванням:** VPS, якщо у вас раніше були від’єднання gateway. Локальний запуск чудовий, коли ви активно користуєтеся Mac і хочете локальний доступ до файлів або автоматизацію UI з видимим браузером. + **Рекомендований варіант за замовчуванням:** VPS, якщо у вас раніше були відключення gateway. Локальний запуск чудово підходить, коли ви активно користуєтеся Mac і хочете мати доступ до локальних файлів або автоматизації UI з видимим браузером. - - Не обов’язково, але **рекомендовано для надійності та ізоляції**. + + Це не обов’язково, але **рекомендується для надійності та ізоляції**. - - **Виділений host (VPS/Mac mini/Pi):** завжди ввімкнений, менше переривань через сон/перезавантаження, чистіші дозволи, легше підтримувати в роботі. - - **Спільний ноутбук/desktop:** цілком підходить для тестування й активного використання, але очікуйте пауз, коли машина засинає або оновлюється. + - **Виділений хост (VPS/Mac mini/Pi):** завжди ввімкнений, менше переривань через сон/перезавантаження, чистіші дозволи, легше підтримувати безперервну роботу. + - **Спільний ноутбук/настільний ПК:** цілком нормально для тестування й активного використання, але очікуйте пауз, коли машина засинає або оновлюється. - Якщо хочете мати найкраще з обох світів, тримайте Gateway на виділеному host і під’єднуйте свій ноутбук як **node** для локальних screen/camera/exec-інструментів. Див. [Nodes](/uk/nodes). - Для вказівок з безпеки див. [Безпека](/uk/gateway/security). + Якщо ви хочете отримати найкраще з обох світів, тримайте Gateway на виділеному хості, а свій ноутбук під’єднайте як **node** для локальних інструментів screen/camera/exec. Див. [Nodes](/uk/nodes). + Рекомендації з безпеки див. у [Security](/uk/gateway/security). - - OpenClaw легкий. Для базового Gateway + одного chat-каналу: + + OpenClaw легкий. Для базового Gateway + одного chat channel: - **Абсолютний мінімум:** 1 vCPU, 1GB RAM, ~500MB диска. - - **Рекомендовано:** 1-2 vCPU, 2GB RAM або більше для запасу (журнали, медіа, кілька каналів). Інструменти Node і автоматизація браузера можуть бути вимогливими до ресурсів. + - **Рекомендовано:** 1–2 vCPU, 2GB RAM або більше із запасом (логи, медіа, кілька channels). Інструменти Node та автоматизація браузера можуть вимагати багато ресурсів. - ОС: використовуйте **Ubuntu LTS** (або будь-який сучасний Debian/Ubuntu). Саме цей шлях встановлення для Linux протестовано найкраще. + ОС: використовуйте **Ubuntu LTS** (або будь-який сучасний Debian/Ubuntu). Шлях встановлення для Linux найкраще протестовано саме там. - Документація: [Linux](/uk/platforms/linux), [VPS-хостинг](/uk/vps). + Документація: [Linux](/uk/platforms/linux), [VPS hosting](/uk/vps). - - Так. Ставтеся до VM так само, як до VPS: вона має бути завжди ввімкненою, доступною та мати достатньо - RAM для Gateway і будь-яких каналів, які ви ввімкнете. + + Так. Ставтеся до VM так само, як до VPS: вона має бути завжди ввімкнена, доступна та мати достатньо + RAM для Gateway і всіх channels, які ви вмикаєте. Базові рекомендації: - **Абсолютний мінімум:** 1 vCPU, 1GB RAM. - - **Рекомендовано:** 2GB RAM або більше, якщо ви запускаєте кілька каналів, автоматизацію браузера чи media-інструменти. + - **Рекомендовано:** 2GB RAM або більше, якщо ви використовуєте кілька channels, автоматизацію браузера чи медіаінструменти. - **ОС:** Ubuntu LTS або інший сучасний Debian/Ubuntu. - Якщо ви на Windows, **WSL2 — це найпростіше налаштування в стилі VM** і воно має найкращу - сумісність інструментів. Див. [Windows](/uk/platforms/windows), [VPS-хостинг](/uk/vps). + Якщо ви працюєте у Windows, **WSL2 — найпростіше налаштування у стилі VM** і має найкращу + сумісність з інструментами. Див. [Windows](/uk/platforms/windows), [VPS hosting](/uk/vps). Якщо ви запускаєте macOS у VM, див. [macOS VM](/uk/install/macos-vm). @@ -919,153 +919,153 @@ x-i18n: - OpenClaw — це персональний AI-помічник, якого ви запускаєте на власних пристроях. Він відповідає на поверхнях повідомлень, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat, а також bundled channel plugins, як-от QQ Bot) і також може працювати з голосом + live Canvas на підтримуваних платформах. **Gateway** — це завжди ввімкнена control plane; помічник і є продуктом. + OpenClaw — це персональний AI-помічник, який ви запускаєте на власних пристроях. Він відповідає в месенджерах, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat, а також bundled channel plugins, як-от QQ Bot) і також може працювати з голосом + live Canvas на підтримуваних платформах. **Gateway** — це постійно активна control plane; помічник і є продуктом. - OpenClaw — це не «просто обгортка над Claude». Це **локальна control plane**, яка дозволяє вам запускати - потужного помічника на **вашому власному обладнанні**, доступного через chat-застосунки, якими ви вже користуєтеся, із - сесіями зі станом, memory та інструментами — без передачі контролю над вашими робочими процесами hosted - SaaS. + OpenClaw — це не "просто обгортка для Claude". Це **локально-орієнтована control plane**, яка дає змогу запускати + потужного помічника на **вашому власному обладнанні**, доступного з чат-застосунків, якими ви вже користуєтеся, з + sessions зі станом, memory та інструментами — без передачі контролю над вашими процесами + розміщеному SaaS. Основні переваги: - - **Ваші пристрої, ваші дані:** запускайте Gateway там, де хочете (Mac, Linux, VPS) і тримайте - workspace + історію сесій локально. - - **Справжні канали, а не web-пісочниця:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage тощо, + - **Ваші пристрої, ваші дані:** запускайте Gateway де завгодно (Mac, Linux, VPS) і зберігайте + workspace + історію session локально. + - **Реальні channels, а не веб-пісочниця:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage тощо, а також мобільний голос і Canvas на підтримуваних платформах. - - **Незалежність від моделі:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо, з маршрутизацією - по агенту і failover. - - **Лише локальний варіант:** запускайте локальні моделі, щоб **усі дані могли залишатися на вашому пристрої**, якщо хочете. - - **Маршрутизація мультиагентності:** окремі агенти для кожного каналу, облікового запису або задачі, кожен із власним - workspace і значеннями за замовчуванням. - - **Open source і hackable:** перевіряйте, розширюйте і self-host-те без прив’язки до постачальника. + - **Незалежність від model:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо, з маршрутизацією + і резервним перемиканням на рівні agent. + - **Лише локальний варіант:** запускайте локальні models, щоб **усі дані могли залишатися на вашому пристрої**, якщо ви цього хочете. + - **Маршрутизація multi-agent:** окремі agents для channel, облікового запису чи завдання, кожен зі своїм + workspace і параметрами за замовчуванням. + - **Відкритий код і можливість змінювати:** перевіряйте, розширюйте та розміщуйте самостійно без прив’язки до постачальника. - Документація: [Gateway](/uk/gateway), [Канали](/uk/channels), [Мультиагентність](/uk/concepts/multi-agent), + Документація: [Gateway](/uk/gateway), [Channels](/uk/channels), [Multi-agent](/uk/concepts/multi-agent), [Memory](/uk/concepts/memory). - - Гарні перші проєкти: + + Хороші перші проєкти: - - Створити сайт (WordPress, Shopify або простий статичний сайт). + - Створити вебсайт (WordPress, Shopify або простий статичний сайт). - Прототипувати мобільний застосунок (структура, екрани, план API). - - Упорядкувати файли й папки (очищення, іменування, теги). - - Під’єднати Gmail і автоматизувати підсумки або follow up. + - Упорядкувати файли та папки (очищення, іменування, тегування). + - Підключити Gmail і автоматизувати зведення або подальші дії. - Він може виконувати великі задачі, але найкраще працює, коли ви ділите їх на фази й - використовуєте sub-agents для паралельної роботи. + Він може виконувати великі завдання, але найкраще працює, коли ви ділите їх на фази та + використовуєте sub agents для паралельної роботи. - - Щоденні виграші зазвичай виглядають так: + + Повсякденна користь зазвичай виглядає так: - - **Персональні брифінги:** підсумки пошти, календаря та новин, які вам важливі. - - **Дослідження й чернетки:** швидкі дослідження, підсумки та перші чернетки для листів або документів. - - **Нагадування й follow up:** nudges і чеклисти, керовані cron або heartbeat. - - **Автоматизація браузера:** заповнення форм, збір даних і повторення web-завдань. - - **Координація між пристроями:** надішліть задачу з телефона, дозвольте Gateway виконати її на сервері й отримайте результат назад у chat. + - **Персональні зведення:** підсумки пошти, календаря та новин, які вас цікавлять. + - **Дослідження та чернетки:** швидкий пошук інформації, підсумки та перші чернетки листів або документів. + - **Нагадування та подальші дії:** поштовхи та чеклісти на основі Cron або Heartbeat. + - **Автоматизація браузера:** заповнення форм, збір даних і повторення веб-завдань. + - **Координація між пристроями:** надішліть завдання з телефона, дайте Gateway виконати його на сервері й отримайте результат назад у чаті. - - Так — для **дослідження, кваліфікації та підготовки чернеток**. Він може сканувати сайти, створювати shortlists, - підсумовувати потенційних клієнтів і писати чернетки для outreach або реклами. + + Так — для **дослідження, кваліфікації та підготовки чернеток**. Він може сканувати сайти, створювати короткі списки, + підсумовувати інформацію про потенційних клієнтів і писати чернетки аутричу або рекламних текстів. - Для **outreach або рекламних кампаній** залишайте людину в контурі. Уникайте спаму, дотримуйтеся місцевих законів і - політик платформ та перевіряйте все перед відправленням. Найбезпечніший підхід — нехай - OpenClaw створює чернетку, а ви схвалюєте. + Для **аутричу чи запуску реклами** залишайте людину в циклі. Уникайте спаму, дотримуйтеся місцевих законів і + правил платформи та перевіряйте все перед надсиланням. Найбезпечніший підхід — нехай + OpenClaw готує чернетку, а ви її затверджуєте. - Документація: [Безпека](/uk/gateway/security). + Документація: [Security](/uk/gateway/security). - + OpenClaw — це **персональний помічник** і шар координації, а не заміна IDE. Використовуйте - Claude Code або Codex для найшвидшого прямого циклу програмування всередині репозиторію. Використовуйте OpenClaw, коли вам - потрібні стійка memory, міжпристроєвий доступ і оркестрація інструментів. + Claude Code або Codex для найшвидшого прямого циклу кодування всередині репозиторію. Використовуйте OpenClaw, коли вам + потрібні довготривала memory, доступ із різних пристроїв та оркестрація інструментів. Переваги: - - **Постійна memory + workspace** між сесіями - - **Доступ із багатьох платформ** (WhatsApp, Telegram, TUI, WebChat) - - **Оркестрація інструментів** (browser, файли, планування, hooks) - - **Завжди ввімкнений Gateway** (запускайте на VPS, взаємодійте звідусіль) - - **Nodes** для локального browser/screen/camera/exec + - **Постійна memory + workspace** між sessions + - **Доступ із різних платформ** (WhatsApp, Telegram, TUI, WebChat) + - **Оркестрація інструментів** (browser, files, scheduling, hooks) + - **Завжди ввімкнений Gateway** (працює на VPS, взаємодія звідусіль) + - **Nodes** для локальних browser/screen/camera/exec Вітрина: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) -## Skills та автоматизація +## Skills і автоматизація - - Використовуйте керовані override-и замість редагування копії в репозиторії. Помістіть свої зміни в `~/.openclaw/skills//SKILL.md` (або додайте папку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет такий: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`, тож керовані override-и все одно мають перевагу над bundled Skills без змін у git. Якщо вам потрібно встановити skill глобально, але зробити її видимою лише для деяких агентів, тримайте спільну копію в `~/.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` → bundled → `skills.load.extraDirs`, тож керовані override все одно мають вищий пріоритет за bundled skills без змін у git. Якщо вам потрібно, щоб skill було встановлено глобально, але видно лише деяким agents, зберігайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` та `agents.list[].skills`. Лише зміни, варті upstream, мають жити в репозиторії та надсилатися як PR. - - Так. Додайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Типовий пріоритет: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` за замовчуванням встановлює в `./skills`, який OpenClaw розглядає як `/skills` у наступній сесії. Якщо skill має бути видимою лише певним агентам, поєднайте це з `agents.defaults.skills` або `agents.list[].skills`. + + Так. Додавайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Пріоритет за замовчуванням: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` за замовчуванням встановлює в `./skills`, що OpenClaw трактує як `/skills` під час наступної session. Якщо skill має бути видимий лише певним agents, поєднайте це з `agents.defaults.skills` або `agents.list[].skills`. - - Наразі підтримуються такі шаблони: + + На сьогодні підтримуються такі шаблони: - - **Cron jobs**: ізольовані задачі можуть задавати override `model` для кожної задачі. - - **Sub-agents**: маршрутизуйте задачі до окремих агентів із різними моделями за замовчуванням. - - **Перемикання на вимогу**: використовуйте `/model`, щоб будь-коли змінити модель поточної сесії. + - **Cron jobs**: ізольовані завдання можуть задавати override `model` для кожного завдання. + - **Sub-agents**: спрямовуйте завдання до окремих agents з різними models за замовчуванням. + - **Перемикання на вимогу**: використовуйте `/model`, щоб у будь-який момент змінити model поточної session. - Див. [Cron jobs](/uk/automation/cron-jobs), [Маршрутизація мультиагентності](/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 працюють у власній сесії, - повертають підсумок і зберігають чутливість вашого основного chat. + + Використовуйте **sub-agents** для довгих або паралельних завдань. Sub-agents працюють у власній session, + повертають підсумок і не дають вашому основному чату зависати. - Попросіть бота «створити sub-agent для цієї задачі» або використайте `/subagents`. - Використовуйте `/status` у chat, щоб бачити, що Gateway робить прямо зараз (і чи він зайнятий). + Попросіть свого бота "spawn a sub-agent for this task" або використайте `/subagents`. + Використовуйте `/status` у чаті, щоб бачити, що Gateway робить просто зараз (і чи він зайнятий). - Порада щодо токенів: і довгі задачі, і sub-agents споживають токени. Якщо вас хвилює вартість, задайте - дешевшу модель для sub-agents через `agents.defaults.subagents.model`. + Порада щодо токенів: і довгі завдання, і sub-agents споживають токени. Якщо вартість важлива, задайте + дешевшу model для sub-agents через `agents.defaults.subagents.model`. - Документація: [Sub-agents](/uk/tools/subagents), [Фонові задачі](/uk/automation/tasks). + Документація: [Sub-agents](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks). - - Використовуйте прив’язки thread. Ви можете прив’язати Discord thread до subagent-а або цілі session, щоб подальші повідомлення в цьому thread залишалися на прив’язаній сесії. + + Використовуйте прив’язки thread. Ви можете прив’язати Discord thread до subagent або цілі session, щоб подальші повідомлення в цьому thread залишалися в межах цієї прив’язаної session. - Базовий потік: + Базовий процес: - - Створіть через `sessions_spawn` з `thread: true` (і, за бажання, `mode: "session"` для постійних follow-up). + - Створіть через `sessions_spawn` з `thread: true` (і, за бажанням, `mode: "session"` для постійшого продовження). - Або прив’яжіть вручну через `/focus `. - - Використовуйте `/agents`, щоб перевірити стан прив’язки. - - Використовуйте `/session idle ` і `/session max-age `, щоб керувати авто-втратою фокусу. + - Використовуйте `/agents`, щоб переглянути стан прив’язки. + - Використовуйте `/session idle ` і `/session max-age `, щоб керувати автоматичним скасуванням фокуса. - Використовуйте `/unfocus`, щоб від’єднати thread. - Потрібна конфігурація: + Потрібна config: - - Глобальні значення за замовчуванням: `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`. + - Глобальні параметри за замовчуванням: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. + - Override для Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. + - Автоматична прив’язка під час створення: задайте `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). - - Спочатку перевірте розв’язаний маршрут requester-а: + + Спочатку перевірте визначений маршрут запитувача: - - Доставка completion-mode subagent віддає перевагу будь-якому прив’язаному thread або маршруту conversation, якщо він існує. - - Якщо origin завершення містить лише канал, OpenClaw повертається до збереженого маршруту сесії requester-а (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все ще могла спрацювати. - - Якщо немає ні прив’язаного маршруту, ні придатного збереженого маршруту, пряма доставка може не вдатися, і результат повернеться до queued session delivery замість негайної публікації в chat. - - Недійсні або застарілі цілі все ще можуть примусити fallback до queue або остаточну помилку доставки. - - Якщо остання видима відповідь assistant у дочірньому процесі — це точний мовчазний токен `NO_REPLY` / `no_reply` або рівно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує announce замість публікації застарілого попереднього прогресу. - - Якщо дочірній процес завершився за timeout після лише викликів інструментів, announce може згорнути це до короткого підсумку часткового прогресу замість відтворення сирого виводу інструментів. + - Доставка subagent у режимі completion віддає перевагу будь-якому прив’язаному thread або маршруту conversation, якщо такий існує. + - Якщо джерело completion містить лише channel, OpenClaw використовує запасний маршрут із збереженого маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все ще могла спрацювати. + - Якщо немає ні прив’язаного маршруту, ні придатного збереженого маршруту, пряма доставка може завершитися невдачею, і результат замість негайної публікації в чаті перейде до доставки через queued session. + - Некоректні або застарілі цілі все одно можуть примусово спричинити запасний перехід до queue або остаточну невдачу доставки. + - Якщо остання видима відповідь assistant у дочірньому процесі — це точний тихий токен `NO_REPLY` / `no_reply` або точно `ANNOUNCE_SKIP`, OpenClaw навмисно приглушує оголошення замість публікації застарілого попереднього прогресу. + - Якщо дочірній процес завершився за тайм-аутом після одних лише викликів інструментів, оголошення може згорнути це в короткий підсумок часткового прогресу замість відтворення сирого виводу інструментів. Налагодження: @@ -1073,19 +1073,19 @@ x-i18n: openclaw tasks show ``` - Документація: [Sub-agents](/uk/tools/subagents), [Фонові задачі](/uk/automation/tasks), [Інструмент Session](/uk/concepts/session-tool). + Документація: [Sub-agents](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks), [Session Tools](/uk/concepts/session-tool). Cron виконується всередині процесу Gateway. Якщо Gateway не працює безперервно, - заплановані задачі не виконуватимуться. + заплановані завдання не запускатимуться. - Чеклист: + Чекліст: - - Підтвердьте, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не встановлено. + - Переконайтеся, що Cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не задано. - Перевірте, що Gateway працює 24/7 (без сну/перезапусків). - - Перевірте налаштування timezone для задачі (`--tz` проти timezone host). + - Перевірте налаштування часового поясу для завдання (`--tz` порівняно з часовим поясом хоста). Налагодження: @@ -1094,21 +1094,21 @@ x-i18n: openclaw cron runs --id --limit 50 ``` - Документація: [Cron jobs](/uk/automation/cron-jobs), [Автоматизація й задачі](/uk/automation). + Документація: [Cron jobs](/uk/automation/cron-jobs), [Автоматизація та завдання](/uk/automation). - + Спочатку перевірте режим доставки: - `--no-deliver` / `delivery.mode: "none"` означає, що зовнішнє повідомлення не очікується. - - Відсутня або недійсна announce-ціль (`channel` / `to`) означає, що runner пропустив outbound delivery. - - Помилки auth каналу (`unauthorized`, `Forbidden`) означають, що runner спробував доставити, але облікові дані це заблокували. - - Мовчазний ізольований результат (`NO_REPLY` / `no_reply` тільки) вважається навмисно недоставним, тому runner також пригнічує queued fallback delivery. + - Відсутня або некоректна ціль оголошення (`channel` / `to`) означає, що runner пропустив вихідну доставку. + - Збої auth channel (`unauthorized`, `Forbidden`) означають, що runner спробував доставити, але облікові дані це заблокували. + - Тихий ізольований результат (`NO_REPLY` / `no_reply` only) вважається навмисно недоставлюваним, тож runner також приглушує запасну queued delivery. - Для ізольованих cron job-ів runner володіє фінальною доставкою. Очікується, - що агент поверне текстовий підсумок, який runner зможе надіслати. `--no-deliver` зберігає - цей результат внутрішнім; це не дозволяє агенту напряму надсилати через + Для ізольованих Cron jobs фінальною доставкою керує runner. Від agent очікується + повернення текстового підсумку для надсилання runner. + `--no-deliver` зберігає цей результат внутрішнім; він не дозволяє agent натомість надсилати напряму через message tool. Налагодження: @@ -1118,27 +1118,27 @@ x-i18n: openclaw tasks show ``` - Документація: [Cron jobs](/uk/automation/cron-jobs), [Фонові задачі](/uk/automation/tasks). + Документація: [Cron jobs](/uk/automation/cron-jobs), [Фонові завдання](/uk/automation/tasks). - - Зазвичай це шлях живого перемикання моделі, а не дублювання розкладу. + + Зазвичай це шлях live-перемикання model, а не дубльоване планування. - Ізольований cron може зберегти runtime handoff моделі й повторити спробу, коли активний - запуск викидає `LiveSessionModelSwitchError`. Повторна спроба зберігає перемкненого - провайдера/модель, і якщо перемикання несло новий override профілю auth, cron - також зберігає його перед повтором. + Ізольований Cron може зберегти передачу runtime model і повторити запуск, коли активний + процес викидає `LiveSessionModelSwitchError`. Повторна спроба зберігає перемкнені + provider/model, а якщо перемикання також включало новий override профілю auth, Cron + теж зберігає його перед повтором. Пов’язані правила вибору: - - Override моделі Gmail hook має найвищий пріоритет, коли це застосовно. - - Потім `model` для задачі. - - Потім будь-який збережений override моделі cron-session. - - Потім звичайний вибір моделі агента/за замовчуванням. + - Спочатку має пріоритет override model Gmail hook, якщо застосовно. + - Потім `model` для конкретного завдання. + - Потім будь-який збережений override model cron-session. + - Потім звичайний вибір agent/default model. - Цикл повторів обмежений. Після початкової спроби плюс 2 повтори перемикання - cron переривається замість нескінченного циклу. + Цикл повторних спроб обмежений. Після початкової спроби плюс 2 повтори через перемикання + Cron перериває виконання замість нескінченного циклу. Налагодження: @@ -1151,9 +1151,9 @@ x-i18n: - - Використовуйте нативні команди `openclaw skills` або покладіть Skills у свій workspace. UI Skills для macOS недоступний на Linux. - Переглянути Skills можна на [https://clawhub.ai](https://clawhub.ai). + + Використовуйте нативні команди `openclaw skills` або розміщуйте skills у своєму workspace. UI Skills для macOS недоступний на Linux. + Переглядати skills можна на [https://clawhub.ai](https://clawhub.ai). ```bash openclaw skills search "calendar" @@ -1168,37 +1168,37 @@ x-i18n: Нативний `openclaw skills install` записує в каталог `skills/` активного workspace. Встановлюйте окремий CLI `clawhub`, лише якщо хочете публікувати або - синхронізувати власні Skills. Для спільних встановлень між агентами покладіть skill у + синхронізувати власні skills. Для спільних установлень між agents розміщуйте skill у `~/.openclaw/skills` і використовуйте `agents.defaults.skills` або - `agents.list[].skills`, якщо хочете звузити, які агенти можуть її бачити. + `agents.list[].skills`, якщо хочете обмежити, які agents можуть його бачити. - - Так. Використовуйте scheduler Gateway: + + Так. Використовуйте планувальник Gateway: - - **Cron jobs** для запланованих або повторюваних задач (зберігаються між перезапусками). - - **Heartbeat** для періодичних перевірок «головної сесії». - - **Ізольовані jobs** для автономних агентів, які публікують підсумки або доставляють повідомлення в chat-и. + - **Cron jobs** для запланованих або повторюваних завдань (зберігаються після перезапусків). + - **Heartbeat** для періодичних перевірок "main session". + - **Ізольовані jobs** для автономних agents, які публікують підсумки або доставляють їх у чати. - Документація: [Cron jobs](/uk/automation/cron-jobs), [Автоматизація й задачі](/uk/automation), + Документація: [Cron jobs](/uk/automation/cron-jobs), [Автоматизація та завдання](/uk/automation), [Heartbeat](/uk/gateway/heartbeat). - - Не напряму. macOS Skills обмежуються через `metadata.openclaw.os` плюс потрібні бінарники, і Skills з’являються в system prompt, лише якщо вони придатні на **gateway host**. У Linux Skills тільки для `darwin` (як-от `apple-notes`, `apple-reminders`, `things-mac`) не завантажаться, якщо ви не перевизначите gating. + + Не напряму. Навички macOS обмежуються через `metadata.openclaw.os` плюс необхідні бінарники, а навички з’являються в системному prompt лише тоді, коли вони придатні на **хості Gateway**. На Linux навички лише для `darwin` (як-от `apple-notes`, `apple-reminders`, `things-mac`) не завантажаться, якщо ви не перевизначите це обмеження. - У вас є три підтримувані шаблони: + У вас є три підтримувані варіанти: - **Варіант A — запускати Gateway на Mac (найпростіше).** - Запускайте Gateway там, де існують бінарники macOS, а тоді під’єднуйтеся з Linux у [віддаленому режимі](#gateway-порти-вже-запущені-і-віддалений-режим) або через Tailscale. Skills завантажаться нормально, бо gateway host — це macOS. + **Варіант A — запустити Gateway на Mac (найпростіше).** + Запустіть Gateway там, де існують бінарники macOS, а потім підключайтеся з Linux у [віддаленому режимі](#gateway-порти-вже-запущені-та-віддалений-режим) або через Tailscale. Навички завантажаться звичайним чином, тому що хост Gateway — це macOS. - **Варіант B — використовувати macOS node (без SSH).** - Запускайте Gateway на Linux, під’єднайте macOS node (menubar app) і встановіть **Node Run Commands** на "Always Ask" або "Always Allow" на Mac. OpenClaw може вважати Skills лише для macOS придатними, коли потрібні бінарники існують на node. Агент запускає ці Skills через інструмент `nodes`. Якщо ви виберете "Always Ask", схвалення "Always Allow" у prompt додає цю команду до allowlist. + **Варіант B — використати macOS node (без SSH).** + Запустіть Gateway на Linux, під’єднайте macOS node (menubar app) і встановіть **Node Run Commands** у значення "Always Ask" або "Always Allow" на Mac. OpenClaw може вважати навички лише для macOS придатними, коли потрібні бінарники існують на node. Agent виконує ці навички через інструмент `nodes`. Якщо ви виберете "Always Ask", підтвердження "Always Allow" у prompt додасть цю команду до allowlist. - **Варіант C — проксувати бінарники macOS через SSH (просунуто).** - Тримайте Gateway на Linux, але зробіть так, щоб потрібні CLI-бінарники резолвилися в SSH-обгортки, які виконуються на Mac. Потім override-те 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 host (наприклад `~/bin/memo`). - 3. Override-те metadata skill, щоб дозволити Linux: + 2. Додайте обгортку в `PATH` на хості Linux (наприклад, `~/bin/memo`). + 3. Перевизначте metadata skill (workspace або `~/.openclaw/skills`), щоб дозволити Linux: ```markdown --- @@ -1219,38 +1219,38 @@ x-i18n: --- ``` - 4. Почніть нову сесію, щоб знімок Skills оновився. + 4. Почніть нову session, щоб знімок skills оновився. - - Вбудовано наразі — ні. + + Наразі вбудованої немає. Варіанти: - - **Власний skill / plugin:** найкраще для надійного API-доступу (і Notion, і HeyGen мають API). - - **Автоматизація браузера:** працює без коду, але повільніше й крихкіше. + - **Користувацький skill / Plugin:** найкраще для надійного доступу до API (і Notion, і HeyGen мають API). + - **Автоматизація браузера:** працює без коду, але повільніше й менш надійно. - Якщо ви хочете зберігати контекст по клієнту (робочі процеси агенції), простий шаблон такий: + Якщо ви хочете зберігати контекст окремо для кожного клієнта (робочі процеси agency), простий шаблон такий: - - Одна сторінка Notion на клієнта (контекст + вподобання + активна робота). - - Попросіть агента отримувати цю сторінку на початку сесії. + - Одна сторінка Notion на кожного клієнта (контекст + вподобання + активна робота). + - Попросіть agent отримувати цю сторінку на початку session. - Якщо вам потрібна нативна інтеграція, відкрийте feature request або створіть skill, - орієнтовану на ці API. + Якщо вам потрібна нативна інтеграція, створіть запит на нову функцію або зберіть skill, + орієнтований на ці API. - Встановлення Skills: + Установлення skills: ```bash openclaw skills install openclaw skills update --all ``` - Нативні встановлення потрапляють у каталог `skills/` активного workspace. Для спільних Skills між агентами розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо лише деякі агенти повинні бачити спільне встановлення, налаштуйте `agents.defaults.skills` або `agents.list[].skills`. Деякі Skills очікують бінарники, установлені через Homebrew; на Linux це означає Linuxbrew (див. вище запис ЧаПів про Homebrew на Linux). Див. [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і [ClawHub](/uk/tools/clawhub). + Нативні встановлення потрапляють у каталог `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). - + Використовуйте вбудований профіль браузера `user`, який під’єднується через Chrome DevTools MCP: ```bash @@ -1258,172 +1258,172 @@ x-i18n: 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 ``` - Цей шлях локальний для host. Якщо Gateway працює десьінде, або запускайте node host на машині з браузером, або використовуйте віддалений CDP. + Цей шлях локальний для хоста. Якщо Gateway працює деінде, або запустіть хост node на машині з браузером, або використовуйте віддалений CDP. - Поточні обмеження `existing-session` / `user`: + Поточні обмеження для `existing-session` / `user`: - - дії працюють через ref, а не через CSS-selector + - дії прив’язані до `ref`, а не до CSS-селекторів - завантаження файлів потребує `ref` / `inputRef` і наразі підтримує лише один файл за раз - - `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії все ще потребують керованого browser або сирого CDP-профілю + - `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії все ще потребують керованого браузера або сирого профілю CDP -## Пісочниця та memory +## Ізоляція та memory - - Так. Див. [Пісочниця](/uk/gateway/sandboxing). Для налаштування, пов’язаного з Docker (повний gateway у Docker або образи пісочниці), див. [Docker](/uk/install/docker). + + Так. Див. [Ізоляція](/uk/gateway/sandboxing). Для налаштування, специфічного для Docker (повний gateway у Docker або образи sandbox), див. [Docker](/uk/install/docker). - Стандартний image орієнтований на безпеку й працює від імені користувача `node`, тому він не - містить system packages, Homebrew чи bundled browser-ів. Для повнішого налаштування: + Образ за замовчуванням орієнтований насамперед на безпеку та працює від імені користувача `node`, тому не + містить системних пакетів, Homebrew чи bundled браузерів. Для повнішого налаштування: - - Зберігайте `/home/node` через `OPENCLAW_HOME_VOLUME`, щоб кеші виживали. - - Вбудовуйте системні залежності в image за допомогою `OPENCLAW_DOCKER_APT_PACKAGES`. - - Встановлюйте browser-и Playwright через bundled CLI: + - Зберігайте `/home/node` через `OPENCLAW_HOME_VOLUME`, щоб кеші не зникали. + - Вбудуйте системні залежності в образ через `OPENCLAW_DOCKER_APT_PACKAGES`. + - Установіть браузери Playwright через bundled CLI: `node /app/node_modules/playwright-core/cli.js install chromium` - - Установіть `PLAYWRIGHT_BROWSERS_PATH` і переконайтеся, що цей шлях зберігається. + - Задайте `PLAYWRIGHT_BROWSERS_PATH` і переконайтеся, що цей шлях зберігається. Документація: [Docker](/uk/install/docker), [Browser](/uk/tools/browser). - - Так — якщо ваш приватний трафік це **DM**, а публічний трафік — **групи**. + + Так — якщо ваш приватний трафік — це **DM**, а публічний трафік — **groups**. - Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб групові/канальні сесії (non-main keys) працювали в Docker, а головна DM-сесія лишалася на host. Потім обмежте, які інструменти доступні в сесіях пісочниці, через `tools.sandbox.tools`. + Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб sessions груп/channel (ключі не-main) працювали в Docker, тоді як main DM session залишалася на хості. Потім обмежте, які інструменти доступні в ізольованих sessions, через `tools.sandbox.tools`. - Покрокове налаштування + приклад конфігурації: [Групи: персональні DM + публічні групи](/uk/channels/groups#pattern-personal-dms-public-groups-single-agent) + Покрокове налаштування + приклад config: [Groups: особисті DM + публічні групи](/uk/channels/groups#pattern-personal-dms-public-groups-single-agent) - Довідник ключової конфігурації: [Конфігурація Gateway](/uk/gateway/configuration-reference#agentsdefaultssandbox) + Довідка щодо ключової config: [Конфігурація Gateway](/uk/gateway/configuration-reference#agentsdefaultssandbox) - - Установіть `agents.defaults.sandbox.docker.binds` на `["host:path:mode"]` (наприклад, `"/home/user/src:/src:ro"`). Глобальні прив’язки та прив’язки для конкретного агента об’єднуються; прив’язки для агента ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого і пам’ятайте, що прив’язки обходять файлові стіни пісочниці. + + Установіть `agents.defaults.sandbox.docker.binds` у `["host:path:mode"]` (наприклад, `"/home/user/src:/src:ro"`). Глобальні прив’язки й прив’язки для окремого agent об’єднуються; прив’язки окремого agent ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого й пам’ятайте, що прив’язки обходять межі файлової системи sandbox. - OpenClaw перевіряє джерела bind як за нормалізованим шляхом, так і за канонічним шляхом, розв’язаним через найглибшого існуючого предка. Це означає, що виходи через symlink-parent усе одно закриваються безпечно навіть коли останній сегмент шляху ще не існує, а перевірки allowed-root усе одно застосовуються після розв’язання symlink. + OpenClaw перевіряє джерела bind як за нормалізованим шляхом, так і за canonical path, визначеним через найглибший наявний предок. Це означає, що виходи через 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). - Memory OpenClaw — це просто Markdown-файли в workspace агента: + Memory OpenClaw — це просто Markdown-файли в workspace agent: - Щоденні нотатки в `memory/YYYY-MM-DD.md` - - Куровані довгострокові нотатки в `MEMORY.md` (лише для main/private session) + - Добірні довгострокові нотатки в `MEMORY.md` (лише main/private sessions) - OpenClaw також виконує **мовчазний flush memory перед compaction**, щоб нагадати моделі - записати стійкі нотатки перед auto-compaction. Це працює лише коли workspace - доступний для запису (read-only sandboxes пропускають це). Див. [Memory](/uk/concepts/memory). + OpenClaw також виконує **тихий flush memory перед Compaction**, щоб нагадати моделі + записати стійкі нотатки перед автоматичним Compaction. Це запускається лише тоді, коли workspace + доступний для запису (sandbox у режимі лише читання це пропускають). Див. [Memory](/uk/concepts/memory). - - Попросіть бота **записати факт у memory**. Довгострокові нотатки мають іти в `MEMORY.md`, + + Попросіть бота **записати факт у memory**. Довгострокові нотатки мають бути в `MEMORY.md`, короткостроковий контекст — у `memory/YYYY-MM-DD.md`. - Це все ще зона, яку ми покращуємо. Допомагає нагадувати моделі зберігати спогади; - вона знатиме, що робити. Якщо вона продовжує забувати, перевірте, що Gateway використовує той самий - workspace в кожному запуску. + Це все ще область, яку ми покращуємо. Допомагає нагадувати моделі зберігати memory; + вона знатиме, що робити. Якщо вона все одно забуває, перевірте, що Gateway використовує той самий + workspace під час кожного запуску. - Документація: [Memory](/uk/concepts/memory), [Workspace агента](/uk/concepts/agent-workspace). + Документація: [Memory](/uk/concepts/memory), [Робочий простір agent](/uk/concepts/agent-workspace). - + Файли memory живуть на диску й зберігаються, доки ви їх не видалите. Обмеженням є ваше - сховище, а не модель. **Контекст сесії** все одно обмежений вікном контексту моделі, - тому довгі розмови можуть compact-итися або обрізатися. Саме тому існує пошук по - memory — він повертає в контекст лише релевантні частини. + сховище, а не модель. **Контекст session** усе ще обмежений вікном контексту + моделі, тому довгі розмови можуть проходити через Compaction або обрізання. Саме тому + існує пошук у memory — він повертає в контекст лише релевантні частини. Документація: [Memory](/uk/concepts/memory), [Контекст](/uk/concepts/context). - - Лише якщо ви використовуєте **OpenAI embeddings**. Codex OAuth покриває chat/completions і - **не** дає доступу до embeddings, тож **вхід через Codex (OAuth або - вхід через Codex CLI)** не допоможе для семантичного пошуку memory. OpenAI embeddings - усе ще потребують справжній API key (`OPENAI_API_KEY` або `models.providers.openai.apiKey`). + + Лише якщо ви використовуєте **OpenAI embeddings**. OAuth Codex покриває chat/completions і + **не** надає доступу до embeddings, тому **вхід через Codex (OAuth або + вхід через Codex CLI)** не допоможе для семантичного пошуку в memory. Для embeddings OpenAI + усе одно потрібен справжній API-ключ (`OPENAI_API_KEY` або `models.providers.openai.apiKey`). - Якщо ви явно не задаєте провайдера, OpenClaw автоматично вибирає провайдера, коли він - може розв’язати API key (профілі auth, `models.providers.*.apiKey` або env vars). - Він віддає перевагу OpenAI, якщо розв’язується ключ OpenAI, інакше Gemini, якщо - розв’язується ключ Gemini, потім Voyage, потім Mistral. Якщо жодного віддаленого ключа немає, - пошук memory лишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштований і наявний + Якщо ви явно не задаєте provider, OpenClaw автоматично вибирає provider, коли + може визначити API-ключ (auth profiles, `models.providers.*.apiKey` або env vars). + Він віддає перевагу OpenAI, якщо визначено ключ OpenAI, інакше Gemini, якщо ключ Gemini + визначено, потім Voyage, потім Mistral. Якщо віддалений ключ недоступний, пошук у memory + залишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштовано й наявний шлях до локальної моделі, OpenClaw - віддає перевагу `local`. Ollama підтримується, коли ви явно встановлюєте + віддає перевагу `local`. Ollama підтримується, якщо ви явно задаєте `memorySearch.provider = "ollama"`. - Якщо ви віддаєте перевагу локальному режиму, встановіть `memorySearch.provider = "local"` (і за бажанням - `memorySearch.fallback = "none"`). Якщо вам потрібні Gemini embeddings, установіть + Якщо ви хочете залишитися локально, задайте `memorySearch.provider = "local"` (і за бажанням + `memorySearch.fallback = "none"`). Якщо вам потрібні embeddings Gemini, задайте `memorySearch.provider = "gemini"` і надайте `GEMINI_API_KEY` (або - `memorySearch.remote.apiKey`). Ми підтримуємо embedding-моделі **OpenAI, Gemini, Voyage, Mistral, Ollama або local** - — подробиці налаштування див. у [Memory](/uk/concepts/memory). + `memorySearch.remote.apiKey`). Ми підтримуємо embedding-моделі **OpenAI, Gemini, Voyage, Mistral, Ollama або local** — + деталі налаштування див. у [Memory](/uk/concepts/memory). -## Де що лежить на диску +## Де що зберігається на диску - + Ні — **стан OpenClaw локальний**, але **зовнішні сервіси все одно бачать те, що ви їм надсилаєте**. - - **Локально за замовчуванням:** сесії, файли memory, конфігурація і workspace живуть на gateway host - (`~/.openclaw` + ваш каталог workspace). - - **Віддалено за необхідністю:** повідомлення, які ви надсилаєте провайдерам моделей (Anthropic/OpenAI тощо), ідуть до - їхніх API, а chat-платформи (WhatsApp/Telegram/Slack тощо) зберігають дані повідомлень на + - **Локально за замовчуванням:** sessions, файли memory, config і workspace живуть на хості Gateway + (`~/.openclaw` + каталог вашого workspace). + - **Віддалено за необхідністю:** повідомлення, які ви надсилаєте провайдерам моделей (Anthropic/OpenAI тощо), передаються + до їхніх API, а chat-платформи (WhatsApp/Telegram/Slack тощо) зберігають дані повідомлень на своїх серверах. - - **Ви контролюєте слід:** використання локальних моделей зберігає prompt-и на вашій машині, але трафік - каналів усе одно проходить через сервери каналу. + - **Ви керуєте слідом:** використання локальних моделей залишає prompt на вашій машині, але трафік + channel все одно проходить через сервери відповідного channel. - Пов’язане: [Workspace агента](/uk/concepts/agent-workspace), [Memory](/uk/concepts/memory). + Пов’язане: [Робочий простір agent](/uk/concepts/agent-workspace), [Memory](/uk/concepts/memory). - Усе живе в `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`): + Усе зберігається в `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`): - | Path | Призначення | + | Path | Призначення | | --------------------------------------------------------------- | ------------------------------------------------------------------ | - | `$OPENCLAW_STATE_DIR/openclaw.json` | Основна конфігурація (JSON5) | + | `$OPENCLAW_STATE_DIR/openclaw.json` | Основна config (JSON5) | | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Застарілий імпорт OAuth (копіюється в auth profiles під час першого використання) | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles (OAuth, API keys і необов’язкові `keyRef`/`tokenRef`) | - | `$OPENCLAW_STATE_DIR/secrets.json` | Необов’язкове резервне сховище секретів у файлі для `file` SecretRef providers | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Файл застарілої сумісності (статичні записи `api_key` очищаються) | - | `$OPENCLAW_STATE_DIR/credentials/` | Стан провайдера (наприклад `whatsapp//creds.json`) | - | `$OPENCLAW_STATE_DIR/agents/` | Стан окремих агентів (agentDir + sessions) | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | Історія розмов і стан (для кожного агента) | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані сесій (для кожного агента) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Auth profiles (OAuth, API-ключі та необов’язкові `keyRef`/`tokenRef`) | + | `$OPENCLAW_STATE_DIR/secrets.json` | Необов’язковий file-backed payload секретів для провайдерів `file` SecretRef | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Застарілий файл сумісності (статичні записи `api_key` очищуються) | + | `$OPENCLAW_STATE_DIR/credentials/` | Стан провайдера (наприклад, `whatsapp//creds.json`) | + | `$OPENCLAW_STATE_DIR/agents/` | Стан для кожного agent (agentDir + sessions) | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | Історія розмов і стан (для кожного agent) | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані session (для кожного agent) | - Застарілий шлях для одного агента: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`). + Застарілий шлях для single-agent: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`). - Ваш **workspace** (`AGENTS.md`, файли memory, Skills тощо) зберігається окремо й налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). + Ваш **workspace** (`AGENTS.md`, файли memory, skills тощо) зберігається окремо й налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). - - Ці файли живуть у **workspace агента**, а не в `~/.openclaw`. + + Ці файли зберігаються в **workspace agent**, а не в `~/.openclaw`. - - **Workspace (для кожного агента)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, - `MEMORY.md` (або застарілий fallback `memory.md`, коли `MEMORY.md` відсутній), + - **Workspace (для кожного agent):** `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, + `MEMORY.md` (або застарілий запасний варіант `memory.md`, якщо `MEMORY.md` відсутній), `memory/YYYY-MM-DD.md`, необов’язковий `HEARTBEAT.md`. - - **State dir (`~/.openclaw`)**: конфігурація, стан каналу/провайдера, профілі auth, сесії, журнали, - і спільні Skills (`~/.openclaw/skills`). + - **State dir (`~/.openclaw`)**: config, стан channel/provider, auth profiles, sessions, логи, + і спільні skills (`~/.openclaw/skills`). - Workspace за замовчуванням — `~/.openclaw/workspace`, налаштовується через: + Типовий workspace — `~/.openclaw/workspace`, налаштовується через: ```json5 { @@ -1431,44 +1431,44 @@ x-i18n: } ``` - Якщо бот «забуває» після перезапуску, перевірте, що Gateway використовує той самий - workspace при кожному запуску (і пам’ятайте: remote mode використовує **workspace gateway host-а**, + Якщо бот "забуває" після перезапуску, переконайтеся, що Gateway використовує той самий + workspace під час кожного запуску (і пам’ятайте: віддалений режим використовує **workspace хоста gateway**, а не вашого локального ноутбука). - Порада: якщо ви хочете стійку поведінку або вподобання, попросіть бота **записати це в - AGENTS.md або MEMORY.md**, а не покладатися на історію chat. + Порада: якщо ви хочете зберегти поведінку або вподобання надовго, попросіть бота **записати це в + AGENTS.md або MEMORY.md**, а не покладатися на історію чату. - Див. [Workspace агента](/uk/concepts/agent-workspace) і [Memory](/uk/concepts/memory). + Див. [Робочий простір agent](/uk/concepts/agent-workspace) і [Memory](/uk/concepts/memory). - Помістіть свій **workspace агента** у **приватний** git-репозиторій і робіть його резервну копію - десь у приватному місці (наприклад у GitHub private). Це збереже memory + файли AGENTS/SOUL/USER - та дозволить пізніше відновити «розум» помічника. + Помістіть свій **workspace agent** у **приватний** git-репозиторій і зберігайте резервну копію десь + у приватному місці (наприклад, GitHub private). Це збереже memory + файли AGENTS/SOUL/USER + й дозволить пізніше відновити "розум" помічника. - **Не** commit-те нічого з `~/.openclaw` (облікові дані, сесії, токени або зашифровані payload-и секретів). - Якщо вам потрібне повне відновлення, робіть резервні копії і workspace, і state directory - окремо (див. питання про міграцію вище). + **Не** робіть commit нічого з `~/.openclaw` (облікові дані, sessions, токени або зашифровані payload секретів). + Якщо вам потрібне повне відновлення, окремо зробіть резервну копію і workspace, і state directory + (див. питання про міграцію вище). - Документація: [Workspace агента](/uk/concepts/agent-workspace). + Документація: [Робочий простір agent](/uk/concepts/agent-workspace). - Див. окремий гайд: [Видалення](/uk/install/uninstall). + Див. окремий посібник: [Видалення](/uk/install/uninstall). - - Так. Workspace — це **cwd за замовчуванням** і якір memory, а не жорстка пісочниця. - Відносні шляхи розв’язуються всередині workspace, але абсолютні шляхи можуть отримати доступ до інших - місць host-а, якщо пісочниця не ввімкнена. Якщо вам потрібна ізоляція, використовуйте - [`agents.defaults.sandbox`](/uk/gateway/sandboxing) або налаштування пісочниці для конкретного агента. Якщо ви - хочете, щоб репозиторій був cwd за замовчуванням, вкажіть `workspace` - цього агента на корінь репозиторію. Репозиторій OpenClaw — це лише сирці; тримайте - workspace окремо, якщо тільки ви свідомо не хочете, щоб агент працював усередині нього. + + Так. Workspace — це **типовий cwd** і прив’язка для memory, а не жорсткий sandbox. + Відносні шляхи розв’язуються всередині workspace, але абсолютні шляхи можуть звертатися до інших + розташувань хоста, якщо sandbox не увімкнено. Якщо вам потрібна ізоляція, використовуйте + [`agents.defaults.sandbox`](/uk/gateway/sandboxing) або налаштування sandbox для окремого agent. Якщо ви + хочете, щоб репозиторій був типовим робочим каталогом, укажіть `workspace` + цього agent на корінь репозиторію. Репозиторій OpenClaw — це лише вихідний код; тримайте + workspace окремо, якщо тільки ви навмисно не хочете, щоб agent працював усередині нього. - Приклад (репозиторій як cwd за замовчуванням): + Приклад (репозиторій як типовий cwd): ```json5 { @@ -1482,30 +1482,30 @@ x-i18n: - - Станом session володіє **gateway host**. Якщо ви в remote mode, сховище session, яке вас цікавить, знаходиться на віддаленій машині, а не на вашому локальному ноутбуці. Див. [Керування session](/uk/concepts/session). + + Стан session належить **хосту gateway**. Якщо ви працюєте у віддаленому режимі, потрібне вам сховище session знаходиться на віддаленій машині, а не на вашому локальному ноутбуці. Див. [Керування session](/uk/concepts/session). -## Основи конфігурації +## Основи config - - OpenClaw читає необов’язкову конфігурацію **JSON5** з `$OPENCLAW_CONFIG_PATH` (типово: `~/.openclaw/openclaw.json`): + + OpenClaw читає необов’язкову config **JSON5** з `$OPENCLAW_CONFIG_PATH` (типово: `~/.openclaw/openclaw.json`): ``` $OPENCLAW_CONFIG_PATH ``` - Якщо файл відсутній, використовуються відносно безпечні значення за замовчуванням (зокрема workspace за замовчуванням `~/.openclaw/workspace`). + Якщо файл відсутній, використовуються відносно безпечні значення за замовчуванням (зокрема типовий workspace `~/.openclaw/workspace`). - Bind без loopback **потребують коректного шляху auth gateway**. На практиці це означає: + Прив’язки не до loopback **потребують коректного шляху auth gateway**. На практиці це означає: - - auth через shared secret: token або password - - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим identity-aware reverse proxy без loopback + - auth через shared secret: токен або пароль + - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим identity-aware reverse proxy не на loopback ```json5 { @@ -1521,32 +1521,32 @@ x-i18n: Примітки: - - `gateway.remote.token` / `.password` **самі по собі** не вмикають auth локального 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 і його не вдається розв’язати, розв’язання завершується безпечним закриттям (ніякий remote fallback це не маскує). - - Налаштування Control UI через shared secret автентифікуються через `connect.params.auth.token` або `connect.params.auth.password` (зберігається в налаштуваннях app/UI). Режими з ідентичністю, як-от Tailscale Serve або `trusted-proxy`, натомість використовують request headers. Уникайте розміщення shared secret у URL. - - З `gateway.auth.mode: "trusted-proxy"` reverse proxy на тому самому host через loopback усе одно **не** задовольняє trusted-proxy auth. Trusted proxy має бути налаштованим джерелом без loopback. + - `gateway.remote.token` / `.password` **самі по собі** не вмикають локальну auth gateway. + - Локальні шляхи виклику можуть використовувати `gateway.remote.*` як запасний варіант лише тоді, коли `gateway.auth.*` не задано. + - Для auth через пароль задайте `gateway.auth.mode: "password"` плюс `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). + - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і його не вдається розв’язати, розв’язання надійно завершується помилкою (без прихованого запасного варіанта через remote). + - Налаштування 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. - - OpenClaw примусово вимагає gateway auth за замовчуванням, зокрема і на loopback. У звичайному шляху за замовчуванням це означає auth через token: якщо явний шлях auth не налаштовано, під час запуску gateway резолвиться режим token і token генерується автоматично, зберігаючись у `gateway.auth.token`, тож **локальні WS-клієнти повинні автентифікуватися**. Це блокує виклики Gateway іншими локальними процесами. + + OpenClaw примусово вимагає auth gateway за замовчуванням, зокрема й на loopback. У звичайному типовому сценарії це означає auth через токен: якщо явний шлях auth не налаштовано, під час запуску gateway вибирається режим token і токен генерується автоматично, зберігаючись у `gateway.auth.token`, тож **локальні WS-клієнти мають проходити автентифікацію**. Це блокує інші локальні процеси від виклику Gateway. - Якщо ви віддаєте перевагу іншому шляху auth, можете явно вибрати режим password (або, для identity-aware reverse proxy без loopback, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно встановіть `gateway.auth.mode: "none"` у конфігурації. Doctor може згенерувати token у будь-який момент: `openclaw doctor --generate-gateway-token`. + Якщо вам потрібен інший шлях auth, ви можете явно вибрати режим password (або, для identity-aware reverse proxy не на loopback, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно задайте `gateway.auth.mode: "none"` у config. Doctor може згенерувати токен у будь-який момент: `openclaw doctor --generate-gateway-token`. - - Gateway відстежує конфігурацію та підтримує hot-reload: + + Gateway відстежує config і підтримує hot-reload: - - `gateway.reload.mode: "hybrid"` (типово): безпечні зміни застосовуються hot, для критичних виконується restart - - Також підтримуються `hot`, `restart`, `off` + - `gateway.reload.mode: "hybrid"` (типово): безпечно застосовує зміни на гарячу, а для критичних виконує перезапуск + - також підтримуються `hot`, `restart`, `off` - - Установіть `cli.banner.taglineMode` у конфігурації: + + Задайте `cli.banner.taglineMode` у config: ```json5 { @@ -1558,24 +1558,24 @@ x-i18n: } ``` - - `off`: приховує текст слогана, але залишає рядок заголовка/версії банера. + - `off`: приховує текст слогана, але залишає рядок із назвою banner/версією. - `default`: щоразу використовує `All your chats, one OpenClaw.`. - - `random`: ротаційні кумедні/сезонні слогани (типова поведінка). - - Якщо ви не хочете жодного банера, установіть env `OPENCLAW_HIDE_BANNER=1`. + - `random`: чергування кумедних/сезонних слоганів (типова поведінка). + - Якщо ви не хочете banner взагалі, задайте env `OPENCLAW_HIDE_BANNER=1`. - `web_fetch` працює без API key. `web_search` залежить від вибраного - провайдера: + `web_fetch` працює без API-ключа. `web_search` залежить від вибраного + provider: - - Провайдери на основі API, такі як Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, потребують звичайного налаштування API key. - - Ollama Web Search не потребує ключа, але використовує ваш налаштований Ollama host і вимагає `ollama signin`. + - Провайдери на основі 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`. + - SearXNG не потребує ключа/може бути self-hosted; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. - **Рекомендовано:** запустіть `openclaw configure --section web` і виберіть провайдера. - Альтернативи через env: + **Рекомендовано:** виконайте `openclaw configure --section web` і виберіть provider. + Альтернативи через середовище: - Brave: `BRAVE_API_KEY` - Exa: `EXA_API_KEY` @@ -1617,59 +1617,59 @@ x-i18n: } ``` - Конфігурація web-search для конкретного провайдера тепер живе під `plugins.entries..config.webSearch.*`. - Застарілі шляхи провайдера `tools.web.search.*` усе ще тимчасово завантажуються для сумісності, але їх не слід використовувати в нових конфігураціях. - Конфігурація fallback web-fetch Firecrawl живе під `plugins.entries.firecrawl.config.webFetch.*`. + Конфігурація web-search, специфічна для provider, тепер розміщується в `plugins.entries..config.webSearch.*`. + Застарілі шляхи provider `tools.web.search.*` усе ще тимчасово завантажуються для сумісності, але їх не слід використовувати в нових config. + Запасна config 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-провайдера fetch із доступних облікових даних. Наразі bundled-провайдер — Firecrawl. - - Демони читають env vars із `~/.openclaw/.env` (або середовища сервісу). + - Якщо `tools.web.fetch.provider` пропущено, OpenClaw автоматично визначає першого готового запасного provider fetch зі доступних облікових даних. Наразі bundled provider — це Firecrawl. + - Демони читають env vars з `~/.openclaw/.env` (або із середовища сервісу). - Документація: [Web-інструменти](/uk/tools/web). + Документація: [Web tools](/uk/tools/web). - - `config.apply` замінює **всю конфігурацію**. Якщо ви надсилаєте частковий об’єкт, усе + + `config.apply` замінює **всю config цілком**. Якщо ви надсилаєте частковий об’єкт, усе інше видаляється. Відновлення: - - Відновіть із резервної копії (git або скопійованого `~/.openclaw/openclaw.json`). - - Якщо резервної копії немає, повторно запустіть `openclaw doctor` і заново налаштуйте канали/моделі. - - Якщо це сталося неочікувано, створіть bug report і додайте свою останню відому конфігурацію або будь-яку резервну копію. - - Локальний coding-agent часто може відновити працездатну конфігурацію з журналів або історії. + - Відновіть із резервної копії (git або скопійований `~/.openclaw/openclaw.json`). + - Якщо резервної копії немає, повторно запустіть `openclaw doctor` і знову налаштуйте channels/models. + - Якщо це було неочікувано, створіть bug report і додайте свою останню відому config або будь-яку резервну копію. + - Локальний coding agent часто може відновити робочу config із логів або історії. Як уникнути: - - Використовуйте `openclaw config set` для малих змін. + - Використовуйте `openclaw config set` для невеликих змін. - Використовуйте `openclaw configure` для інтерактивного редагування. - - Спочатку використовуйте `config.schema.lookup`, якщо ви не впевнені в точному шляху або формі поля; воно повертає неглибокий вузол schema плюс підсумки безпосередніх дочірніх елементів для покрокового дослідження. - - Використовуйте `config.patch` для часткових RPC-редагувань; залишайте `config.apply` лише для повної заміни конфігурації. - - Якщо ви використовуєте інструмент `gateway`, доступний лише owner, із запуску агента, він усе одно відхиляє записи в `tools.exec.ask` / `tools.exec.security` (зокрема застарілі псевдоніми `tools.bash.*`, які нормалізуються до тих самих захищених шляхів exec). + - Спочатку використовуйте `config.schema.lookup`, коли ви не впевнені в точному шляху чи формі поля; він повертає вузол неглибокої schema плюс підсумки безпосередніх дочірніх елементів для покрокового заглиблення. + - Використовуйте `config.patch` для часткових редагувань через RPC; залишайте `config.apply` лише для повної заміни config. + - Якщо ви використовуєте інструмент `gateway` лише для owner з запуску agent, він усе одно відхилятиме записи в `tools.exec.ask` / `tools.exec.security` (зокрема застарілі псевдоніми `tools.bash.*`, які нормалізуються до тих самих захищених шляхів exec). Документація: [Config](/cli/config), [Configure](/cli/configure), [Doctor](/uk/gateway/doctor). - - Поширений шаблон — **один Gateway** (наприклад, Raspberry Pi) плюс **nodes** і **agents**: + + Типовий шаблон — **один Gateway** (наприклад, Raspberry Pi) плюс **nodes** і **agents**: - - **Gateway (центральний):** володіє каналами (Signal/WhatsApp), маршрутизацією і сесіями. - - **Nodes (пристрої):** Macs/iOS/Android під’єднуються як периферія й надають локальні інструменти (`system.run`, `canvas`, `camera`). - - **Agents (workers):** окремі мізки/workspaces для спеціальних ролей (наприклад, "Hetzner ops", "Personal data"). - - **Sub-agents:** породжують фонову роботу з основного агента, коли вам потрібен паралелізм. - - **TUI:** під’єднується до Gateway і перемикає агентів/сесії. + - **Gateway (центральний):** керує channels (Signal/WhatsApp), маршрутизацією і sessions. + - **Nodes (пристрої):** Mac/iOS/Android підключаються як периферія і надають локальні інструменти (`system.run`, `canvas`, `camera`). + - **Agents (workers):** окремі "мізки"/workspace для спеціальних ролей (наприклад, "Hetzner ops", "Особисті дані"). + - **Sub-agents:** запускають фонову роботу з main agent, коли вам потрібен паралелізм. + - **TUI:** підключається до Gateway і перемикає agents/sessions. - Документація: [Nodes](/uk/nodes), [Віддалений доступ](/uk/gateway/remote), [Маршрутизація мультиагентності](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [TUI](/web/tui). + Документація: [Nodes](/uk/nodes), [Віддалений доступ](/uk/gateway/remote), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [TUI](/web/tui). - - Так. Це опція конфігурації: + + Так. Це параметр config: ```json5 { @@ -1682,45 +1682,45 @@ x-i18n: } ``` - Типове значення — `false` (headful). Headless із більшою ймовірністю викликає anti-bot перевірки на деяких сайтах. Див. [Browser](/uk/tools/browser). + Типове значення — `false` (із видимим вікном). Headless-режим з більшою ймовірністю викликає anti-bot перевірки на деяких сайтах. Див. [Browser](/uk/tools/browser). - Headless використовує **той самий рушій Chromium** і працює для більшості автоматизації (форми, кліки, скрапінг, входи). Основні відмінності: + Headless використовує **той самий рушій Chromium** і працює для більшості сценаріїв автоматизації (форми, кліки, scraping, входи). Основні відмінності: - - Немає видимого вікна браузера (використовуйте screenshot-и, якщо потрібні візуальні дані). + - Немає видимого вікна браузера (використовуйте знімки екрана, якщо потрібна візуалізація). - Деякі сайти суворіше ставляться до автоматизації в headless-режимі (CAPTCHA, anti-bot). - Наприклад, X/Twitter часто блокує headless-сесії. + Наприклад, X/Twitter часто блокує headless sessions. - Установіть `browser.executablePath` на ваш бінарник Brave (або будь-якого browser-а на основі Chromium) і перезапустіть Gateway. - Повні приклади конфігурації див. у [Browser](/uk/tools/browser#use-brave-or-another-chromium-based-browser). + Установіть `browser.executablePath` на ваш бінарник Brave (або будь-який браузер на базі Chromium) і перезапустіть Gateway. + Повні приклади config див. у [Browser](/uk/tools/browser#use-brave-or-another-chromium-based-browser). -## Віддалені gateway та nodes +## Віддалені gateway і nodes - - Повідомлення Telegram обробляються **gateway**. Gateway запускає агента і - лише потім викликає nodes через **Gateway WebSocket**, коли потрібен node tool: + + Повідомлення Telegram обробляє **gateway**. Gateway запускає agent і + лише потім викликає nodes через **Gateway WebSocket**, коли потрібен інструмент node: Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - Nodes не бачать вхідний трафік провайдерів; вони отримують лише node RPC-виклики. + Nodes не бачать вхідний трафік provider; вони отримують лише виклики node RPC. - - Коротко: **під’єднайте свій комп’ютер як node**. Gateway працює в іншому місці, але він може - викликати інструменти `node.*` (screen, camera, system) на вашій локальній машині через Gateway WebSocket. + + Коротка відповідь: **під’єднайте свій комп’ютер як node**. Gateway працює деінде, але може + викликати інструменти `node.*` (екран, камера, система) на вашій локальній машині через Gateway WebSocket. Типове налаштування: - 1. Запустіть Gateway на завжди ввімкненому host-і (VPS/домашній сервер). - 2. Додайте gateway host і свій комп’ютер до одного tailnet. - 3. Переконайтеся, що Gateway WS доступний (tailnet bind або SSH tunnel). - 4. Відкрийте локально застосунок macOS і під’єднайтеся в режимі **Remote over SSH** (або напряму через tailnet), + 1. Запустіть Gateway на завжди ввімкненому хості (VPS/домашній сервер). + 2. Підключіть хост Gateway і ваш комп’ютер до однієї tailnet. + 3. Переконайтеся, що WS Gateway доступний (прив’язка tailnet або SSH tunnel). + 4. Відкрийте локально macOS app і підключіться в режимі **Remote over SSH** (або напряму через tailnet), щоб він міг зареєструватися як node. 5. Схваліть node на Gateway: @@ -1729,107 +1729,107 @@ x-i18n: openclaw devices approve ``` - Окремий TCP-міст не потрібен; nodes під’єднуються через Gateway WebSocket. + Окремий TCP bridge не потрібен; nodes підключаються через Gateway WebSocket. - Нагадування про безпеку: під’єднання macOS node дозволяє `system.run` на цій машині. Під’єднуйте - лише ті пристрої, яким довіряєте, і перегляньте [Безпека](/uk/gateway/security). + Нагадування щодо безпеки: під’єднання node macOS дозволяє `system.run` на цій машині. Підключайте + лише пристрої, яким довіряєте, і перегляньте [Security](/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 remote mode](/uk/platforms/mac/remote), [Security](/uk/gateway/security). - - Перевірте базові речі: + + Перевірте основи: - Gateway працює: `openclaw gateway status` - Стан Gateway: `openclaw status` - - Стан каналу: `openclaw channels status` + - Стан channel: `openclaw channels status` Потім перевірте auth і маршрутизацію: - - Якщо ви використовуєте Tailscale Serve, переконайтеся, що `gateway.auth.allowTailscale` встановлено правильно. - - Якщо ви під’єднуєтеся через SSH tunnel, підтвердьте, що локальний tunnel піднятий і вказує на правильний порт. - - Переконайтеся, що ваші allowlist-и (DM або group) включають ваш обліковий запис. + - Якщо ви використовуєте Tailscale Serve, переконайтеся, що `gateway.auth.allowTailscale` налаштовано правильно. + - Якщо ви підключаєтеся через SSH tunnel, переконайтеся, що локальний tunnel працює і вказує на правильний порт. + - Переконайтеся, що ваші allowlist (DM або group) містять ваш обліковий запис. - Документація: [Tailscale](/uk/gateway/tailscale), [Віддалений доступ](/uk/gateway/remote), [Канали](/uk/channels). + Документація: [Tailscale](/uk/gateway/tailscale), [Віддалений доступ](/uk/gateway/remote), [Channels](/uk/channels). - - Так. Вбудованого мосту «бот-до-бота» немає, але це можна надійно організувати кількома - способами: + + Так. Вбудованого мосту "bot-to-bot" немає, але це можна налаштувати кількома + надійними способами: - **Найпростіше:** використовуйте звичайний chat-канал, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). - Нехай Бот A надсилає повідомлення Боту B, а потім Бот B відповідає як зазвичай. + **Найпростіше:** використовуйте звичайний chat channel, до якого обидва боти мають доступ (Telegram/Slack/WhatsApp). + Нехай Bot A надсилає повідомлення Bot B, а потім Bot B відповідає як зазвичай. - **CLI-міст (загальний):** запустіть script, який викликає інший Gateway через - `openclaw agent --message ... --deliver`, націлюючись на chat, який слухає - інший бот. Якщо один бот працює на віддаленому VPS, направте свій CLI на цей віддалений Gateway + **CLI bridge (універсальний):** запустіть скрипт, який викликає інший Gateway через + `openclaw agent --message ... --deliver`, націлюючись на чат, який слухає інший бот. + Якщо один бот розміщено на віддаленому VPS, спрямуйте свій CLI на цей віддалений Gateway через SSH/Tailscale (див. [Віддалений доступ](/uk/gateway/remote)). - Приклад шаблону (запускати з машини, яка може досягти цільового Gateway): + Приклад шаблону (запускати з машини, яка може дістатися цільового Gateway): ```bash - openclaw agent --message "Привіт від локального бота" --deliver --channel telegram --reply-to + openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - Порада: додайте запобіжник, щоб два боти не зациклилися безкінечно (відповідь лише на згадку, channel - allowlist-и або правило «не відповідати на повідомлення ботів»). + Порада: додайте захист, щоб два боти не зациклювалися безкінечно (лише згадки, allowlist для channel + або правило "не відповідати на повідомлення ботів"). - Документація: [Віддалений доступ](/uk/gateway/remote), [CLI агента](/cli/agent), [Надсилання агентом](/uk/tools/agent-send). + Документація: [Віддалений доступ](/uk/gateway/remote), [Agent CLI](/cli/agent), [Agent send](/uk/tools/agent-send). - - Ні. Один Gateway може хостити кількох агентів, кожен із власним workspace, моделями за замовчуванням, - і маршрутизацією. Це нормальне налаштування, і воно значно дешевше та простіше, ніж запускати - один VPS на агента. + + Ні. Один Gateway може розміщувати кількох agents, кожен із власним workspace, models за замовчуванням + та маршрутизацією. Це типовий варіант і він набагато дешевший і простіший, ніж запускати + окремий VPS для кожного agent. Використовуйте окремі VPS лише тоді, коли вам потрібна жорстка ізоляція (межі безпеки) або дуже - різні конфігурації, якими ви не хочете ділитися. В іншому разі тримайте один Gateway і - використовуйте кілька агентів або sub-agents. + різні config, якими ви не хочете ділитися. В інших випадках тримайте один Gateway і + використовуйте кількох agents або sub-agents. - - Так — nodes є першокласним способом доступу до вашого ноутбука з віддаленого Gateway, і вони + + Так — nodes є основним способом доступу до вашого ноутбука з віддаленого Gateway і відкривають більше, ніж просто доступ до оболонки. Gateway працює на macOS/Linux (Windows через WSL2) і є - легким (підійде невеликий VPS або коробка рівня Raspberry Pi; 4 GB RAM достатньо), тож поширене - налаштування — це завжди ввімкнений host плюс ваш ноутбук як node. + легким (невеликий VPS або пристрій рівня Raspberry Pi цілком підходить; 4 GB RAM більш ніж достатньо), тому типовий + сценарій — це завжди ввімкнений хост плюс ваш ноутбук як node. - - **Не потрібен вхідний SSH.** Nodes самі під’єднуються до Gateway WebSocket і використовують pairing пристроїв. - - **Безпечніший контроль виконання.** `system.run` обмежується allowlist-ами/sхваленнями node на цьому ноутбуці. + - **Не потрібен вхідний SSH.** Nodes самі підключаються до Gateway WebSocket і використовують pair-підключення пристрою. + - **Безпечніший контроль виконання.** `system.run` на цьому ноутбуці захищено allowlist/затвердженнями node. - **Більше інструментів пристрою.** Nodes надають `canvas`, `camera` і `screen` на додачу до `system.run`. - - **Локальна автоматизація браузера.** Тримайте Gateway на VPS, але запускайте Chrome локально через node host на ноутбуці, або під’єднуйтеся до локального Chrome на host через Chrome MCP. + - **Локальна автоматизація браузера.** Тримайте Gateway на VPS, але запускайте Chrome локально через хост node на ноутбуці або підключайтеся до локального Chrome на хості через Chrome MCP. - SSH підходить для епізодичного доступу до оболонки, але nodes простіші для постійних агентських робочих процесів і - автоматизації пристроїв. + SSH підходить для разового доступу до оболонки, але nodes простіші для постійних робочих процесів agent і + автоматизації пристрою. - Документація: [Nodes](/uk/nodes), [CLI для Nodes](/cli/nodes), [Browser](/uk/tools/browser). + Документація: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes), [Browser](/uk/tools/browser). - - Ні. На host має працювати лише **один gateway**, якщо ви навмисно не запускаєте ізольовані профілі (див. [Кілька gateway](/uk/gateway/multiple-gateways)). Nodes — це периферія, яка під’єднується - до gateway (nodes iOS/Android або macOS "node mode" у menubar app). Для headless node - host-ів і керування через CLI див. [CLI node host](/cli/node). + + Ні. На одному хості має працювати лише **один gateway**, якщо тільки ви навмисно не запускаєте ізольовані профілі (див. [Кілька gateway](/uk/gateway/multiple-gateways)). Nodes — це периферійні елементи, які підключаються + до gateway (nodes iOS/Android або режим macOS "node mode" у menubar app). Для headless + хостів node і керування через CLI див. [Node host CLI](/cli/node). - Для змін `gateway`, `discovery` і `canvasHost` потрібен повний restart. + Для змін `gateway`, `discovery` і `canvasHost` потрібен повний перезапуск. - + Так. - - `config.schema.lookup`: перевірити одне піддерево конфігурації з його неглибоким вузлом schema, відповідною UI-підказкою та підсумками безпосередніх дочірніх елементів перед записом + - `config.schema.lookup`: перевірити одне піддерево config із його неглибоким вузлом schema, відповідною UI-підказкою та підсумками безпосередніх дочірніх елементів перед записом - `config.get`: отримати поточний snapshot + hash - - `config.patch`: безпечне часткове оновлення (бажано для більшості RPC-редагувань); виконує hot-reload, коли можливо, і restart, коли потрібно - - `config.apply`: перевіряє + замінює повну конфігурацію; виконує hot-reload, коли можливо, і restart, коли потрібно + - `config.patch`: безпечне часткове оновлення (рекомендовано для більшості редагувань через RPC); виконує hot-reload, коли можливо, і перезапуск, коли потрібно + - `config.apply`: перевірити й замінити всю config; виконує hot-reload, коли можливо, і перезапуск, коли потрібно - Інструмент runtime `gateway`, доступний лише owner, усе ще відмовляється переписувати `tools.exec.ask` / `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec - + ```json5 { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, @@ -1837,29 +1837,29 @@ x-i18n: } ``` - Це встановлює ваш workspace і обмежує, хто може запускати бота. + Це задає ваш workspace і обмежує, хто може запускати бота. - + Мінімальні кроки: - 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 (рекомендовано)** - - В admin console Tailscale увімкніть MagicDNS, щоб VPS мав стабільну назву. - 4. **Використовуйте hostname tailnet** + - В адміністративній консолі Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім’я. + 4. **Використовуйте ім’я хоста tailnet** - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net` - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789` - Якщо ви хочете Control UI без SSH, використовуйте Tailscale Serve на VPS: + Якщо ви хочете використовувати Control UI без SSH, застосуйте Tailscale Serve на VPS: ```bash openclaw gateway --tailscale serve @@ -1869,14 +1869,14 @@ x-i18n: - - Serve відкриває **Control UI + WS Gateway**. Nodes під’єднуються через той самий endpoint Gateway WS. + + Serve відкриває **Gateway Control UI + WS**. Nodes підключаються через ту саму кінцеву точку Gateway WS. Рекомендоване налаштування: - 1. **Переконайтеся, що VPS і Mac знаходяться в одному tailnet**. - 2. **Використовуйте застосунок macOS у режимі Remote** (SSH-ціллю може бути hostname tailnet). - Застосунок протунелює порт Gateway і під’єднається як node. + 1. **Переконайтеся, що VPS і Mac перебувають в одній tailnet**. + 2. **Використовуйте macOS app у режимі Remote** (ціль SSH може бути hostname tailnet). + Застосунок тунелює порт Gateway і підключається як node. 3. **Схваліть node** на gateway: ```bash @@ -1884,18 +1884,18 @@ x-i18n: openclaw devices approve ``` - Документація: [Протокол Gateway](/uk/gateway/protocol), [Виявлення](/uk/gateway/discovery), [Віддалений режим macOS](/uk/platforms/mac/remote). + Документація: [Протокол Gateway](/uk/gateway/protocol), [Discovery](/uk/gateway/discovery), [macOS remote mode](/uk/platforms/mac/remote). Якщо вам потрібні лише **локальні інструменти** (screen/camera/exec) на другому ноутбуці, додайте його як - **node**. Це залишає один Gateway і уникає дублювання конфігурації. Локальні node tools - наразі підтримуються лише на macOS, але ми плануємо розширити це на інші ОС. + **node**. Це зберігає один Gateway і дозволяє уникнути дублювання config. Локальні інструменти node + наразі доступні лише на macOS, але ми плануємо розширити їх на інші ОС. - Встановлюйте другий Gateway лише тоді, коли вам потрібна **жорстка ізоляція** або два повністю окремі боти. + Другий Gateway встановлюйте лише тоді, коли вам потрібна **жорстка ізоляція** або два повністю окремі боти. - Документація: [Nodes](/uk/nodes), [CLI для Nodes](/cli/nodes), [Кілька gateway](/uk/gateway/multiple-gateways). + Документація: [Nodes](/uk/nodes), [Nodes CLI](/cli/nodes), [Кілька gateway](/uk/gateway/multiple-gateways). @@ -1903,15 +1903,15 @@ x-i18n: ## Env vars і завантаження .env - - OpenClaw читає env vars із батьківського процесу (оболонка, launchd/systemd, CI тощо) і додатково завантажує: + + OpenClaw читає env vars із батьківського процесу (shell, launchd/systemd, CI тощо) і додатково завантажує: - `.env` з поточного робочого каталогу - - глобальний fallback `.env` із `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`) + - глобальний запасний `.env` з `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`) - Жоден файл `.env` не перевизначає вже існуючі env vars. + Жоден файл `.env` не перевизначає наявні env vars. - Ви також можете визначати inline env vars у конфігурації (застосовуються лише якщо їх бракує в process env): + Ви також можете визначати вбудовані env vars у config (застосовуються лише якщо вони відсутні в env процесу): ```json5 { @@ -1922,15 +1922,15 @@ x-i18n: } ``` - Повний порядок пріоритету й джерела див. у [/environment](/uk/help/environment). + Повний порядок пріоритету та джерела див. у [/environment](/uk/help/environment). - - Два поширені виправлення: + + Два поширені способи виправлення: - 1. Покладіть відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися, навіть коли service не успадковує env вашої оболонки. - 2. Увімкніть імпорт оболонки (opt-in зручність): + 1. Помістіть відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися, навіть коли сервіс не успадковує env вашої shell. + 2. Увімкніть імпорт shell (необов’язкова зручність): ```json5 { @@ -1948,22 +1948,22 @@ x-i18n: - - `openclaw models status` повідомляє, чи увімкнено **імпорт env з оболонки**. "Shell env: off" + + `openclaw models status` повідомляє, чи увімкнено **імпорт env із shell**. "Shell env: off" **не** означає, що ваших env vars немає — це лише означає, що OpenClaw не завантажуватиме вашу login shell автоматично. - Якщо Gateway працює як service (launchd/systemd), він не успадковує env - вашої оболонки. Виправлення — зробіть одне з цього: + Якщо Gateway працює як сервіс (launchd/systemd), він не успадковує середовище + вашої shell. Виправити це можна одним із таких способів: - 1. Покладіть token у `~/.openclaw/.env`: + 1. Помістіть токен у `~/.openclaw/.env`: ``` COPILOT_GITHUB_TOKEN=... ``` - 2. Або увімкніть імпорт оболонки (`env.shellEnv.enabled: true`). - 3. Або додайте його в блок `env` конфігурації (застосовується лише якщо бракує). + 2. Або увімкніть імпорт shell (`env.shellEnv.enabled: true`). + 3. Або додайте його до блоку `env` у config (застосовується лише якщо відсутній). Потім перезапустіть gateway і перевірте знову: @@ -1977,18 +1977,18 @@ x-i18n: -## Сесії та кілька чатів +## Sessions і кілька чатів - Надішліть `/new` або `/reset` як окреме повідомлення. Див. [Керування session](/uk/concepts/session). + Надішліть `/new` або `/reset` окремим повідомленням. Див. [Керування session](/uk/concepts/session). - - Сесії можуть завершуватися після `session.idleMinutes`, але за замовчуванням це **вимкнено** (типове значення **0**). - Установіть додатне значення, щоб увімкнути завершення через неактивність. Коли це ввімкнено, **наступне** - повідомлення після періоду неактивності починає новий ID session для цього chat key. - Це не видаляє transcript-и — лише починає нову session. + + Sessions можуть завершуватися після `session.idleMinutes`, але за замовчуванням це **вимкнено** (типове значення **0**). + Установіть додатне значення, щоб увімкнути завершення через бездіяльність. Коли це ввімкнено, **наступне** + повідомлення після періоду бездіяльності починає новий ідентифікатор session для цього chat key. + Це не видаляє transcript — лише починає нову session. ```json5 { @@ -2000,41 +2000,41 @@ x-i18n: - - Так, через **маршрутизацію мультиагентності** та **sub-agents**. Ви можете створити одного координатора - та кількох worker-агентів із власними workspace і моделями. + + Так, через **маршрутизацію multi-agent** і **sub-agents**. Ви можете створити одного координуючого + agent і кілька worker-agents із власними workspace і models. - Утім, це краще сприймати як **цікавий експеримент**. Він важкий на токени й часто - менш ефективний, ніж використання одного бота з окремими сесіями. Типова модель, яку ми - уявляємо, — це один бот, з яким ви розмовляєте, і різні сесії для паралельної роботи. Такий - бот також може за потреби породжувати sub-agents. + Водночас це краще сприймати як **цікавий експеримент**. Це витрачає багато токенів і часто + менш ефективно, ніж використання одного бота з окремими sessions. Типова модель, яку ми + уявляємо, — це один бот, з яким ви спілкуєтеся, з різними sessions для паралельної роботи. Цей + бот також може запускати sub-agents за потреби. - Документація: [Маршрутизація мультиагентності](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [CLI для Agents](/cli/agents). + Документація: [Маршрутизація multi-agent](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [Agents CLI](/cli/agents). - - Контекст session обмежений вікном моделі. Довгі chat-и, великі виводи інструментів або багато - файлів можуть спричинити compaction або truncation. + + Контекст session обмежено вікном моделі. Довгі чати, великі виводи інструментів або багато + файлів можуть спричинити Compaction або обрізання. Що допомагає: - Попросіть бота підсумувати поточний стан і записати його у файл. - - Використовуйте `/compact` перед довгими задачами, а `/new` — при зміні теми. - - Тримайте важливий контекст у workspace і просіть бота перечитувати його. - - Використовуйте sub-agents для довгих або паралельних задач, щоб основний chat залишався меншим. - - Виберіть модель із більшим вікном контексту, якщо це трапляється часто. + - Використовуйте `/compact` перед довгими завданнями, а `/new` — під час зміни теми. + - Зберігайте важливий контекст у workspace і просіть бота перечитувати його. + - Використовуйте sub-agents для довгої або паралельної роботи, щоб main chat залишався меншим. + - Виберіть model із більшим вікном контексту, якщо це трапляється часто. - Використовуйте команду reset: + Використовуйте команду скидання: ```bash openclaw reset ``` - Неінтерактивне повне скидання: + Повне неінтерактивне скидання: ```bash openclaw reset --scope full --yes --non-interactive @@ -2048,14 +2048,14 @@ x-i18n: Примітки: - - Онбординг також пропонує **Reset**, якщо бачить наявну конфігурацію. Див. [Онбординг (CLI)](/uk/start/wizard). - - Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скидайте кожен state dir (типово це `~/.openclaw-`). - - Скидання dev: `openclaw gateway --dev --reset` (лише для dev; стирає dev config + credentials + sessions + workspace). + - Onboarding також пропонує **Reset**, якщо виявляє наявну config. Див. [Onboarding (CLI)](/uk/start/wizard). + - Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скиньте кожен state dir (типово це `~/.openclaw-`). + - Скидання для dev: `openclaw gateway --dev --reset` (лише для dev; очищає config dev + облікові дані + sessions + workspace). - - Використайте один із варіантів: + + Використайте один із цих варіантів: - **Compact** (зберігає розмову, але підсумовує старіші ходи): @@ -2063,35 +2063,35 @@ x-i18n: /compact ``` - або `/compact `, щоб скерувати підсумок. + або `/compact `, щоб керувати підсумком. - - **Reset** (новий ID session для того самого chat key): + - **Скидання** (новий ідентифікатор session для того самого chat key): ``` /new /reset ``` - Якщо це продовжується: + Якщо це повторюється: - - Увімкніть або налаштуйте **обрізання session** (`agents.defaults.contextPruning`), щоб скоротити старий вивід інструментів. - - Використовуйте модель із більшим вікном контексту. + - Увімкніть або налаштуйте **session pruning** (`agents.defaults.contextPruning`), щоб обрізати старий вивід інструментів. + - Використовуйте model із більшим вікном контексту. - Документація: [Compaction](/uk/concepts/compaction), [Обрізання session](/uk/concepts/session-pruning), [Керування session](/uk/concepts/session). + Документація: [Compaction](/uk/concepts/compaction), [Session pruning](/uk/concepts/session-pruning), [Керування session](/uk/concepts/session). - Це помилка перевірки провайдера: модель видала блок `tool_use` без обов’язкового - `input`. Зазвичай це означає, що історія session застаріла або пошкоджена (часто після довгих thread-ів - або зміни tool/schema). + Це помилка перевірки provider: модель згенерувала блок `tool_use` без обов’язкового + `input`. Зазвичай це означає, що історія session застаріла або пошкоджена (часто після довгих thread + або зміни інструмента/schema). - Виправлення: почніть нову session через `/new` (окреме повідомлення). + Виправлення: почніть нову session командою `/new` (окремим повідомленням). - Heartbeat-и запускаються кожні **30m** за замовчуванням (**1h** при використанні OAuth auth). Налаштуйте або вимкніть їх: + Heartbeat запускається кожні **30m** за замовчуванням (**1h** при використанні auth через OAuth). Налаштуйте або вимкніть їх: ```json5 { @@ -2105,19 +2105,19 @@ x-i18n: } ``` - Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки та markdown - заголовки на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб заощадити API calls. - Якщо файл відсутній, heartbeat усе одно запускається, і модель сама вирішує, що робити. + Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки й markdown-заголовки + на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб заощадити API-виклики. + Якщо файл відсутній, heartbeat усе одно запускається, і модель вирішує, що робити. - Override-и для агента використовують `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). + Override для окремого agent використовують `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). - - Ні. OpenClaw працює від **вашого власного облікового запису**, тож якщо ви є в групі, OpenClaw може її бачити. - За замовчуванням відповіді в групах блокуються, доки ви не дозволите відправників (`groupPolicy: "allowlist"`). + + Ні. OpenClaw працює від **вашого власного облікового запису**, тому якщо ви є в групі, OpenClaw може її бачити. + За замовчуванням відповіді в групах заблоковані, доки ви не дозволите відправників (`groupPolicy: "allowlist"`). - Якщо ви хочете, щоб запускати відповіді в групі могли лише **ви**: + Якщо ви хочете, щоб відповідати в групах могли запускати лише **ви**: ```json5 { @@ -2133,77 +2133,1173 @@ x-i18n: - Варіант 1 (найшвидше): дивіться хвіст журналів і надішліть тестове повідомлення в групу: + Варіант 1 (найшвидший): перегляньте хвіст логів і надішліть тестове повідомлення в групу: ```bash openclaw logs --follow --json ``` - Шукайте `chatId` (або `from`), що закінчується на `@g.us`, наприклад: + Знайдіть `chatId` (або `from`), що закінчується на `@g.us`, наприклад: `1234567890-1234567890@g.us`. - Варіант 2 (якщо вже налаштовано/додано до allowlist): перелічіть групи з конфігурації: + Варіант 2 (якщо вже налаштовано/додано в allowlist): перелічіть групи з config: ```bash openclaw directory groups list --channel whatsapp ``` - Документація: [WhatsApp](/uk/channels/whatsapp), [Directory](/cli/directory), [Журнали](/cli/logs). + Документація: [WhatsApp](/uk/channels/whatsapp), [Directory](/cli/directory), [Logs](/cli/logs). Дві поширені причини: - - Увімкнено gating за згадками (типово). Ви маєте @згадати бота (або збігтися з `mentionPatterns`). - - Ви налаштували `channels.whatsapp.groups` без `"*"`, і групу не додано до allowlist. + - Увімкнено обмеження за згадкою (типово). Ви маєте @згадати бота (або відповідати `mentionPatterns`). + - Ви налаштували `channels.whatsapp.groups` без `"*"`, і цю групу не додано до allowlist. - Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). + Див. [Groups](/uk/channels/groups) і [Group messages](/uk/channels/group-messages). - - Прямі chat-и за замовчуванням згортаються в основну session. Групи/канали мають власні session key, а теми Telegram / thread-и Discord — це окремі session. Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). + + Прямі чати за замовчуванням згортаються до main session. Groups/channels мають власні ключі session, а topics Telegram / threads Discord — це окремі sessions. Див. [Groups](/uk/channels/groups) і [Group messages](/uk/channels/group-messages). - - Жорстких лімітів немає. Десятки (навіть сотні) — нормально, але стежте за: + + Жорстких обмежень немає. Десятки (навіть сотні) — це нормально, але звертайте увагу на: - - **Зростанням диска:** sessions + transcript-и живуть у `~/.openclaw/agents//sessions/`. - - **Вартістю токенів:** більше агентів означає більше одночасного використання моделей. - - **Операційними накладними витратами:** профілі auth для кожного агента, workspace і маршрутизація каналів. + - **Зростання диска:** sessions + transcripts живуть у `~/.openclaw/agents//sessions/`. + - **Витрати токенів:** більше agents означає більше одночасного використання моделей. + - **Операційні накладні витрати:** auth profiles, workspace та маршрутизація channel для кожного agent. Поради: - - Тримайте один **активний** workspace на агента (`agents.defaults.workspace`). - - Обрізайте старі sessions (видаляйте JSONL або записи сховища), якщо диск росте. - - Використовуйте `openclaw doctor`, щоб знаходити зайві workspace та невідповідності профілів. + - Тримайте один **активний** workspace на agent (`agents.defaults.workspace`). + - Очищуйте старі sessions (видаляйте JSONL або записи сховища), якщо диск розростається. + - Використовуйте `openclaw doctor`, щоб виявляти зайві workspace і невідповідності профілів. - Так. Використовуйте **Маршрутизацію мультиагентності**, щоб запускати кількох ізольованих агентів і маршрутизувати вхідні повідомлення за - каналом/обліковим записом/peer. Slack підтримується як канал і може бути прив’язаний до конкретних агентів. + Так. Використовуйте **Маршрутизацію Multi-Agent**, щоб запускати кілька ізольованих agents і спрямовувати вхідні повідомлення за + channel/account/peer. Slack підтримується як channel і може бути прив’язаний до конкретних agents. - Доступ до browser потужний, але це не «зробити все, що може людина» — anti-bot, CAPTCHA і MFA - усе ще можуть блокувати автоматизацію. Для найнадійнішого керування browser використовуйте локальний Chrome MCP на host, - або використовуйте CDP на машині, де browser реально працює. + Доступ до браузера потужний, але не означає "може зробити все, що людина" — anti-bot, CAPTCHA і MFA + усе ще можуть блокувати автоматизацію. Для найнадійнішого керування браузером використовуйте локальний Chrome MCP на хості, + або використовуйте CDP на машині, яка фактично запускає браузер. - Рекомендоване налаштування: + Найкраща практика налаштування: - - Завжди ввімкнений gateway host (VPS/Mac mini). - - Один агент на роль (bindings). - - Slack channel(и), прив’язані до цих агентів. - - Локальний browser через Chrome MCP або node, коли потрібно. + - Постійно ввімкнений хост Gateway (VPS/Mac mini). + - Один agent на роль (bindings). + - Channels Slack, прив’язані до цих agents. + - Локальний браузер через Chrome MCP або node за потреби. - Документація: [Маршрутизація мультиагентності](/uk/concepts/multi-agent), [Slack](/uk/channels/slack), + Документація: [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [Slack](/uk/channels/slack), [Browser](/uk/tools/browser), [Nodes](/uk/nodes). -## Моделі: типові значення, вибір, псевдоніми, перемикання +## Models: типові значення, вибір, псевдоніми, перемикання - - default model у OpenClaw — це те, що \ No newline at end of file + + Модель за замовчуванням в OpenClaw — це те, що ви задаєте як: + + ``` + agents.defaults.model.primary + ``` + + На models посилаються як `provider/model` (приклад: `openai/gpt-5.4`). Якщо ви пропускаєте provider, OpenClaw спочатку намагається знайти псевдонім, потім — унікальний збіг точно цього model id серед налаштованих providers, і лише після цього використовує налаштований provider за замовчуванням як застарілий шлях сумісності. Якщо цей provider більше не надає налаштовану model за замовчуванням, OpenClaw переключається на перші налаштовані provider/model замість того, щоб показувати застаріле типове значення видаленого provider. Вам усе одно слід **явно** задавати `provider/model`. + + + + + **Рекомендоване типове значення:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку provider. + **Для agents з увімкненими інструментами або agents з недовіреним входом:** ставте силу model вище за вартість. + **Для звичайного/низькоризикового чату:** використовуйте дешевші резервні models і маршрутизуйте за роллю agent. + + Для MiniMax є окрема документація: [MiniMax](/uk/providers/minimax) і + [Локальні моделі](/uk/gateway/local-models). + + Практичне правило: використовуйте **найкращу model, яку можете собі дозволити** для важливих завдань, і дешевшу + model для повсякденного чату або підсумків. Ви можете маршрутизувати models за agent і використовувати sub-agents для + паралелізації довгих завдань (кожен sub-agent споживає токени). Див. [Models](/uk/concepts/models) і + [Sub-agents](/uk/tools/subagents). + + Серйозне попередження: слабші/надмірно квантизовані models більш вразливі до prompt + injection і небезпечної поведінки. Див. [Security](/uk/gateway/security). + + Більше контексту: [Models](/uk/concepts/models). + + + + + Використовуйте **команди model** або редагуйте лише поля **model**. Уникайте повної заміни config. + + Безпечні варіанти: + + - `/model` у чаті (швидко, для поточної session) + - `openclaw models set ...` (оновлює лише config model) + - `openclaw configure --section model` (інтерактивно) + - редагуйте `agents.defaults.model` у `~/.openclaw/openclaw.json` + + Уникайте `config.apply` із частковим об’єктом, якщо ви не збираєтеся замінити всю config. + Для редагувань через RPC спочатку перевіряйте через `config.schema.lookup` і надавайте перевагу `config.patch`. Дані lookup дають нормалізований шлях, документацію/обмеження неглибокої schema та підсумки безпосередніх дочірніх елементів + для часткових оновлень. + Якщо ви таки перезаписали config, відновіть її з резервної копії або повторно запустіть `openclaw doctor` для виправлення. + + Документація: [Models](/uk/concepts/models), [Configure](/cli/configure), [Config](/cli/config), [Doctor](/uk/gateway/doctor). + + + + + Так. Ollama — найпростіший шлях до локальних models. + + Найшвидше налаштування: + + 1. Установіть Ollama з `https://ollama.com/download` + 2. Завантажте локальну model, наприклад `ollama pull gemma4` + 3. Якщо вам потрібні також хмарні models, виконайте `ollama signin` + 4. Запустіть `openclaw onboard` і виберіть `Ollama` + 5. Виберіть `Local` або `Cloud + Local` + + Примітки: + + - `Cloud + Local` надає вам хмарні models плюс локальні models Ollama + - хмарні models, як-от `kimi-k2.5:cloud`, не потребують локального завантаження + - для ручного перемикання використовуйте `openclaw models list` і `openclaw models set ollama/` + + Примітка щодо безпеки: менші або сильно квантизовані models більш вразливі до prompt + injection. Ми наполегливо рекомендуємо **великі models** для будь-якого бота, який може використовувати інструменти. + Якщо ви все ж хочете маленькі models, увімкніть sandboxing і суворі allowlist інструментів. + + Документація: [Ollama](/uk/providers/ollama), [Локальні моделі](/uk/gateway/local-models), + [Провайдери моделей](/uk/concepts/model-providers), [Security](/uk/gateway/security), + [Ізоляція](/uk/gateway/sandboxing). + + + + + - У цих розгортаннях можуть бути різні налаштування, і вони можуть змінюватися з часом; фіксованої рекомендації щодо provider немає. + - Перевіряйте поточне налаштування runtime на кожному gateway через `openclaw models status`. + - Для agents із чутливими до безпеки/увімкненими інструментами використовуйте найсильнішу модель останнього покоління з доступних. + + + + Використовуйте команду `/model` як окреме повідомлення: + + ``` + /model sonnet + /model opus + /model gpt + /model gpt-mini + /model gemini + /model gemini-flash + /model gemini-flash-lite + ``` + + Це вбудовані псевдоніми. Користувацькі псевдоніми можна додавати через `agents.defaults.models`. + + Ви можете переглянути доступні models через `/model`, `/model list` або `/model status`. + + `/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 буде спробовано наступним. + Він також показує налаштовану кінцеву точку provider (`baseUrl`) і режим API (`api`), коли це доступно. + + **Як зняти фіксацію profile, який я задав через @profile?** + + Повторно запустіть `/model` **без** суфікса `@profile`: + + ``` + /model anthropic/claude-opus-4-6 + ``` + + Якщо ви хочете повернутися до типового значення, виберіть його через `/model` (або надішліть `/model `). + Використовуйте `/model status`, щоб підтвердити, який auth profile активний. + + + + + Так. Установіть одну як типову й перемикайтеся за потреби: + + - **Швидке перемикання (для session):** `/model gpt-5.4` для щоденних завдань, `/model openai-codex/gpt-5.4` для кодування з OAuth Codex. + - **Типове значення + перемикання:** задайте `agents.defaults.model.primary` як `openai/gpt-5.4`, а потім перемикайтеся на `openai-codex/gpt-5.4` під час кодування (або навпаки). + - **Sub-agents:** спрямовуйте завдання кодування до sub-agents з іншою model за замовчуванням. + + Див. [Models](/uk/concepts/models) і [Slash-команди](/uk/tools/slash-commands). + + + + + Використовуйте або перемикач для session, або типове значення в config: + + - **Для session:** надішліть `/fast on`, поки session використовує `openai/gpt-5.4` або `openai-codex/gpt-5.4`. + - **Типове значення для model:** задайте `agents.defaults.models["openai/gpt-5.4"].params.fastMode` як `true`. + - **Також для OAuth Codex:** якщо ви також використовуєте `openai-codex/gpt-5.4`, задайте там той самий прапорець. + + Приклад: + + ```json5 + { + agents: { + defaults: { + models: { + "openai/gpt-5.4": { + params: { + fastMode: true, + }, + }, + "openai-codex/gpt-5.4": { + params: { + fastMode: true, + }, + }, + }, + }, + }, + } + ``` + + Для OpenAI fast mode відповідає `service_tier = "priority"` у підтримуваних нативних запитах Responses. Session `/fast` має вищий пріоритет за типові значення config. + + Див. [Thinking and fast mode](/uk/tools/thinking) і [OpenAI fast mode](/uk/providers/openai#openai-fast-mode). + + + + + Якщо задано `agents.defaults.models`, це стає **allowlist** для `/model` і будь-яких + override session. Вибір model, якої немає в цьому списку, повертає: + + ``` + Model "provider/model" is not allowed. Use /model to list available models. + ``` + + Ця помилка повертається **замість** звичайної відповіді. Виправлення: додайте model до + `agents.defaults.models`, приберіть allowlist або виберіть model через `/model list`. + + + + + Це означає, що **provider не налаштовано** (не знайдено config provider MiniMax або auth + profile), тому model не вдається визначити. + + Чекліст для виправлення: + + 1. Оновіться до актуального релізу OpenClaw (або працюйте з вихідного коду `main`), а потім перезапустіть gateway. + 2. Переконайтеся, що MiniMax налаштовано (майстром або через JSON), або що auth MiniMax + існує в env/auth profiles, щоб відповідний provider можна було додати + (`MINIMAX_API_KEY` для `minimax`, `MINIMAX_OAUTH_TOKEN` або збережений OAuth MiniMax + для `minimax-portal`). + 3. Використовуйте точний id model (з урахуванням регістру) для вашого шляху auth: + `minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed` для налаштування через API-ключ, + або `minimax-portal/MiniMax-M2.7` / + `minimax-portal/MiniMax-M2.7-highspeed` для налаштування через OAuth. + 4. Виконайте: + + ```bash + openclaw models list + ``` + + і виберіть зі списку (або `/model list` у чаті). + + Див. [MiniMax](/uk/providers/minimax) і [Models](/uk/concepts/models). + + + + + Так. Використовуйте **MiniMax як типову** і перемикайте models **для session** за потреби. + Резервні варіанти призначені для **помилок**, а не для "складних завдань", тому використовуйте `/model` або окремого agent. + + **Варіант A: перемикання для session** + + ```json5 + { + env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." }, + agents: { + defaults: { + model: { primary: "minimax/MiniMax-M2.7" }, + models: { + "minimax/MiniMax-M2.7": { alias: "minimax" }, + "openai/gpt-5.4": { alias: "gpt" }, + }, + }, + }, + } + ``` + + Потім: + + ``` + /model gpt + ``` + + **Варіант B: окремі agents** + + - Типова model для Agent A: MiniMax + - Типова model для Agent B: OpenAI + - Маршрутизуйте за agent або використовуйте `/agent` для перемикання + + Документація: [Models](/uk/concepts/models), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [MiniMax](/uk/providers/minimax), [OpenAI](/uk/providers/openai). + + + + + Так. OpenClaw постачається з кількома типовими скороченнями (застосовуються лише тоді, коли model існує в `agents.defaults.models`): + + - `opus` → `anthropic/claude-opus-4-6` + - `sonnet` → `anthropic/claude-sonnet-4-6` + - `gpt` → `openai/gpt-5.4` + - `gpt-mini` → `openai/gpt-5.4-mini` + - `gpt-nano` → `openai/gpt-5.4-nano` + - `gemini` → `google/gemini-3.1-pro-preview` + - `gemini-flash` → `google/gemini-3-flash-preview` + - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` + + Якщо ви задаєте власний псевдонім із такою самою назвою, перемагає ваше значення. + + + + + Псевдоніми беруться з `agents.defaults.models..alias`. Приклад: + + ```json5 + { + agents: { + defaults: { + model: { primary: "anthropic/claude-opus-4-6" }, + models: { + "anthropic/claude-opus-4-6": { alias: "opus" }, + "anthropic/claude-sonnet-4-6": { alias: "sonnet" }, + "anthropic/claude-haiku-4-5": { alias: "haiku" }, + }, + }, + }, + } + ``` + + Тоді `/model sonnet` (або `/`, коли це підтримується) розв’язується в цей ID model. + + + + + OpenRouter (оплата за токени; багато models): + + ```json5 + { + agents: { + defaults: { + model: { primary: "openrouter/anthropic/claude-sonnet-4-6" }, + models: { "openrouter/anthropic/claude-sonnet-4-6": {} }, + }, + }, + env: { OPENROUTER_API_KEY: "sk-or-..." }, + } + ``` + + Z.AI (models GLM): + + ```json5 + { + agents: { + defaults: { + model: { primary: "zai/glm-5" }, + models: { "zai/glm-5": {} }, + }, + }, + env: { ZAI_API_KEY: "..." }, + } + ``` + + Якщо ви посилаєтеся на provider/model, але потрібний ключ provider відсутній, ви отримаєте помилку auth під час виконання (наприклад, `No API key found for provider "zai"`). + + **Після додавання нового agent не знайдено API-ключ для provider** + + Зазвичай це означає, що **новий agent** має порожнє сховище auth. Auth є прив’язаною до agent і + зберігається тут: + + ``` + ~/.openclaw/agents//agent/auth-profiles.json + ``` + + Варіанти виправлення: + + - Виконайте `openclaw agents add ` і налаштуйте auth у майстрі. + - Або скопіюйте `auth-profiles.json` з `agentDir` головного agent до `agentDir` нового agent. + + **Не** використовуйте спільний `agentDir` для кількох agents; це спричиняє конфлікти auth/session. + + + + +## Резервне перемикання model і "All models failed" + + + + Резервне перемикання відбувається у два етапи: + + 1. **Ротація auth profile** у межах того самого provider. + 2. **Резервний перехід model** до наступної model у `agents.defaults.model.fallbacks`. + + До невдалих profiles застосовуються cooldown (експоненційне збільшення затримки), тож OpenClaw може продовжувати відповідати, навіть коли provider обмежений rate limit або тимчасово не працює. + + Кошик rate limit включає не лише звичайні відповіді `429`. OpenClaw + також вважає повідомлення на кшталт `Too many concurrent requests`, + `ThrottlingException`, `concurrency limit reached`, + `workers_ai ... quota limit exceeded`, `resource exhausted` і періодичні + обмеження вікна використання (`weekly/monthly limit reached`) такими, що + варті резервного перемикання через rate limit. + + Деякі відповіді, схожі на billing, не є `402`, а деякі HTTP-відповіді `402` + також залишаються в цьому тимчасовому кошику. Якщо provider повертає + явний billing-текст на `401` або `403`, OpenClaw усе ще може тримати це + в категорії billing, але текстові зіставлення, специфічні для provider, залишаються в межах + provider, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Якщо повідомлення `402` + натомість схоже на повторюване вікно використання або + ліміт витрат organization/workspace (`daily limit reached, resets tomorrow`, + `organization spending limit exceeded`), OpenClaw трактує це як + `rate_limit`, а не як довге відключення через billing. + + Помилки переповнення контексту відрізняються: сигнатури на кшталт + `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/повторної спроби замість переходу + до резервної model. + + Загальний текст помилок сервера навмисно вужчий, ніж "усе, де є + unknown/error". OpenClaw вважає гідними резервного перемикання такі + залежні від provider тимчасові форми, як-от bare Anthropic `An unknown error occurred`, bare OpenRouter + `Provider returned error`, помилки причини зупинки на кшталт `Unhandled stop reason: + error`, JSON-пейлоади `api_error` із текстом тимчасових серверних помилок + (`internal server error`, `unknown error, 520`, `upstream error`, `backend + error`) і помилки перевантаження provider на кшталт `ModelNotReadyException` — якщо контекст provider + збігається. + Загальний внутрішній запасний текст на кшталт `LLM request failed with an unknown + error.` залишається консервативним і сам по собі не запускає резервне перемикання model. + + + + + Це означає, що система спробувала використати ID auth profile `anthropic:default`, але не змогла знайти для нього облікові дані в очікуваному сховищі auth. + + **Чекліст для виправлення:** + + - **Перевірте, де зберігаються auth profiles** (нові та застарілі шляхи) + - Поточний шлях: `~/.openclaw/agents//agent/auth-profiles.json` + - Застарілий шлях: `~/.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`, щоб побачити налаштовані models і чи пройшли providers автентифікацію. + + **Чекліст для виправлення "No credentials found for profile anthropic"** + + Це означає, що виконання прив’язане до auth profile Anthropic, але Gateway + не може знайти його у своєму сховищі auth. + + - **Використовуйте Claude CLI** + - Виконайте `openclaw models auth login --provider anthropic --method cli --set-default` на хості gateway. + - **Якщо ви хочете використовувати натомість API-ключ** + - Помістіть `ANTHROPIC_API_KEY` у `~/.openclaw/.env` на **хості gateway**. + - Очистьте будь-який зафіксований порядок, що примусово вимагає відсутній profile: + + ```bash + openclaw models auth order clear --provider anthropic + ``` + + - **Переконайтеся, що запускаєте команди на хості gateway** + - У віддаленому режимі auth profiles живуть на машині gateway, а не на вашому ноутбуці. + + + + + Якщо ваша config model містить Google Gemini як резервний варіант (або ви перемкнулися на скорочення Gemini), OpenClaw спробує її під час резервного перемикання model. Якщо ви не налаштували облікові дані Google, побачите `No API key found for provider "google"`. + + Виправлення: або надайте auth Google, або приберіть/уникайте models Google у `agents.defaults.model.fallbacks` / псевдонімах, щоб резервне перемикання не спрямовувалося туди. + + **LLM request rejected: thinking signature required (Google Antigravity)** + + Причина: історія session містить **блоки thinking без signatures** (часто через + перерваний/частковий потік). Google Antigravity вимагає signatures для блоків thinking. + + Виправлення: тепер OpenClaw видаляє блоки thinking без signatures для Claude Google Antigravity. Якщо це все ще з’являється, почніть **нову session** або задайте `/thinking off` для цього agent. + + + + +## Auth profiles: що це таке і як ними керувати + +Пов’язане: [/concepts/oauth](/uk/concepts/oauth) (OAuth-потоки, зберігання токенів, шаблони для кількох облікових записів) + + + + Auth profile — це іменований запис облікових даних (OAuth або API-ключ), прив’язаний до provider. Profiles зберігаються тут: + + ``` + ~/.openclaw/agents//agent/auth-profiles.json + ``` + + + + + OpenClaw використовує ID з префіксом provider, наприклад: + + - `anthropic:default` (поширений варіант, коли немає email-ідентичності) + - `anthropic:` для OAuth-ідентичностей + - користувацькі ID на ваш вибір (наприклад, `anthropic:work`) + + + + + Так. Config підтримує необов’язкові metadata для profiles і порядок для кожного provider (`auth.order.`). Це **не** зберігає секрети; воно зіставляє ID із provider/mode і задає порядок ротації. + + OpenClaw може тимчасово пропустити profile, якщо вона перебуває в короткому **cooldown** (rate limits/timeouts/auth failures) або в довшому стані **disabled** (billing/недостатньо кредитів). Щоб перевірити це, виконайте `openclaw models status --json` і перевірте `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`. + + Cooldown через rate limit можуть бути прив’язані до model. Profile, яка перебуває в cooldown + для однієї model, усе ще може бути придатною для спорідненої model у межах того самого provider, + тоді як billing/disabled-вікна все ще блокують увесь profile. + + Ви також можете задати **override порядку для agent** (зберігається в `auth-state.json` цього agent) через CLI: + + ```bash + # За замовчуванням використовує налаштований default 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) + 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 замість того, щоб тихо його пробувати. + + + + + OpenClaw підтримує обидва варіанти: + + - **OAuth** часто використовує доступ за підпискою (де це застосовно). + - **API-ключі** використовують білінг pay-per-token. + + Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і API-ключі. + + + + +## Gateway: порти, "already running" і віддалений режим + + + + `gateway.port` керує єдиним мультиплексованим портом для WebSocket + HTTP (Control UI, hooks тощо). + + Пріоритет: + + ``` + --port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789 + ``` + + + + + Тому що "running" — це погляд **supervisor** (launchd/systemd/schtasks). RPC probe — це коли CLI фактично підключається до gateway WebSocket і викликає `status`. + + Використовуйте `openclaw gateway status` і довіряйте цим рядкам: + + - `Probe target:` (URL, який probe фактично використав) + - `Listening:` (що насправді прив’язано до порту) + - `Last gateway error:` (типова першопричина, коли процес живий, але порт не слухає) + + + + + Ви редагуєте один файл config, а сервіс працює з іншим (часто через невідповідність `--profile` / `OPENCLAW_STATE_DIR`). + + Виправлення: + + ```bash + openclaw gateway install --force + ``` + + Запустіть це з тим самим `--profile` / середовищем, яке сервіс має використовувати. + + + + + OpenClaw забезпечує блокування runtime, одразу прив’язуючи слухач WebSocket під час запуску (типово `ws://127.0.0.1:18789`). Якщо прив’язка завершується помилкою `EADDRINUSE`, викидається `GatewayLockError`, що означає: інший інстанс уже слухає. + + Виправлення: зупиніть інший інстанс, звільніть порт або запустіть з `openclaw gateway --port `. + + + + + Установіть `gateway.mode: "remote"` і вкажіть URL віддаленого WebSocket, за потреби з віддаленими обліковими даними shared secret: + + ```json5 + { + gateway: { + mode: "remote", + remote: { + url: "ws://gateway.tailnet:18789", + token: "your-token", + password: "your-password", + }, + }, + } + ``` + + Примітки: + + - `openclaw gateway` запускається лише тоді, коли `gateway.mode` має значення `local` (або якщо ви передаєте прапорець перевизначення). + - macOS app відстежує файл config і в реальному часі перемикає режими, коли ці значення змінюються. + - `gateway.remote.token` / `.password` — це лише клієнтські віддалені облікові дані; вони самі по собі не вмикають локальну auth gateway. + + + + + Ваш шлях auth gateway і метод auth UI не збігаються. + + Факти (з коду): + + - Control UI зберігає токен у `sessionStorage` для поточної session вкладки браузера та вибраного URL gateway, тож оновлення в тій самій вкладці продовжують працювати без відновлення довготривалого зберігання токена в localStorage. + - За `AUTH_TOKEN_MISMATCH` довірені клієнти можуть виконати одну обмежену повторну спробу з кешованим токеном пристрою, коли gateway повертає підказки для повтору (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). + - Ця повторна спроба з кешованим токеном тепер повторно використовує кешовані схвалені scopes, збережені разом із токеном пристрою. Явні виклики `deviceToken` / явні `scopes` усе ще зберігають свій запитаний набір scope замість успадкування кешованих scopes. + - Поза цим шляхом повтору пріоритет auth під час підключення такий: спочатку явний shared token/password, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap token. + - Перевірки scope bootstrap token мають префікси ролей. Вбудований allowlist bootstrap operator задовольняє лише запити operator; node або інші ролі не-operator усе ще потребують scopes із префіксом власної ролі. + + Виправлення: + + - Найшвидше: `openclaw dashboard` (виводить + копіює URL dashboard, намагається відкрити; у headless показує підказку щодо SSH). + - Якщо у вас ще немає токена: `openclaw doctor --generate-gateway-token`. + - Якщо віддалено, спочатку налаштуйте 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, а не сирий URL loopback/tailnet, який оминає заголовки ідентичності Tailscale. + - Режим trusted-proxy: переконайтеся, що ви заходите через налаштований identity-aware proxy не на loopback, а не через loopback proxy на тому самому хості чи сирий URL gateway. + - Якщо невідповідність зберігається після однієї повторної спроби, перевипустіть/пересхваліть токен підключеного пристрою: + - `openclaw devices list` + - `openclaw devices rotate --device --role operator` + - Якщо цей виклик rotate каже, що в ньому відмовлено, перевірте дві речі: + - sessions paired-device можуть перевипускати лише **власний** пристрій, якщо в них також немає `operator.admin` + - явні значення `--scope` не можуть перевищувати поточні операторські scopes викликача + - Досі застрягли? Виконайте `openclaw status --all` і дотримуйтеся [Усунення проблем](/uk/gateway/troubleshooting). Подробиці auth див. у [Dashboard](/web/dashboard). + + + + + Прив’язка `tailnet` вибирає IP-адресу Tailscale з мережевих інтерфейсів (100.64.0.0/10). Якщо машина не підключена до Tailscale (або інтерфейс вимкнений), прив’язуватися немає до чого. + + Виправлення: + + - Запустіть Tailscale на цьому хості (щоб він мав адресу 100.x), або + - Перемкніться на `gateway.bind: "loopback"` / `"lan"`. + + Примітка: `tailnet` задається явно. `auto` віддає перевагу loopback; використовуйте `gateway.bind: "tailnet"`, коли хочете прив’язку лише до tailnet. + + + + + Зазвичай ні — один Gateway може обслуговувати кілька messaging channels і agents. Використовуйте кілька Gateway лише тоді, коли вам потрібна надлишковість (наприклад, резервний бот) або жорстка ізоляція. + + Так, але потрібно ізолювати: + + - `OPENCLAW_CONFIG_PATH` (config для кожного інстансу) + - `OPENCLAW_STATE_DIR` (state для кожного інстансу) + - `agents.defaults.workspace` (ізоляція workspace) + - `gateway.port` (унікальні порти) + + Швидке налаштування (рекомендовано): + + - Використовуйте `openclaw --profile ...` для кожного інстансу (автоматично створює `~/.openclaw-`). + - Установіть унікальний `gateway.port` у config кожного профілю (або передайте `--port` для ручних запусків). + - Установіть сервіс для кожного профілю: `openclaw --profile gateway install`. + + Profiles також додають суфікси до назв сервісів (`ai.openclaw.`; застарілі `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). + Повний посібник: [Кілька gateway](/uk/gateway/multiple-gateways). + + + + + Gateway — це **сервер WebSocket**, і він очікує, що найпершим повідомленням + буде frame `connect`. Якщо він отримує щось інше, то закриває з’єднання + з **code 1008** (порушення політики). + + Поширені причини: + + - Ви відкрили **HTTP** URL у браузері (`http://...`) замість клієнта WS. + - Ви використали неправильний порт або шлях. + - Proxy або tunnel прибрав auth headers або надіслав запит, який не є запитом Gateway. + + Швидкі виправлення: + + 1. Використовуйте URL WS: `ws://:18789` (або `wss://...`, якщо HTTPS). + 2. Не відкривайте порт WS у звичайній вкладці браузера. + 3. Якщо auth увімкнено, додайте token/password у frame `connect`. + + Якщо ви використовуєте CLI або TUI, URL має виглядати так: + + ``` + openclaw tui --url ws://:18789 --token + ``` + + Подробиці протоколу: [Протокол Gateway](/uk/gateway/protocol). + + + + +## Logging і налагодження + + + + Файлові логи (структуровані): + + ``` + /tmp/openclaw/openclaw-YYYY-MM-DD.log + ``` + + Ви можете задати стабільний шлях через `logging.file`. Рівень file log визначається через `logging.level`. Докладність консолі контролюється через `--verbose` і `logging.consoleLevel`. + + Найшвидший перегляд хвоста логів: + + ```bash + openclaw logs --follow + ``` + + Логи сервісу/supervisor (коли gateway працює через launchd/systemd): + + - macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` і `gateway.err.log` (типово: `~/.openclaw/logs/...`; profiles використовують `~/.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). + + + + + Використовуйте допоміжні команди gateway: + + ```bash + openclaw gateway status + openclaw gateway restart + ``` + + Якщо ви запускаєте gateway вручну, `openclaw gateway --force` може повернути порт. Див. [Gateway](/uk/gateway). + + + + + Існує **два режими встановлення у Windows**: + + **1) WSL2 (рекомендовано):** Gateway працює всередині Linux. + + Відкрийте PowerShell, увійдіть у WSL, а потім перезапустіть: + + ```powershell + wsl + openclaw gateway status + openclaw gateway restart + ``` + + Якщо ви ніколи не встановлювали сервіс, запустіть його на передньому плані: + + ```bash + openclaw gateway run + ``` + + **2) Нативний Windows (не рекомендується):** Gateway працює безпосередньо у Windows. + + Відкрийте PowerShell і виконайте: + + ```powershell + openclaw gateway status + openclaw gateway restart + ``` + + Якщо ви запускаєте його вручну (без сервісу), використовуйте: + + ```powershell + openclaw gateway run + ``` + + Документація: [Windows (WSL2)](/uk/platforms/windows), [Інструкція з роботи сервісу Gateway](/uk/gateway). + + + + + Почніть зі швидкої перевірки стану: + + ```bash + openclaw status + openclaw models status + openclaw channels status + openclaw logs --follow + ``` + + Поширені причини: + + - Auth model не завантажено на **хості gateway** (перевірте `models status`). + - Pairing/allowlist channel блокує відповіді (перевірте config channel + логи). + - WebChat/Dashboard відкрито без правильного токена. + + Якщо ви працюєте віддалено, переконайтеся, що tunnel/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 має правильний токен? `openclaw dashboard` + 4. Якщо віддалено, чи tunnel/Tailscale-з’єднання активне? + + Потім перегляньте хвіст логів: + + ```bash + openclaw logs --follow + ``` + + Документація: [Dashboard](/web/dashboard), [Віддалений доступ](/uk/gateway/remote), [Усунення проблем](/uk/gateway/troubleshooting). + + + + + Почніть із логів і стану channel: + + ```bash + openclaw channels status + openclaw channels logs --channel telegram + ``` + + Далі зіставте помилку: + + - `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. + + Документація: [Telegram](/uk/channels/telegram), [Усунення проблем із channels](/uk/channels/troubleshooting). + + + + + Спочатку переконайтеся, що Gateway доступний і agent може працювати: + + ```bash + openclaw status + openclaw models status + openclaw logs --follow + ``` + + У TUI використовуйте `/status`, щоб побачити поточний стан. Якщо ви очікуєте відповіді в chat + channel, переконайтеся, що доставку ввімкнено (`/deliver on`). + + Документація: [TUI](/web/tui), [Slash-команди](/uk/tools/slash-commands). + + + + + Якщо ви встановили сервіс: + + ```bash + openclaw gateway stop + openclaw gateway start + ``` + + Це зупиняє/запускає **сервіс під керуванням supervisor** (launchd на macOS, systemd на Linux). + Використовуйте це, коли Gateway працює у фоновому режимі як демон. + + Якщо ви запускаєте у foreground, зупиніть через Ctrl-C, а потім: + + ```bash + openclaw gateway run + ``` + + Документація: [Інструкція з роботи сервісу Gateway](/uk/gateway). + + + + + - `openclaw gateway restart`: перезапускає **фоновий сервіс** (launchd/systemd). + - `openclaw gateway`: запускає gateway **у foreground** для цієї сесії термінала. + + Якщо ви встановили сервіс, використовуйте команди gateway. Використовуйте `openclaw gateway`, коли + вам потрібен одноразовий запуск у foreground. + + + + + Запустіть Gateway з `--verbose`, щоб отримати більше деталей у консолі. Потім перевірте файл логу щодо auth channel, маршрутизації model і помилок RPC. + + + +## Медіа та вкладення + + + + Вихідні вкладення від agent мають містити рядок `MEDIA:` (в окремому рядку). Див. [Налаштування помічника OpenClaw](/uk/start/openclaw) і [Agent send](/uk/tools/agent-send). + + Надсилання через CLI: + + ```bash + openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png + ``` + + Також перевірте: + + - Цільовий channel підтримує вихідні медіа і не заблокований allowlist. + - Файл відповідає обмеженням розміру provider (зображення змінюються до максимуму 2048px). + - `tools.fs.workspaceOnly=true` обмежує надсилання локальних шляхів workspace, temp/media-store і файлами, перевіреними sandbox. + - `tools.fs.workspaceOnly=false` дозволяє `MEDIA:` надсилати локальні файли хоста, які agent уже може читати, але лише для медіа плюс безпечних типів документів (зображення, аудіо, відео, PDF та документи Office). Звичайний текст і файли, схожі на секрети, усе одно блокуються. + + Див. [Зображення](/uk/nodes/images). + + + + +## Безпека та контроль доступу + + + + Ставтеся до вхідних DM як до недовіреного вводу. Значення за замовчуванням спроєктовані для зменшення ризику: + + - Типова поведінка на channels, що підтримують DM, — це **pairing**: + - Невідомі відправники отримують код pairing; бот не обробляє їхнє повідомлення. + - Схвалення: `openclaw pairing approve --channel [--account ] ` + - Кількість очікуваних запитів обмежено **3 на channel**; перевіряйте `openclaw pairing list --channel [--account ]`, якщо код не надійшов. + - Публічне відкриття DM потребує явного opt-in (`dmPolicy: "open"` і allowlist `"*"`). + + Запустіть `openclaw doctor`, щоб виявити ризиковані політики DM. + + + + + Ні. Prompt injection стосується **недовіреного вмісту**, а не лише того, хто може надсилати DM боту. + Якщо ваш помічник читає зовнішній вміст (web search/fetch, сторінки браузера, email, + docs, вкладення, вставлені логи), цей вміст може містити інструкції, які намагаються + перехопити модель. Це може трапитися, навіть якщо **ви — єдиний відправник**. + + Найбільший ризик виникає, коли ввімкнені інструменти: модель можна змусити + ексфільтрувати контекст або викликати інструменти від вашого імені. Зменшуйте зону ураження так: + + - використовуйте "reader" agent у режимі лише читання або без інструментів для підсумовування недовіреного вмісту + - тримайте `web_search` / `web_fetch` / `browser` вимкненими для agents з увімкненими інструментами + - також вважайте недовіреним декодований текст файлів/документів: OpenResponses + `input_file` і витягнення з медіавкладень обгортають витягнутий текст + явними маркерами меж зовнішнього вмісту замість передачі сирого тексту файлу + - використовуйте sandboxing і суворі allowlist інструментів + + Подробиці: [Security](/uk/gateway/security). + + + + + Так, для більшості сценаріїв. Ізоляція бота за допомогою окремих облікових записів і номерів телефону + зменшує зону ураження, якщо щось піде не так. Це також полегшує ротацію + облікових даних або відкликання доступу без впливу на ваші особисті облікові записи. + + Починайте з малого. Надавайте доступ лише до тих інструментів і облікових записів, які вам справді потрібні, і розширюйте + його пізніше за потреби. + + Документація: [Security](/uk/gateway/security), [Pairing](/uk/channels/pairing). + + + + + Ми **не** рекомендуємо повну автономність щодо ваших особистих повідомлень. Найбезпечніший шаблон: + + - Тримайте DM у режимі **pairing** або в жорсткому allowlist. + - Використовуйте **окремий номер або обліковий запис**, якщо хочете, щоб він надсилав повідомлення від вашого імені. + - Нехай він створює чернетку, а ви **схвалюйте перед надсиланням**. + + Якщо хочете поекспериментувати, робіть це на окремому обліковому записі й тримайте його ізольованим. Див. + [Security](/uk/gateway/security). + + + + + Так, **якщо** agent працює лише в чаті, а вхідні дані довірені. Менші рівні + більш схильні до перехоплення інструкцій, тому уникайте їх для agents з увімкненими інструментами + або під час читання недовіреного вмісту. Якщо вам усе ж потрібна менша model, жорстко обмежте + інструменти й запускайте всередині sandbox. Див. [Security](/uk/gateway/security). + + + + Коди pairing надсилаються **лише** коли невідомий відправник пише боту і + ввімкнено `dmPolicy: "pairing"`. Сам по собі `/start` не генерує код. + + Перевірте запити, що очікують: + + ```bash + openclaw pairing list telegram + ``` + + Якщо вам потрібен негайний доступ, додайте свій sender id до allowlist або встановіть `dmPolicy: "open"` + для цього облікового запису. + + + + + Ні. Типова політика DM у WhatsApp — **pairing**. Невідомі відправники отримують лише код pairing, а їхнє повідомлення **не обробляється**. OpenClaw відповідає лише в ті чати, з яких отримує повідомлення, або на явні надсилання, які ініціюєте ви. + + Схвалення pairing: + + ```bash + openclaw pairing approve whatsapp + ``` + + Перегляд запитів, що очікують: + + ```bash + openclaw pairing list whatsapp + ``` + + Запит номера телефону в майстрі: він використовується для налаштування вашого **allowlist/owner**, щоб ваші власні DM були дозволені. Він не використовується для автоматичного надсилання. Якщо ви запускаєте на своєму особистому номері WhatsApp, використовуйте цей номер і ввімкніть `channels.whatsapp.selfChatMode`. + + + + +## Команди чату, переривання завдань і "воно не зупиняється" + + + + Більшість внутрішніх повідомлень або повідомлень інструментів з’являються лише тоді, коли для цієї session увімкнено **verbose**, **trace** або **reasoning**. + + Виправлення в чаті, де ви це бачите: + + ``` + /verbose off + /trace off + /reasoning off + ``` + + Якщо все одно занадто шумно, перевірте налаштування session у Control UI і встановіть verbose + у значення **inherit**. Також переконайтеся, що ви не використовуєте профіль бота, у якому `verboseDefault` задано + як `on` у config. + + Документація: [Thinking and verbose](/uk/tools/thinking), [Security](/uk/gateway/security#reasoning-verbose-output-in-groups). + + + + + Надішліть будь-що з цього **як окреме повідомлення** (без slash): + + ``` + stop + stop action + stop current action + stop run + stop current run + stop agent + stop the agent + stop openclaw + openclaw stop + stop don't do anything + stop do not do anything + stop doing anything + please stop + stop please + abort + esc + wait + exit + interrupt + ``` + + Це тригери переривання (не slash-команди). + + Для фонових процесів (з інструмента exec) ви можете попросити agent виконати: + + ``` + process action:kill sessionId:XXX + ``` + + Огляд slash-команд: див. [Slash-команди](/uk/tools/slash-commands). + + Більшість команд мають надсилатися як **окреме** повідомлення, що починається з `/`, але деякі скорочення (наприклад, `/status`) також працюють inline для відправників з allowlist. + + + + + OpenClaw блокує **крос-провайдерний** обмін повідомленнями за замовчуванням. Якщо виклик інструмента прив’язано + до Telegram, він не надішле в Discord, доки ви явно цього не дозволите. + + Увімкніть крос-провайдерний обмін повідомленнями для agent: + + ```json5 + { + tools: { + message: { + crossContext: { + allowAcrossProviders: true, + marker: { enabled: true, prefix: "[from {channel}] " }, + }, + }, + }, + } + ``` + + Після редагування config перезапустіть gateway. + + + + + Режим queue визначає, як нові повідомлення взаємодіють із поточним виконанням. Використовуйте `/queue`, щоб змінювати режими: + + - `steer` - нові повідомлення перенаправляють поточне завдання + - `followup` - повідомлення виконуються по одному + - `collect` - пакетування повідомлень і одна відповідь (типово) + - `steer-backlog` - спочатку перенаправити, потім обробити беклог + - `interrupt` - перервати поточне виконання і почати заново + + Ви можете додавати параметри, як-от `debounce:2s cap:25 drop:summarize`, для режимів followup. + + + + +## Різне + + + + В OpenClaw облікові дані й вибір model — це окремі речі. Установлення `ANTHROPIC_API_KEY` (або збереження API-ключа Anthropic в auth profiles) вмикає автентифікацію, але фактична model за замовчуванням — це те, що ви налаштовуєте в `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, який виконується. + + + +--- + +Усе ще застрягли? Запитайте в [Discord](https://discord.com/invite/clawd) або відкрийте [обговорення GitHub](https://github.com/openclaw/openclaw/discussions). diff --git a/docs/uk/tools/slash-commands.md b/docs/uk/tools/slash-commands.md index 53edae039..815746192 100644 --- a/docs/uk/tools/slash-commands.md +++ b/docs/uk/tools/slash-commands.md @@ -2,35 +2,35 @@ read_when: - Використання або налаштування команд чату - Налагодження маршрутизації команд або дозволів -summary: 'Слеш-команди: текстові vs нативні, конфігурація та підтримувані команди' +summary: 'Слеш-команди: текстові чи нативні, конфігурація та підтримувані команди' title: Слеш-команди x-i18n: - generated_at: "2026-04-10T21:20:33Z" + generated_at: "2026-04-12T18:22:04Z" model: gpt-5.4 provider: openai - source_hash: 2cc346361c3b1a63aae9ec0f28706f4cb0b866b6c858a3999101f6927b923b4a + source_hash: 9ef6f54500fa2ce3b873a8398d6179a0882b8bf6fba38f61146c64671055505e source_path: tools/slash-commands.md workflow: 15 --- # Слеш-команди -Команди обробляються Gateway. Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`. -Команда чату bash лише для хоста використовує `! ` (із псевдонімом `/bash `). +Команди обробляються Gateway. Більшість команд треба надсилати як **окреме** повідомлення, що починається з `/`. +Команда чату bash лише для хоста використовує `! ` (з псевдонімом `/bash `). Є дві пов’язані системи: - **Команди**: окремі повідомлення `/...`. -- **Директиви**: `/think`, `/fast`, `/verbose`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`. - - Директиви видаляються з повідомлення до того, як його побачить модель. - - У звичайних повідомленнях чату (не лише з директивами) вони трактуються як «вбудовані підказки» і **не** зберігають налаштування сесії. - - У повідомленнях, що містять лише директиви (повідомлення складається тільки з директив), вони зберігаються в сесії та відповідають підтвердженням. +- **Директиви**: `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`. + - Директиви прибираються з повідомлення до того, як його побачить модель. + - У звичайних повідомленнях чату (не лише з директив), вони розглядаються як «вбудовані підказки» і **не** зберігають налаштування сесії. + - У повідомленнях лише з директивами (повідомлення містить тільки директиви) вони зберігаються в сесії та повертають підтвердження. - Директиви застосовуються лише для **авторизованих відправників**. Якщо задано `commands.allowFrom`, це єдиний - список дозволених; інакше авторизація походить зі списків дозволених каналів/парування разом із `commands.useAccessGroups`. - Для неавторизованих відправників директиви трактуються як звичайний текст. + список дозволених джерел; інакше авторизація визначається списками дозволених джерел/паруванням каналу плюс `commands.useAccessGroups`. + Неавторизовані відправники бачитимуть директиви як звичайний текст. Також є кілька **вбудованих скорочень** (лише для відправників зі списку дозволених/авторизованих): `/help`, `/commands`, `/status`, `/whoami` (`/id`). -Вони виконуються негайно, видаляються до того, як повідомлення побачить модель, а решта тексту продовжує оброблятися звичайним потоком. +Вони виконуються негайно, прибираються до того, як повідомлення побачить модель, а решта тексту проходить через звичайний потік. ## Конфігурація @@ -62,104 +62,105 @@ x-i18n: - `commands.text` (типово `true`) вмикає розбір `/...` у повідомленнях чату. - На поверхнях без нативних команд (WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams) текстові команди все одно працюють, навіть якщо встановити це значення в `false`. - `commands.native` (типово `"auto"`) реєструє нативні команди. - - Auto: увімкнено для Discord/Telegram; вимкнено для Slack (доки ви не додасте slash commands); ігнорується для провайдерів без нативної підтримки. - - Щоб перевизначити для конкретного провайдера, задайте `channels.discord.commands.native`, `channels.telegram.commands.native` або `channels.slack.commands.native` (bool або `"auto"`). + - Auto: увімкнено для Discord/Telegram; вимкнено для Slack (поки ви не додасте slash-команди); ігнорується для провайдерів без нативної підтримки. + - Щоб перевизначити значення для окремого провайдера, задайте `channels.discord.commands.native`, `channels.telegram.commands.native` або `channels.slack.commands.native` (булеве значення або `"auto"`). - `false` очищає раніше зареєстровані команди в Discord/Telegram під час запуску. Команди Slack керуються в застосунку Slack і не видаляються автоматично. -- `commands.nativeSkills` (типово `"auto"`) реєструє команди **Skills** нативно, коли це підтримується. - - Auto: увімкнено для Discord/Telegram; вимкнено для Slack (у Slack потрібно створювати окрему slash command для кожного skill). - - Щоб перевизначити для конкретного провайдера, задайте `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` або `channels.slack.commands.nativeSkills` (bool або `"auto"`). -- `commands.bash` (типово `false`) вмикає `! ` для запуску команд оболонки хоста (`/bash ` є псевдонімом; потрібні списки дозволених `tools.elevated`). -- `commands.bashForegroundMs` (типово `2000`) визначає, скільки часу bash чекає перед перемиканням у фоновий режим (`0` одразу переводить у фон). +- `commands.nativeSkills` (типово `"auto"`) реєструє команди **Skills** нативно, якщо це підтримується. + - Auto: увімкнено для Discord/Telegram; вимкнено для Slack (у Slack потрібно створювати slash-команду для кожного skill). + - Щоб перевизначити значення для окремого провайдера, задайте `channels.discord.commands.nativeSkills`, `channels.telegram.commands.nativeSkills` або `channels.slack.commands.nativeSkills` (булеве значення або `"auto"`). +- `commands.bash` (типово `false`) вмикає `! ` для виконання команд оболонки на хості (`/bash ` — псевдонім; потрібні списки дозволених `tools.elevated`). +- `commands.bashForegroundMs` (типово `2000`) визначає, як довго bash очікує перед переходом у фоновий режим (`0` одразу переводить у фон). - `commands.config` (типово `false`) вмикає `/config` (читання/запис `openclaw.json`). -- `commands.mcp` (типово `false`) вмикає `/mcp` (читання/запис конфігурації MCP, якою керує OpenClaw, у `mcp.servers`). -- `commands.plugins` (типово `false`) вмикає `/plugins` (виявлення/статус plugins, а також елементи керування встановленням і ввімкненням/вимкненням). -- `commands.debug` (типово `false`) вмикає `/debug` (лише перевизначення під час виконання). -- `commands.restart` (типово `true`) вмикає `/restart`, а також дії інструментів перезапуску gateway. -- `commands.ownerAllowFrom` (необов’язково) задає явний список дозволених власника для поверхонь команд/інструментів, доступних лише власнику. Це окремо від `commands.allowFrom`. -- `commands.ownerDisplay` визначає, як ідентифікатори власника відображаються в системному prompt: `raw` або `hash`. -- `commands.ownerDisplaySecret` необов’язково задає HMAC-секрет, який використовується, коли `commands.ownerDisplay="hash"`. -- `commands.allowFrom` (необов’язково) задає список дозволених для авторизації команд окремо для кожного провайдера. Якщо його налаштовано, це - єдине джерело авторизації для команд і директив (списки дозволених каналів/парування та `commands.useAccessGroups` - ігноруються). Використовуйте `"*"` як глобальне типове значення; ключі конкретних провайдерів мають пріоритет. -- `commands.useAccessGroups` (типово `true`) застосовує списки дозволених/політики для команд, якщо `commands.allowFrom` не задано. +- `commands.mcp` (типово `false`) вмикає `/mcp` (читання/запис конфігурації MCP, керованої OpenClaw, у `mcp.servers`). +- `commands.plugins` (типово `false`) вмикає `/plugins` (виявлення/стан plugins, а також керування встановленням і ввімкненням/вимкненням). +- `commands.debug` (типово `false`) вмикає `/debug` (перевизначення лише під час виконання). +- `commands.restart` (типово `true`) вмикає `/restart` і дії інструментів перезапуску gateway. +- `commands.ownerAllowFrom` (необов’язково) задає явний список дозволених джерел для власника для поверхонь команд/інструментів, доступних лише власнику. Це окремо від `commands.allowFrom`. +- `commands.ownerDisplay` визначає, як ідентифікатори власника відображаються в системному промпті: `raw` або `hash`. +- `commands.ownerDisplaySecret` необов’язково задає секрет HMAC, який використовується, коли `commands.ownerDisplay="hash"`. +- `commands.allowFrom` (необов’язково) задає список дозволених джерел для авторизації команд окремо для кожного провайдера. Якщо налаштовано, це + єдине джерело авторизації для команд і директив (списки дозволених джерел/парування каналу та `commands.useAccessGroups` + ігноруються). Використовуйте `"*"` для глобального значення за замовчуванням; ключі окремих провайдерів мають вищий пріоритет. +- `commands.useAccessGroups` (типово `true`) примусово застосовує списки дозволених джерел/політики до команд, якщо `commands.allowFrom` не задано. ## Список команд Поточне джерело істини: -- вбудовані core-команди походять із `src/auto-reply/commands-registry.shared.ts` -- згенеровані dock-команди походять із `src/auto-reply/commands-registry.data.ts` -- plugin-команди походять із викликів plugin `registerCommand()` -- фактична доступність на вашому gateway усе ще залежить від прапорців конфігурації, поверхні каналу та встановлених/увімкнених plugins +- вбудовані core-команди беруться з `src/auto-reply/commands-registry.shared.ts` +- згенеровані dock-команди беруться з `src/auto-reply/commands-registry.data.ts` +- plugin-команди надходять із викликів plugin `registerCommand()` +- фактична доступність на вашому gateway усе одно залежить від прапорців конфігурації, поверхні каналу та встановлених/увімкнених plugins ### Вбудовані core-команди -Вбудовані команди, доступні зараз: +Доступні сьогодні вбудовані команди: -- `/new [model]` запускає нову сесію; `/reset` — це псевдонім скидання. -- `/compact [instructions]` стискає контекст сесії. Див. [/concepts/compaction](/uk/concepts/compaction). +- `/new [model]` запускає нову сесію; `/reset` — псевдонім для скидання. +- `/compact [instructions]` виконує Compaction контексту сесії. Див. [/concepts/compaction](/uk/concepts/compaction). - `/stop` перериває поточний запуск. -- `/session idle ` і `/session max-age ` керують строком дії прив’язки до потоку. -- `/think ` задає рівень thinking. Псевдоніми: `/thinking`, `/t`. +- `/session idle ` і `/session max-age ` керують завершенням прив’язки до потоку за строком дії. +- `/think ` задає рівень мислення. Псевдоніми: `/thinking`, `/t`. - `/verbose on|off|full` перемикає докладний вивід. Псевдонім: `/v`. -- `/fast [status|on|off]` показує або задає швидкий режим. -- `/reasoning [on|off|stream]` перемикає видимість reasoning. Псевдонім: `/reason`. -- `/elevated [on|off|ask|full]` перемикає elevated mode. Псевдонім: `/elev`. -- `/exec host= security= ask= node=` показує або задає типові значення exec. -- `/model [name|#|status]` показує або задає модель. -- `/models [provider] [page] [limit=|size=|all]` виводить список провайдерів або моделей для провайдера. +- `/trace on|off` перемикає вивід трасування Plugin для поточної сесії. +- `/fast [status|on|off]` показує або встановлює швидкий режим. +- `/reasoning [on|off|stream]` перемикає видимість міркувань. Псевдонім: `/reason`. +- `/elevated [on|off|ask|full]` перемикає підвищений режим. Псевдонім: `/elev`. +- `/exec host= security= ask= node=` показує або встановлює типові значення exec. +- `/model [name|#|status]` показує або встановлює модель. +- `/models [provider] [page] [limit=|size=|all]` перелічує провайдерів або моделі для провайдера. - `/queue ` керує поведінкою черги (`steer`, `interrupt`, `followup`, `collect`, `steer-backlog`), а також параметрами на кшталт `debounce:2s cap:25 drop:summarize`. -- `/help` показує короткий підсумок довідки. +- `/help` показує коротку довідку. - `/commands` показує згенерований каталог команд. -- `/tools [compact|verbose]` показує, що поточний агент може використовувати просто зараз. -- `/status` показує статус під час виконання, зокрема використання/квоту провайдера, якщо доступно. -- `/tasks` виводить активні/нещодавні фонові завдання для поточної сесії. +- `/tools [compact|verbose]` показує, що поточний агент може використовувати прямо зараз. +- `/status` показує стан виконання, зокрема використання/квоту провайдера, якщо доступно. +- `/tasks` перелічує активні/нещодавні фонові завдання для поточної сесії. - `/context [list|detail|json]` пояснює, як збирається контекст. - `/export-session [path]` експортує поточну сесію в HTML. Псевдонім: `/export`. - `/whoami` показує ваш ідентифікатор відправника. Псевдонім: `/id`. - `/skill [input]` запускає skill за назвою. -- `/allowlist [list|add|remove] ...` керує записами списку дозволених. Лише текстова команда. -- `/approve ` опрацьовує запити на підтвердження exec. +- `/allowlist [list|add|remove] ...` керує записами списку дозволених джерел. Лише текстова команда. +- `/approve ` обробляє запити на погодження exec. - `/btw ` ставить побічне запитання без зміни майбутнього контексту сесії. Див. [/tools/btw](/uk/tools/btw). -- `/subagents list|kill|log|info|send|steer|spawn` керує запусками sub-agent для поточної сесії. -- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` керує сесіями ACP і параметрами під час виконання. +- `/subagents list|kill|log|info|send|steer|spawn` керує запусками субагентів для поточної сесії. +- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` керує сесіями ACP і параметрами виконання. - `/focus ` прив’язує поточний потік Discord або тему/розмову Telegram до цілі сесії. - `/unfocus` знімає поточну прив’язку. -- `/agents` виводить список агентів, прив’язаних до потоку, для поточної сесії. -- `/kill ` перериває один або всі запущені sub-agent. -- `/steer ` надсилає керувальне повідомлення запущеному sub-agent. Псевдонім: `/tell`. +- `/agents` перелічує агентів, прив’язаних до потоку, для поточної сесії. +- `/kill ` перериває один або всі запущені субагенти. +- `/steer ` надсилає керуюче повідомлення запущеному субагенту. Псевдонім: `/tell`. - `/config show|get|set|unset` читає або записує `openclaw.json`. Лише для власника. Потрібно `commands.config: true`. -- `/mcp show|get|set|unset` читає або записує конфігурацію MCP-сервера, якою керує OpenClaw, у `mcp.servers`. Лише для власника. Потрібно `commands.mcp: true`. -- `/plugins list|inspect|show|get|install|enable|disable` перевіряє або змінює стан plugin. `/plugin` — це псевдонім. Запис — лише для власника. Потрібно `commands.plugins: true`. +- `/mcp show|get|set|unset` читає або записує конфігурацію MCP-сервера, керовану OpenClaw, у `mcp.servers`. Лише для власника. Потрібно `commands.mcp: true`. +- `/plugins list|inspect|show|get|install|enable|disable` перевіряє або змінює стан plugins. `/plugin` — псевдонім. Запис — лише для власника. Потрібно `commands.plugins: true`. - `/debug show|set|unset|reset` керує перевизначеннями конфігурації лише під час виконання. Лише для власника. Потрібно `commands.debug: true`. -- `/usage off|tokens|full|cost` керує нижнім колонтитулом використання для кожної відповіді або виводить локальний підсумок витрат. +- `/usage off|tokens|full|cost` керує нижнім колонтитулом використання для кожної відповіді або виводить локальний зведений звіт про вартість. - `/tts on|off|status|provider|limit|summary|audio|help` керує TTS. Див. [/tools/tts](/uk/tools/tts). -- `/restart` перезапускає OpenClaw, якщо це ввімкнено. Типово: увімкнено; встановіть `commands.restart: false`, щоб вимкнути. -- `/activation mention|always` задає режим активації групи. +- `/restart` перезапускає OpenClaw, якщо ввімкнено. Типово: увімкнено; щоб вимкнути, задайте `commands.restart: false`. +- `/activation mention|always` задає режим активації в групі. - `/send on|off|inherit` задає політику надсилання. Лише для власника. -- `/bash ` запускає команду оболонки хоста. Лише текстова команда. Псевдонім: `! `. Потрібно `commands.bash: true` плюс списки дозволених `tools.elevated`. +- `/bash ` виконує команду оболонки на хості. Лише текстова команда. Псевдонім: `! `. Потрібно `commands.bash: true` і списки дозволених `tools.elevated`. - `!poll [sessionId]` перевіряє фонове завдання bash. - `!stop [sessionId]` зупиняє фонове завдання bash. ### Згенеровані dock-команди -Dock-команди генеруються з channel plugins із підтримкою native-command. Поточний вбудований набір: +Dock-команди генеруються з channel plugins із підтримкою нативних команд. Поточний вбудований набір: - `/dock-discord` (псевдонім: `/dock_discord`) - `/dock-mattermost` (псевдонім: `/dock_mattermost`) - `/dock-slack` (псевдонім: `/dock_slack`) - `/dock-telegram` (псевдонім: `/dock_telegram`) -### Команди bundled plugin +### Команди вбудованих plugins -Bundled plugins можуть додавати більше слеш-команд. Поточні bundled-команди в цьому репозиторії: +Вбудовані plugins можуть додавати більше slash-команд. Поточні вбудовані команди в цьому репозиторії: -- `/dreaming [on|off|status|help]` перемикає memory dreaming. Див. [Dreaming](/uk/concepts/dreaming). +- `/dreaming [on|off|status|help]` перемикає Dreaming пам’яті. Див. [Dreaming](/uk/concepts/dreaming). - `/pair [qr|status|pending|approve|cleanup|notify]` керує потоком парування/налаштування пристрою. Див. [Pairing](/uk/channels/pairing). -- `/phone status|arm [duration]|disarm` тимчасово вмикає високоризикові команди phone node. +- `/phone status|arm [duration]|disarm` тимчасово вмикає команди вузла телефона з високим рівнем ризику. - `/voice status|list [limit]|set ` керує конфігурацією голосу Talk. У Discord нативна назва команди — `/talkvoice`. - `/card ...` надсилає шаблони LINE rich card. Див. [LINE](/uk/channels/line). -- `/codex status|models|threads|resume|compact|review|account|mcp|skills` перевіряє та керує bundled harness сервера застосунку Codex. Див. [Codex Harness](/uk/plugins/codex-harness). +- `/codex status|models|threads|resume|compact|review|account|mcp|skills` перевіряє та керує вбудованим harness сервера застосунку Codex. Див. [Codex Harness](/uk/plugins/codex-harness). - Команди лише для QQBot: - `/bot-ping` - `/bot-version` @@ -167,72 +168,73 @@ Bundled plugins можуть додавати більше слеш-команд - `/bot-upgrade` - `/bot-logs` -### Динамічні skill-команди +### Динамічні команди Skills -Skills, які може викликати користувач, також доступні як слеш-команди: +Skills, які може викликати користувач, також доступні як slash-команди: - `/skill [input]` завжди працює як універсальна точка входу. -- skills також можуть з’являтися як прямі команди, наприклад `/prose`, коли skill/plugin їх реєструє. +- skills також можуть з’являтися як прямі команди, наприклад `/prose`, коли їх реєструє skill/plugin. - нативна реєстрація skill-команд керується через `commands.nativeSkills` і `channels..commands.nativeSkills`. Примітки: - Команди приймають необов’язковий символ `:` між командою та аргументами (наприклад, `/think: high`, `/send: on`, `/help:`). -- `/new ` приймає псевдонім моделі, `provider/model` або назву провайдера (нечітке зіставлення); якщо збігу немає, текст трактується як тіло повідомлення. -- Для повного розподілу використання провайдера використовуйте `openclaw status --usage`. -- `/allowlist add|remove` вимагає `commands.config=true` і враховує канал `configWrites`. -- У каналах із кількома обліковими записами `/allowlist --account `, націлений на конфігурацію, і `/config set channels..accounts....` також враховують `configWrites` цільового облікового запису. -- `/usage` керує нижнім колонтитулом використання для кожної відповіді; `/usage cost` виводить локальний підсумок витрат із журналів сесій OpenClaw. -- `/restart` увімкнено типово; встановіть `commands.restart: false`, щоб вимкнути його. +- `/new ` приймає псевдонім моделі, `provider/model` або назву провайдера (нечіткий збіг); якщо збігу немає, текст розглядається як тіло повідомлення. +- Для повного розподілу використання провайдера скористайтеся `openclaw status --usage`. +- `/allowlist add|remove` вимагає `commands.config=true` і враховує `configWrites` каналу. +- У каналах із кількома акаунтами команди `/allowlist --account `, націлені на конфігурацію, і `/config set channels..accounts....` також враховують `configWrites` цільового акаунта. +- `/usage` керує нижнім колонтитулом використання для кожної відповіді; `/usage cost` виводить локальний зведений звіт про вартість із журналів сесій OpenClaw. +- `/restart` увімкнено типово; щоб вимкнути, задайте `commands.restart: false`. - `/plugins install ` приймає ті самі специфікації plugin, що й `openclaw plugins install`: локальний шлях/архів, npm-пакет або `clawhub:`. - `/plugins enable|disable` оновлює конфігурацію plugin і може запропонувати перезапуск. -- Нативна команда лише для Discord: `/vc join|leave|status` керує голосовими каналами (потрібні `channels.discord.voice` і нативні команди; недоступна як текстова команда). -- Команди прив’язки до потоку Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) вимагають, щоб ефективні прив’язки до потоку були увімкнені (`session.threadBindings.enabled` та/або `channels.discord.threadBindings.enabled`). +- Нативна команда лише для Discord: `/vc join|leave|status` керує голосовими каналами (потрібні `channels.discord.voice` і нативні команди; недоступна як текстова). +- Команди прив’язки потоку Discord (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) вимагають, щоб ефективні прив’язки потоку були ввімкнені (`session.threadBindings.enabled` та/або `channels.discord.threadBindings.enabled`). - Довідник команд ACP і поведінка під час виконання: [ACP Agents](/uk/tools/acp-agents). -- `/verbose` призначено для налагодження та додаткової видимості; у звичайному використанні тримайте його **вимкненим**. -- `/fast on|off` зберігає перевизначення сесії. Щоб очистити його й повернутися до типових значень із конфігурації, використовуйте опцію `inherit` в інтерфейсі Sessions. -- `/fast` залежить від провайдера: OpenAI/OpenAI Codex зіставляють його з `service_tier=priority` на нативних endpoints Responses, тоді як прямі публічні запити Anthropic, зокрема трафік з OAuth-автентифікацією, надісланий до `api.anthropic.com`, зіставляють його з `service_tier=auto` або `standard_only`. Див. [OpenAI](/uk/providers/openai) і [Anthropic](/uk/providers/anthropic). -- Підсумки збоїв інструментів усе ще показуються, коли це доречно, але докладний текст збоїв включається лише коли `/verbose` має значення `on` або `full`. -- `/reasoning` (і `/verbose`) ризиковані в групових налаштуваннях: вони можуть розкрити внутрішні міркування або вивід інструментів, які ви не мали наміру показувати. Краще залишати їх вимкненими, особливо в групових чатах. -- `/model` одразу зберігає нову модель сесії. -- Якщо агент неактивний, наступний запуск використає її одразу. -- Якщо запуск уже активний, OpenClaw позначає живе перемикання як відкладене та перезапускає на новій моделі лише в чистій точці повторної спроби. +- `/verbose` призначена для налагодження та додаткової видимості; у звичайному використанні тримайте її **вимкненою**. +- `/trace` вужча за `/verbose`: вона показує лише рядки trace/debug, що належать plugin, і не вмикає звичайний докладний вивід інструментів. +- `/fast on|off` зберігає перевизначення сесії. Щоб очистити його та повернутися до типових значень із конфігурації, використайте опцію `inherit` в інтерфейсі Sessions. +- `/fast` залежить від провайдера: OpenAI/OpenAI Codex зіставляють її з `service_tier=priority` у нативних endpoint Responses, тоді як прямі публічні запити Anthropic, включно з трафіком з OAuth-автентифікацією, надісланим до `api.anthropic.com`, зіставляють її з `service_tier=auto` або `standard_only`. Див. [OpenAI](/uk/providers/openai) і [Anthropic](/uk/providers/anthropic). +- Підсумки збоїв інструментів усе ще показуються, коли це доречно, але докладний текст помилки включається лише тоді, коли `/verbose` має значення `on` або `full`. +- `/reasoning`, `/verbose` і `/trace` ризиковані в групових налаштуваннях: вони можуть розкрити внутрішні міркування, вивід інструментів або діагностику plugin, які ви не планували показувати. Краще залишати їх вимкненими, особливо в групових чатах. +- `/model` негайно зберігає нову модель сесії. +- Якщо агент простоює, наступний запуск використає її відразу. +- Якщо запуск уже активний, OpenClaw позначає живе перемикання як відкладене й перезапускає на нову модель лише в чистій точці повторної спроби. - Якщо активність інструментів або вивід відповіді вже почалися, відкладене перемикання може залишатися в черзі до пізнішої можливості повторної спроби або до наступного ходу користувача. -- **Швидкий шлях:** повідомлення лише з командою від відправників зі списку дозволених обробляються негайно (в обхід черги й моделі). -- **Керування згадками в групі:** повідомлення лише з командою від відправників зі списку дозволених обходять вимоги щодо згадування. -- **Вбудовані скорочення (лише для відправників зі списку дозволених):** деякі команди також працюють, коли вбудовані у звичайне повідомлення, і видаляються до того, як модель побачить решту тексту. - - Приклад: `hey /status` запускає відповідь зі статусом, а решта тексту продовжує оброблятися звичайним потоком. +- **Швидкий шлях:** повідомлення лише з командами від відправників зі списку дозволених обробляються негайно (в обхід черги та моделі). +- **Обмеження згадування в групі:** повідомлення лише з командами від відправників зі списку дозволених обходять вимоги щодо згадування. +- **Вбудовані скорочення (лише для відправників зі списку дозволених):** деякі команди також працюють, коли вбудовані у звичайне повідомлення, і прибираються до того, як модель побачить решту тексту. + - Приклад: `hey /status` запускає відповідь зі статусом, а решта тексту проходить через звичайний потік. - Наразі: `/help`, `/commands`, `/status`, `/whoami` (`/id`). -- Неавторизовані повідомлення лише з командою тихо ігноруються, а вбудовані токени `/...` трактуються як звичайний текст. -- **Skill-команди:** skills з позначкою `user-invocable` доступні як слеш-команди. Назви очищуються до `a-z0-9_` (максимум 32 символи); у разі колізій додаються числові суфікси (наприклад, `_2`). - - `/skill [input]` запускає skill за назвою (це корисно, коли обмеження нативних команд не дають створити окремі команди для кожного skill). +- Неавторизовані повідомлення лише з командами мовчки ігноруються, а вбудовані токени `/...` розглядаються як звичайний текст. +- **Skill-команди:** Skills з позначкою `user-invocable` доступні як slash-команди. Назви санітизуються до `a-z0-9_` (максимум 32 символи); у разі колізій додаються числові суфікси (наприклад, `_2`). + - `/skill [input]` запускає skill за назвою (це корисно, коли обмеження нативних команд не дозволяють мати окремі команди для кожного skill). - Типово skill-команди пересилаються моделі як звичайний запит. - Skills можуть необов’язково оголошувати `command-dispatch: tool`, щоб маршрутизувати команду безпосередньо до інструмента (детерміновано, без моделі). - Приклад: `/prose` (plugin OpenProse) — див. [OpenProse](/uk/prose). -- **Аргументи нативних команд:** Discord використовує автодоповнення для динамічних параметрів (і кнопкові меню, коли ви пропускаєте обов’язкові аргументи). Telegram і Slack показують кнопкове меню, коли команда підтримує вибір значень і ви пропускаєте аргумент. +- **Аргументи нативних команд:** Discord використовує автодоповнення для динамічних параметрів (і меню кнопок, коли ви пропускаєте обов’язкові аргументи). Telegram і Slack показують меню кнопок, коли команда підтримує варіанти вибору, а ви пропускаєте аргумент. ## `/tools` -`/tools` відповідає на запитання про стан під час виконання, а не про конфігурацію: **що цей агент може використовувати просто зараз у +`/tools` відповідає на запитання про виконання, а не про конфігурацію: **що цей агент може використовувати прямо зараз у цій розмові**. - Типовий `/tools` є компактним і оптимізованим для швидкого перегляду. - `/tools verbose` додає короткі описи. -- Поверхні нативних команд, які підтримують аргументи, надають той самий перемикач режиму як `compact|verbose`. -- Результати прив’язані до сесії, тому зміна агента, каналу, потоку, авторизації відправника або моделі може +- Поверхні нативних команд, які підтримують аргументи, надають той самий перемикач режиму `compact|verbose`. +- Результати прив’язані до сесії, тож зміна агента, каналу, потоку, авторизації відправника або моделі може змінити вивід. - `/tools` включає інструменти, які реально доступні під час виконання, зокрема core-інструменти, підключені - plugin-інструменти та інструменти, що належать каналам. + plugin-інструменти та інструменти, що належать каналу. -Для редагування профілів і перевизначень використовуйте панель Tools у Control UI або поверхні конфігурації/каталогу, а не -трактуйте `/tools` як статичний каталог. +Для редагування профілю та перевизначень використовуйте панель Tools в інтерфейсі керування або поверхні конфігурації/каталогу, +а не сприймайте `/tools` як статичний каталог. -## Поверхні використання (що і де показується) +## Поверхні використання (що де показується) -- **Використання/квота провайдера** (наприклад, «Claude 80% left») показується в `/status` для провайдера поточної моделі, коли відстеження використання увімкнено. OpenClaw нормалізує вікна провайдера до `% left`; для MiniMax поля percent із лише залишком інвертуються перед показом, а відповіді `model_remains` віддають перевагу запису chat-model плюс мітці плану з тегом моделі. -- **Рядки токенів/кешу** в `/status` можуть повертатися до останнього запису використання в транскрипті, коли живий знімок сесії неповний. Наявні ненульові живі значення все одно мають пріоритет, а резервний варіант із транскрипту також може відновити мітку активної моделі під час виконання та більшу загальну кількість, орієнтовану на prompt, коли збережені підсумки відсутні або менші. -- **Токени/вартість для кожної відповіді** контролюються через `/usage off|tokens|full` (додаються до звичайних відповідей). -- `/model status` стосується **моделей/автентифікації/endpoints**, а не використання. +- **Використання/квота провайдера** (наприклад, «Claude 80% left») показується в `/status` для поточного провайдера моделі, якщо відстеження використання ввімкнене. OpenClaw нормалізує вікна провайдерів до `% left`; для MiniMax поля відсотка з лише залишком інвертуються перед показом, а відповіді `model_remains` віддають перевагу запису chat-model плюс мітці плану, прив’язаній до моделі. +- **Рядки токенів/кешу** в `/status` можуть повертатися до останнього запису використання з транскрипту, якщо живий знімок сесії містить мало даних. Наявні ненульові живі значення все одно мають пріоритет, а резерв із транскрипту також може відновити мітку активної runtime-моделі плюс більший загальний обсяг, орієнтований на промпт, коли збережені підсумки відсутні або менші. +- **Токени/вартість для кожної відповіді** керуються через `/usage off|tokens|full` (додаються до звичайних відповідей). +- `/model status` стосується **моделей/автентифікації/endpoint**, а не використання. ## Вибір моделі (`/model`) @@ -252,13 +254,13 @@ Skills, які може викликати користувач, також до Примітки: - `/model` і `/model list` показують компактний нумерований вибір (сімейство моделей + доступні провайдери). -- У Discord `/model` і `/models` відкривають інтерактивний вибір зі спадними списками провайдера й моделі та кроком Submit. -- `/model <#>` вибирає зі списку цього вибору (і за можливості віддає перевагу поточному провайдеру). -- `/model status` показує докладний перегляд, зокрема налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), коли доступно. +- У Discord `/model` і `/models` відкривають інтерактивний вибір із випадними списками провайдера й моделі та кроком Submit. +- `/model <#>` вибирає зі списку вибору (і, коли можливо, надає перевагу поточному провайдеру). +- `/model status` показує докладний вигляд, зокрема налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), якщо доступно. -## Перевизначення для налагодження +## Перевизначення налагодження -`/debug` дає змогу задавати **лише під час виконання** перевизначення конфігурації (у пам’яті, не на диску). Лише для власника. Типово вимкнено; увімкніть через `commands.debug: true`. +`/debug` дає змогу задавати **перевизначення конфігурації лише під час виконання** (у пам’яті, не на диску). Лише для власника. Типово вимкнено; увімкніть через `commands.debug: true`. Приклади: @@ -272,8 +274,29 @@ Skills, які може викликати користувач, також до Примітки: -- Перевизначення застосовуються негайно до нових читань конфігурації, але **не** записуються до `openclaw.json`. -- Використовуйте `/debug reset`, щоб очистити всі перевизначення та повернутися до конфігурації на диску. +- Перевизначення застосовуються негайно до нових читань конфігурації, але **не** записуються в `openclaw.json`. +- Використовуйте `/debug reset`, щоб очистити всі перевизначення й повернутися до конфігурації на диску. + +## Вивід trace Plugin + +`/trace` дає змогу перемикати **рядки trace/debug plugin у межах сесії** без увімкнення повного докладного режиму. + +Приклади: + +```text +/trace +/trace on +/trace off +``` + +Примітки: + +- `/trace` без аргументу показує поточний стан trace для сесії. +- `/trace on` вмикає рядки trace plugin для поточної сесії. +- `/trace off` знову вимикає їх. +- Рядки trace plugin можуть з’являтися в `/status` і як додаткове діагностичне повідомлення після звичайної відповіді асистента. +- `/trace` не замінює `/debug`; `/debug` як і раніше керує перевизначеннями конфігурації лише під час виконання. +- `/trace` не замінює `/verbose`; звичайний докладний вивід інструментів/статусу все ще належить до `/verbose`. ## Оновлення конфігурації @@ -291,12 +314,12 @@ Skills, які може викликати користувач, також до Примітки: -- Перед записом конфігурація перевіряється; недійсні зміни відхиляються. -- Оновлення через `/config` зберігаються після перезапусків. +- Перед записом конфігурація проходить валідацію; некоректні зміни відхиляються. +- Оновлення `/config` зберігаються після перезапусків. ## Оновлення MCP -`/mcp` записує визначення MCP-серверів, якими керує OpenClaw, у `mcp.servers`. Лише для власника. Типово вимкнено; увімкніть через `commands.mcp: true`. +`/mcp` записує визначення MCP-серверів, керованих OpenClaw, у `mcp.servers`. Лише для власника. Типово вимкнено; увімкніть через `commands.mcp: true`. Приклади: @@ -309,12 +332,12 @@ Skills, які може викликати користувач, також до Примітки: -- `/mcp` зберігає конфігурацію в конфігурації OpenClaw, а не в налаштуваннях проєкту, якими керує Pi. -- Адаптери під час виконання визначають, які транспорти реально можна виконувати. +- `/mcp` зберігає конфігурацію в конфігурації OpenClaw, а не в налаштуваннях проєкту, що належать Pi. +- Адаптери runtime вирішують, які транспорти реально можна виконати. -## Оновлення plugin +## Оновлення plugins -`/plugins` дає операторам змогу перевіряти знайдені plugins і перемикати їх увімкнення в конфігурації. Для потоків лише читання можна використовувати `/plugin` як псевдонім. Типово вимкнено; увімкніть через `commands.plugins: true`. +`/plugins` дає змогу операторам перевіряти виявлені plugins і перемикати їх увімкнення в конфігурації. Для потоків лише читання можна використовувати `/plugin` як псевдонім. Типово вимкнено; увімкніть через `commands.plugins: true`. Приклади: @@ -328,22 +351,22 @@ Skills, які може викликати користувач, також до Примітки: -- `/plugins list` і `/plugins show` використовують реальне виявлення plugins для поточного робочого простору разом із конфігурацією на диску. -- `/plugins enable|disable` оновлює лише конфігурацію plugin; він не встановлює і не видаляє plugins. +- `/plugins list` і `/plugins show` використовують реальне виявлення plugins у поточному робочому просторі та конфігурації на диску. +- `/plugins enable|disable` оновлює лише конфігурацію plugin; воно не встановлює й не видаляє plugins. - Після змін `enable/disable` перезапустіть gateway, щоб застосувати їх. ## Примітки щодо поверхонь -- **Текстові команди** виконуються в нормальній чат-сесії (DM використовують `main`, групи мають власну сесію). +- **Текстові команди** виконуються у звичайній сесії чату (DM ділять `main`, групи мають власну сесію). - **Нативні команди** використовують ізольовані сесії: - Discord: `agent::discord:slash:` - Slack: `agent::slack:slash:` (префікс налаштовується через `channels.slack.slashCommand.sessionPrefix`) - - Telegram: `telegram:slash:` (націлюється на чат-сесію через `CommandTargetSessionKey`) -- **`/stop`** націлюється на активну чат-сесію, щоб мати змогу перервати поточний запуск. -- **Slack:** `channels.slack.slashCommand` усе ще підтримується для однієї команди у стилі `/openclaw`. Якщо ви вмикаєте `commands.native`, потрібно створити по одній slash command у Slack для кожної вбудованої команди (з тими самими назвами, що й `/help`). Меню аргументів команд для Slack доставляються як ефемерні кнопки Block Kit. - - Нативний виняток Slack: реєструйте `/agentstatus` (а не `/status`), тому що Slack резервує `/status`. Текстовий `/status` у повідомленнях Slack усе ще працює. + - Telegram: `telegram:slash:` (націлюється на сесію чату через `CommandTargetSessionKey`) +- **`/stop`** націлюється на активну сесію чату, щоб можна було перервати поточний запуск. +- **Slack:** `channels.slack.slashCommand` усе ще підтримується для однієї команди у стилі `/openclaw`. Якщо ви вмикаєте `commands.native`, потрібно створити одну slash-команду Slack для кожної вбудованої команди (з тими самими назвами, що й `/help`). Меню аргументів команд для Slack доставляються як ефемерні кнопки Block Kit. + - Виняток для нативних команд Slack: реєструйте `/agentstatus` (а не `/status`), тому що Slack резервує `/status`. Текстовий `/status` у повідомленнях Slack усе одно працює. -## BTW side questions +## Побічні запитання BTW `/btw` — це швидке **побічне запитання** про поточну сесію. @@ -356,13 +379,13 @@ Skills, які може викликати користувач, також до - воно доставляється як живий побічний результат, а не як звичайне повідомлення асистента. Це робить `/btw` корисним, коли вам потрібне тимчасове уточнення, поки основне -завдання продовжується. +завдання триває. Приклад: ```text -/btw what are we doing right now? +/btw що ми зараз робимо? ``` -Див. [BTW Side Questions](/uk/tools/btw), щоб дізнатися повну поведінку та -подробиці UX клієнта. +Див. [BTW Side Questions](/uk/tools/btw), щоб ознайомитися з повною поведінкою та +деталями клієнтського UX. diff --git a/docs/uk/tools/thinking.md b/docs/uk/tools/thinking.md index 700ca8ebb..758196b36 100644 --- a/docs/uk/tools/thinking.md +++ b/docs/uk/tools/thinking.md @@ -1,109 +1,118 @@ --- read_when: - - Налаштування розбору або значень за замовчуванням для директив thinking, fast-mode чи verbose -summary: Синтаксис директив для /think, /fast, /verbose і видимості reasoning -title: Рівні мислення + - Налаштування парсингу або значень за замовчуванням для директив thinking, fast-mode чи verbose +summary: Синтаксис директив для `/think`, `/fast`, `/verbose`, `/trace` і видимості міркувань +title: Рівні thinking x-i18n: - generated_at: "2026-04-05T18:21:19Z" + generated_at: "2026-04-12T18:22:22Z" model: gpt-5.4 provider: openai - source_hash: f60aeb6ab4c7ce858f725f589f54184b29d8c91994d18c8deafa75179b9a62cb + source_hash: 4f3b1341281f07ba4e9061e3355845dca234be04cc0d358594312beeb7676e68 source_path: tools/thinking.md workflow: 15 --- -# Рівні мислення (/think directives) +# Рівні thinking (/think директиви) ## Що це робить - Вбудована директива в будь-якому вхідному тілі: `/t `, `/think:` або `/thinking `. -- Рівні (псевдоніми): `off | minimal | low | medium | high | xhigh | adaptive` +- Рівні (аліаси): `off | minimal | low | medium | high | xhigh | adaptive` - minimal → “think” - low → “think hard” - medium → “think harder” - high → “ultrathink” (максимальний бюджет) - - xhigh → “ultrathink+” (лише моделі GPT-5.2 + Codex) - - adaptive → керований провайдером адаптивний бюджет reasoning (підтримується для сімейства моделей Anthropic Claude 4.6) - - `x-high`, `x_high`, `extra-high`, `extra high` і `extra_high` відповідають `xhigh`. - - `highest`, `max` відповідають `high`. + - xhigh → “ultrathink+” (лише GPT-5.2 + моделі Codex) + - adaptive → адаптивний бюджет міркувань, керований провайдером (підтримується для сімейства моделей Anthropic Claude 4.6) + - `x-high`, `x_high`, `extra-high`, `extra high` і `extra_high` зіставляються з `xhigh`. + - `highest`, `max` зіставляються з `high`. - Примітки щодо провайдерів: - - Для моделей Anthropic Claude 4.6 за замовчуванням використовується `adaptive`, якщо явний рівень мислення не задано. - - Для MiniMax (`minimax/*`) на Anthropic-сумісному шляху потокової передачі за замовчуванням використовується `thinking: { type: "disabled" }`, якщо ви явно не задасте thinking у параметрах моделі або параметрах запиту. Це запобігає витоку дельт `reasoning_content` із ненативного формату потоку Anthropic у MiniMax. - - Z.AI (`zai/*`) підтримує лише бінарне мислення (`on`/`off`). Будь-який рівень, відмінний від `off`, трактується як `on` (зіставляється з `low`). - - Moonshot (`moonshot/*`) зіставляє `/think off` з `thinking: { type: "disabled" }`, а будь-який рівень, відмінний від `off`, — з `thinking: { type: "enabled" }`. Коли thinking увімкнено, Moonshot приймає для `tool_choice` лише `auto|none`; OpenClaw нормалізує несумісні значення до `auto`. + - Для моделей Anthropic Claude 4.6 значенням за замовчуванням є `adaptive`, якщо явний рівень thinking не задано. + - Для MiniMax (`minimax/*`) на Anthropic-сумісному шляху потокової передачі типовим є `thinking: { type: "disabled" }`, якщо ви явно не задасте thinking у параметрах моделі або параметрах запиту. Це запобігає витоку дельт `reasoning_content` із ненативного Anthropic-потоку MiniMax. + - Z.AI підтримує лише двійковий thinking (`on`/`off`). Будь-який рівень, відмінний від `off`, трактується як `on` (зіставляється з `low`). + - Moonshot зіставляє `/think off` з `thinking: { type: "disabled" }`, а будь-який рівень, відмінний від `off`, — з `thinking: { type: "enabled" }`. Коли thinking увімкнено, Moonshot приймає лише `tool_choice` `auto|none`; OpenClaw нормалізує несумісні значення до `auto`. ## Порядок визначення 1. Вбудована директива в повідомленні (застосовується лише до цього повідомлення). 2. Перевизначення сесії (встановлюється надсиланням повідомлення, що містить лише директиву). -3. Значення за замовчуванням для окремого агента (`agents.list[].thinkingDefault` у конфігурації). -4. Глобальне значення за замовчуванням (`agents.defaults.thinkingDefault` у конфігурації). -5. Резервний варіант: `adaptive` для моделей Anthropic Claude 4.6, `low` для інших моделей із підтримкою reasoning, і `off` — інакше. +3. Типове значення для конкретного агента (`agents.list[].thinkingDefault` у конфігурації). +4. Глобальне типове значення (`agents.defaults.thinkingDefault` у конфігурації). +5. Запасний варіант: `adaptive` для моделей Anthropic Claude 4.6, `low` для інших моделей із підтримкою міркувань, інакше `off`. -## Установлення значення сесії за замовчуванням +## Установлення типового значення для сесії -- Надішліть повідомлення, яке складається **лише** з директиви (пробіли дозволені), наприклад `/think:medium` або `/t high`. -- Це закріплюється для поточної сесії (за замовчуванням для конкретного відправника); скидається через `/think:off` або idle reset сесії. -- Надсилається відповідь-підтвердження (`Thinking level set to high.` / `Thinking disabled.`). Якщо рівень недійсний (наприклад `/thinking big`), команду буде відхилено з підказкою, а стан сесії залишиться без змін. -- Надішліть `/think` (або `/think:`) без аргументу, щоб побачити поточний рівень мислення. +- Надішліть повідомлення, яке **містить лише** директиву (дозволені пробіли), наприклад `/think:medium` або `/t high`. +- Це закріплюється для поточної сесії (типово для конкретного відправника); скидається через `/think:off` або скидання сесії через бездіяльність. +- Надсилається підтверджувальна відповідь (`Thinking level set to high.` / `Thinking disabled.`). Якщо рівень недійсний (наприклад, `/thinking big`), команду буде відхилено з підказкою, а стан сесії залишиться без змін. +- Надішліть `/think` (або `/think:`) без аргументу, щоб побачити поточний рівень thinking. -## Застосування агентом +## Застосування за агентом -- **Вбудований Pi**: визначений рівень передається до середовища виконання вбудованого агента Pi. +- **Вбудований Pi**: визначений рівень передається в runtime вбудованого агента Pi. ## Швидкий режим (/fast) - Рівні: `on|off`. -- Повідомлення лише з директивою перемикає перевизначення швидкого режиму сесії та повертає `Fast mode enabled.` / `Fast mode disabled.`. +- Повідомлення лише з директивою перемикає перевизначення швидкого режиму для сесії та повертає `Fast mode enabled.` / `Fast mode disabled.`. - Надішліть `/fast` (або `/fast status`) без режиму, щоб побачити поточний ефективний стан швидкого режиму. - OpenClaw визначає швидкий режим у такому порядку: - 1. Вбудований/директивний `/fast on|off` + 1. Вбудована директива/повідомлення лише з директивою `/fast on|off` 2. Перевизначення сесії - 3. Значення за замовчуванням для окремого агента (`agents.list[].fastModeDefault`) - 4. Конфігурація для окремої моделі: `agents.defaults.models["/"].params.fastMode` - 5. Резервний варіант: `off` -- Для `openai/*` швидкий режим зіставляється з пріоритетною обробкою OpenAI шляхом надсилання `service_tier=priority` у підтримуваних запитах Responses. + 3. Типове значення для конкретного агента (`agents.list[].fastModeDefault`) + 4. Конфігурація для конкретної моделі: `agents.defaults.models["/"].params.fastMode` + 5. Запасний варіант: `off` +- Для `openai/*` швидкий режим зіставляється з пріоритетною обробкою OpenAI через надсилання `service_tier=priority` у підтримуваних запитах Responses. - Для `openai-codex/*` швидкий режим надсилає той самий прапорець `service_tier=priority` у Codex Responses. OpenClaw зберігає один спільний перемикач `/fast` для обох шляхів автентифікації. -- Для прямих публічних запитів `anthropic/*`, включно з трафіком OAuth-автентифікації, надісланим до `api.anthropic.com`, швидкий режим зіставляється з рівнями сервісу Anthropic: `/fast on` встановлює `service_tier=auto`, `/fast off` встановлює `service_tier=standard_only`. +- Для прямих публічних запитів `anthropic/*`, включно з трафіком з OAuth-автентифікацією, надісланим до `api.anthropic.com`, швидкий режим зіставляється з рівнями сервісу Anthropic: `/fast on` задає `service_tier=auto`, `/fast off` задає `service_tier=standard_only`. - Для `minimax/*` на Anthropic-сумісному шляху `/fast on` (або `params.fastMode: true`) переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. -- Явні параметри моделі Anthropic `serviceTier` / `service_tier` перевизначають значення швидкого режиму за замовчуванням, коли задано обидва. OpenClaw, як і раніше, пропускає ін’єкцію рівня сервісу Anthropic для базових URL проксі, що не належать Anthropic. +- Явні параметри моделі Anthropic `serviceTier` / `service_tier` мають пріоритет над типовим значенням швидкого режиму, якщо задано обидва. OpenClaw, як і раніше, пропускає ін’єкцію рівня сервісу Anthropic для не-Anthropic проксі `base URL`. ## Директиви verbose (/verbose або /v) -- Рівні: `on` (minimal) | `full` | `off` (за замовчуванням). -- Повідомлення лише з директивою перемикає verbose режим сесії та повертає `Verbose logging enabled.` / `Verbose logging disabled.`; недійсні рівні повертають підказку без зміни стану. -- `/verbose off` зберігає явне перевизначення сесії; очистити його можна через інтерфейс Sessions, вибравши `inherit`. -- Вбудована директива впливає лише на це повідомлення; в інших випадках застосовуються значення за замовчуванням сесії/глобальні. +- Рівні: `on` (мінімальний) | `full` | `off` (типово). +- Повідомлення лише з директивою перемикає verbose для сесії та повертає `Verbose logging enabled.` / `Verbose logging disabled.`; недійсні рівні повертають підказку без зміни стану. +- `/verbose off` зберігає явне перевизначення сесії; очистьте його через UI Sessions, вибравши `inherit`. +- Вбудована директива впливає лише на це повідомлення; інакше застосовуються типові значення сесії/глобальні. - Надішліть `/verbose` (або `/verbose:`) без аргументу, щоб побачити поточний рівень verbose. -- Коли verbose увімкнено, агенти, які видають структуровані результати інструментів (Pi, інші JSON-агенти), надсилають кожен виклик інструмента назад як окреме повідомлення лише з метаданими, з префіксом ` : `, коли доступно (path/command). Ці підсумки інструментів надсилаються щойно запускається кожен інструмент (окремими бульбашками), а не як потокові дельти. -- Підсумки збоїв інструментів залишаються видимими у звичайному режимі, але сирі суфікси з деталями помилок приховано, якщо verbose не дорівнює `on` або `full`. -- Коли verbose має значення `full`, вивід інструментів також пересилається після завершення (окрема бульбашка, усічена до безпечної довжини). Якщо ви перемикаєте `/verbose on|full|off`, поки виконання ще триває, наступні бульбашки інструментів враховують нове налаштування. +- Коли verbose увімкнено, агенти, які повертають структуровані результати інструментів (Pi, інші JSON-агенти), надсилають кожен виклик інструмента назад як окреме повідомлення лише з метаданими, з префіксом ` : `, коли доступно (шлях/команда). Ці зведення інструментів надсилаються щойно кожен інструмент запускається (окремими бульбашками), а не як потокові дельти. +- Зведення про збої інструментів залишаються видимими у звичайному режимі, але необроблені суфікси з деталями помилок приховуються, якщо verbose не дорівнює `on` або `full`. +- Коли verbose дорівнює `full`, виводи інструментів також пересилаються після завершення (окрема бульбашка, обрізана до безпечної довжини). Якщо ви перемкнете `/verbose on|full|off`, поки виконання ще триває, наступні бульбашки інструментів врахують нове налаштування. -## Видимість reasoning (/reasoning) +## Директиви trace для plugin (/trace) + +- Рівні: `on` | `off` (типово). +- Повідомлення лише з директивою перемикає trace-вивід plugin для сесії та повертає `Plugin trace enabled.` / `Plugin trace disabled.`. +- Вбудована директива впливає лише на це повідомлення; інакше застосовуються типові значення сесії/глобальні. +- Надішліть `/trace` (або `/trace:`) без аргументу, щоб побачити поточний рівень trace. +- `/trace` вужчий, ніж `/verbose`: він показує лише рядки trace/debug, що належать plugin, наприклад зведення налагодження Active Memory. +- Рядки trace можуть з’являтися у `/status` і як додаткове діагностичне повідомлення після звичайної відповіді асистента. + +## Видимість міркувань (/reasoning) - Рівні: `on|off|stream`. -- Повідомлення лише з директивою перемикає, чи показуються блоки мислення у відповідях. -- Коли цю опцію ввімкнено, reasoning надсилається як **окреме повідомлення** з префіксом `Reasoning:`. -- `stream` (лише Telegram): транслює reasoning у чернетку-бульбашку Telegram під час генерації відповіді, а потім надсилає фінальну відповідь без reasoning. -- Псевдонім: `/reason`. +- Повідомлення лише з директивою перемикає, чи показуються блоки thinking у відповідях. +- Коли це ввімкнено, міркування надсилаються як **окреме повідомлення** з префіксом `Reasoning:`. +- `stream` (лише Telegram): транслює міркування в чернетку бульбашки Telegram під час генерації відповіді, а потім надсилає фінальну відповідь без міркувань. +- Аліас: `/reason`. - Надішліть `/reasoning` (або `/reasoning:`) без аргументу, щоб побачити поточний рівень reasoning. -- Порядок визначення: вбудована директива, потім перевизначення сесії, потім значення за замовчуванням для окремого агента (`agents.list[].reasoningDefault`), потім резервний варіант (`off`). +- Порядок визначення: вбудована директива, потім перевизначення сесії, потім типове значення для конкретного агента (`agents.list[].reasoningDefault`), потім запасний варіант (`off`). ## Пов’язане -- Документація щодо підвищеного режиму міститься в [Elevated mode](/tools/elevated). +- Документація про підвищений режим міститься в [Підвищений режим](/uk/tools/elevated). -## Heartbeats +## Heartbeat -- Тіло heartbeat probe — це налаштований prompt heartbeat (за замовчуванням: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Вбудовані директиви в heartbeat-повідомленні застосовуються як зазвичай (але уникайте зміни значень сесії за замовчуванням із heartbeat-повідомлень). -- Для доставки heartbeat за замовчуванням використовується лише фінальний payload. Щоб також надсилати окреме повідомлення `Reasoning:` (коли воно доступне), установіть `agents.defaults.heartbeat.includeReasoning: true` або для окремого агента `agents.list[].heartbeat.includeReasoning: true`. +- Тіло probe Heartbeat — це налаштований запит Heartbeat (типово: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Вбудовані директиви в повідомленні Heartbeat застосовуються як завжди (але уникайте зміни типових значень сесії з Heartbeat). +- Доставка Heartbeat типово використовує лише фінальний payload. Щоб також надсилати окреме повідомлення `Reasoning:` (коли доступне), задайте `agents.defaults.heartbeat.includeReasoning: true` або для конкретного агента `agents.list[].heartbeat.includeReasoning: true`. -## Вебінтерфейс чату +## Веб-інтерфейс чату -- Селектор thinking у вебчаті відображає збережений рівень сесії зі сховища/config вхідної сесії під час завантаження сторінки. -- Вибір іншого рівня одразу записує перевизначення сесії через `sessions.patch`; він не чекає наступного надсилання й не є одноразовим перевизначенням `thinkingOnce`. -- Перший варіант завжди має вигляд `Default ()`, де визначене значення за замовчуванням береться з активної моделі сесії: `adaptive` для Claude 4.6 на Anthropic/Bedrock, `low` для інших моделей із підтримкою reasoning, `off` — інакше. -- Селектор залишається обізнаним про провайдера: +- Перемикач thinking у веб-чаті під час завантаження сторінки відображає збережений рівень сесії зі сховища вхідних сесій/конфігурації. +- Вибір іншого рівня одразу записує перевизначення сесії через `sessions.patch`; він не чекає наступного надсилання і не є одноразовим перевизначенням `thinkingOnce`. +- Перший варіант завжди має вигляд `Default ()`, де визначене типове значення береться з активної моделі сесії: `adaptive` для Claude 4.6 на Anthropic/Bedrock, `low` для інших моделей із підтримкою міркувань, інакше `off`. +- Вибір залишається обізнаним про провайдера: - більшість провайдерів показують `off | minimal | low | medium | high | adaptive` - - Z.AI показує бінарний варіант `off | on` -- `/think:` і далі працює та оновлює той самий збережений рівень сесії, тож директиви чату й селектор залишаються синхронізованими. + - Z.AI показує двійкові `off | on` +- `/think:` як і раніше працює та оновлює той самий збережений рівень сесії, тож директиви чату і перемикач залишаються синхронізованими.