diff --git a/docs/uk/concepts/models.md b/docs/uk/concepts/models.md index b755d2661..d0c5f5e80 100644 --- a/docs/uk/concepts/models.md +++ b/docs/uk/concepts/models.md @@ -3,13 +3,13 @@ read_when: - Додавання або змінення CLI моделей (models list/set/scan/aliases/fallbacks) - Зміна поведінки резервних варіантів моделі або UX вибору - Оновлення перевірок сканування моделей (інструменти/зображення) -summary: 'CLI моделей: список, встановлення, псевдоніми, резервні варіанти, сканування, статус' +summary: 'CLI моделей: список, встановлення, псевдоніми, резервні варіанти, сканування, стан' title: CLI моделей x-i18n: - generated_at: "2026-04-22T19:55:24Z" + generated_at: "2026-04-22T22:25:43Z" model: gpt-5.4 provider: openai - source_hash: 99174b625d265fe4743f4e0ca7ea3897bb446a485dde0841e101fe136a08558a + source_hash: 18d915f3f761aaff5efc3bf752f5abddeb625e1a386ab3d701f46fd92244f20e source_path: concepts/models.md workflow: 15 --- @@ -24,34 +24,34 @@ x-i18n: OpenClaw вибирає моделі в такому порядку: 1. **Основна** модель (`agents.defaults.model.primary` або `agents.defaults.model`). -2. **Резервні варіанти** в `agents.defaults.model.fallbacks` (за порядком). +2. **Резервні варіанти** в `agents.defaults.model.fallbacks` (по порядку). 3. **Резервне перемикання автентифікації провайдера** відбувається всередині провайдера перед переходом до наступної моделі. Пов’язане: - `agents.defaults.models` — це allowlist/каталог моделей, які OpenClaw може використовувати (разом із псевдонімами). - `agents.defaults.imageModel` використовується **лише тоді**, коли основна модель не може приймати зображення. -- `agents.defaults.pdfModel` використовується інструментом `pdf`. Якщо його не вказано, інструмент повертається до `agents.defaults.imageModel`, а потім до визначеної для сесії/типової моделі. -- `agents.defaults.imageGenerationModel` використовується спільною можливістю генерації зображень. Якщо його не вказано, `image_generate` усе одно може визначити типовий варіант провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації зображень у порядку `provider-id`. Якщо ви задаєте конкретний провайдер/модель, також налаштуйте автентифікацію/API key цього провайдера. -- `agents.defaults.musicGenerationModel` використовується спільною можливістю генерації музики. Якщо його не вказано, `music_generate` усе одно може визначити типовий варіант провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації музики в порядку `provider-id`. Якщо ви задаєте конкретний провайдер/модель, також налаштуйте автентифікацію/API key цього провайдера. -- `agents.defaults.videoGenerationModel` використовується спільною можливістю генерації відео. Якщо його не вказано, `video_generate` усе одно може визначити типовий варіант провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації відео в порядку `provider-id`. Якщо ви задаєте конкретний провайдер/модель, також налаштуйте автентифікацію/API key цього провайдера. -- Типові значення для окремих агентів можуть перевизначати `agents.defaults.model` через `agents.list[].model` разом із прив’язками (див. [/concepts/multi-agent](/uk/concepts/multi-agent)). +- `agents.defaults.pdfModel` використовується інструментом `pdf`. Якщо його не вказано, інструмент повертається до `agents.defaults.imageModel`, а потім до визначеної моделі сесії/моделі за замовчуванням. +- `agents.defaults.imageGenerationModel` використовується спільною можливістю генерації зображень. Якщо його не вказано, `image_generate` усе одно може визначити значення за замовчуванням провайдера з автентифікацією. Спочатку він пробує поточного провайдера за замовчуванням, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. Якщо ви вказуєте конкретний provider/model, також налаштуйте автентифікацію/API key цього провайдера. +- `agents.defaults.musicGenerationModel` використовується спільною можливістю генерації музики. Якщо його не вказано, `music_generate` усе одно може визначити значення за замовчуванням провайдера з автентифікацією. Спочатку він пробує поточного провайдера за замовчуванням, а потім решту зареєстрованих провайдерів генерації музики у порядку provider-id. Якщо ви вказуєте конкретний provider/model, також налаштуйте автентифікацію/API key цього провайдера. +- `agents.defaults.videoGenerationModel` використовується спільною можливістю генерації відео. Якщо його не вказано, `video_generate` усе одно може визначити значення за замовчуванням провайдера з автентифікацією. Спочатку він пробує поточного провайдера за замовчуванням, а потім решту зареєстрованих провайдерів генерації відео у порядку provider-id. Якщо ви вказуєте конкретний provider/model, також налаштуйте автентифікацію/API key цього провайдера. +- Значення за замовчуванням для окремого агента можуть перевизначати `agents.defaults.model` через `agents.list[].model` разом із прив’язками (див. [/concepts/multi-agent](/uk/concepts/multi-agent)). ## Швидка політика моделей - Встановіть основною найсильнішу модель останнього покоління, яка вам доступна. -- Використовуйте резервні варіанти для завдань, чутливих до вартості/затримки, і для менш критичного чату. -- Для агентів з увімкненими інструментами або для недовірених вхідних даних уникайте старіших/слабших рівнів моделей. +- Використовуйте резервні варіанти для чутливих до вартості/затримки завдань і менш критичного чату. +- Для агентів з увімкненими інструментами або недовірених вхідних даних уникайте старіших/слабших рівнів моделей. -## Онбординг (рекомендовано) +## Початкове налаштування (рекомендовано) -Якщо ви не хочете вручну редагувати конфігурацію, запустіть онбординг: +Якщо ви не хочете вручну редагувати конфігурацію, запустіть початкове налаштування: ```bash openclaw onboard ``` -Він може налаштувати модель + автентифікацію для поширених провайдерів, зокрема **OpenAI Code (Codex) subscription** (OAuth) та **Anthropic** (API key або Claude CLI). +Воно може налаштувати модель + автентифікацію для поширених провайдерів, включно з підпискою **OpenAI Code (Codex)** (OAuth) і **Anthropic** (API key або Claude CLI). ## Ключі конфігурації (огляд) @@ -63,20 +63,32 @@ openclaw onboard - `agents.defaults.models` (allowlist + псевдоніми + параметри провайдера) - `models.providers` (власні провайдери, записані в `models.json`) -Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми провайдерів, як-от `z.ai/*`, нормалізуються до `zai/*`. +Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми провайдерів, такі як `z.ai/*`, нормалізуються до `zai/*`. -Приклади конфігурації провайдерів (зокрема OpenCode) наведено в +Приклади конфігурації провайдерів (включно з OpenCode) наведено в [/providers/opencode](/uk/providers/opencode). -## «Модель не дозволена» (і чому відповіді зупиняються) +### Безпечне редагування allowlist -Якщо задано `agents.defaults.models`, воно стає **allowlist** для `/model` і для перевизначень сесії. Коли користувач вибирає модель, якої немає в цьому allowlist, OpenClaw повертає: +Використовуйте додаткові записи під час ручного оновлення `agents.defaults.models`: + +```bash +openclaw config set agents.defaults.models '{"openai-codex/gpt-5.4":{}}' --strict-json --merge +``` + +`openclaw config set` захищає мапи моделей/провайдерів від випадкового перезапису. Просте присвоєння об’єкта для `agents.defaults.models`, `models.providers` або `models.providers..models` відхиляється, якщо воно видалить наявні записи. Використовуйте `--merge` для додаткових змін; використовуйте `--replace` лише тоді, коли передане значення має стати повним цільовим значенням. + +Інтерактивне налаштування провайдера та `openclaw configure --section model` також об’єднують вибрані значення в межах провайдера з наявним allowlist, тому додавання Codex, Ollama або іншого провайдера не видаляє не пов’язані записи моделей. + +## "Model is not allowed" (і чому відповіді зупиняються) + +Якщо встановлено `agents.defaults.models`, він стає **allowlist** для `/model` і для перевизначень сесії. Коли користувач вибирає модель, якої немає в цьому allowlist, OpenClaw повертає: ``` Model "provider/model" is not allowed. Use /model to list available models. ``` -Це відбувається **до** генерації звичайної відповіді, тому може здаватися, що повідомлення «не отримало відповіді». Виправити це можна так: +Це відбувається **до** створення звичайної відповіді, тому може здаватися, що повідомлення «не отримало відповіді». Виправити це можна так: - Додати модель до `agents.defaults.models`, або - Очистити allowlist (видалити `agents.defaults.models`), або @@ -110,28 +122,26 @@ Model "provider/model" is not allowed. Use /model to list available models. Примітки: -- `/model` (і `/model list`) — це компактний нумерований вибір (сімейство моделей + доступні провайдери). -- У Discord `/model` і `/models` відкривають інтерактивний вибір із випадними списками провайдера та моделі, а також кроком Submit. -- `/models add` доступна типово й може бути вимкнена через `commands.modelsWrite=false`. -- Якщо ввімкнено, `/models add ` — це найшвидший шлях; просто `/models add` запускає керований процес із вибором провайдера спочатку, де це підтримується. +- `/model` (і `/model list`) — це компактний нумерований засіб вибору (сімейство моделей + доступні провайдери). +- У Discord `/model` і `/models` відкривають інтерактивний засіб вибору з випадними списками провайдера й моделі та кроком Submit. +- `/models add` доступна за замовчуванням і може бути вимкнена через `commands.modelsWrite=false`. +- Якщо команду увімкнено, `/models add ` — найшвидший шлях; проста `/models add` запускає покроковий потік із вибором провайдера спочатку, де це підтримується. - Після `/models add` нова модель стає доступною в `/models` і `/model` без перезапуску Gateway. -- `/model <#>` вибирає модель із цього списку. -- `/model` одразу зберігає новий вибір для сесії. +- `/model <#>` вибирає зі списку цього засобу вибору. +- `/model` одразу зберігає новий вибір сесії. - Якщо агент неактивний, наступний запуск одразу використовує нову модель. -- Якщо запуск уже активний, OpenClaw позначає перемикання на льоту як очікуване й перезапускає в нову модель лише в чистій точці повторної спроби. -- Якщо активність інструментів або виведення відповіді вже почалися, очікуване перемикання може залишатися в черзі до пізнішої можливості повторної спроби або до наступного ходу користувача. -- `/model status` — це детальне подання (кандидати автентифікації та, коли налаштовано, `baseUrl` кінцевої точки провайдера + режим `api`). -- Посилання на модель розбираються шляхом поділу за **першим** `/`. Під час введення `/model ` використовуйте `provider/model`. -- Якщо сам ID моделі містить `/` (у стилі OpenRouter), ви маєте вказати префікс провайдера (приклад: `/model openrouter/moonshotai/kimi-k2`). +- Якщо запуск уже активний, OpenClaw позначає перемикання наживо як очікуване та перезапускає на нову модель лише в чистій точці повторної спроби. +- Якщо активність інструментів або виведення відповіді вже почалися, очікуване перемикання може залишатися в черзі до пізнішої можливості повторної спроби або наступного ходу користувача. +- `/model status` — це докладний перегляд (кандидати автентифікації та, якщо налаштовано, `baseUrl` кінцевої точки провайдера + режим `api`). +- Посилання на моделі розбираються шляхом поділу за **першим** `/`. Використовуйте `provider/model`, коли вводите `/model `. +- Якщо сам model id містить `/` (у стилі OpenRouter), ви маєте вказати префікс провайдера (приклад: `/model openrouter/moonshotai/kimi-k2`). - Якщо ви не вказуєте провайдера, OpenClaw визначає введення в такому порядку: 1. збіг псевдоніма - 2. однозначний збіг налаштованого провайдера для цього точного ID моделі без префікса - 3. застарілий резервний перехід до налаштованого типового провайдера - Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw - натомість переходить до першого налаштованого провайдера/моделі, щоб уникнути - показу застарілого типового значення видаленого провайдера. + 2. унікальний збіг налаштованого провайдера для цього точного model id без префікса + 3. застарілий резервний перехід до налаштованого провайдера за замовчуванням + Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw замість цього переходить до першого налаштованого provider/model, щоб уникнути показу застарілого значення за замовчуванням від видаленого провайдера. -Повна поведінка команди/конфігурація: [Косі команди](/uk/tools/slash-commands). +Повна поведінка/конфігурація команди: [Slash commands](/uk/tools/slash-commands). Приклади: @@ -141,7 +151,7 @@ Model "provider/model" is not allowed. Use /model to list available models. /models add lmstudio qwen/qwen3.5-9b ``` -## CLI команди +## Команди CLI ```bash openclaw models list @@ -168,30 +178,26 @@ openclaw models image-fallbacks clear ### `models list` -Типово показує налаштовані моделі. Корисні прапорці: +За замовчуванням показує налаштовані моделі. Корисні прапорці: - `--all`: повний каталог - `--local`: лише локальні провайдери - `--provider `: фільтр за провайдером - `--plain`: одна модель на рядок -- `--json`: машинозчитуваний вивід +- `--json`: машиночитний вивід -`--all` включає рядки статичного каталогу вбудованих провайдерів ще до налаштування автентифікації, тож подання лише для виявлення можуть показувати моделі, недоступні, доки ви не додасте відповідні облікові дані провайдера. +`--all` включає рядки статичного каталогу вбудованих провайдерів ще до налаштування автентифікації, тому перегляди лише для виявлення можуть показувати моделі, які недоступні, доки ви не додасте відповідні облікові дані провайдера. ### `models status` -Показує визначені основну модель, резервні варіанти, модель для зображень і огляд автентифікації налаштованих провайдерів. Також показує стан завершення строку дії OAuth для профілів, знайдених у сховищі автентифікації (типово попереджає за 24 год). `--plain` виводить лише визначену основну модель. -Стан OAuth показується завжди (і включається у вивід `--json`). Якщо налаштований провайдер не має облікових даних, `models status` виводить розділ **Відсутня автентифікація**. -JSON містить `auth.oauth` (вікно попередження + профілі) та `auth.providers` -(ефективна автентифікація для кожного провайдера, зокрема облікові дані з env). `auth.oauth` -стосується лише стану профілів у сховищі автентифікації; провайдери лише з env там не з’являються. -Використовуйте `--check` для автоматизації (код виходу `1` для відсутніх/прострочених, `2` для тих, що скоро спливають). -Використовуйте `--probe` для живих перевірок автентифікації; рядки перевірок можуть надходити з профілів автентифікації, облікових даних env або `models.json`. -Якщо явний `auth.order.` пропускає збережений профіль, перевірка повідомляє -`excluded_by_auth_order` замість спроби його використати. Якщо автентифікація є, але для цього провайдера неможливо визначити модель, придатну для перевірки, перевірка повідомляє `status: no_model`. +Показує визначену основну модель, резервні варіанти, модель зображень і огляд автентифікації налаштованих провайдерів. Також відображає стан завершення дії OAuth для профілів, знайдених у сховищі автентифікації (типово попереджає в межах 24 год). `--plain` виводить лише визначену основну модель. +Стан OAuth показується завжди (і включається у вивід `--json`). Якщо налаштований провайдер не має облікових даних, `models status` виводить розділ **Missing auth**. +JSON включає `auth.oauth` (вікно попередження + профілі) і `auth.providers` (ефективна автентифікація для кожного провайдера, включно з обліковими даними з env). `auth.oauth` — це лише стан профілів зі сховища автентифікації; провайдери лише з env там не відображаються. +Використовуйте `--check` для автоматизації (код виходу `1`, якщо відсутні/прострочені, `2`, якщо скоро завершаться). +Використовуйте `--probe` для живих перевірок автентифікації; рядки перевірок можуть походити з профілів автентифікації, облікових даних env або `models.json`. +Якщо явний `auth.order.` пропускає збережений профіль, перевірка повертає `excluded_by_auth_order` замість спроби його використати. Якщо автентифікація є, але для цього провайдера не вдається визначити модель, придатну для probe, перевірка повертає `status: no_model`. -Вибір автентифікації залежить від провайдера/облікового запису. Для постійно активних хостів Gateway -API key зазвичай найпередбачуваніші; також підтримується повторне використання Claude CLI та наявних профілів OAuth/token Anthropic. +Вибір автентифікації залежить від провайдера/облікового запису. Для хостів Gateway, які працюють постійно, API key зазвичай найпередбачуваніші; також підтримується повторне використання Claude CLI та наявних профілів OAuth/token Anthropic. Приклад (Claude CLI): @@ -200,64 +206,59 @@ claude auth login openclaw models status ``` -## Сканування (безплатні моделі OpenRouter) +## Сканування (безкоштовні моделі OpenRouter) -`openclaw models scan` перевіряє **каталог безплатних моделей** OpenRouter і може -за бажанням виконувати перевірку моделей на підтримку інструментів і зображень. +`openclaw models scan` перевіряє **каталог безкоштовних моделей** OpenRouter і за потреби може виконувати probe моделей на підтримку інструментів і зображень. Основні прапорці: -- `--no-probe`: пропустити живі перевірки (лише метадані) +- `--no-probe`: пропустити живі probe (лише метадані) - `--min-params `: мінімальний розмір параметрів (у мільярдах) - `--max-age-days `: пропустити старіші моделі -- `--provider `: фільтр за префіксом провайдера +- `--provider `: фільтр префікса провайдера - `--max-candidates `: розмір списку резервних варіантів - `--set-default`: встановити `agents.defaults.model.primary` на перший вибір -- `--set-image`: встановити `agents.defaults.imageModel.primary` на перший вибір зображення +- `--set-image`: встановити `agents.defaults.imageModel.primary` на перший вибір зображень -Перевірка потребує API key OpenRouter (з профілів автентифікації або -`OPENROUTER_API_KEY`). Без ключа використовуйте `--no-probe`, щоб лише перелічити кандидатів. +Виконання probe потребує OpenRouter API key (з профілів автентифікації або `OPENROUTER_API_KEY`). Без ключа використовуйте `--no-probe`, щоб лише перелічити кандидатів. Результати сканування ранжуються за: -1. Підтримка зображень -2. Затримка інструментів -3. Розмір контексту -4. Кількість параметрів +1. Підтримкою зображень +2. Затримкою інструментів +3. Розміром контексту +4. Кількістю параметрів Вхідні дані - Список OpenRouter `/models` (фільтр `:free`) -- Потребує API key OpenRouter із профілів автентифікації або `OPENROUTER_API_KEY` (див. [/environment](/uk/help/environment)) +- Потребує OpenRouter API key з профілів автентифікації або `OPENROUTER_API_KEY` (див. [/environment](/uk/help/environment)) - Необов’язкові фільтри: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates` -- Керування перевіркою: `--timeout`, `--concurrency` +- Керування probe: `--timeout`, `--concurrency` -Під час запуску в TTY ви можете інтерактивно вибирати резервні варіанти. У неінтерактивному -режимі передайте `--yes`, щоб прийняти типові значення. +Під час запуску в TTY ви можете інтерактивно вибрати резервні варіанти. У неінтерактивному режимі передайте `--yes`, щоб прийняти значення за замовчуванням. ## Реєстр моделей (`models.json`) -Власні провайдери в `models.providers` записуються в `models.json` у каталозі -агента (типово `~/.openclaw/agents//agent/models.json`). Цей файл -типово об’єднується, якщо тільки `models.mode` не встановлено в `replace`. +Власні провайдери в `models.providers` записуються в `models.json` у каталозі агента (типово `~/.openclaw/agents//agent/models.json`). Цей файл за замовчуванням об’єднується, якщо `models.mode` не встановлено в `replace`. -Пріоритет у режимі злиття для однакових ID провайдерів: +Пріоритет у режимі злиття для збіжних ID провайдерів: -- Непорожній `baseUrl`, уже наявний в `models.json` агента, має пріоритет. +- Непорожній `baseUrl`, уже наявний у `models.json` агента, має пріоритет. - Непорожній `apiKey` у `models.json` агента має пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті конфігурації/профілю автентифікації. -- Значення `apiKey` провайдера, якими керує SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для посилань file/exec) замість збереження розкритих секретів. -- Значення заголовків провайдера, якими керує SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-посилань, `secretref-managed` для посилань file/exec). -- Порожні або відсутні `apiKey`/`baseUrl` агента переходять до конфігурації `models.providers`. +- Значення `apiKey` для провайдерів, якими керує SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження розкритих секретів. +- Значення заголовків провайдера, якими керує SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань). +- Порожні або відсутні `apiKey`/`baseUrl` агента повертаються до конфігурації `models.providers`. - Інші поля провайдера оновлюються з конфігурації та нормалізованих даних каталогу. -Збереження маркерів є авторитетним щодо джерела: OpenClaw записує маркери з активного знімка конфігурації джерела (до розв’язання), а не з розв’язаних значень секретів часу виконання. -Це застосовується щоразу, коли OpenClaw повторно генерує `models.json`, зокрема в шляхах, ініційованих командами, як-от `openclaw agent`. +Збереження маркерів є авторитетним щодо джерела: OpenClaw записує маркери з активного знімка конфігурації джерела (до розкриття значень), а не з розкритих значень секретів під час виконання. +Це застосовується щоразу, коли OpenClaw повторно генерує `models.json`, включно зі шляхами, ініційованими командами, такими як `openclaw agent`. ## Пов’язане - [Провайдери моделей](/uk/concepts/model-providers) — маршрутизація провайдерів і автентифікація - [Резервне перемикання моделей](/uk/concepts/model-failover) — ланцюжки резервних варіантів - [Генерація зображень](/uk/tools/image-generation) — конфігурація моделі зображень -- [Генерація музики](/uk/tools/music-generation) — конфігурація музичної моделі -- [Генерація відео](/uk/tools/video-generation) — конфігурація відеомоделі +- [Генерація музики](/uk/tools/music-generation) — конфігурація моделі музики +- [Генерація відео](/uk/tools/video-generation) — конфігурація моделі відео - [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделей diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index 60caac149..3aaa9e7d9 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -1,70 +1,70 @@ --- read_when: - - Потрібні точні семантики полів конфігурації або значення за замовчуванням + - Вам потрібні точні семантики полів конфігурації або значення за замовчуванням - Ви перевіряєте блоки конфігурації каналу, моделі, Gateway або інструмента -summary: Довідник із конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем -title: Довідник із конфігурації +summary: Довідник з конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем +title: Довідник з конфігурації x-i18n: - generated_at: "2026-04-22T05:34:59Z" + generated_at: "2026-04-22T22:25:46Z" model: gpt-5.4 provider: openai - source_hash: f0d6fc076f54e84bef5beefbcc42d8f172cc79792c716f76103894303e3042ac + source_hash: f602f43fe750e99d5fed261634ce569c0034415cd1769e501e98d0ebe0ad1c19 source_path: gateway/configuration-reference.md workflow: 15 --- -# Довідник із конфігурації +# Довідник з конфігурації -Основний довідник із конфігурації для `~/.openclaw/openclaw.json`. Огляд, орієнтований на завдання, див. у [Configuration](/uk/gateway/configuration). +Основний довідник з конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration). -Ця сторінка охоплює основні поверхні конфігурації OpenClaw і дає посилання назовні, коли підсистема має власний докладніший довідник. Вона **не** намагається вбудувати на одній сторінці кожен каталог команд, що належить каналу/Plugin, або кожен глибокий параметр пам’яті/QMD. +На цій сторінці описано основні поверхні конфігурації OpenClaw і наведено посилання, якщо підсистема має власний, глибший довідник. Вона **не** намагається вбудувати на одну сторінку кожен каталог команд, що належить каналу/плагіну, або кожен глибокий параметр пам’яті/QMD. Джерело істини в коді: -- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, з об’єднаними метаданими bundled/Plugin/channel, коли вони доступні -- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів поглибленого перегляду +- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, із метаданими bundled/plugin/channel, об’єднаними за наявності +- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів деталізації - `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш документації конфігурації щодо поточної поверхні схеми -Окремі докладні довідники: +Окремі глибокі довідники: -- [Довідник із конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації Dreaming у `plugins.entries.memory-core.config.dreaming` -- [Слеш-команди](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд -- сторінки відповідного каналу/Plugin для поверхонь команд, специфічних для каналу +- [Довідник з конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming` +- [Slash Commands](/uk/tools/slash-commands) для поточного каталогу вбудованих + bundled команд +- сторінки власників каналів/плагінів для поверхонь команд, специфічних для каналів -Формат конфігурації — **JSON5** (дозволені коментарі й кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено. +Формат конфігурації — **JSON5** (дозволені коментарі та кінцеві коми). Усі поля необов’язкові — якщо їх пропущено, OpenClaw використовує безпечні значення за замовчуванням. --- ## Канали -Кожен канал запускається автоматично, коли існує його секція конфігурації (якщо тільки не вказано `enabled: false`). +Кожен канал запускається автоматично, коли існує його розділ конфігурації (якщо не вказано `enabled: false`). ### Доступ до DM і груп -Усі канали підтримують політики DM і політики груп: +Усі канали підтримують політики DM і групові політики: -| Політика DM | Поведінка | -| ------------------- | --------------------------------------------------------------- | -| `pairing` (типово) | Невідомі відправники отримують одноразовий код сполучення; власник має підтвердити | -| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволених сполучених контактів) | -| `open` | Дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) | -| `disabled` | Ігнорувати всі вхідні DM | +| Політика DM | Поведінка | +| ------------------- | ---------------------------------------------------------------- | +| `pairing` (типово) | Невідомі відправники отримують одноразовий код сполучення; власник має схвалити | +| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволених після сполучення) | +| `open` | Дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) | +| `disabled` | Ігнорувати всі вхідні DM | -| Політика груп | Поведінка | +| Групова політика | Поведінка | | --------------------- | ------------------------------------------------------ | | `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволених | -| `open` | Обійти списки дозволених груп (обмеження за згадуванням усе ще застосовується) | +| `open` | Обійти списки дозволених для груп (обмеження за згадками все одно застосовується) | | `disabled` | Блокувати всі повідомлення груп/кімнат | -`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` провайдера не встановлено. -Коди сполучення діють 1 годину. Незавершені запити на сполучення DM обмежені **3 на канал**. +`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` провайдера не задано. +Коди сполучення спливають через 1 годину. Кількість запитів на сполучення DM, що очікують, обмежена **3 на канал**. Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (fail-closed) із попередженням під час запуску. -### Перевизначення моделі для каналів +### Перевизначення моделі для каналу -Використовуйте `channels.modelByChannel`, щоб закріпити конкретні ідентифікатори каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Це зіставлення каналу застосовується, коли сесія ще не має перевизначення моделі (наприклад, установленого через `/model`). +Використовуйте `channels.modelByChannel`, щоб закріпити певні ID каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Прив’язка каналу застосовується, коли для сесії ще немає перевизначення моделі (наприклад, заданого через `/model`). ```json5 { @@ -85,9 +85,9 @@ x-i18n: } ``` -### Типові значення каналів і Heartbeat +### Значення каналів за замовчуванням і Heartbeat -Використовуйте `channels.defaults` для спільної поведінки політики груп і Heartbeat у різних провайдерів: +Використовуйте `channels.defaults` для спільної групової політики та поведінки Heartbeat між провайдерами: ```json5 { @@ -105,15 +105,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`: резервна політика груп, коли `groupPolicy` на рівні провайдера не встановлено. -- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь контекст цитат/гілок/історії), `allowlist` (включати контекст лише від відправників зі списку дозволених), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення для каналу: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: включати здорові статуси каналів у вивід Heartbeat. +- `channels.defaults.groupPolicy`: резервна групова політика, коли `groupPolicy` на рівні провайдера не задано. +- `channels.defaults.contextVisibility`: режим видимості додаткового контексту за замовчуванням для всіх каналів. Значення: `all` (типово, включати весь контекст цитат/гілок/історії), `allowlist` (включати контекст лише від дозволених відправників), `allowlist_quote` (як `allowlist`, але зберігати явний контекст цитування/відповіді). Перевизначення на рівні каналу: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: включати статуси здорових каналів у вивід Heartbeat. - `channels.defaults.heartbeat.showAlerts`: включати деградовані/помилкові статуси у вивід Heartbeat. - `channels.defaults.heartbeat.useIndicator`: відображати компактний вивід Heartbeat у стилі індикатора. ### WhatsApp -WhatsApp працює через вебканал Gateway (Baileys Web). Він запускається автоматично, коли існує прив’язана сесія. +WhatsApp працює через вебканал Gateway (Baileys Web). Він запускається автоматично, коли існує пов’язана сесія. ```json5 { @@ -146,7 +146,7 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` - + ```json5 { @@ -164,10 +164,10 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- Вихідні команди типово використовують обліковий запис `default`, якщо він є; інакше — перший налаштований ідентифікатор облікового запису (після сортування). -- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. -- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується командою `openclaw doctor` до `whatsapp/default`. -- Перевизначення для окремого облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. +- Вихідні команди типово використовують обліковий запис `default`, якщо він є; інакше — перший налаштований ID облікового запису (після сортування). +- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. +- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується командою `openclaw doctor` у `whatsapp/default`. +- Перевизначення на рівні облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -225,12 +225,12 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; символічні посилання відхиляються), з `TELEGRAM_BOT_TOKEN` як резервним варіантом для типового облікового запису. -- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. -- У конфігураціях із кількома обліковими записами (2+ ідентифікатори облікових записів) установіть явний типовий обліковий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього немає або значення некоректне. -- `configWrites: false` блокує ініційовані через Telegram записи конфігурації (міграції ID супергруп, `/config set|unset`). -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- Попередній перегляд потоків у Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах). +- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; симлінки відхиляються), із резервним `TELEGRAM_BOT_TOKEN` для типового облікового запису. +- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. +- У багатооблікових конфігураціях (2+ ID облікових записів) задайте явний типовий обліковий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього бракує або значення некоректне. +- `configWrites: false` блокує записи конфігурації, ініційовані з Telegram (міграції ID супергруп, `/config set|unset`). +- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив’язки ACP для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Попередній перегляд потоків Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах). - Політика повторних спроб: див. [Політика повторних спроб](/uk/concepts/retry). ### Discord @@ -333,34 +333,34 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервним варіантом для типового облікового запису. -- Прямі вихідні виклики, що явно передають Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime. -- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. -- Використовуйте `user:` (DM) або `channel:` (канал guild) для цілей доставки; прості числові ідентифікатори відхиляються. -- Слаги guild мають нижній регістр, а пробіли в них замінюються на `-`; ключі каналів використовують назву у вигляді слага (без `#`). Надавайте перевагу ID guild. +- Токен: `channels.discord.token`, із резервним `DISCORD_BOT_TOKEN` для типового облікового запису. +- Прямі вихідні виклики, які явно передають Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime. +- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. +- Для цілей доставки використовуйте `user:` (DM) або `channel:` (канал guild); числові ID без префікса відхиляються. +- Slug-и guild мають нижній регістр, а пробіли замінюються на `-`; ключі каналів використовують slug-ім’я (без `#`). Надавайте перевагу ID guild. - Повідомлення, створені ботом, типово ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно відфільтровуються). -- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення на рівні каналу) відкидає повідомлення, у яких згадується інший користувач або роль, але не бот (крім @everyone/@here). +- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення на рівні каналу) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (крім @everyone/@here). - `maxLinesPerMessage` (типово 17) розбиває довгі за висотою повідомлення, навіть якщо вони коротші за 2000 символів. -- `channels.discord.threadBindings` керує маршрутизацією з прив’язкою до гілок Discord: - - `enabled`: перевизначення Discord для функцій сесій із прив’язкою до гілок (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і доставка/маршрутизація з прив’язкою) - - `idleHours`: перевизначення Discord для автоматичного зняття фокуса через неактивність у годинах (`0` вимикає) +- `channels.discord.threadBindings` керує маршрутизацією, прив’язаною до гілок Discord: + - `enabled`: перевизначення Discord для функцій сесій, прив’язаних до гілок (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і пов’язана доставка/маршрутизація) + - `idleHours`: перевизначення Discord для автоматичного зняття focus через неактивність у годинах (`0` вимикає) - `maxAgeHours`: перевизначення Discord для жорсткого максимального віку в годинах (`0` вимикає) - - `spawnSubagentSessions`: перемикач opt-in для автоматичного створення/прив’язки гілок через `sessions_spawn({ thread: true })` + - `spawnSubagentSessions`: перемикач opt-in для автоматичного створення/прив’язки гілок `sessions_spawn({ thread: true })` - Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і гілок (використовуйте id каналу/гілки в `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` задає колір акценту для контейнерів компонентів Discord v2. +- `channels.discord.ui.components.accentColor` задає акцентний колір для контейнерів Discord components v2. - `channels.discord.voice` вмикає розмови в голосових каналах Discord і необов’язкові перевизначення auto-join + TTS. - `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` напряму передаються в параметри DAVE `@discordjs/voice` (типово `true` і `24`). -- OpenClaw додатково намагається відновити прийом голосу, виходячи з голосової сесії та приєднуючись знову після повторних збоїв дешифрування. -- `channels.discord.streaming` — канонічний ключ режиму потокової передачі. Застарілі `streamMode` і булеві значення `streaming` мігруються автоматично. -- `channels.discord.autoPresence` зіставляє доступність runtime зі статусом присутності бота (healthy => online, degraded => idle, exhausted => dnd) і дає змогу необов’язково перевизначати текст статусу. -- `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваним ім’ям/тегом (аварійний режим сумісності). -- `channels.discord.execApprovals`: власна доставка погоджень exec для Discord і авторизація погоджувачів. +- OpenClaw також намагається відновити прийом голосу, виходячи з голосової сесії та повторно приєднуючись після повторних збоїв дешифрування. +- `channels.discord.streaming` — канонічний ключ режиму потокової передачі. Застарілі значення `streamMode` і булеві значення `streaming` автоматично мігруються. +- `channels.discord.autoPresence` зіставляє доступність runtime зі статусом присутності бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. +- `channels.discord.dangerouslyAllowNameMatching` повторно вмикає зіставлення за змінним ім’ям/тегом (режим сумісності на крайній випадок). +- `channels.discord.execApprovals`: нативна для Discord доставка погоджень exec і авторизація погоджувачів. - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі погодження exec активуються, коли погоджувачів можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Discord, яким дозволено погоджувати запити exec. Якщо не вказано, використовується `commands.ownerAllowFrom`. - - `agentFilter`: необов’язковий список дозволених ID агентів. Якщо пропустити, погодження пересилатимуться для всіх агентів. - - `sessionFilter`: необов’язкові шаблони ключів сесії (підрядок або regex). - - `target`: куди надсилати запити на погодження. `"dm"` (типово) надсилає в DM погоджувачам, `"channel"` надсилає у вихідний канал, `"both"` надсилає в обидва місця. Коли ціль містить `"channel"`, кнопками можуть користуватися лише визначені погоджувачі. - - `cleanupAfterResolve`: якщо `true`, видаляє DM із погодженням після схвалення, відхилення або тайм-ауту. + - `approvers`: ID користувачів Discord, яким дозволено погоджувати exec-запити. Якщо не вказано, використовується резервне значення з `commands.ownerAllowFrom`. + - `agentFilter`: необов’язковий allowlist ID агентів. Якщо пропустити, погодження пересилаються для всіх агентів. + - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). + - `target`: куди надсилати запити на погодження. `"dm"` (типово) надсилає в DM погоджувачів, `"channel"` — у вихідний канал, `"both"` — в обидва місця. Коли ціль містить `"channel"`, кнопками можуть користуватися лише визначені погоджувачі. + - `cleanupAfterResolve`: якщо `true`, видаляє DM із погодженнями після погодження, відхилення або тайм-ауту. **Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (із `guilds..users` для всіх повідомлень). @@ -393,11 +393,11 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- JSON облікового запису сервісу: вбудований (`serviceAccount`) або на основі файлу (`serviceAccountFile`). -- Також підтримується SecretRef облікового запису сервісу (`serviceAccountRef`). -- Резервні змінні середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- JSON службового облікового запису: вбудований (`serviceAccount`) або на основі файла (`serviceAccountFile`). +- Також підтримується SecretRef службового облікового запису (`serviceAccountRef`). +- Резервні значення середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - Для цілей доставки використовуйте `spaces/` або `users/`. -- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваним email principal (аварійний режим сумісності). +- `channels.googlechat.dangerouslyAllowNameMatching` повторно вмикає зіставлення за змінним email principal (режим сумісності на крайній випадок). ### Slack @@ -464,35 +464,35 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він } ``` -- **Socket mode** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як резервні змінні середовища для типового облікового запису). +- **Режим socket** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як резервні значення змінних середовища для типового облікового запису). - **HTTP mode** вимагає `botToken` плюс `signingSecret` (у корені або для окремого облікового запису). -- `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті +- `botToken`, `appToken`, `signingSecret` і `userToken` приймають звичайні текстові рядки або об’єкти SecretRef. -- Знімки облікових записів Slack показують поля джерела/статусу для окремих - облікових даних, такі як `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у HTTP mode, +- Знімки облікових записів Slack показують поля джерела/статусу для кожних облікових даних, такі як + `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у HTTP mode, `signingSecretStatus`. `configured_unavailable` означає, що обліковий запис - налаштований через SecretRef, але поточний шлях команди/runtime не зміг + налаштовано через SecretRef, але поточний шлях команди/runtime не зміг визначити значення секрету. -- `configWrites: false` блокує ініційовані через Slack записи конфігурації. -- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. -- `channels.slack.streaming.mode` — канонічний ключ режиму потокової передачі Slack. `channels.slack.streaming.nativeTransport` керує власним транспортом потокової передачі Slack. Застарілі `streamMode`, булеві значення `streaming` і `nativeStreaming` мігруються автоматично. +- `configWrites: false` блокує записи конфігурації, ініційовані зі Slack. +- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. +- `channels.slack.streaming.mode` — канонічний ключ режиму потокової передачі Slack. `channels.slack.streaming.nativeTransport` керує нативним транспортом потокової передачі Slack. Застарілі значення `streamMode`, булеві значення `streaming` і `nativeStreaming` автоматично мігруються. - Для цілей доставки використовуйте `user:` (DM) або `channel:`. **Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). -**Ізоляція сесій гілок:** `thread.historyScope` — окремо для кожної гілки (типово) або спільно для каналу. `thread.inheritParent` копіює стенограму батьківського каналу в нові гілки. +**Ізоляція сесій гілок:** `thread.historyScope` — окремо для кожної гілки (типово) або спільно на канал. `thread.inheritParent` копіює журнал батьківського каналу в нові гілки. -- Власна потокова передача Slack разом зі статусом гілки Slack у стилі асистента "is typing..." вимагають ціль у вигляді гілки відповіді. DM верхнього рівня типово залишаються поза гілками, тому вони використовують `typingReaction` або звичайну доставку замість попереднього перегляду у стилі гілки. +- Нативна потокова передача Slack разом зі статусом гілки Slack у стилі assistant "is typing..." потребують ціль відповіді у гілці. DM верхнього рівня типово лишаються поза гілками, тому використовують `typingReaction` або звичайну доставку замість попереднього перегляду у стилі гілки. - `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: власна доставка погоджень exec для Slack і авторизація погоджувачів. Та сама схема, що й для Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). +- `channels.slack.execApprovals`: нативна для Slack доставка погоджень exec і авторизація погоджувачів. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). -| Група дій | Типово | Примітки | -| ------------ | -------- | ------------------------ | -| reactions | увімкнено | Реакції + список реакцій | +| Група дій | Типово | Примітки | +| ------------ | -------- | ---------------------- | +| reactions | увімкнено | Реакція + список реакцій | | messages | увімкнено | Читання/надсилання/редагування/видалення | | pins | увімкнено | Закріплення/відкріплення/список | | memberInfo | увімкнено | Інформація про учасника | -| emojiList | увімкнено | Список користувацьких emoji | +| emojiList | увімкнено | Список власних emoji | ### Mattermost @@ -528,21 +528,21 @@ Mattermost постачається як Plugin: `openclaw plugins install @open Режими чату: `oncall` (відповідати на @-згадування, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса тригера). -Коли власні команди Mattermost увімкнено: +Коли нативні команди Mattermost увімкнені: - `commands.callbackPath` має бути шляхом (наприклад, `/api/channels/mattermost/command`), а не повним URL. - `commands.callbackUrl` має вказувати на endpoint Gateway OpenClaw і бути доступним із сервера Mattermost. -- Власні виклики слеш-команд автентифікуються за токенами для окремих команд, які Mattermost повертає - під час реєстрації слеш-команд. Якщо реєстрація не вдається або жодної - команди не активовано, OpenClaw відхиляє виклики з повідомленням +- Нативні slash callback-и автентифікуються за допомогою токенів для кожної команди, які + Mattermost повертає під час реєстрації slash-команд. Якщо реєстрація не вдається або + жодну команду не активовано, OpenClaw відхиляє callback-и з `Unauthorized: invalid command token.` -- Для приватних/tailnet/internal хостів зворотних викликів Mattermost може вимагати, - щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен зворотного виклику. +- Для приватних/tailnet/internal хостів callback-ів Mattermost може вимагати, + щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен callback-а. Використовуйте значення хоста/домену, а не повні URL. -- `channels.mattermost.configWrites`: дозволити або заборонити ініційовані через Mattermost записи конфігурації. +- `channels.mattermost.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Mattermost. - `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в каналах. -- `channels.mattermost.groups..requireMention`: перевизначення обмеження за згадуванням для окремого каналу (`"*"` для типового значення). -- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- `channels.mattermost.groups..requireMention`: перевизначення обмеження за згадкою на рівні каналу (`"*"` для типового значення). +- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. ### Signal @@ -565,9 +565,9 @@ Mattermost постачається як Plugin: `openclaw plugins install @open **Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). -- `channels.signal.account`: прив’язати запуск каналу до конкретної ідентичності облікового запису Signal. -- `channels.signal.configWrites`: дозволити або заборонити ініційовані через Signal записи конфігурації. -- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- `channels.signal.account`: закріпити запуск каналу за конкретною ідентичністю облікового запису Signal. +- `channels.signal.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Signal. +- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. ### BlueBubbles @@ -586,14 +586,14 @@ BlueBubbles — рекомендований шлях для iMessage (на ос } ``` -- Основні шляхи ключів, охоплені тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних ACP-сесій. Використовуйте handle або цільовий рядок BlueBubbles (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Основні шляхи ключів, описані тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. +- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних ACP-сесій. Використовуйте дескриптор BlueBubbles або рядок цілі (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). - Повну конфігурацію каналу BlueBubbles задокументовано в [BlueBubbles](/uk/channels/bluebubbles). ### iMessage -OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Daemon або порт не потрібні. +OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Не потрібні ані демон, ані порт. ```json5 { @@ -617,15 +617,15 @@ OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Daemon або } ``` -- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. +- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. -- Потребує Full Disk Access до БД Messages. +- Потрібен Full Disk Access до БД Messages. - Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів. -- `cliPath` може вказувати на SSH-обгортку; установіть `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. +- `cliPath` може вказувати на SSH-обгортку; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. - `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (типово: `/Users/*/Library/Messages/Attachments`). - SCP використовує сувору перевірку ключа хоста, тож переконайтеся, що ключ хоста relay уже існує в `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: дозволити або заборонити ініційовані через iMessage записи конфігурації. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних ACP-сесій. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- `channels.imessage.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з iMessage. +- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних ACP-сесій. Використовуйте нормалізований дескриптор або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). @@ -638,7 +638,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix працює на основі Plugin і налаштовується в `channels.matrix`. +Matrix підтримується Plugin і налаштовується в `channels.matrix`. ```json5 { @@ -668,25 +668,25 @@ Matrix працює на основі Plugin і налаштовується в } ``` -- Автентифікація за токеном використовує `accessToken`; автентифікація за паролем використовує `userId` + `password`. -- `channels.matrix.proxy` спрямовує HTTP-трафік Matrix через явний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначати його через `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/internal homeserver. `proxy` і цей opt-in для мережі — незалежні елементи керування. -- `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у конфігураціях із кількома обліковими записами. -- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати й нові запрошення у стилі DM ігноруються, доки ви не встановите `autoJoin: "allowlist"` із `autoJoinAllowlist` або `autoJoin: "always"`. -- `channels.matrix.execApprovals`: власна доставка погоджень exec для Matrix і авторизація погоджувачів. +- Автентифікація токеном використовує `accessToken`; автентифікація паролем використовує `userId` + `password`. +- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явно вказаний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначати його через `channels.matrix.accounts..proxy`. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/internal homeserver-и. `proxy` і цей мережевий opt-in — незалежні елементи керування. +- `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у багатооблікових конфігураціях. +- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати та нові запрошення у стилі DM ігноруються, доки ви не задасте `autoJoin: "allowlist"` з `autoJoinAllowlist` або `autoJoin: "always"`. +- `channels.matrix.execApprovals`: нативна для Matrix доставка погоджень exec і авторизація погоджувачів. - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі погодження exec активуються, коли погоджувачів можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Matrix (наприклад, `@owner:example.org`), яким дозволено погоджувати запити exec. - - `agentFilter`: необов’язковий список дозволених ID агентів. Якщо пропустити, погодження пересилатимуться для всіх агентів. - - `sessionFilter`: необов’язкові шаблони ключів сесії (підрядок або regex). + - `approvers`: ID користувачів Matrix (наприклад, `@owner:example.org`), яким дозволено погоджувати exec-запити. + - `agentFilter`: необов’язковий allowlist ID агентів. Якщо пропустити, погодження пересилаються для всіх агентів. + - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). - `target`: куди надсилати запити на погодження. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`. - - Перевизначення для окремого облікового запису: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` керує тим, як DM у Matrix групуються в сесії: `per-user` (типово) спільно використовує сесію за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату. -- Перевірки статусу Matrix і живі пошуки в каталозі використовують ту саму політику проксі, що й runtime-трафік. -- Повну конфігурацію Matrix, правила націлювання й приклади налаштування задокументовано в [Matrix](/uk/channels/matrix). + - Перевизначення на рівні облікового запису: `channels.matrix.accounts..execApprovals`. +- `channels.matrix.dm.sessionScope` керує тим, як DM Matrix групуються в сесії: `per-user` (типово) спільно використовує сесію за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату. +- Перевірки статусу Matrix і live-пошук у каталозі використовують ту саму політику проксі, що й runtime-трафік. +- Повну конфігурацію Matrix, правила таргетингу та приклади налаштування задокументовано в [Matrix](/uk/channels/matrix). ### Microsoft Teams -Microsoft Teams працює на основі Plugin і налаштовується в `channels.msteams`. +Microsoft Teams підтримується Plugin і налаштовується в `channels.msteams`. ```json5 { @@ -701,12 +701,12 @@ Microsoft Teams працює на основі Plugin і налаштовуєт } ``` -- Основні шляхи ключів, охоплені тут: `channels.msteams`, `channels.msteams.configWrites`. -- Повну конфігурацію Teams (облікові дані, Webhook, політика DM/груп, перевизначення для окремих team/channel) задокументовано в [Microsoft Teams](/uk/channels/msteams). +- Основні шляхи ключів, описані тут: `channels.msteams`, `channels.msteams.configWrites`. +- Повну конфігурацію Teams (облікові дані, webhook, політика DM/груп, перевизначення для окремих team/channel) задокументовано в [Microsoft Teams](/uk/channels/msteams). ### IRC -IRC працює на основі Plugin і налаштовується в `channels.irc`. +IRC підтримується Plugin і налаштовується в `channels.irc`. ```json5 { @@ -727,13 +727,13 @@ IRC працює на основі Plugin і налаштовується в `ch } ``` -- Основні шляхи ключів, охоплені тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ідентифікатором облікового запису. -- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/обмеження за згадуванням) задокументовано в [IRC](/uk/channels/irc). +- Основні шляхи ключів, описані тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає ID налаштованого облікового запису. +- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/обмеження за згадками) задокументовано в [IRC](/uk/channels/irc). -### Кілька облікових записів (усі канали) +### Багатообліковість (усі канали) -Запускайте кілька облікових записів на канал (кожен із власним `accountId`): +Запускайте кілька облікових записів на канал (кожен зі своїм `accountId`): ```json5 { @@ -758,24 +758,24 @@ IRC працює на основі Plugin і налаштовується в `ch - Токени середовища застосовуються лише до облікового запису **default**. - Базові налаштування каналу застосовуються до всіх облікових записів, якщо не перевизначені для окремого облікового запису. - Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен обліковий запис до іншого агента. -- Якщо ви додаєте не-типовий обліковий запис через `openclaw channels add` (або онбординг каналу), коли все ще перебуваєте в однокористувацькій конфігурації каналу верхнього рівня, OpenClaw спочатку піднімає значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у карту облікових записів каналу, щоб початковий обліковий запис продовжував працювати. Більшість каналів переміщують їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. -- Наявні прив’язки лише до каналу (без `accountId`) і далі зіставляються з типовим обліковим записом; прив’язки з областю окремого облікового запису залишаються необов’язковими. -- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у піднятий обліковий запис, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. +- Якщо ви додаєте не-типовий обліковий запис через `openclaw channels add` (або онбординг каналу), поки ще використовуєте однооблікову конфігурацію каналу верхнього рівня, OpenClaw спочатку переносить значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у карту облікових записів каналу, щоб початковий обліковий запис і далі працював. Більшість каналів переміщують їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default ціль. +- Наявні прив’язки лише на рівні каналу (без `accountId`) і далі відповідають типовому обліковому запису; прив’язки на рівні облікового запису залишаються необов’язковими. +- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у promoted account, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default ціль. ### Інші канали Plugin -Багато каналів Plugin налаштовуються як `channels.` і задокументовані на їхніх окремих сторінках каналів (наприклад, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). +Багато каналів Plugin налаштовуються як `channels.` і задокументовані на власних сторінках каналів (наприклад, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). Див. повний індекс каналів: [Channels](/uk/channels). -### Обмеження за згадуванням у групових чатах +### Обмеження за згадками в групових чатах -Для групових повідомлень типово **потрібне згадування** (метадані згадування або безпечні regex-шаблони). Застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. +Для групових повідомлень типово **потрібна згадка** (метадані згадки або безпечні regex-шаблони). Застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. -**Типи згадувань:** +**Типи згадок:** -- **Згадування в метаданих**: рідні @-згадування платформи. Ігноруються в режимі self-chat WhatsApp. +- **Згадки в метаданих**: нативні @-згадки платформи. Ігноруються в режимі self-chat WhatsApp. - **Текстові шаблони**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Некоректні шаблони та небезпечне вкладене повторення ігноруються. -- Обмеження за згадуванням застосовується лише тоді, коли виявлення можливе (рідні згадування або принаймні один шаблон). +- Обмеження за згадками застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один шаблон). ```json5 { @@ -788,7 +788,7 @@ IRC працює на основі Plugin і налаштовується в `ch } ``` -`messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначати його через `channels..historyLimit` (або для окремого облікового запису). Установіть `0`, щоб вимкнути. +`messages.groupChat.historyLimit` задає глобальне значення за замовчуванням. Канали можуть перевизначати його через `channels..historyLimit` (або на рівні облікового запису). Встановіть `0`, щоб вимкнути. #### Ліміти історії DM @@ -805,13 +805,13 @@ IRC працює на основі Plugin і налаштовується в `ch } ``` -Розв’язання: перевизначення для окремого DM → типове значення провайдера → без ліміту (зберігається все). +Порядок визначення: перевизначення для окремого DM → значення провайдера за замовчуванням → без ліміту (зберігається все). -Підтримуються: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. +Підтримується: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. #### Режим self-chat -Додайте власний номер у `allowFrom`, щоб увімкнути режим self-chat (ігнорує рідні @-згадування, відповідає лише на текстові шаблони): +Додайте власний номер до `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадки, відповідає лише на текстові шаблони): ```json5 { @@ -832,7 +832,7 @@ IRC працює на основі Plugin і налаштовується в `ch } ``` -### Команди (обробка команд у чаті) +### Команди (обробка команд чату) ```json5 { @@ -859,40 +859,40 @@ IRC працює на основі Plugin і налаштовується в `ch } ``` - + - Цей блок налаштовує поверхні команд. Поточний каталог вбудованих + bundled команд див. у [Slash Commands](/uk/tools/slash-commands). -- Ця сторінка — **довідник за ключами конфігурації**, а не повний каталог команд. Команди, що належать каналам/Plugin, такі як QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, задокументовані на сторінках відповідних каналів/Plugin, а також у [Slash Commands](/uk/tools/slash-commands). +- Ця сторінка — **довідник ключів конфігурації**, а не повний каталог команд. Команди, що належать каналу/плагіну, такі як QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, задокументовані на сторінках відповідних каналів/плагінів, а також у [Slash Commands](/uk/tools/slash-commands). - Текстові команди мають бути **окремими** повідомленнями з початковим `/`. -- `native: "auto"` вмикає рідні команди для Discord/Telegram, але залишає Slack вимкненим. -- `nativeSkills: "auto"` вмикає рідні команди Skills для Discord/Telegram, але залишає Slack вимкненим. -- Перевизначення для каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди. -- Перевизначуйте реєстрацію рідних команд Skills для каналу через `channels..commands.nativeSkills`. +- `native: "auto"` вмикає нативні команди для Discord/Telegram, залишає Slack вимкненим. +- `nativeSkills: "auto"` вмикає нативні команди Skills для Discord/Telegram, залишає Slack вимкненим. +- Перевизначення для окремого каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди. +- Перевизначайте реєстрацію нативних команд Skills для окремого каналу через `channels..commands.nativeSkills`. - `channels.telegram.customCommands` додає додаткові записи меню бота Telegram. -- `bash: true` вмикає `! ` для shell хоста. Потрібні `tools.elevated.enabled` і відправник у `tools.elevated.allowFrom.`. -- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів gateway `chat.send` постійні записи `/config set|unset` також вимагають `operator.admin`; режим лише читання `/config show` залишається доступним для звичайних клієнтів оператора з правом запису. -- `mcp: true` вмикає `/mcp` для конфігурації MCP-сервера під керуванням OpenClaw у `mcp.servers`. -- `plugins: true` вмикає `/plugins` для виявлення, встановлення та керування вмиканням/вимиканням Plugin. -- `channels..configWrites` керує мутаціями конфігурації для кожного каналу (типово: true). -- Для каналів із кількома обліковими записами `channels..accounts..configWrites` також керує записами, націленими на цей обліковий запис (наприклад, `/allowlist --config --account ` або `/config set channels..accounts....`). -- `restart: false` вимикає `/restart` і дії інструмента перезапуску gateway. Типове значення: `true`. -- `ownerAllowFrom` — це явний список дозволених власників для команд/інструментів лише для власника. Він відокремлений від `allowFrom`. -- `ownerDisplay: "hash"` хешує ідентифікатори власників у системному запиті. Установіть `ownerDisplaySecret`, щоб керувати хешуванням. -- `allowFrom` задається для кожного провайдера. Якщо його встановлено, це **єдине** джерело авторизації (списки дозволених каналу/сполучення та `useAccessGroups` ігноруються). -- `useAccessGroups: false` дає змогу командам обходити політики груп доступу, коли `allowFrom` не встановлено. -- Відображення документації команд: - - каталог вбудованих + bundled команд: [Slash Commands](/uk/tools/slash-commands) +- `bash: true` вмикає `! ` для оболонки хоста. Потрібні `tools.elevated.enabled` і відправник у `tools.elevated.allowFrom.`. +- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів Gateway `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; доступний лише для читання `/config show` лишається доступним для звичайних клієнтів оператора з правами запису. +- `mcp: true` вмикає `/mcp` для конфігурації MCP-сервера, яким керує OpenClaw, у `mcp.servers`. +- `plugins: true` вмикає `/plugins` для пошуку Plugin, встановлення та керування ввімкненням/вимкненням. +- `channels..configWrites` керує мутаціями конфігурації для окремого каналу (типово: true). +- Для багатооблікових каналів `channels..accounts..configWrites` також керує записами, націленими на цей обліковий запис (наприклад, `/allowlist --config --account ` або `/config set channels..accounts....`). +- `restart: false` вимикає `/restart` і дії інструмента перезапуску Gateway. Типове значення: `true`. +- `ownerAllowFrom` — це явний список дозволених власників для команд/інструментів лише для власника. Він окремий від `allowFrom`. +- `ownerDisplay: "hash"` хешує id власників у system prompt. Задайте `ownerDisplaySecret`, щоб керувати хешуванням. +- `allowFrom` задається окремо для кожного провайдера. Якщо його встановлено, це **єдине** джерело авторизації (списки дозволених каналу/сполучення та `useAccessGroups` ігноруються). +- `useAccessGroups: false` дозволяє командам обходити політики груп доступу, якщо `allowFrom` не задано. +- Карта документації команд: + - каталог вбудованих + bundled: [Slash Commands](/uk/tools/slash-commands) - поверхні команд, специфічні для каналів: [Channels](/uk/channels) - команди QQ Bot: [QQ Bot](/uk/channels/qqbot) - команди сполучення: [Pairing](/uk/channels/pairing) - команда картки LINE: [LINE](/uk/channels/line) - - dreaming для пам’яті: [Dreaming](/uk/concepts/dreaming) + - memory dreaming: [Dreaming](/uk/concepts/dreaming) --- -## Типові значення агента +## Значення агентів за замовчуванням ### `agents.defaults.workspace` @@ -906,7 +906,7 @@ IRC працює на основі Plugin і налаштовується в `ch ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, що показується в рядку Runtime системного запиту. Якщо не встановлено, OpenClaw автоматично визначає його, піднімаючись угору від workspace. +Необов’язковий корінь репозиторію, що показується в рядку Runtime системного prompt. Якщо не задано, OpenClaw автоматично визначає його, піднімаючись угору від workspace. ```json5 { @@ -934,7 +934,7 @@ IRC працює на основі Plugin і налаштовується в `ch - Пропустіть `agents.defaults.skills`, щоб типово не обмежувати Skills. - Пропустіть `agents.list[].skills`, щоб успадкувати типові значення. -- Установіть `agents.list[].skills: []`, щоб не мати Skills. +- Встановіть `agents.list[].skills: []`, щоб не використовувати жодних Skills. - Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він не об’єднується з типовими значеннями. @@ -950,9 +950,9 @@ IRC працює на основі Plugin і налаштовується в `ch ### `agents.defaults.contextInjection` -Керує тим, коли bootstrap-файли workspace вбудовуються в системний запит. Типове значення: `"always"`. +Керує тим, коли bootstrap-файли workspace вбудовуються в system prompt. Типове значення: `"always"`. -- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне вбудовування bootstrap workspace, зменшуючи розмір запиту. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст. +- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне вбудовування bootstrap workspace, зменшуючи розмір prompt. Запуски Heartbeat і повторні спроби після Compaction все одно перебудовують контекст. ```json5 { @@ -962,7 +962,7 @@ IRC працює на основі Plugin і налаштовується в `ch ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів на один bootstrap-файл workspace перед обрізанням. Типове значення: `12000`. +Максимум символів на один bootstrap-файл workspace до усікання. Типове значення: `12000`. ```json5 { @@ -972,7 +972,7 @@ IRC працює на основі Plugin і налаштовується в `ch ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що вбудовуються через всі bootstrap-файли workspace. Типове значення: `60000`. +Максимальна загальна кількість символів, що вбудовуються з усіх bootstrap-файлів workspace. Типове значення: `60000`. ```json5 { @@ -982,12 +982,12 @@ IRC працює на основі Plugin і налаштовується в `ch ### `agents.defaults.bootstrapPromptTruncationWarning` -Керує видимим агенту текстом попередження, коли bootstrap-контекст обрізається. +Керує видимим для агента текстом попередження, коли bootstrap-контекст усічено. Типове значення: `"once"`. -- `"off"`: ніколи не вбудовувати текст попередження в системний запит. -- `"once"`: вбудовувати попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано). -- `"always"`: вбудовувати попередження під час кожного запуску, коли є обрізання. +- `"off"`: ніколи не вбудовувати текст попередження в system prompt. +- `"once"`: вбудовувати попередження один раз для кожного унікального сигнатурного усікання (рекомендовано). +- `"always"`: вбудовувати попередження під час кожного запуску, коли є усікання. ```json5 { @@ -997,22 +997,22 @@ IRC працює на основі Plugin і налаштовується в `ch ### Карта відповідальності за бюджет контексту -OpenClaw має кілька високонавантажених бюджетів запиту/контексту, і вони -навмисно розділені за підсистемами замість того, щоб усі проходили через один -загальний параметр. +OpenClaw має кілька великих бюджетів prompt/контексту, і вони +навмисно розділені за підсистемами, а не проходять через один загальний +параметр. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: звичайне вбудовування bootstrap workspace. - `agents.defaults.startupContext.*`: - одноразовий початковий пролог для `/new` і `/reset`, включно з недавніми + одноразова стартова преамбула для `/new` і `/reset`, включно з недавніми файлами `memory/*.md` за днями. - `skills.limits.*`: - компактний список Skills, вбудований у системний запит. + компактний список Skills, вбудований у system prompt. - `agents.defaults.contextLimits.*`: - обмежені фрагменти runtime і вбудовані блоки, що належать runtime. + обмежені runtime-витяги та вбудовані блоки, що належать runtime. - `memory.qmd.limits.*`: - розмір фрагментів і вбудовування для індексованого пошуку в пам’яті. + розмір фрагментів індексованого пошуку пам’яті та вбудовування. Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший бюджет: @@ -1022,8 +1022,7 @@ OpenClaw має кілька високонавантажених бюджеті #### `agents.defaults.startupContext` -Керує початковим прологом першого ходу, що вбудовується в запуски `/new` і `/reset` -без додаткового контексту. +Керує стартовою преамбулою першого ходу, яка вбудовується під час звичайних запусків `/new` і `/reset`. ```json5 { @@ -1044,7 +1043,7 @@ OpenClaw має кілька високонавантажених бюджеті #### `agents.defaults.contextLimits` -Спільні типові значення для обмежених поверхонь контексту runtime. +Спільні типові значення для обмежених поверхонь runtime-контексту. ```json5 { @@ -1061,13 +1060,13 @@ OpenClaw має кілька високонавантажених бюджеті } ``` -- `memoryGetMaxChars`: типовий ліміт фрагмента `memory_get` перед додаванням - метаданих обрізання та повідомлення про продовження. +- `memoryGetMaxChars`: типовий ліміт витягу `memory_get` до того, як буде додано + метадані усікання та повідомлення про продовження. - `memoryGetDefaultLines`: типове вікно рядків `memory_get`, коли `lines` пропущено. -- `toolResultMaxChars`: актуальний ліміт результату інструмента, що використовується для збережених результатів і - відновлення переповнення. -- `postCompactionMaxChars`: ліміт фрагмента AGENTS.md, що використовується під час вбудовування +- `toolResultMaxChars`: поточний ліміт результатів інструментів, який використовується для збережених результатів і + відновлення після переповнення. +- `postCompactionMaxChars`: ліміт витягу AGENTS.md, який використовується під час вбудовування оновлення після Compaction. #### `agents.list[].contextLimits` @@ -1099,8 +1098,8 @@ OpenClaw має кілька високонавантажених бюджеті #### `skills.limits.maxSkillsPromptChars` -Глобальний ліміт для компактного списку Skills, вбудованого в системний запит. Це -не впливає на читання файлів `SKILL.md` за потреби. +Глобальний ліміт для компактного списку Skills, вбудованого в system prompt. Це +не впливає на читання файлів `SKILL.md` на вимогу. ```json5 { @@ -1114,7 +1113,7 @@ OpenClaw має кілька високонавантажених бюджеті #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Перевизначення для окремого агента для бюджету запиту Skills. +Перевизначення для окремого агента для бюджету prompt Skills. ```json5 { @@ -1133,10 +1132,10 @@ OpenClaw має кілька високонавантажених бюджеті ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень transcript/tool перед викликами провайдера. +Максимальний розмір у пікселях для найдовшої сторони зображення в блоках зображень transcript/tool перед викликами провайдера. Типове значення: `1200`. -Менші значення зазвичай зменшують використання vision-token і розмір payload запиту для запусків із великою кількістю скриншотів. +Менші значення зазвичай зменшують використання vision-токенів і розмір payload запиту для запусків із великою кількістю скриншотів. Більші значення зберігають більше візуальних деталей. ```json5 @@ -1147,7 +1146,7 @@ OpenClaw має кілька високонавантажених бюджеті ### `agents.defaults.userTimezone` -Часовий пояс для контексту системного запиту (не для часових позначок повідомлень). Якщо не задано, використовується часовий пояс хоста. +Часовий пояс для контексту system prompt (не для часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста. ```json5 { @@ -1157,7 +1156,7 @@ OpenClaw має кілька високонавантажених бюджеті ### `agents.defaults.timeFormat` -Формат часу в системному запиті. Типове значення: `auto` (налаштування ОС). +Формат часу в system prompt. Типове значення: `auto` (налаштування ОС). ```json5 { @@ -1215,48 +1214,50 @@ OpenClaw має кілька високонавантажених бюджеті ``` - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Форма рядка задає лише основну модель. - - Форма об’єкта задає основну модель плюс упорядковані моделі для failover. + - Рядкова форма задає лише основну модель. + - Форма об’єкта задає основну модель плюс впорядковані failover-моделі. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується шляхом інструмента `image` як його конфігурація vision-моделі. - Також використовується як резервна маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею tool/Plugin, що генерує зображення. + - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/Plugin, що генерує зображення. - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-2` для OpenAI Images. - - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію/API key провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). - - Якщо поле пропущено, `image_generate` усе одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. + - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію провайдера/API key (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). + - Якщо поле пропущено, `image_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім — інші зареєстровані провайдери генерації зображень у порядку id провайдера. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`. - - Якщо поле пропущено, `music_generate` усе одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку provider-id. - - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію/API key провайдера. + - Якщо поле пропущено, `music_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім — інші зареєстровані провайдери генерації музики в порядку id провайдера. + - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію провайдера/API key. - `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`. - Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`. - - Якщо поле пропущено, `video_generate` усе одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку provider-id. - - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію/API key провайдера. - - Bundled провайдер генерації відео Qwen підтримує не більше 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. + - Якщо поле пропущено, `video_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку воно пробує поточного типового провайдера, а потім — інші зареєстровані провайдери генерації відео в порядку id провайдера. + - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію провайдера/API key. + - Bundled провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` і `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується інструментом `pdf` для маршрутизації моделі. - - Якщо поле пропущено, інструмент PDF використовує резервно `imageModel`, а потім визначену модель сесії/типову модель. + - Якщо поле пропущено, інструмент PDF спершу повертається до `imageModel`, а потім — до визначеної моделі сесії/типової моделі. - `pdfMaxBytesMb`: типовий ліміт розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. -- `pdfMaxPages`: типова максимальна кількість сторінок, які враховуються режимом резервного витягування в інструменті `pdf`. +- `pdfMaxPages`: типова максимальна кількість сторінок, яка враховується в режимі резервного вилучення інструмента `pdf`. - `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`. - `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`. -- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4`). Якщо пропустити провайдера, OpenClaw спочатку пробує alias, потім унікальний збіг exact model id серед налаштованих провайдерів, і лише потім повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому надавайте перевагу явному `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари provider/model замість того, щоб показувати застаріле типове значення видаленого провайдера. -- `models`: налаштований каталог моделей і список дозволених для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). +- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4`). Якщо ви пропускаєте провайдера, OpenClaw спочатку пробує alias, потім — унікальний збіг exact model id серед налаштованих провайдерів, і лише після цього повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повертається до першого налаштованого provider/model замість того, щоб показувати застаріле типове значення видаленого провайдера. +- `models`: налаштований каталог моделей і allowlist для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). + - Безпечні зміни: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відмовляє в замінах, які видалили б наявні записи allowlist, якщо ви не передасте `--replace`. + - Потоки configure/onboarding на рівні провайдера об’єднують вибрані моделі провайдера в цю мапу й зберігають уже налаштованих, але не пов’язаних провайдерів. - `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`). -- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), після чого `agents.list[].params` (для відповідного id агента) перевизначає за ключем. Докладніше див. у [Prompt Caching](/uk/reference/prompt-caching). -- `embeddedHarness`: типова політика низькорівневого runtime вбудованого агента. Використовуйте `runtime: "auto"`, щоб зареєстровані harness Plugin могли перехоплювати підтримувані моделі, `runtime: "pi"` — щоб примусово використовувати вбудований harness PI, або зареєстрований id harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. -- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта й за можливості зберігають наявні списки fallback. +- Пріоритет об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для окремої моделі), а потім `agents.list[].params` (для відповідного id агента) перевизначає за ключами. Докладніше див. [Prompt Caching](/uk/reference/prompt-caching). +- `embeddedHarness`: типова низькорівнева політика runtime для вбудованого агента. Використовуйте `runtime: "auto"`, щоб дозволити зареєстрованим Plugin harness брати на себе підтримувані моделі, `runtime: "pi"` — щоб примусово використовувати вбудований harness PI, або зареєстрований id harness, наприклад `runtime: "codex"`. Встановіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. +- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди add/remove для резервних варіантів), зберігають канонічну форму об’єкта та, коли можливо, зберігають наявні списки резервних варіантів. - `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). Типове значення: 4. ### `agents.defaults.embeddedHarness` `embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента. -У більшості розгортань слід залишити типове значення `{ runtime: "auto", fallback: "pi" }`. +У більшості розгортань варто залишити типове значення `{ runtime: "auto", fallback: "pi" }`. Використовуйте це, коли довірений Plugin надає нативний harness, наприклад bundled -harness app-server Codex. +app-server harness Codex. ```json5 { @@ -1272,13 +1273,13 @@ harness app-server Codex. } ``` -- `runtime`: `"auto"`, `"pi"` або id зареєстрованого harness Plugin. Bundled Plugin Codex реєструє `codex`. -- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований harness PI як резервний варіант сумісності, коли harness Plugin не вибрано. `"none"` призводить до помилки, якщо вибраний harness Plugin відсутній або не підтримується, замість тихого використання PI. Помилки вибраного harness Plugin завжди показуються напряму. -- Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає резервний перехід до PI для цього процесу. -- Для розгортань лише з Codex установіть `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. -- Це керує лише вбудованим harness чату. Генерація медіа, vision, PDF, музика, відео й TTS усе ще використовують свої налаштування provider/model. +- `runtime`: `"auto"`, `"pi"` або id зареєстрованого Plugin harness. Bundled Plugin Codex реєструє `codex`. +- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований harness PI як сумісний резервний варіант, коли жоден Plugin harness не вибрано. `"none"` призводить до помилки, якщо вибраний Plugin harness відсутній або не підтримується, замість тихого використання PI. Збої вибраного Plugin harness завжди показуються безпосередньо. +- Перевизначення середовища: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає резервний перехід до PI для цього процесу. +- Для розгортань лише з Codex встановіть `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. +- Це керує лише вбудованим chat harness. Генерація медіа, vision, PDF, музика, відео та TTS і далі використовують свої налаштування provider/model. -**Скорочені вбудовані alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): +**Вбудовані скорочення alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): | Alias | Модель | | ------------------- | -------------------------------------- | @@ -1293,13 +1294,13 @@ harness app-server Codex. Ваші налаштовані alias завжди мають пріоритет над типовими. -Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не встановите `--thinking off` або самі не визначите `agents.defaults.models["zai/"].params.thinking`. -Моделі Z.AI типово вмикають `tool_stream` для потокової передачі викликів інструментів. Установіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. -Для моделей Anthropic Claude 4.6 типовим є thinking `adaptive`, якщо явно не задано рівень thinking. +Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не задасте `--thinking off` або самі не визначите `agents.defaults.models["zai/"].params.thinking`. +Моделі Z.AI типово вмикають `tool_stream` для потокової передачі викликів інструментів. Встановіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. +Моделі Anthropic Claude 4.6 типово використовують `adaptive` thinking, коли явний рівень thinking не задано. ### `agents.defaults.cliBackends` -Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли збоять API-провайдери. +Необов’язкові backend-и CLI для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють. ```json5 { @@ -1327,13 +1328,13 @@ harness app-server Codex. } ``` -- CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені. -- Сесії підтримуються, коли встановлено `sessionArg`. -- Пряме передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів. +- Backend-и CLI орієнтовані на текст; інструменти завжди вимкнені. +- Сесії підтримуються, коли задано `sessionArg`. +- Передача зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` -Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілами ігнорується. Корисно для контрольованих експериментів із запитами. +Замінює весь system prompt, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із prompt. ```json5 { @@ -1374,15 +1375,15 @@ harness app-server Codex. } ``` -- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути. -- `includeSystemPromptSection`: якщо `false`, прибирає секцію Heartbeat із системного запиту та пропускає вбудовування `HEARTBEAT.md` у bootstrap-контекст. Типове значення: `true`. -- `suppressToolErrorWarnings`: якщо `true`, пригнічує payload попереджень про помилки інструментів під час запусків Heartbeat. -- `timeoutSeconds`: максимальний час у секундах, дозволений для ходу агента Heartbeat, після чого він переривається. Якщо не встановлено, використовується `agents.defaults.timeoutSeconds`. -- `directPolicy`: політика прямої доставки/DM. `allow` (типово) дозволяє доставку до прямої цілі. `block` пригнічує доставку до прямої цілі та повертає `reason=dm-blocked`. -- `lightContext`: якщо `true`, запуски Heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів workspace. -- `isolatedSession`: якщо `true`, кожен запуск Heartbeat виконується в новій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один Heartbeat приблизно зі ~100K до ~2–5K токенів. +- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Встановіть `0m`, щоб вимкнути. +- `includeSystemPromptSection`: коли `false`, прибирає розділ Heartbeat із system prompt і пропускає вбудовування `HEARTBEAT.md` у bootstrap-контекст. Типове значення: `true`. +- `suppressToolErrorWarnings`: коли `true`, приглушує payload-и попереджень про помилки інструментів під час запусків Heartbeat. +- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента Heartbeat до його переривання. Якщо не задано, використовується `agents.defaults.timeoutSeconds`. +- `directPolicy`: політика прямої доставки/DM. `allow` (типово) дозволяє доставку на пряму ціль. `block` приглушує доставку на пряму ціль і видає `reason=dm-blocked`. +- `lightContext`: коли `true`, запуски Heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів workspace. +- `isolatedSession`: коли `true`, кожен запуск Heartbeat виконується в новій сесії без попередньої історії розмови. Та сама схема ізоляції, що й у Cron `sessionTarget: "isolated"`. Зменшує вартість токенів на один Heartbeat приблизно зі ~100K до ~2-5K токенів. - Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, Heartbeat запускаються **лише для цих агентів**. -- Heartbeat запускає повні ходи агента — коротші інтервали витрачають більше токенів. +- Heartbeat запускає повноцінні ходи агента — коротші інтервали спалюють більше токенів. ### `agents.defaults.compaction` @@ -1396,15 +1397,15 @@ harness app-server Codex. timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom + identifierInstructions: "Зберігайте id розгортань, id тікетів і пари host:port точно без змін.", // used when identifierPolicy=custom postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override notifyUser: true, // send brief notices when compaction starts and completes (default: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, - systemPrompt: "Session nearing compaction. Store durable memories now.", - prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.", + systemPrompt: "Сесія наближається до Compaction. Збережіть тривалі спогади зараз.", + prompt: "Запишіть усі довготривалі нотатки в memory/YYYY-MM-DD.md; якщо зберігати нічого, дайте відповідь точним тихим токеном NO_REPLY.", }, }, }, @@ -1412,19 +1413,19 @@ harness app-server Codex. } ``` -- `mode`: `default` або `safeguard` (підсумовування шматками для довгої історії). Див. [Compaction](/uk/concepts/compaction). -- `provider`: id зареєстрованого Plugin провайдера Compaction. Якщо встановлено, замість вбудованого підсумовування LLM викликається `summarize()` провайдера. У разі помилки повертається до вбудованого варіанта. Установлення провайдера примусово задає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). -- `timeoutSeconds`: максимальна кількість секунд, дозволених для однієї операції Compaction, перш ніж OpenClaw її перерве. Типове значення: `900`. +- `mode`: `default` або `safeguard` (підсумовування довгої історії частинами). Див. [Compaction](/uk/concepts/compaction). +- `provider`: id зареєстрованого Plugin провайдера Compaction. Якщо задано, замість вбудованого підсумовування LLM викликається `summarize()` цього провайдера. У разі збою відбувається повернення до вбудованого варіанта. Встановлення провайдера примусово задає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). +- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції Compaction, після чого OpenClaw її перериває. Типове значення: `900`. - `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування Compaction. -- `identifierInstructions`: необов’язковий користувацький текст щодо збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. -- `postCompactionSections`: необов’язкові назви секцій H2/H3 з AGENTS.md для повторного вбудовування після Compaction. Типове значення — `["Session Startup", "Red Lines"]`; установіть `[]`, щоб вимкнути повторне вбудовування. Якщо значення не задано або явно задано цю типову пару, старіші заголовки `Every Session`/`Safety` також приймаються як застарілий резервний варіант. +- `identifierInstructions`: необов’язковий власний текст про збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. +- `postCompactionSections`: необов’язкові назви секцій H2/H3 з AGENTS.md, які повторно вбудовуються після Compaction. Типово `["Session Startup", "Red Lines"]`; задайте `[]`, щоб вимкнути повторне вбудовування. Якщо поле не задано або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як резервний застарілий варіант. - `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування Compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а підсумки Compaction — виконуватися на іншій; якщо не задано, Compaction використовує основну модель сесії. -- `notifyUser`: якщо `true`, надсилає користувачу короткі сповіщення, коли Compaction починається і коли завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб Compaction працював безшумно. -- `memoryFlush`: тихий агентний хід перед автоматичним Compaction для збереження довготривалих спогадів. Пропускається, коли workspace доступний лише для читання. +- `notifyUser`: якщо `true`, надсилає короткі сповіщення користувачеві, коли Compaction починається й коли завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб Compaction залишався безшумним. +- `memoryFlush`: безшумний хід агента перед автоматичним Compaction для збереження тривалих спогадів. Пропускається, якщо workspace доступний лише для читання. ### `agents.defaults.contextPruning` -Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. +Обрізає **старі результати інструментів** з контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. ```json5 { @@ -1449,22 +1450,22 @@ harness app-server Codex. - `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` визначає, як часто обрізання може запускатися знову (після останнього торкання кешу). -- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім за потреби повністю очищає старіші результати. +- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього звернення до кешу). +- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім, якщо потрібно, повністю очищає старіші результати інструментів. -**М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині. +**М’яке скорочення** зберігає початок і кінець та вставляє `...` посередині. **Повне очищення** замінює весь результат інструмента заповнювачем. Примітки: -- Блоки зображень ніколи не обрізаються й не очищаються. -- Співвідношення базуються на кількості символів (приблизно), а не на точних кількостях токенів. +- Блоки зображень ніколи не скорочуються й не очищаються. +- Співвідношення базуються на кількості символів (приблизно), а не на точній кількості токенів. - Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається. -Докладніше про поведінку див. у [Session Pruning](/uk/concepts/session-pruning). +Деталі поведінки див. у [Session Pruning](/uk/concepts/session-pruning). ### Блокова потокова передача @@ -1482,11 +1483,11 @@ harness app-server Codex. } ``` -- Канали, відмінні від Telegram, вимагають явного `*.blockStreaming: true`, щоб увімкнути блокові відповіді. -- Перевизначення для каналу: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типовим є `minChars: 1500`. +- Канали, відмінні від Telegram, потребують явного `*.blockStreaming: true`, щоб увімкнути блокові відповіді. +- Перевизначення на рівні каналу: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`. - `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500 мс. Перевизначення для окремого агента: `agents.list[].humanDelay`. -Докладніше про поведінку й нарізання блоків див. у [Streaming](/uk/concepts/streaming). +Деталі поведінки й нарізання блоків див. у [Streaming](/uk/concepts/streaming). ### Індикатори набору @@ -1501,8 +1502,8 @@ harness app-server Codex. } ``` -- Типові значення: `instant` для прямих чатів/згадувань, `message` для групових чатів без згадування. -- Перевизначення для сесії: `session.typingMode`, `session.typingIntervalSeconds`. +- Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. +- Перевизначення для окремої сесії: `session.typingMode`, `session.typingIntervalSeconds`. Див. [Typing Indicators](/uk/concepts/typing-indicators). @@ -1510,7 +1511,7 @@ harness app-server Codex. ### `agents.defaults.sandbox` -Необов’язкова ізоляція для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). +Необов’язкова sandbox-ізоляція для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). ```json5 { @@ -1605,24 +1606,24 @@ harness app-server Codex. } ``` - + **Backend:** - `docker`: локальний runtime Docker (типово) -- `ssh`: загальний віддалений runtime на основі SSH +- `ssh`: універсальний віддалений runtime на основі SSH - `openshell`: runtime OpenShell -Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться до +Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переміщуються до `plugins.entries.openshell.config`. **Конфігурація backend SSH:** - `target`: ціль SSH у форматі `user@host[:port]` -- `command`: команда клієнта SSH (типово: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace на кожну область +- `command`: команда SSH-клієнта (типово: `ssh`) +- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace за кожною областю - `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються до OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує в тимчасові файли під час runtime +- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує у тимчасові файли під час runtime - `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH **Пріоритет автентифікації SSH:** @@ -1630,25 +1631,25 @@ harness app-server Codex. - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data` на основі SecretRef визначаються з активного знімка runtime секретів до запуску сесії sandbox +- Значення `*Data` на основі SecretRef визначаються з активного знімка runtime секретів до початку сесії sandbox **Поведінка backend SSH:** -- один раз засіває віддалений workspace після створення або повторного створення -- далі тримає віддалений SSH workspace канонічним +- один раз ініціалізує віддалений workspace після створення або повторного створення +- далі зберігає віддалений SSH-workspace як канонічний - маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH - не синхронізує віддалені зміни назад на хост автоматично -- не підтримує контейнерів браузера sandbox +- не підтримує браузерні контейнери sandbox **Доступ до workspace:** -- `none`: workspace sandbox на кожну область у `~/.openclaw/sandboxes` +- `none`: workspace sandbox за кожною областю в `~/.openclaw/sandboxes` - `ro`: workspace sandbox у `/workspace`, workspace агента монтується лише для читання в `/agent` - `rw`: workspace агента монтується для читання/запису в `/workspace` **Область:** -- `session`: контейнер + workspace на кожну сесію +- `session`: окремий контейнер + workspace для кожної сесії - `agent`: один контейнер + workspace на агента (типово) - `shared`: спільний контейнер і workspace (без ізоляції між сесіями) @@ -1680,30 +1681,30 @@ harness app-server Codex. **Режим OpenShell:** -- `mirror`: засіяти віддалений простір із локального перед exec, синхронізувати назад після exec; локальний workspace залишається канонічним -- `remote`: засіяти віддалений простір один раз при створенні sandbox, далі тримати віддалений workspace канонічним +- `mirror`: ініціалізувати віддалений простір із локального перед exec, синхронізувати назад після exec; локальний workspace лишається канонічним +- `remote`: один раз ініціалізувати віддалений простір під час створення sandbox, далі зберігати віддалений workspace як канонічний -У режимі `remote` локальні редагування на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку засівання. -Транспортом є SSH до sandbox OpenShell, але життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією керує Plugin. +У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку ініціалізації. +Транспортом є SSH до sandbox OpenShell, але життєвим циклом sandbox і необов’язковою mirror-синхронізацією керує Plugin. -**`setupCommand`** запускається один раз після створення контейнера (через `sh -lc`). Потребує вихідного доступу до мережі, кореня з правом запису, користувача root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, кореневої файлової системи з можливістю запису та користувача root. -**Для контейнерів типово встановлено `network: "none"`** — задайте `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. -`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите +**Типово контейнери використовують `network: "none"`** — встановіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихід назовні. +`"host"` заблоковано. `"container:"` типово також заблоковано, якщо ви явно не встановите `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний режим). **Вхідні вкладення** розміщуються в `media/inbound/*` в активному workspace. **`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремого агента об’єднуються. -**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в системний запит. Не потребує `browser.enabled` в `openclaw.json`. -Доступ спостерігача через noVNC типово використовує автентифікацію VNC, і OpenClaw видає короткоживучий URL із токеном (замість розкриття пароля у спільному URL). +**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в system prompt. Не потребує `browser.enabled` у `openclaw.json`. +Доступ спостерігача через noVNC типово використовує автентифікацію VNC, а OpenClaw видає URL із короткоживучим токеном (замість того, щоб показувати пароль у спільному URL). - `allowHostControl: false` (типово) блокує для sandbox-сесій націлювання на браузер хоста. -- `network` типово має значення `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна зв’язність bridge. -- `cdpSourceRange` за потреби обмежує вхідний доступ до CDP на межі контейнера діапазоном CIDR (наприклад, `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо задано (включно з `[]`), замінює `docker.binds` для контейнера браузера. -- Типові параметри запуску визначені в `scripts/sandbox-browser-entrypoint.sh` і налаштовані для хостів із контейнерами: +- `network` типово має значення `openclaw-sandbox-browser` (виділена bridge-мережа). Встановлюйте `bridge` лише тоді, коли вам явно потрібна глобальна bridge-підключеність. +- `cdpSourceRange` за потреби обмежує вхід CDP на межі контейнера до діапазону CIDR (наприклад, `172.21.0.1/32`). +- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо задано (включно з `[]`), воно замінює `docker.binds` для контейнера браузера. +- Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для хостів контейнерів: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1720,24 +1721,24 @@ harness app-server Codex. - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (типово увімкнено) + - `--disable-extensions` (типово ввімкнено) - `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu` - типово увімкнені; їх можна вимкнути за допомогою - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо цього вимагає використання WebGL/3D. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш робочий процес + типово ввімкнені й можуть бути вимкнені через + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо це потрібно для WebGL/3D. + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` повторно вмикає розширення, якщо ваш workflow залежить від них. - - `--renderer-process-limit=2` можна змінити за допомогою - `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати - типове обмеження процесів Chromium. - - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли увімкнено `noSandbox`. - - Типові значення є базовими для образу контейнера; щоб змінити типові параметри контейнера, використовуйте власний - образ браузера з власним entrypoint. + - `--renderer-process-limit=2` можна змінити через + `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; встановіть `0`, щоб використовувати + типовий ліміт процесів Chromium. + - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. + - Типові значення є базовими для образу контейнера; щоб змінити типові параметри контейнера, + використовуйте власний образ браузера з власним entrypoint. -Ізоляція браузера й `sandbox.docker.binds` доступні лише для Docker. +Браузерна sandbox-ізоляція та `sandbox.docker.binds` доступні лише для Docker. -Створення образів: +Зібрати образи: ```bash scripts/sandbox-setup.sh # main sandbox image @@ -1794,26 +1795,26 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id`: стабільний id агента (обов’язково). -- `default`: коли встановлено кілька значень, перше має пріоритет (записується попередження). Якщо не встановлено жодного, типовим стає перший запис у списку. -- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback). Cron-завдання, які перевизначають лише `primary`, усе одно успадковують типові fallback, якщо ви не встановите `fallbacks: []`. -- `params`: параметри потоку для окремого агента, які зливаються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень, специфічних для агента, таких як `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. -- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо пропущено, агент успадковує `agents.defaults.skills`, коли це значення задано; явний список замінює типові значення замість злиття, а `[]` означає відсутність Skills. -- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не задано перевизначення для окремого повідомлення чи сесії. -- `reasoningDefault`: необов’язкове типове значення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, якщо не задано перевизначення reasoning для окремого повідомлення чи сесії. -- `fastModeDefault`: необов’язкове типове значення швидкого режиму для окремого агента (`true | false`). Застосовується, якщо не задано перевизначення швидкого режиму для окремого повідомлення чи сесії. -- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex", fallback: "none" }`, щоб зробити один агент лише для Codex, тоді як інші агенти зберігатимуть типовий fallback PI. -- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` з типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сесії harness ACP. +- `default`: якщо задано для кількох агентів, перший має пріоритет (логуються попередження). Якщо не задано ні для кого, типовим є перший запис у списку. +- `model`: рядкова форма перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallbacks). Cron-завдання, які перевизначають лише `primary`, усе одно успадковують типові fallbacks, якщо ви не задасте `fallbacks: []`. +- `params`: параметри потоку для окремого агента, об’єднані поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень, специфічних для агента, як-от `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. +- `skills`: необов’язковий allowlist Skills для окремого агента. Якщо пропущено, агент успадковує `agents.defaults.skills`, коли його задано; явний список замінює типові значення замість об’єднання, а `[]` означає відсутність Skills. +- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не задано перевизначення для окремого повідомлення або сесії. +- `reasoningDefault`: необов’язкове типове значення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, якщо не задано перевизначення reasoning для окремого повідомлення або сесії. +- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, якщо не задано перевизначення fast mode для окремого повідомлення або сесії. +- `embeddedHarness`: необов’язкове перевизначення низькорівневої політики harness для окремого агента. Використовуйте `{ runtime: "codex", fallback: "none" }`, щоб зробити один агент лише Codex, тоді як інші агенти зберігатимуть типовий резервний перехід до PI. +- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово працювати в ACP harness-сесіях. - `identity.avatar`: шлях відносно workspace, URL `http(s)` або URI `data:`. - `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. -- `subagents.allowAgents`: список дозволених id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). -- Захист успадкування sandbox: якщо сесія-запитувач працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. -- `subagents.requireAgentId`: коли `true`, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типово: false). +- `subagents.allowAgents`: allowlist id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). +- Захист успадкування sandbox: якщо сесія-запитувач працює в sandbox, `sessions_spawn` відхиляє цілі, які працювали б без sandbox. +- `subagents.requireAgentId`: якщо `true`, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типово: false). --- ## Маршрутизація між агентами -Запускайте кілька ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). +Запускайте кілька ізольованих агентів усередині одного Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). ```json5 { @@ -1830,16 +1831,16 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -### Поля зіставлення прив’язок +### Поля відповідності прив’язок -- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній `type` типово означає route), `acp` для постійних прив’язок розмов ACP. +- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип відсутній, типово використовується route), `acp` для постійних ACP-прив’язок розмов. - `match.channel` (обов’язково) - `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо пропущено = типовий обліковий запис) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (необов’язково; залежить від каналу) +- `match.guildId` / `match.teamId` (необов’язково; специфічні для каналу) - `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }` -**Детермінований порядок зіставлення:** +**Детермінований порядок відповідності:** 1. `match.peer` 2. `match.guildId` @@ -1848,9 +1849,9 @@ scripts/sandbox-browser-setup.sh # optional browser image 5. `match.accountId: "*"` (на весь канал) 6. Типовий агент -У межах кожного рівня перемагає перший відповідний запис `bindings`. +У межах кожного рівня перемагає перший запис `bindings`, що збігся. -Для записів `type: "acp"` OpenClaw виконує зіставлення за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує порядок рівнів route-прив’язок, наведений вище. +Для записів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + account + `match.peer.id`) і не використовує порядок рівнів route-прив’язок, наведений вище. ### Профілі доступу для окремих агентів @@ -1872,7 +1873,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1901,7 +1902,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1947,7 +1948,7 @@ scripts/sandbox-browser-setup.sh # optional browser image -Докладніше про пріоритети див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). +Подробиці щодо пріоритетів див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). --- @@ -1998,36 +1999,36 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` - + - **`scope`**: базова стратегія групування сесій для контекстів групового чату. - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу. - - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли потрібен спільний контекст). + - `global`: усі учасники в контексті каналу використовують одну спільну сесію (використовуйте лише тоді, коли справді потрібен спільний контекст). - **`dmScope`**: як групуються DM. - - `main`: усі DM спільно використовують основну сесію. + - `main`: усі DM використовують спільну основну сесію. - `per-peer`: ізоляція за id відправника між каналами. - - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для inbox із кількома користувачами). - - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для кількох облікових записів). -- **`identityLinks`**: зіставляє канонічні id з peer із префіксом провайдера для спільного використання сесій між каналами. -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, спрацьовує той, чий строк настає раніше. + - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для inbox з кількома користувачами). + - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для багатооблікових конфігурацій). +- **`identityLinks`**: відображення канонічних id на peers із префіксами провайдера для спільного використання сесій між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовані обидва варіанти, спрацьовує той, що настане раніше. - **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як alias для `direct`. -- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківської сесії, дозволене під час створення розгалуженої сесії гілки (типово `100000`). - - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw починає нову сесію гілки замість успадкування історії стенограми батьківської сесії. - - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти розгалуження від батьківської сесії. -- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного кошика прямого чату. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість ходів зворотної відповіді між агентами під час обмінів агент-до-агента (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжки ping-pong. -- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перший збіг deny має пріоритет. -- **`maintenance`**: елементи керування очищенням сховища сесій і зберіганням. +- **`parentForkMaxTokens`**: максимальний `totalTokens` батьківської сесії, дозволений під час створення forked session для гілки (типове значення `100000`). + - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw запускає нову сесію гілки замість успадкування історії transcript батьківської сесії. + - Встановіть `0`, щоб вимкнути цей захист і завжди дозволяти fork від батьківської сесії. +- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного bucket прямих чатів. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів відповіді між агентами під час обміну агент-до-агента (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong chaining. +- **`sendPolicy`**: відповідність за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона, що збіглася, має пріоритет. +- **`maintenance`**: очищення сховища сесій + керування retention. - `mode`: `warn` лише виводить попередження; `enforce` застосовує очищення. - - `pruneAfter`: граничний вік для застарілих записів (типово `30d`). + - `pruneAfter`: віковий поріг для застарілих записів (типово `30d`). - `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`). - - `rotateBytes`: ротує `sessions.json`, коли його розмір перевищує це значення (типово `10mb`). - - `resetArchiveRetention`: строк зберігання архівів стенограм `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. - - `maxDiskBytes`: необов’язковий жорсткий бюджет диска для каталогу сесій. У режимі `warn` лише пише попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. - - `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово дорівнює `80%` від `maxDiskBytes`. -- **`threadBindings`**: глобальні типові значення для функцій сесій із прив’язкою до гілок. + - `rotateBytes`: ротація `sessions.json`, коли файл перевищує цей розмір (типово `10mb`). + - `resetArchiveRetention`: retention для архівів transcript `*.reset.`. Типово дорівнює `pruneAfter`; встановіть `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий жорсткий бюджет диска для каталогу сесій. У режимі `warn` лише логуються попередження; у режимі `enforce` спочатку видаляються найстаріші артефакти/сесії. + - `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово `80%` від `maxDiskBytes`. +- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до гілок. - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: типове автоматичне зняття фокуса через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати) + - `idleHours`: типове автоматичне зняття focus через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати) - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати) @@ -2066,36 +2067,36 @@ scripts/sandbox-browser-setup.sh # optional browser image ### Префікс відповіді -Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Перевизначення для окремого каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Розв’язання (перемагає найспецифічніше): обліковий запис → канал → глобальне значення. `""` вимикає і зупиняє каскад. `"auto"` виводить `[{identity.name}]`. +Порядок визначення (найспецифічніше значення перемагає): обліковий запис → канал → глобальне. `""` вимикає й зупиняє каскадування. `"auto"` формує `[{identity.name}]`. **Змінні шаблону:** -| Змінна | Опис | Приклад | -| ---------------- | ------------------------ | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| Змінна | Опис | Приклад | +| ---------------- | ---------------------- | --------------------------- | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | | `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва провайдера | `anthropic` | -| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Назва identity агента | (те саме, що `"auto"`) | +| `{provider}` | Назва провайдера | `anthropic` | +| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | +| `{identity.name}` | Ім’я identity агента | (те саме, що `"auto"`) | Змінні нечутливі до регістру. `{think}` — alias для `{thinkingLevel}`. -### Реакція-підтвердження +### Реакція підтвердження -- Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. -- Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок розв’язання: обліковий запис → канал → `messages.ackReaction` → резервне значення identity. +- Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Встановіть `""`, щоб вимкнути. +- Перевизначення для окремого каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. +- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення identity. - Область: `group-mentions` (типово), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: видаляє підтвердження після відповіді у Slack, Discord і Telegram. +- `removeAckAfterReply`: прибирає ack після відповіді у Slack, Discord і Telegram. - `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу у Slack, Discord і Telegram. - У Slack і Discord, якщо значення не встановлено, реакції статусу залишаються ввімкненими, коли активні реакції-підтвердження. - У Telegram для ввімкнення реакцій статусу життєвого циклу потрібно явно встановити `true`. + У Slack і Discord, якщо не задано, реакції статусу залишаються ввімкненими, коли активні ack-реакції. + У Telegram потрібно явно встановити `true`, щоб увімкнути реакції статусу життєвого циклу. -### Вхідний debounce +### Debounce вхідних повідомлень -Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди обходять debounce. +Об’єднує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення скидають буфер негайно. Керувальні команди обходять debounce. ### TTS (text-to-speech) @@ -2138,12 +2139,12 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` керує типовим режимом автоматичного TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує фактичний стан. -- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумовування. +- `auto` керує типовим режимом auto-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні налаштування, а `/tts status` показує фактичний стан. +- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного summary. - `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово має значення `false` (opt-in). -- API key резервно беруться з `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. -- `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок розв’язання: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. -- Коли `openai.baseUrl` вказує на endpoint, відмінний від OpenAI, OpenClaw обробляє його як OpenAI-сумісний TTS-сервер і послаблює валідацію моделі/голосу. +- API key використовують резервні значення `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. +- `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. +- Коли `openai.baseUrl` вказує на endpoint, відмінний від OpenAI, OpenClaw трактує його як OpenAI-compatible TTS-сервер і послаблює валідацію model/voice. --- @@ -2173,13 +2174,13 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька провайдерів Talk. -- Застарілі пласкі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) підтримуються лише для сумісності й автоматично мігруються в `talk.providers.`. -- Voice ID резервно беруться з `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. -- `providers.*.apiKey` приймає відкриті рядки або об’єкти SecretRef. -- Резервний варіант `ELEVENLABS_API_KEY` застосовується лише тоді, коли API key Talk не налаштовано. -- `providers.*.voiceAliases` дає змогу директивам Talk використовувати дружні назви. -- `silenceTimeoutMs` керує тим, як довго режим Talk чекає після тиші користувача, перш ніж надіслати стенограму. Якщо не задано, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). +- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кілька провайдерів Talk. +- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) підтримуються лише для сумісності та автоматично мігруються в `talk.providers.`. +- Для Voice ID використовуються резервні значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. +- `providers.*.apiKey` приймає звичайні текстові рядки або об’єкти SecretRef. +- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано API key Talk. +- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви. +- `silenceTimeoutMs` керує тим, скільки Talk mode чекає після мовчання користувача, перш ніж надсилати transcript. Якщо не задано, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). --- @@ -2187,37 +2188,37 @@ scripts/sandbox-browser-setup.sh # optional browser image ### Профілі інструментів -`tools.profile` задає базовий список дозволених перед `tools.allow`/`tools.deny`: +`tools.profile` задає базовий allowlist перед `tools.allow`/`tools.deny`: Локальний онбординг типово встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються). -| Профіль | Включає | -| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | лише `session_status` | +| Профіль | Містить | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `minimal` | лише `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | -| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Без обмежень (те саме, що й без значення) | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | Без обмежень (те саме, що й без значення) | ### Групи інструментів -| Група | Інструменти | -| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як alias для `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | -| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Усі вбудовані інструменти (без провайдерських Plugin) | +| Група | Інструменти | +| ----------------- | --------------------------------------------------------------------------------------------------------------------- | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як alias для `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation`| `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Усі вбудовані інструменти (без Plugin провайдерів) | ### `tools.allow` / `tools.deny` -Глобальна політика дозволу/заборони інструментів (deny має пріоритет). Нечутлива до регістру, підтримує шаблони `*`. Застосовується навіть тоді, коли sandbox Docker вимкнено. +Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Нечутлива до регістру, підтримує wildcard `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено. ```json5 { @@ -2243,7 +2244,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.elevated` -Керує підвищеним доступом `exec` поза sandbox: +Керує доступом elevated exec поза sandbox: ```json5 { @@ -2261,7 +2262,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. - `/elevated on|off|ask|full` зберігає стан для кожної сесії; вбудовані директиви застосовуються до одного повідомлення. -- Підвищений `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціллю exec є `node`). +- Elevated `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціль `exec` — це `node`). ### `tools.exec` @@ -2285,8 +2286,8 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.loopDetection` -Перевірки безпеки циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення. -Параметри можна задавати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`. +Перевірки безпеки від циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення. +Параметри можна визначати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`. ```json5 { @@ -2308,12 +2309,12 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `historySize`: максимальна історія викликів інструментів, що зберігається для аналізу циклів. -- `warningThreshold`: поріг шаблону повторення без прогресу для попереджень. +- `warningThreshold`: поріг повторюваного шаблону без прогресу для попереджень. - `criticalThreshold`: вищий поріг повторення для блокування критичних циклів. -- `globalCircuitBreakerThreshold`: жорсткий поріг зупинки для будь-якого запуску без прогресу. +- `globalCircuitBreakerThreshold`: поріг жорсткої зупинки для будь-якого запуску без прогресу. - `detectors.genericRepeat`: попереджати про повторні виклики того самого інструмента з тими самими аргументами. -- `detectors.knownPollNoProgress`: попереджати/блокувати відомі інструменти опитування (`process.poll`, `command_status` тощо). -- `detectors.pingPong`: попереджати/блокувати шаблони чергування пар без прогресу. +- `detectors.knownPollNoProgress`: попереджати/блокувати відомі poll-інструменти (`process.poll`, `command_status` тощо). +- `detectors.pingPong`: попереджати/блокувати чергування шаблонів пар без прогресу. - Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, валідація завершується помилкою. ### `tools.web` @@ -2348,7 +2349,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.media` -Налаштовує обробку вхідних медіа (зображення/аудіо/відео): +Налаштовує розуміння вхідних медіа (зображення/аудіо/відео): ```json5 { @@ -2391,7 +2392,7 @@ scripts/sandbox-browser-setup.sh # optional browser image **Запис CLI** (`type: "cli"`): - `command`: виконуваний файл для запуску -- `args`: аргументи з шаблонами (підтримуються `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) +- `args`: шаблонізовані аргументи (підтримуються `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) **Спільні поля:** @@ -2401,11 +2402,11 @@ scripts/sandbox-browser-setup.sh # optional browser image Автентифікація провайдера дотримується стандартного порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`. -**Поля асинхронного завершення:** +**Поля async completion:** - `asyncCompletion.directSend`: коли `true`, завершені асинхронні завдання `music_generate` - і `video_generate` спочатку намагаються напряму доставити результат у канал. Типове значення: `false` - (застарілий шлях пробудження сесії запитувача/доставки моделлю). + і `video_generate` спочатку намагаються доставити результат безпосередньо в канал. Типове значення: `false` + (застарілий шлях requester-session wake/model-delivery). @@ -2424,7 +2425,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.sessions` -Керує тим, які сесії можуть бути ціллю для інструментів сесій (`sessions_list`, `sessions_history`, `sessions_send`). +Керує тим, на які сесії можуть націлюватися інструменти сесій (`sessions_list`, `sessions_history`, `sessions_send`). Типове значення: `tree` (поточна сесія + сесії, породжені нею, наприклад субагенти). @@ -2441,9 +2442,9 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: -- `self`: лише поточний ключ сесії. +- `self`: лише ключ поточної сесії. - `tree`: поточна сесія + сесії, породжені поточною сесією (субагенти). -- `agent`: будь-яка сесія, що належить поточному id агента (може включати інших користувачів, якщо ви запускаєте сесії per-sender під тим самим id агента). +- `agent`: будь-яка сесія, що належить поточному id агента (може включати інших користувачів, якщо ви використовуєте per-sender сесії під тим самим id агента). - `all`: будь-яка сесія. Націлювання між агентами все одно вимагає `tools.agentToAgent`. - Обмеження sandbox: коли поточна сесія працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`. @@ -2470,15 +2471,15 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: - Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє. -- Файли матеріалізуються в дочірньому workspace за шляхом `.openclaw/attachments//` з `.manifest.json`. -- Вміст вкладень автоматично редагується під час збереження стенограми. -- Входи Base64 перевіряються суворою перевіркою алфавіту/відступів і захистом розміру до декодування. -- Для каталогів використовуються права `0700`, а для файлів — `0600`. +- Файли матеріалізуються в дочірньому workspace у `.openclaw/attachments//` з `.manifest.json`. +- Вміст вкладень автоматично редагується під час збереження transcript. +- Вхідні дані base64 перевіряються суворою перевіркою алфавіту/доповнення та перевіркою розміру до декодування. +- Для каталогів використовуються права `0700`, для файлів — `0600`. - Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише тоді, коли `retainOnSessionKeep: true`. ### `tools.experimental` -Прапори експериментальних вбудованих інструментів. Типово вимкнено, якщо не застосовується правило автоматичного ввімкнення strict-agentic GPT-5. +Прапорці експериментальних вбудованих інструментів. Типово вимкнені, якщо не спрацьовує правило автоувімкнення strict-agentic GPT-5. ```json5 { @@ -2493,8 +2494,8 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: - `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи. -- Типове значення: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цією областю, або `false`, щоб тримати його вимкненим навіть для strict-agentic запусків GPT-5. -- Коли інструмент увімкнено, системний запит також додає вказівки щодо використання, щоб модель застосовувала його лише для суттєвої роботи й тримала не більше одного кроку `in_progress`. +- Типове значення: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цим сценарієм, або `false`, щоб тримати його вимкненим навіть для strict-agentic запусків GPT-5. +- Коли інструмент увімкнено, system prompt також додає вказівки з використання, щоб модель використовувала його лише для суттєвої роботи й тримала не більше одного кроку в стані `in_progress`. ### `agents.defaults.subagents` @@ -2515,15 +2516,15 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `model`: типова модель для породжених субагентів. Якщо не задано, субагенти успадковують модель викликача. -- `allowAgents`: типовий список дозволених цільових id агентів для `sessions_spawn`, коли агент-запитувач не задає власне `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). -- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента пропускає `runTimeoutSeconds`. `0` означає відсутність тайм-ауту. +- `allowAgents`: типовий allowlist id цільових агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). +- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента не передає `runTimeoutSeconds`. `0` означає відсутність тайм-ауту. - Політика інструментів для субагента: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Користувацькі провайдери та base URL +## Власні провайдери та base URL -OpenClaw використовує вбудований каталог моделей. Додавайте користувацьких провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. +OpenClaw використовує вбудований каталог моделей. Додавайте власних провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -2552,47 +2553,48 @@ OpenClaw використовує вбудований каталог модел } ``` -- Використовуйте `authHeader: true` + `headers` для нестандартних потреб автентифікації. +- Використовуйте `authHeader: true` + `headers` для власних потреб автентифікації. - Перевизначайте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий alias змінної середовища). -- Пріоритет злиття для провайдерів із відповідними ID: - - Непорожні значення `baseUrl` у `models.json` агента мають пріоритет. +- Пріоритет об’єднання для однакових id провайдерів: + - Непорожні значення `baseUrl` з `models.json` агента мають пріоритет. - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті config/auth-profile. - - Значення `apiKey` провайдера, керовані через SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження визначених секретів. - - Значення заголовків провайдера, керовані через SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань). - - Порожні або відсутні `apiKey`/`baseUrl` агента резервно беруться з `models.providers` у конфігурації. - - Для відповідних моделей `contextWindow`/`maxTokens` використовують більше значення між явною конфігурацією та неявними значеннями каталогу. - - Для відповідних моделей `contextTokens` зберігає явне обмеження runtime, якщо воно задане; використовуйте це, щоб обмежити фактичний контекст без зміни нативних метаданих моделі. - - Використовуйте `models.mode: "replace"`, коли хочете, щоб конфігурація повністю переписала `models.json`. - - Збереження маркерів є авторитетним на рівні джерела: маркери записуються з активного знімка конфігурації джерела (до визначення), а не з визначених значень секретів runtime. + - Значення `apiKey` провайдера, керовані SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs) замість збереження розкритих секретів. + - Значення заголовків провайдера, керовані SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs). + - Порожні або відсутні `apiKey`/`baseUrl` агента повертаються до `models.providers` у конфігурації. + - Для однакових моделей `contextWindow`/`maxTokens` використовують вище значення між явною конфігурацією та неявними значеннями каталогу. + - Для однакових моделей `contextTokens` зберігає явне runtime-обмеження, коли воно є; використовуйте це, щоб обмежити фактичний контекст без зміни нативних метаданих моделі. + - Використовуйте `models.mode: "replace"`, якщо хочете, щоб конфігурація повністю переписала `models.json`. + - Збереження маркерів є авторитетним за джерелом: маркери записуються з активного знімка конфігурації джерела (до визначення), а не з розкритих секретних значень runtime. -### Відомості про поля провайдера +### Деталі полів провайдера - `models.mode`: поведінка каталогу провайдерів (`merge` або `replace`). -- `models.providers`: карта користувацьких провайдерів, де ключем є id провайдера. +- `models.providers`: мапа власних провайдерів, ключована за id провайдера. + - Безпечні зміни: використовуйте `openclaw config set models.providers. '' --strict-json --merge` або `openclaw config set models.providers..models '' --strict-json --merge` для додаткових оновлень. `config set` відмовляє в руйнівних замінах, якщо ви не передасте `--replace`. - `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо). -- `models.providers.*.apiKey`: облікові дані провайдера (надавайте перевагу SecretRef/підстановці з env). +- `models.providers.*.apiKey`: облікові дані провайдера (краще використовувати SecretRef/підстановку env). - `models.providers.*.auth`: стратегія автентифікації (`api-key`, `token`, `oauth`, `aws-sdk`). - `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вбудовує `options.num_ctx` у запити (типово: `true`). -- `models.providers.*.authHeader`: примусово передавати облікові дані в заголовку `Authorization`, коли це потрібно. -- `models.providers.*.baseUrl`: базовий URL API верхнього рівня. -- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації через проксі/тенант. -- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів до провайдерів моделей. - - `request.headers`: додаткові заголовки (зливаються з типовими значеннями провайдера). Значення приймають SecretRef. +- `models.providers.*.authHeader`: примусово передає облікові дані в заголовку `Authorization`, коли це потрібно. +- `models.providers.*.baseUrl`: базовий URL upstream API. +- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації через proxy/tenant. +- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів провайдера моделей. + - `request.headers`: додаткові заголовки (об’єднуються з типовими заголовками провайдера). Значення приймають SecretRef. - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value`, необов’язковим `prefix`). - - `request.proxy`: перевизначення HTTP-проксі. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`. + - `request.proxy`: перевизначення HTTP-proxy. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`. - `request.tls`: перевизначення TLS для прямих з’єднань. Поля: `ca`, `cert`, `key`, `passphrase` (усі приймають SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, коли DNS визначається в приватні, CGNAT або подібні діапазони, через захист SSRF вибірки HTTP провайдера (opt-in оператора для довірених self-hosted OpenAI-сумісних endpoint). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-захист fetch. Типове значення: `false`. + - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS визначається в приватні, CGNAT або подібні діапазони, через guard HTTP fetch провайдера (opt-in для оператора для довірених self-hosted endpoint OpenAI-compatible). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-gate fetch. Типове значення `false`. - `models.providers.*.models`: явні записи каталогу моделей провайдера. -- `models.providers.*.models.*.contextWindow`: метадані нативного вікна контексту моделі. -- `models.providers.*.models.*.contextTokens`: необов’язкове обмеження контексту runtime. Використовуйте це, коли хочете менший фактичний бюджет контексту, ніж нативне `contextWindow` моделі. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім ненативним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це значення в `false` під час runtime. Порожній/пропущений `baseUrl` зберігає типову поведінку OpenAI. -- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-сумісних chat endpoint, що підтримують лише рядки. Коли `true`, OpenClaw зводить масиви `messages[].content` лише з текстом до звичайних рядків перед надсиланням запиту. -- `plugins.entries.amazon-bedrock.config.discovery`: кореневий розділ параметрів автознаходження Bedrock. +- `models.providers.*.models.*.contextWindow`: метадані нативного context window моделі. +- `models.providers.*.models.*.contextTokens`: необов’язкове runtime-обмеження контексту. Використовуйте це, коли потрібен менший фактичний бюджет контексту, ніж нативний `contextWindow` моделі. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім ненативним `baseUrl` (host не `api.openai.com`) OpenClaw під час runtime примусово встановлює це значення в `false`. Порожній або пропущений `baseUrl` зберігає типову поведінку OpenAI. +- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-compatible chat endpoint, які приймають лише рядки. Коли `true`, OpenClaw згортає масиви `messages[].content`, що складаються лише з тексту, у звичайні рядки перед надсиланням запиту. +- `plugins.entries.amazon-bedrock.config.discovery`: корінь налаштувань автоматичного виявлення Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне виявлення. - `plugins.entries.amazon-bedrock.config.discovery.region`: регіон AWS для виявлення. - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр provider-id для цільового виявлення. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: інтервал опитування для оновлення виявлення. -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервне вікно контексту для виявлених моделей. +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервний context window для виявлених моделей. - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервна максимальна кількість вихідних токенів для виявлених моделей. ### Приклади провайдерів @@ -2631,7 +2633,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` — для прямого Z.AI. +Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` для прямого Z.AI. @@ -2648,7 +2650,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або посилання `opencode-go/...` для каталогу Go. Скорочений варіант: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`. +Установіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або `opencode-go/...` для каталогу Go. Скорочення: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`. @@ -2665,11 +2667,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` приймаються як alias. Скорочений варіант: `openclaw onboard --auth-choice zai-api-key`. +Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` — припустимі alias. Скорочення: `openclaw onboard --auth-choice zai-api-key`. - Загальний endpoint: `https://api.z.ai/api/paas/v4` - Endpoint для кодування (типовий): `https://api.z.ai/api/coding/paas/v4` -- Для загального endpoint визначте користувацького провайдера з перевизначенням base URL. +- Для загального endpoint визначте власного провайдера з перевизначенням base URL. @@ -2711,8 +2713,8 @@ OpenClaw використовує вбудований каталог модел Для endpoint у Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. Нативні endpoint Moonshot оголошують сумісність використання потокової передачі на спільному -транспорті `openai-completions`, і OpenClaw визначає це за можливостями endpoint, -а не лише за вбудованим id провайдера. +транспорті `openai-completions`, і OpenClaw прив’язує це до можливостей endpoint, +а не лише до вбудованого id провайдера. @@ -2730,7 +2732,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Anthropic-сумісний, вбудований провайдер. Скорочений варіант: `openclaw onboard --auth-choice kimi-code-api-key`. +Сумісний з Anthropic, вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. @@ -2769,7 +2771,7 @@ Anthropic-сумісний, вбудований провайдер. Скоро } ``` -Base URL має не містити `/v1` (клієнт Anthropic додає його). Скорочений варіант: `openclaw onboard --auth-choice synthetic-api-key`. +Base URL має бути без `/v1` (клієнт Anthropic додає його сам). Скорочення: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2809,20 +2811,20 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -Установіть `MINIMAX_API_KEY`. Скорочені варіанти: +Установіть `MINIMAX_API_KEY`. Скорочення: `openclaw onboard --auth-choice minimax-global-api` або `openclaw onboard --auth-choice minimax-cn-api`. Каталог моделей типово містить лише M2.7. -На Anthropic-сумісному шляху потокової передачі OpenClaw типово вимикає thinking MiniMax, -якщо ви явно не встановите `thinking` самостійно. `/fast on` або +На Anthropic-compatible шляху потокової передачі OpenClaw типово вимикає thinking MiniMax, +якщо ви явно не задасте `thinking` самі. `/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. - + -Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; зберігайте об’єднані hosted моделі для fallback. +Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; зберігайте hosted-моделі в режимі merge для резервного варіанта. @@ -2853,18 +2855,18 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `allowBundled`: необов’язковий список дозволених лише для bundled skills (керовані/workspace Skills не зачіпаються). +- `allowBundled`: необов’язковий allowlist лише для bundled Skills (керовані/workspace Skills не зачіпаються). - `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет). -- `install.preferBrew`: коли `true`, надавати перевагу встановленню через Homebrew, якщо `brew` - доступний, перш ніж переходити до інших типів інсталяторів. -- `install.nodeManager`: бажаний node-інсталятор для специфікацій `metadata.openclaw.install` +- `install.preferBrew`: коли `true`, за наявності `brew` спочатку використовувати інсталятори Homebrew, + а вже потім переходити до інших типів інсталяторів. +- `install.nodeManager`: переважний менеджер node для специфікацій `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). - `entries..enabled: false` вимикає Skill, навіть якщо він bundled/встановлений. -- `entries..apiKey`: зручний спосіб для Skills, що оголошують основну змінну середовища (відкритий рядок або об’єкт SecretRef). +- `entries..apiKey`: спрощений спосіб для Skills, які оголошують основну env-змінну (звичайний текстовий рядок або об’єкт SecretRef). --- -## Plugin +## Plugins ```json5 { @@ -2889,40 +2891,40 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й ``` - Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. -- Виявлення приймає нативні Plugin OpenClaw, а також сумісні пакети Codex і Claude, включно з пакетами Claude стандартного компонування без маніфесту. -- **Зміни конфігурації вимагають перезапуску gateway.** -- `allow`: необов’язковий список дозволених (завантажуються лише перелічені Plugin). `deny` має пріоритет. -- `plugins.entries..apiKey`: зручне поле API key на рівні Plugin (коли Plugin це підтримує). -- `plugins.entries..env`: карта змінних середовища в області Plugin. -- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` і ігнорує поля застарілого `before_agent_start`, які змінюють prompt, зберігаючи при цьому застарілі `modelOverride` і `providerOverride`. Це застосовується до нативних hook Plugin і підтримуваних каталогів hook, що надаються пакетами. -- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремих запусків фонових субагентів. -- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень субагентів. Використовуйте `"*"`, лише якщо ви свідомо хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (валідується нативною схемою Plugin OpenClaw, якщо вона доступна). -- `plugins.entries.firecrawl.config.webFetch`: параметри провайдера веб-вибірки Firecrawl. - - `apiKey`: API key Firecrawl (приймає SecretRef). Резервно береться з `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілого `tools.web.fetch.firecrawl.apiKey` або змінної середовища `FIRECRAWL_API_KEY`. +- Виявлення приймає нативні Plugin OpenClaw, а також сумісні bundled Codex і Claude, включно з bundled Claude без manifest у типовому layout. +- **Зміни конфігурації потребують перезапуску gateway.** +- `allow`: необов’язковий allowlist (завантажуються лише перелічені Plugin). `deny` має пріоритет. +- `plugins.entries..apiKey`: спрощене поле API key на рівні Plugin (коли Plugin це підтримує). +- `plugins.entries..env`: мапа env-змінних в області Plugin. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` і ігнорує поля legacy `before_agent_start`, що змінюють prompt, зберігаючи при цьому legacy `modelOverride` і `providerOverride`. Застосовується до нативних hook-ів Plugin і підтримуваних каталогів hook-ів, наданих bundled. +- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремого запуску фонових субагентів. +- `plugins.entries..subagent.allowedModels`: необов’язковий allowlist канонічних цілей `provider/model` для довірених перевизначень субагентів. Використовуйте `"*"`, лише якщо свідомо хочете дозволити будь-яку модель. +- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (перевіряється схемою нативного Plugin OpenClaw, якщо вона доступна). +- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl. + - `apiKey`: API key Firecrawl (приймає SecretRef). Резервно використовує `plugins.entries.firecrawl.config.webSearch.apiKey`, legacy `tools.web.fetch.firecrawl.apiKey` або env-змінну `FIRECRAWL_API_KEY`. - `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`). - - `onlyMainContent`: витягувати зі сторінок лише основний вміст (типово: `true`). + - `onlyMainContent`: витягувати лише основний вміст зі сторінок (типово: `true`). - `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні). - - `timeoutSeconds`: тайм-аут запиту на скрапінг у секундах (типово: `60`). -- `plugins.entries.xai.config.xSearch`: параметри xAI X Search (вебпошук Grok). + - `timeoutSeconds`: тайм-аут запиту scrape у секундах (типово: `60`). +- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok). - `enabled`: увімкнути провайдера X Search. - `model`: модель Grok для пошуку (наприклад, `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: параметри dreaming для пам’яті. Докладніше про фази та пороги див. у [Dreaming](/uk/concepts/dreaming). +- `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming. Фази й пороги див. у [Dreaming](/uk/concepts/dreaming). - `enabled`: головний перемикач dreaming (типово `false`). - `frequency`: Cron-інтервал для кожного повного проходу dreaming (типово `"0 3 * * *"`). - політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації). -- Повна конфігурація пам’яті наведена в [Довіднику з конфігурації пам’яті](/uk/reference/memory-config): +- Повна конфігурація пам’яті міститься в [Довіднику з конфігурації пам’яті](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені Plugin-пакети Claude також можуть додавати вбудовані типові значення Pi з `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі конфігурації OpenClaw. -- `plugins.slots.memory`: вибрати id активного Plugin пам’яті або `"none"` для вимкнення Plugin пам’яті. +- Увімкнені bundled Claude також можуть додавати вбудовані типові значення Pi із `settings.json`; OpenClaw застосовує їх як очищені налаштування агентів, а не як сирі patch-і конфігурації OpenClaw. +- `plugins.slots.memory`: вибрати id активного Plugin пам’яті або `"none"`, щоб вимкнути Plugin пам’яті. - `plugins.slots.contextEngine`: вибрати id активного Plugin рушія контексту; типово `"legacy"`, якщо ви не встановите й не виберете інший рушій. -- `plugins.installs`: метадані встановлення, керовані CLI, які використовуються `openclaw plugins update`. - - Містять `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Сприймайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI, а не ручному редагуванню. +- `plugins.installs`: метадані встановлення, керовані CLI, які використовує `openclaw plugins update`. + - Містить `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. + - Розглядайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI замість ручних змін. Див. [Plugins](/uk/tools/plugin). @@ -2965,29 +2967,29 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й ``` - `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо значення не задано, тому навігація браузера типово залишається суворою. -- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації браузера в приватній мережі. -- У суворому режимі endpoint віддалених профілів CDP (`profiles.*.cdpUrl`) підлягають тому самому блокуванню приватної мережі під час перевірок доступності/виявлення. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація браузера типово лишається суворою. +- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, лише коли ви свідомо довіряєте навігації браузера в приватній мережі. +- У суворому режимі endpoint-и віддалених профілів CDP (`profiles.*.cdpUrl`) під час перевірок доступності/виявлення підлягають такому самому блокуванню приватної мережі. - `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий alias. - У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. -- Віддалені профілі працюють лише в режимі приєднання (start/stop/reset вимкнено). +- Віддалені профілі працюють лише в режимі attach-only (start/stop/reset вимкнено). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. - Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявив `/json/version`; використовуйте WS(S), - коли ваш провайдер надає прямий URL DevTools WebSocket. -- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть приєднуватися на - вибраному хості або через підключений браузерний Node. -- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлюватися на конкретний + Використовуйте HTTP(S), коли хочете, щоб OpenClaw визначав `/json/version`; використовуйте WS(S), + коли провайдер дає вам прямий URL DevTools WebSocket. +- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися + на вибраному хості або через підключений browser node. +- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний профіль браузера на базі Chromium, наприклад Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії на основі snapshot/ref замість націлювання на CSS-селектори, hook завантаження одного файла, - відсутність перевизначення тайм-аутів діалогів, відсутність `wait --load networkidle`, а також - `responsebody`, експорту PDF, перехоплення завантажень і пакетних дій. + дії на основі snapshot/ref замість націлювання CSS-selector-ами, hooks для завантаження одного файла, + без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без + `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. - Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно задавайте `cdpUrl` лише для віддаленого CDP. - Порядок автовиявлення: типовий браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Служба керування: лише loopback (порт виводиться з `gateway.port`, типово `18791`). -- `extraArgs` додає додаткові прапори запуску до локального старту Chromium (наприклад, - `--disable-gpu`, розмір вікна або прапори налагодження). +- Сервіс керування: лише loopback (порт визначається з `gateway.port`, типово `18791`). +- `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад + `--disable-gpu`, розмір вікна або debug-прапорці). --- @@ -3005,7 +3007,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `seamColor`: колір акценту для chrome рідного UI програми (відтінок бульбашки режиму Talk тощо). +- `seamColor`: акцентний колір для chrome нативного UI застосунку (відтінок бульбашки Talk Mode тощо). - `assistant`: перевизначення identity для Control UI. Якщо не задано, використовується identity активного агента. --- @@ -3073,64 +3075,64 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` - + -- `mode`: `local` (запускати gateway) або `remote` (підключатися до віддаленого gateway). Gateway відмовляється запускатися, якщо значення не `local`. +- `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`. - `port`: єдиний мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. - `bind`: `auto`, `loopback` (типово), `lan` (`0.0.0.0`), `tailnet` (лише IP Tailscale) або `custom`. -- **Застарілі alias для bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не alias хостів (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Примітка щодо Docker**: типовий bind `loopback` слухає `127.0.0.1` усередині контейнера. За bridge-мережі Docker (`-p 18789:18789`) трафік надходить на `eth0`, тому gateway недоступний. Використовуйте `--network host`, або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. -- **Auth**: типово обов’язкова. Для bind не на loopback потрібна автентифікація gateway. На практиці це означає спільний token/password або reverse proxy з урахуванням identity із `gateway.auth.mode: "trusted-proxy"`. Wizard онбордингу типово генерує token. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Запуск, а також потоки встановлення/відновлення сервісу завершуються помилкою, якщо налаштовано обидва значення, а mode не задано. -- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних налаштувань loopback; цей варіант навмисно не пропонується в підказках онбордингу. -- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з урахуванням identity і довіряти заголовкам identity від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **джерело проксі не на loopback**; reverse proxy на тому самому хості через loopback не задовольняють вимоги trusted-proxy auth. -- `gateway.auth.allowTailscale`: коли `true`, заголовки identity Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). HTTP API endpoint **не** використовують цю auth заголовками Tailscale; вони дотримуються звичайного режиму HTTP auth gateway. Цей безтокеновий потік передбачає, що хост gateway є довіреним. Типове значення — `true`, коли `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб auth. Застосовується для кожної IP-адреси клієнта та для кожної області auth (спільний секрет і токен пристрою відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. - - В асинхронному шляху Tailscale Serve для Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом помилки. Тому одночасні хибні спроби від одного клієнта можуть спровокувати спрацьовування обмежувача вже на другому запиті, замість того щоб обидва запити пройшли як звичайні невідповідності. - - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; установіть `false`, якщо ви свідомо хочете також обмежувати трафік localhost (для тестових конфігурацій або суворих проксі-розгортань). -- Спроби auth для WS із походження браузера завжди обмежуються, причому виняток для loopback вимкнено (додатковий захист від браузерного brute force на localhost). -- На loopback ці блокування для походження браузера ізольовані за нормалізованим - значенням `Origin`, тому повторні невдалі спроби з одного походження localhost не - блокують автоматично інше походження. -- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічно, потребує auth). -- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються клієнти браузера не з loopback-origin. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервний механізм origin на основі заголовка Host для розгортань, що свідомо покладаються на політику origin через Host-header. -- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське аварійне перевизначення, що дозволяє незашифрований `ws://` до довірених IP приватної мережі; типово незашифрований трафік лишається дозволеним лише для loopback. +- **Застарілі alias для bind**: використовуйте значення режимів bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не alias хоста (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Примітка для Docker**: типовий bind `loopback` слухає `127.0.0.1` усередині контейнера. За bridge-мережі Docker (`-p 18789:18789`) трафік приходить на `eth0`, тож gateway недоступний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. +- **Auth**: типово обов’язкова. Bind-и не в loopback потребують auth gateway. На практиці це означає спільний token/password або reverse proxy з урахуванням identity з `gateway.auth.mode: "trusted-proxy"`. Майстер онбордингу типово генерує token. +- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Потоки запуску та встановлення/відновлення сервісу завершуються помилкою, коли налаштовані обидва варіанти, а режим не задано. +- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних конфігурацій local loopback; цей варіант навмисно не пропонується в підказках онбордингу. +- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з урахуванням identity і довіряти заголовкам identity від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує джерело proxy **не в loopback**; reverse proxy в loopback на тому самому хості не задовольняють auth trusted-proxy. +- `gateway.auth.allowTailscale`: коли `true`, заголовки identity Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). Endpoint-и HTTP API **не** використовують цю auth за заголовками Tailscale; вони дотримуються звичайного режиму HTTP auth gateway. Цей безтокеновий потік припускає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: необов’язковий лімітатор невдалих спроб auth. Застосовується окремо на IP клієнта і на область auth (спільний секрет і device-token відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`. + - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні неправильні спроби від того самого клієнта можуть спрацювати на лімітатор уже на другому запиті замість того, щоб обидві пройти як звичайні невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; встановіть `false`, коли свідомо хочете також обмежувати трафік localhost (для тестових конфігурацій або суворих proxy-розгортань). +- Спроби WS auth із походженням браузера завжди обмежуються без винятку для loopback (додатковий захист від браузерного brute force localhost). +- У loopback ці блокування для браузерного походження ізольовані за нормалізованим значенням `Origin`, + тож повторні невдачі з одного localhost origin не блокують автоматично + інший origin. +- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічно, потребує auth). +- `controlUi.allowedOrigins`: явний allowlist browser-origin для підключень Gateway WebSocket. Обов’язковий, коли браузерні клієнти очікуються з не-loopback origin. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервне визначення origin за Host-header для розгортань, що свідомо покладаються на політику origin на основі Host-header. +- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` `remote.url` має бути `ws://` або `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське аварійне перевизначення, яке дозволяє plaintext `ws://` до довірених IP приватної мережі; типово plaintext і далі дозволено лише для loopback. - `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway. -- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL для зовнішнього relay APNs, який використовують офіційні/TestFlight збірки iOS після публікації реєстрацій relay-backed у gateway. Цей URL має збігатися з URL relay, зібраним у збірці iOS. -- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. Типове значення: `10000`. -- Реєстрації на основі relay делегуються конкретній identity gateway. Пов’язана програма iOS отримує `gateway.identity.get`, включає цю identity у реєстрацію relay і пересилає gateway дозвіл на надсилання в області цієї реєстрації. Інший gateway не може повторно використати таку збережену реєстрацію. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення через env для наведеної вище конфігурації relay. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний механізм лише для розробки, що дозволяє loopback HTTP URL для relay. URL relay у продакшені мають залишатися на HTTPS. -- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типове значення: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`. +- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL для зовнішнього relay APNs, який використовують офіційні/TestFlight збірки iOS після публікації relay-backed реєстрацій у gateway. Цей URL має збігатися з URL relay, скомпільованим у збірку iOS. +- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання gateway-to-relay у мілісекундах. Типове значення `10000`. +- Реєстрації relay-backed делегуються конкретній identity gateway. Пов’язаний застосунок iOS викликає `gateway.identity.get`, включає цю identity в relay-реєстрацію та передає gateway право надсилання, прив’язане до реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові env-перевизначення для наведеного вище налаштування relay. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний варіант лише для розробки для loopback URL relay через HTTP. У production URL relay мають залишатися на HTTPS. +- `gateway.channelHealthCheckMinutes`: інтервал health-monitor каналу в хвилинах. Встановіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типове значення: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг stale-socket у хвилинах. Зберігайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`. - `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor на канал/обліковий запис за ковзну годину. Типове значення: `10`. -- `channels..healthMonitor.enabled`: вимкнення перезапусків health-monitor для окремого каналу за збереження глобального монітора ввімкненим. -- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису в каналах із кількома обліковими записами. Якщо задано, має пріоритет над перевизначенням на рівні каналу. -- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef, але їх не вдалося визначити, визначення завершується із закритою відмовою (без маскування резервним fallback до remote). -- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або додають заголовки переадресованого клієнта. Вказуйте лише проксі, які ви контролюєте. Записи loopback усе ще є дійсними для конфігурацій same-host proxy/local-detection (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять запити loopback придатними для `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо відсутній `X-Forwarded-For`. Типове значення `false` для поведінки fail-closed. -- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список заборон). -- `gateway.tools.allow`: прибирає назви інструментів із типового списку HTTP-заборон. +- `channels..healthMonitor.enabled`: opt-out на рівні каналу для перезапусків health-monitor, залишаючи глобальний monitor увімкненим. +- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для багатооблікових каналів. Якщо задано, воно має пріоритет над перевизначенням на рівні каналу. +- Шляхи виклику локального gateway можуть використовувати `gateway.remote.*` як резервне значення лише тоді, коли `gateway.auth.*` не задано. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не визначено, визначення завершується за fail-closed (без маскування резервним віддаленим варіантом). +- `trustedProxies`: IP reverse proxy, які завершують TLS або додають заголовки forwarded-client. Додавайте лише proxy, якими ви керуєте. Записи loopback і далі є валідними для конфігурацій proxy на тому самому хості / локального виявлення (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. Типово `false` для поведінки fail-closed. +- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список deny). +- `gateway.tools.allow`: прибирає назви інструментів із типового HTTP deny list. -### OpenAI-сумісні endpoint +### OpenAI-compatible endpoint-и - Chat Completions: типово вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Захист URL-входів Responses: +- Захист URL-input для Responses: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Порожні списки дозволених розглядаються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` - і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання через URL. + Порожні allowlist-и трактуються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` + та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання через URL. - Необов’язковий заголовок посиленого захисту відповіді: - - `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для HTTPS-origin, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + - `gateway.http.securityHeaders.strictTransportSecurity` (задавайте лише для HTTPS origin, якими ви керуєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) -### Ізоляція кількох екземплярів +### Ізоляція кількох інстансів Запускайте кілька gateway на одному хості з унікальними портами та каталогами стану: @@ -3140,7 +3142,7 @@ OPENCLAW_STATE_DIR=~/.openclaw-a \ openclaw gateway --port 19001 ``` -Зручні прапори: `--dev` (використовує `~/.openclaw-dev` + порт `19001`), `--profile ` (використовує `~/.openclaw-`). +Зручні прапорці: `--dev` (використовує `~/.openclaw-dev` + порт `19001`), `--profile ` (використовує `~/.openclaw-`). Див. [Multiple Gateways](/uk/gateway/multiple-gateways). @@ -3160,11 +3162,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типове значення: `false`). -- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для локального/dev використання. -- `certPath`: шлях у файловій системі до файла сертифіката TLS. -- `keyPath`: шлях у файловій системі до файла приватного ключа TLS; обмежте до нього права доступу. -- `caPath`: необов’язковий шлях до набору CA для перевірки клієнта або користувацьких ланцюжків довіри. +- `enabled`: вмикає термінацію TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). +- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, якщо явні файли не налаштовано; лише для локального/dev використання. +- `certPath`: шлях у файловій системі до файла TLS-сертифіката. +- `keyPath`: шлях у файловій системі до приватного TLS-ключа; тримайте його з обмеженими правами доступу. +- `caPath`: необов’язковий шлях до bundle CA для перевірки клієнтів або власних ланцюжків довіри. ### `gateway.reload` @@ -3181,12 +3183,12 @@ openclaw gateway --port 19001 ``` - `mode`: керує тим, як зміни конфігурації застосовуються під час runtime. - - `"off"`: ігнорувати зміни в реальному часі; для змін потрібен явний перезапуск. - - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації. + - `"off"`: ігнорувати живі зміни; потрібен явний перезапуск. + - `"restart"`: завжди перезапускати процес gateway після зміни конфігурації. - `"hot"`: застосовувати зміни в процесі без перезапуску. - - `"hybrid"` (типово): спочатку спробувати hot reload; якщо потрібно, перейти до перезапуску. + - `"hybrid"` (типово): спочатку пробувати hot reload; якщо потрібно — переходити до перезапуску. - `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число). -- `deferralTimeoutMs`: максимальний час у мс очікування поточних операцій перед примусовим перезапуском (типово: `300000` = 5 хвилин). +- `deferralTimeoutMs`: максимальний час у мс очікування завершення операцій у польоті перед примусовим перезапуском (типово: `300000` = 5 хвилин). --- @@ -3224,46 +3226,46 @@ openclaw gateway --port 19001 ``` Auth: `Authorization: Bearer ` або `x-openclaw-token: `. -Токени hooks у рядку запиту відхиляються. +Hook-token-и в query string відхиляються. Примітки щодо валідації та безпеки: -- `hooks.enabled=true` вимагає непорожнього `hooks.token`. -- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання токена Gateway відхиляється. +- `hooks.enabled=true` потребує непорожній `hooks.token`. +- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання token gateway відхиляється. - `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`. - Якщо `hooks.allowRequestSessionKey=true`, обмежуйте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). -- Якщо mapping або preset використовує шаблонізований `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не вимагають цього opt-in. +- Якщо mapping або preset використовує шаблонізований `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не потребують цього opt-in. -**Endpoint:** +**Endpoint-и:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - `sessionKey` із payload запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`). - `POST /hooks/` → визначається через `hooks.mappings` - - Значення `sessionKey` у mapping, згенеровані шаблоном, розглядаються як зовнішньо надані й також вимагають `hooks.allowRequestSessionKey=true`. + - Значення `sessionKey` у mapping, згенеровані шаблоном, вважаються зовнішньо поданими й також потребують `hooks.allowRequestSessionKey=true`. - + -- `match.path` зіставляє підшлях після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). -- `match.source` зіставляє поле payload для загальних шляхів. -- Шаблони на кшталт `{{messages[0].subject}}` читають значення з payload. -- `transform` може вказувати на модуль JS/TS, що повертає дію hook. - - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи й traversal відхиляються). -- `agentId` маршрутизує до конкретного агента; невідомі ID резервно спрямовуються до типового агента. -- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити все, `[]` = заборонити все). -- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook-агента без явного `sessionKey`. -- `allowRequestSessionKey`: дозволяє викликачу `/hooks/agent` і ключам сесій mapping, керованим шаблоном, задавати `sessionKey` (типово: `false`). -- `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`. +- `match.path` відповідає підшляху після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). +- `match.source` відповідає полю payload для загальних шляхів. +- Шаблони на кшталт `{{messages[0].subject}}` читають дані з payload. +- `transform` може вказувати на модуль JS/TS, який повертає дію hook. + - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються). +- `agentId` маршрутизує до конкретного агента; невідомі id повертаються до типового агента. +- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити всі, `[]` = заборонити всі). +- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook agent без явного `sessionKey`. +- `allowRequestSessionKey`: дозволити викликачам `/hooks/agent` і ключам сесій mapping, що керуються шаблоном, задавати `sessionKey` (типово: `false`). +- `allowedSessionKeyPrefixes`: необов’язковий allowlist префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`. - `deliver: true` надсилає фінальну відповідь у канал; `channel` типово дорівнює `last`. -- `model` перевизначає LLM для цього запуску hook (має бути дозволений, якщо задано каталог моделей). +- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо задано каталог моделей). ### Інтеграція Gmail - Вбудований preset Gmail використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`. -- Якщо ви зберігаєте таку маршрутизацію для кожного повідомлення, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes`, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. -- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість шаблонного типового значення. +- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, задайте `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes` так, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. +- Якщо вам потрібен `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість типового шаблонізованого значення. ```json5 { @@ -3286,12 +3288,12 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, якщо це налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. +- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, якщо це налаштовано. Встановіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути. - Не запускайте окремий `gog gmail watch serve` паралельно з Gateway. --- -## Хост Canvas +## Canvas host ```json5 { @@ -3303,22 +3305,22 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Обслуговує HTML/CSS/JS і A2UI, які може редагувати агент, через HTTP під портом Gateway: +- Обслуговує HTML/CSS/JS та A2UI, які агент може редагувати, через HTTP на порту Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Лише локально: зберігайте `gateway.bind: "loopback"` (типово). -- Для bind не на loopback: маршрути canvas вимагають auth Gateway (token/password/trusted-proxy), так само як і інші HTTP-поверхні Gateway. -- Node WebView зазвичай не надсилають заголовки auth; після сполучення та підключення Node Gateway рекламує URL можливостей із областю Node для доступу до canvas/A2UI. -- URL можливостей прив’язані до активної WS-сесії Node і швидко спливають. Резервний варіант на основі IP не використовується. -- Вбудовує клієнт live-reload у відданий HTML. -- Автоматично створює початковий `index.html`, якщо каталог порожній. +- Лише локально: залишайте `gateway.bind: "loopback"` (типово). +- Для bind не в loopback: маршрути canvas потребують auth Gateway (token/password/trusted-proxy), так само як і інші HTTP-поверхні Gateway. +- Node WebView зазвичай не надсилають заголовки auth; після сполучення та підключення node Gateway рекламує URL-и можливостей, прив’язані до node, для доступу до canvas/A2UI. +- URL-и можливостей прив’язані до активної WS-сесії node і швидко спливають. Резервний варіант на основі IP не використовується. +- Вбудовує клієнт live-reload у HTML, що обслуговується. +- Автоматично створює стартовий `index.html`, якщо каталог порожній. - Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`. -- Зміни вимагають перезапуску gateway. -- Вимкніть live reload для великих каталогів або при помилках `EMFILE`. +- Зміни потребують перезапуску gateway. +- Вимикайте live reload для великих каталогів або при помилках `EMFILE`. --- -## Виявлення +## Discovery ### mDNS (Bonjour) @@ -3332,11 +3334,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `minimal` (типово): не включати `cliPath` + `sshPort` у TXT-записи. -- `full`: включати `cliPath` + `sshPort`. -- Ім’я хоста типово дорівнює `openclaw`. Перевизначається через `OPENCLAW_MDNS_HOSTNAME`. +- `minimal` (типово): не включає `cliPath` + `sshPort` до TXT-записів. +- `full`: включає `cliPath` + `sshPort`. +- Ім’я хоста типово `openclaw`. Перевизначення через `OPENCLAW_MDNS_HOSTNAME`. -### Широка область (DNS-SD) +### Wide-area (DNS-SD) ```json5 { @@ -3346,7 +3348,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -Записує уніфіковану зону DNS-SD в `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте це з DNS-сервером (рекомендовано CoreDNS) + split DNS у Tailscale. +Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте це з DNS-сервером (рекомендовано CoreDNS) + split DNS у Tailscale. Налаштування: `openclaw dns setup --apply`. @@ -3354,7 +3356,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Середовище -### `env` (вбудовані змінні середовища) +### `env` (вбудовані env-змінні) ```json5 { @@ -3371,14 +3373,14 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Вбудовані змінні середовища застосовуються лише тоді, коли в середовищі процесу відсутній відповідний ключ. -- Файли `.env`: `.env` у CWD + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). +- Вбудовані env-змінні застосовуються лише тоді, коли в process env немає цього ключа. +- Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). - `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. -- Повний пріоритет див. у [Environment](/uk/help/environment). +- Повний порядок пріоритетів див. у [Environment](/uk/help/environment). -### Підстановка змінних середовища +### Підстановка env-змінних -Посилайтеся на змінні середовища в будь-якому рядку конфігурації через `${VAR_NAME}`: +Посилайтеся на env-змінні в будь-якому рядку конфігурації через `${VAR_NAME}`: ```json5 { @@ -3388,16 +3390,16 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. -- Відсутні/порожні змінні викликають помилку під час завантаження конфігурації. +- Підходять лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. +- Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації. - Екрануйте як `$${VAR}` для буквального `${VAR}`. - Працює з `$include`. --- -## Секрети +## Secrets -Посилання на секрети є адитивними: відкриті значення й далі працюють. +Посилання на секрети є додатковими: звичайні текстові значення і далі працюють. ### `SecretRef` @@ -3411,15 +3413,15 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - шаблон `provider`: `^[a-z][a-z0-9_-]{0,63}$` - шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` `id`: абсолютний JSON pointer (наприклад, `"/providers/openai/apiKey"`) +- `id` для `source: "file"`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`) - шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `id` для `source: "exec"` не мають містити сегментів шляху `.` або `..`, розділених `/` (наприклад, `a/../b` відхиляється) +- `id` для `source: "exec"` не повинні містити сегментів шляху `.` або `..`, розділених `/` (наприклад `a/../b` відхиляється) ### Підтримувана поверхня облікових даних - Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface) - `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`. -- Посилання в `auth-profiles.json` включені до визначення runtime і покриття аудиту. +- Посилання з `auth-profiles.json` включені в runtime-визначення й покриття аудиту. ### Конфігурація провайдерів секретів @@ -3451,13 +3453,13 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. Примітки: -- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (`id` має бути `"value"` у режимі singleValue). -- Провайдер `exec` вимагає абсолютного шляху `command` і використовує payload протоколу через stdin/stdout. -- Типово шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання з перевіркою шляху визначеної цілі. -- Якщо налаштовано `trustedDirs`, перевірка trusted-dir застосовується до шляху визначеної цілі. -- Середовище дочірнього процесу `exec` типово є мінімальним; явно передавайте потрібні змінні через `passEnv`. -- Посилання на секрети визначаються під час активації в знімок у пам’яті, після чого шляхи запиту читають лише цей знімок. -- Під час активації застосовується фільтрація активної поверхні: невизначені посилання на ввімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. +- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має дорівнювати `"value"`). +- Провайдер `exec` потребує абсолютний шлях `command` і використовує payload-и протоколу через stdin/stdout. +- Типово шляхи команд-симлінків відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-симлінки з перевіркою шляху до визначеної цілі. +- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до шляху визначеної цілі. +- Середовище дочірнього процесу `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`. +- Посилання на секрети визначаються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. +- Під час активації застосовується фільтрація активної поверхні: невизначені посилання на ввімкнених поверхнях призводять до помилки під час startup/reload, тоді як неактивні поверхні пропускаються з діагностикою. --- @@ -3480,12 +3482,12 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - Профілі для окремого агента зберігаються в `/auth-profiles.json`. -- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. -- Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані auth-profile на основі SecretRef. -- Статичні облікові дані runtime беруться з визначених знімків у пам’яті; застарілі статичні записи `auth.json` очищаються при виявленні. -- Застарілий імпорт OAuth виконується з `~/.openclaw/credentials/oauth.json`. +- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для режимів статичних облікових даних. +- Профілі в режимі OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілів auth на основі SecretRef. +- Статичні runtime-облікові дані надходять із визначених знімків у пам’яті; застарілі статичні записи `auth.json` очищаються при виявленні. +- Застарілі імпорти OAuth беруться з `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). -- Поведінка runtime секретів і інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). +- Поведінка runtime секретів і tooling `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). ### `auth.cooldowns` @@ -3507,20 +3509,21 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні - помилки billing/недостатній кредит (типово: `5`). Явний текст про billing усе ще - може потрапляти сюди навіть у відповідях `401`/`403`, але текстові зіставлення, - специфічні для провайдера, залишаються в межах провайдера, якому вони належать (наприклад, OpenRouter - `Key limit exceeded`). Повторювані повідомлення HTTP `402` про вікно використання або - ліміти витрат organization/workspace натомість залишаються в шляху `rate_limit`. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин billing backoff для окремих провайдерів. -- `billingMaxHours`: обмеження в годинах для експоненційного зростання billing backoff (типово: `24`). +- `billingBackoffHours`: базовий backoff у годинах, коли профіль зазнає невдачі через справжні + помилки billing/недостатнього кредиту (типово: `5`). Явний текст про billing + усе одно може потрапити сюди навіть на відповідях `401`/`403`, але + зіставлення тексту, специфічного для провайдера, залишаються обмеженими + провайдером, якому вони належать (наприклад OpenRouter + `Key limit exceeded`). Повідомлення retryable HTTP `402` про вікно використання або + ліміти витрат організації/workspace і далі потрапляють у шлях `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff для billing на рівні провайдера. +- `billingMaxHours`: верхня межа в годинах для експоненційного зростання backoff billing (типово: `24`). - `authPermanentBackoffMinutes`: базовий backoff у хвилинах для високовпевнених збоїв `auth_permanent` (типово: `10`). -- `authPermanentMaxMinutes`: обмеження в хвилинах для зростання backoff `auth_permanent` (типово: `60`). -- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників backoff (типово: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile в межах одного провайдера для помилок перевантаження перед переходом до fallback моделі (типово: `1`). Сюди потрапляють форми на кшталт `ModelNotReadyException`, коли провайдер зайнятий. +- `authPermanentMaxMinutes`: верхня межа в хвилинах для зростання backoff `auth_permanent` (типово: `60`). +- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників backoff (типово: `24`). +- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера для помилок перевантаження перед переходом до резервної моделі (типово: `1`). Сюди потрапляють форми провайдерської зайнятості на кшталт `ModelNotReadyException`. - `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile в межах одного провайдера для помилок rate-limit перед переходом до fallback моделі (типово: `1`). Цей кошик rate-limit включає текстові форми провайдерів, такі як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера для помилок rate-limit перед переходом до резервної моделі (типово: `1`). Цей bucket rate-limit включає текстові форми провайдера на кшталт `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- @@ -3541,8 +3544,8 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Установіть `logging.file` для стабільного шляху. -- `consoleLevel` підвищується до `debug` з `--verbose`. -- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис пригнічується (додатне ціле число; типово: `524288000` = 500 MB). Для продакшен-розгортань використовуйте зовнішню ротацію логів. +- `consoleLevel` підвищується до `debug`, коли використовується `--verbose`. +- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис пригнічується (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. --- @@ -3580,19 +3583,19 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - `enabled`: головний перемикач для виводу інструментування (типово: `true`). -- `flags`: масив рядків-прапорів, що вмикають цільовий вивід у журнал (підтримуються wildcard, такі як `"telegram.*"` або `"*"`). -- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислу сесію, поки сесія залишається в стані обробки. +- `flags`: масив рядків-прапорців, що вмикають цільовий вивід у журнали (підтримує wildcard-и на кшталт `"telegram.*"` або `"*"`). +- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислі сесії, поки сесія лишається в стані обробки. - `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). - `otel.endpoint`: URL колектора для експорту OTel. - `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`. -- `otel.headers`: додаткові заголовки HTTP/gRPC metadata, що надсилаються з запитами експорту OTel. -- `otel.serviceName`: ім’я сервісу для атрибутів ресурсу. +- `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel. +- `otel.serviceName`: назва сервісу для атрибутів ресурсу. - `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або logs. -- `otel.sampleRate`: коефіцієнт семплювання trace `0`–`1`. -- `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс. -- `cacheTrace.enabled`: журналювати знімки трасування кешу для вбудованих запусків (типово: `false`). -- `cacheTrace.filePath`: шлях виводу для JSONL трасування кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід трасування кешу (усі типово: `true`). +- `otel.sampleRate`: частота семплювання trace `0`–`1`. +- `otel.flushIntervalMs`: інтервал періодичного flush telemetry у мс. +- `cacheTrace.enabled`: журналювати знімки trace кешу для вбудованих запусків (типово: `false`). +- `cacheTrace.filePath`: шлях виводу для JSONL trace кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід trace кешу (усе типово: `true`). --- @@ -3614,12 +3617,12 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `channel`: канал релізів для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`. +- `channel`: канал релізів для npm/git-встановлень — `"stable"`, `"beta"` або `"dev"`. - `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`). -- `auto.enabled`: увімкнути фонове автооновлення для встановлень пакетів (типово: `false`). -- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням для каналу stable (типово: `6`; максимум: `168`). -- `auto.stableJitterHours`: додаткове вікно розтягування розгортання stable у годинах (типово: `12`; максимум: `168`). -- `auto.betaCheckIntervalHours`: як часто виконуються перевірки каналу beta, у годинах (типово: `1`; максимум: `24`). +- `auto.enabled`: увімкнути фонове автооновлення для package-встановлень (типово: `false`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед авто-застосуванням у stable-каналі (типово: `6`; максимум: `168`). +- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (типово: `12`; максимум: `168`). +- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу в годинах (типово: `1`; максимум: `24`). --- @@ -3653,21 +3656,21 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - `enabled`: глобальний feature gate для ACP (типово: `false`). -- `dispatch.enabled`: незалежний gate для диспетчеризації ходів сесій ACP (типово: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання. -- `backend`: id типового backend runtime ACP (має збігатися із зареєстрованим Plugin runtime ACP). -- `defaultAgent`: резервний id цільового агента ACP, коли spawn не задає явну ціль. -- `allowedAgents`: список дозволених id агентів для runtime-сесій ACP; порожнє значення означає відсутність додаткових обмежень. -- `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP. +- `dispatch.enabled`: незалежний gate для диспетчеризації ходів ACP-сесій (типово: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання. +- `backend`: id типового backend runtime ACP (має відповідати зареєстрованому Plugin runtime ACP). +- `defaultAgent`: резервний id цільового агента ACP, коли spawn-и не задають явну ціль. +- `allowedAgents`: allowlist id агентів, дозволених для runtime-сесій ACP; порожнє значення означає відсутність додаткового обмеження. +- `maxConcurrentSessions`: максимальна кількість одночасно активних ACP-сесій. - `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту. -- `stream.maxChunkChars`: максимальний розмір чанка перед розбиттям проєкції потокового блока. -- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів у межах одного ходу (типово: `true`). +- `stream.maxChunkChars`: максимальний розмір блока перед розбиттям проєкції потокового блока. +- `stream.repeatSuppression`: приглушувати повторювані рядки статусу/інструментів на кожен хід (типово: `true`). - `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до термінальних подій ходу. - `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`). -- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, що проєктуються за хід ACP. +- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, що проєктується за один хід ACP. - `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлень ACP. -- `stream.tagVisibility`: запис імен тегів до булевих перевизначень видимості для потокових подій. -- `runtime.ttlMinutes`: idle TTL у хвилинах для робочих процесів сесій ACP до того, як вони стануть придатними для очищення. -- `runtime.installCommand`: необов’язкова команда встановлення, яку слід виконати під час bootstrap середовища runtime ACP. +- `stream.tagVisibility`: запис назв тегів на булеві перевизначення видимості для потокових подій. +- `runtime.ttlMinutes`: idle TTL у хвилинах для worker-ів ACP-сесій до того, як вони стануть придатними для очищення. +- `runtime.installCommand`: необов’язкова команда встановлення, яку слід запустити під час bootstrap середовища runtime ACP. --- @@ -3683,17 +3686,17 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `cli.banner.taglineMode` керує стилем слогана банера: - - `"random"` (типово): змінні кумедні/сезонні слогани. - - `"default"`: фіксований нейтральний слоган (`All your chats, one OpenClaw.`). - - `"off"`: без тексту слогана (заголовок/версія банера все одно показуються). -- Щоб приховати весь банер (а не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`. +- `cli.banner.taglineMode` керує стилем підзаголовка банера: + - `"random"` (типово): змінні кумедні/сезонні підзаголовки. + - `"default"`: фіксований нейтральний підзаголовок (`All your chats, one OpenClaw.`). + - `"off"`: без тексту підзаголовка (заголовок/версія банера все одно показуються). +- Щоб приховати весь банер (а не лише підзаголовки), встановіть env `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Метадані, які записуються потоками керованого налаштування CLI (`onboard`, `configure`, `doctor`): +Метадані, які записують керовані CLI-потоки налаштування (`onboard`, `configure`, `doctor`): ```json5 { @@ -3711,15 +3714,15 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Identity -Див. поля identity у `agents.list` у розділі [Типові значення агента](#agent-defaults). +Див. поля identity в `agents.list` у розділі [Значення агентів за замовчуванням](#agent-defaults). --- -## Bridge (застаріле, вилучено) +## Bridge (legacy, видалено) -Поточні збірки більше не містять TCP bridge. Node підключаються через WebSocket Gateway. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP bridge. Node підключаються через WebSocket Gateway. Ключі `bridge.*` більше не входять до схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). - + ```json { @@ -3757,11 +3760,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків Cron перед видаленням із `sessions.json`. Також керує очищенням архівованих видалених стенограм Cron. Типове значення: `24h`; установіть `false`, щоб вимкнути. -- `runLog.maxBytes`: максимальний розмір файла журналу одного запуску (`cron/runs/.jsonl`) перед обрізанням. Типове значення: `2_000_000` байтів. -- `runLog.keepLines`: найновіші рядки, які зберігаються, коли спрацьовує обрізання журналу запуску. Типове значення: `2000`. -- `webhookToken`: bearer token, який використовується для доставки POST через webhook Cron (`delivery.mode = "webhook"`); якщо пропущено, заголовок auth не надсилається. -- `webhook`: застарілий резервний URL webhook (http/https), який використовується лише для збережених завдань, що досі мають `notify: true`. +- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків Cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених transcript Cron. Типове значення: `24h`; установіть `false`, щоб вимкнути. +- `runLog.maxBytes`: максимальний розмір файла журналу одного запуску (`cron/runs/.jsonl`) перед очищенням. Типове значення: `2_000_000` байтів. +- `runLog.keepLines`: кількість найновіших рядків, що зберігаються при спрацюванні очищення журналу запуску. Типове значення: `2000`. +- `webhookToken`: bearer token, який використовується для доставки POST webhook Cron (`delivery.mode = "webhook"`); якщо пропущено, заголовок auth не надсилається. +- `webhook`: застарілий резервний URL webhook (http/https), який використовується лише для збережених завдань, що все ще мають `notify: true`. ### `cron.retry` @@ -3779,9 +3782,9 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (типово: `3`; діапазон: `0`–`10`). - `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). -- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати всі тимчасові типи. +- `retryOn`: типи помилок, що запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати для всіх тимчасових типів. -Застосовується лише до одноразових завдань Cron. Для повторюваних завдань використовується окрема обробка збоїв. +Застосовується лише до одноразових завдань Cron. Повторювані завдання використовують окрему обробку помилок. ### `cron.failureAlert` @@ -3799,11 +3802,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `enabled`: увімкнути сповіщення про збої для завдань Cron (типово: `false`). -- `after`: кількість послідовних збоїв, після яких спрацьовує сповіщення (додатне ціле число, мінімум: `1`). +- `enabled`: увімкнути сповіщення про помилки для завдань Cron (типово: `false`). +- `after`: кількість послідовних помилок перед спрацюванням сповіщення (додатне ціле число, мінімум: `1`). - `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). -- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` публікує в налаштований webhook. -- `accountId`: необов’язковий id облікового запису або каналу для області доставки сповіщення. +- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` робить POST на налаштований webhook. +- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки сповіщення. ### `cron.failureDestination` @@ -3821,48 +3824,48 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - Типова ціль для сповіщень про збої Cron у всіх завданнях. -- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли існує достатньо даних цілі. +- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли існує достатньо даних про ціль. - `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки. -- `to`: явна ціль announce або URL webhook. Обов’язкове для режиму webhook. +- `to`: явна ціль announce або URL webhook. Обов’язково для режиму webhook. - `accountId`: необов’язкове перевизначення облікового запису для доставки. -- `delivery.failureDestination` для окремого завдання перевизначає це глобальне типове значення. -- Якщо не задано ні глобальної, ні окремої цілі збоїв, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної цілі announce. +- `delivery.failureDestination` на рівні завдання перевизначає це глобальне типове значення. +- Коли не задано ні глобальну, ні ціль збою для конкретного завдання, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної announce-цілі. - `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`. -Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [background tasks](/uk/automation/tasks). +Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [фонові завдання](/uk/automation/tasks). --- ## Змінні шаблону моделі медіа -Заповнювачі шаблону, які розгортаються в `tools.media.models[].args`: +Заповнювачі шаблонів, що розгортаються в `tools.media.models[].args`: | Змінна | Опис | | ----------------- | ------------------------------------------------- | -| `{{Body}}` | Повний текст вхідного повідомлення | -| `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) | -| `{{BodyStripped}}` | Текст із вилученими згадуваннями групи | +| `{{Body}}` | Повне тіло вхідного повідомлення | +| `{{RawBody}}` | Сире тіло (без обгорток історії/відправника) | +| `{{BodyStripped}}`| Тіло без групових згадок | | `{{From}}` | Ідентифікатор відправника | | `{{To}}` | Ідентифікатор призначення | -| `{{MessageSid}}` | ID повідомлення каналу | +| `{{MessageSid}}` | id повідомлення каналу | | `{{SessionId}}` | UUID поточної сесії | -| `{{IsNewSession}}` | `"true"`, коли створено нову сесію | +| `{{IsNewSession}}`| `"true"`, коли створено нову сесію | | `{{MediaUrl}}` | Псевдо-URL вхідного медіа | | `{{MediaPath}}` | Локальний шлях до медіа | | `{{MediaType}}` | Тип медіа (image/audio/document/…) | -| `{{Transcript}}` | Аудіостенограма | -| `{{Prompt}}` | Визначений запит медіа для записів CLI | -| `{{MaxChars}}` | Визначена максимальна кількість символів виводу для записів CLI | +| `{{Transcript}}` | Аудіотранскрипт | +| `{{Prompt}}` | Визначений media prompt для записів CLI | +| `{{MaxChars}}` | Визначений максимум символів виводу для записів CLI | | `{{ChatType}}` | `"direct"` або `"group"` | -| `{{GroupSubject}}` | Тема групи (best effort) | -| `{{GroupMembers}}` | Попередній перегляд учасників групи (best effort) | -| `{{SenderName}}` | Ім’я відображення відправника (best effort) | -| `{{SenderE164}}` | Номер телефону відправника (best effort) | -| `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | +| `{{GroupSubject}}`| Тема групи (best effort) | +| `{{GroupMembers}}`| Попередній перегляд учасників групи (best effort) | +| `{{SenderName}}` | Видиме ім’я відправника (best effort) | +| `{{SenderE164}}` | Номер телефону відправника (best effort) | +| `{{Provider}}` | Підказка про провайдера (whatsapp, telegram, discord тощо) | --- -## Include конфігурації (`$include`) +## Include-и конфігурації (`$include`) Розділяйте конфігурацію на кілька файлів: @@ -3880,11 +3883,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. **Поведінка злиття:** - Один файл: замінює об’єкт, у якому міститься. -- Масив файлів: глибоко зливається по порядку (пізніші значення перевизначають попередні). -- Сусідні ключі: зливаються після include (перевизначають включені значення). -- Вкладені include: до 10 рівнів глибини. -- Шляхи: визначаються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/форми з `../` дозволені лише тоді, коли після визначення вони все одно залишаються в цих межах. -- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок парсингу та циклічних include. +- Масив файлів: глибоко об’єднується по черзі (пізніші значення перевизначають ранні). +- Сусідні ключі: об’єднуються після include-ів (перевизначають включені значення). +- Вкладені include-и: до 10 рівнів глибини. +- Шляхи: визначаються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли вони все одно визначаються в межах цієї межі. +- Помилки: чіткі повідомлення для відсутніх файлів, помилок парсингу та циклічних include-ів. --- diff --git a/docs/uk/gateway/configuration.md b/docs/uk/gateway/configuration.md index 4da6a688d..aedda38f3 100644 --- a/docs/uk/gateway/configuration.md +++ b/docs/uk/gateway/configuration.md @@ -2,32 +2,32 @@ read_when: - Перше налаштування OpenClaw - Пошук поширених шаблонів конфігурації - - Перехід до певних розділів конфігурації + - Перехід до конкретних розділів конфігурації summary: 'Огляд конфігурації: поширені завдання, швидке налаштування та посилання на повний довідник' title: Конфігурація x-i18n: - generated_at: "2026-04-22T21:30:54Z" + generated_at: "2026-04-22T22:25:45Z" model: gpt-5.4 provider: openai - source_hash: 36162008b66dcaaac6d51882f20d74aebd9b637bfddde00395cdfbd5721e3d20 + source_hash: 2296617a25a339048cb1df7b895fec35e96b0740851c89add907fc49307e08d1 source_path: gateway/configuration.md workflow: 15 --- # Конфігурація -OpenClaw зчитує необов’язкову конфігурацію **JSON5** з `~/.openclaw/openclaw.json`. +OpenClaw читає необов’язковий конфігураційний файл **JSON5** з `~/.openclaw/openclaw.json`. -Якщо файл відсутній, OpenClaw використовує безпечні значення за замовчуванням. Поширені причини додати конфігурацію: +Якщо файл відсутній, OpenClaw використовує безпечні значення за замовчуванням. Типові причини додати конфігурацію: - Підключити канали та керувати тим, хто може надсилати повідомлення боту -- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (Cron, хуки) -- Налаштувати сесії, медіа, мережу або UI +- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (cron, hooks) +- Тонко налаштувати сеанси, медіа, мережу або UI Перегляньте [повний довідник](/uk/gateway/configuration-reference), щоб побачити всі доступні поля. -**Вперше працюєте з конфігурацією?** Почніть із `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) з готовими конфігураціями для копіювання. +**Вперше налаштовуєте конфігурацію?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) з повними конфігураціями для копіювання. ## Мінімальна конфігурація @@ -45,8 +45,8 @@ OpenClaw зчитує необов’язкову конфігурацію ```bash - openclaw onboard # повний процес початкового налаштування - openclaw configure # майстер конфігурації + openclaw onboard # full onboarding flow + openclaw configure # config wizard ``` @@ -57,12 +57,12 @@ OpenClaw зчитує необов’язкову конфігурацію - Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і скористайтеся вкладкою **Config**. - Control UI відображає форму на основі актуальної схеми конфігурації, включно з метаданими документації полів - `title` / `description`, а також схемами Plugin і каналів, коли - вони доступні, з редактором **Raw JSON** як запасним варіантом. Для деталізованих - UI та інших інструментів gateway також надає `config.schema.lookup`, щоб - отримати один вузол схеми для заданого шляху разом із підсумками безпосередніх дочірніх елементів. + Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і використовуйте вкладку **Config**. + Control UI відображає форму на основі живої схеми конфігурації, включно з + метаданими документації полів `title` / `description`, а також схемами Plugin і каналів, коли + вони доступні, з редактором **Raw JSON** як запасним варіантом. Для + UI з деталізацією та інших інструментів gateway також надає `config.schema.lookup` для + отримання одного вузла схеми, обмеженого шляхом, і підсумків його безпосередніх дочірніх елементів. Відредагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway відстежує файл і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)). @@ -72,47 +72,47 @@ OpenClaw зчитує необов’язкову конфігурацію -OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на рівні кореня — `$schema` (рядок), щоб редактори могли підключати метадані JSON Schema. +OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, неправильні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на рівні кореня — `$schema` (рядок), щоб редактори могли підключати метадані JSON Schema. Примітки щодо інструментів схеми: - `openclaw config schema` виводить ту саму сім’ю JSON Schema, яку використовують Control UI і валідація конфігурації. -- Вважайте цей вивід схеми канонічним машиночитаним контрактом для - `openclaw.json`; цей огляд і довідник конфігурації його узагальнюють. -- Значення полів `title` і `description` переносяться у вивід схеми для +- Розглядайте цей вивід схеми як канонічний машиночитний контракт для + `openclaw.json`; цей огляд і довідник із конфігурації його узагальнюють. +- Значення полів `title` і `description` переносяться до виводу схеми для редакторів та інструментів форм. -- Вкладені об’єкти, шаблони з wildcard (`*`) і елементи масиву (`[]`) успадковують ті самі - метадані документації, якщо для відповідного поля є документація. -- Гілки композиції `anyOf` / `oneOf` / `allOf` також успадковують ті самі - метадані документації, тож варіанти union/intersection зберігають ті самі підказки для полів. -- `config.schema.lookup` повертає один нормалізований шлях конфігурації з неглибоким - вузлом схеми (`title`, `description`, `type`, `enum`, `const`, поширені межі - та подібні поля валідації), відповідними метаданими підказок UI і стислими описами +- Вкладені об’єкти, шаблони (`*`) та елементи масиву (`[]`) успадковують ті самі + метадані документації, якщо для відповідного поля існує документація. +- Гілки композицій `anyOf` / `oneOf` / `allOf` також успадковують ті самі + метадані документації, тож варіанти union/intersection зберігають ту саму довідку полів. +- `config.schema.lookup` повертає один нормалізований шлях конфігурації з поверхневим + вузлом схеми (`title`, `description`, `type`, `enum`, `const`, поширені обмеження + та подібні поля валідації), відповідними метаданими підказок UI і підсумками безпосередніх дочірніх елементів для інструментів деталізації. -- Схеми Plugin/каналів під час виконання об’єднуються, коли gateway може завантажити +- Схеми Plugin/каналів часу виконання об’єднуються, коли gateway може завантажити поточний реєстр маніфестів. -- `pnpm config:docs:check` виявляє розбіжності між артефактами базової конфігурації для документації - і поточною поверхнею схеми. +- `pnpm config:docs:check` виявляє розбіжності між артефактами базових конфігурацій, + орієнтованими на документацію, і поточною поверхнею схеми. Коли валідація не проходить: - Gateway не запускається - Працюють лише діагностичні команди (`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`) -- Запустіть `openclaw doctor`, щоб побачити точні проблеми -- Запустіть `openclaw doctor --fix` (або `--yes`), щоб застосувати виправлення +- Виконайте `openclaw doctor`, щоб побачити точні проблеми +- Виконайте `openclaw doctor --fix` (або `--yes`), щоб застосувати виправлення -Gateway також зберігає довірену останню відому справну копію після успішного запуску. Якщо -`openclaw.json` пізніше буде змінено поза OpenClaw і він більше не проходитиме валідацію, під час запуску -та гарячого перезавантаження зіпсований файл буде збережено як позначений часовою міткою знімок `.clobbered.*`, -відновлено останню відому справну копію та записано помітне попередження з причиною відновлення. -Якщо перед інакше коректною JSON-конфігурацією випадково додано рядок статусу/журналу, -під час запуску gateway і виконання `openclaw doctor --fix` цей префікс можна видалити, +Gateway також зберігає довірену останню коректну копію після успішного запуску. Якщо +`openclaw.json` пізніше буде змінено поза OpenClaw і він перестане проходити валідацію, запуск +і гаряче перезавантаження збережуть пошкоджений файл як позначений часом знімок `.clobbered.*`, +відновлять останню коректну копію та запишуть помітне попередження з причиною відновлення. +Якщо перед інакше коректною JSON-конфігурацією випадково буде додано рядок статусу/журналу, +запуск gateway і `openclaw doctor --fix` можуть прибрати цей префікс, зберегти забруднений файл як `.clobbered.*` і продовжити роботу з відновленим JSON. -Наступний хід основного агента також отримує попередження системної події про те, що -конфігурацію було відновлено і її не можна бездумно перезаписувати. Оновлення останньої відомої справної копії +Наступний хід основного агента також отримує попередження про системну подію, яке повідомляє, що +конфігурацію було відновлено і її не можна бездумно перезаписувати. Оновлення останньої коректної версії відбувається після валідованого запуску та після прийнятих гарячих перезавантажень, включно з записами конфігурації, виконаними самим OpenClaw, якщо хеш збереженого файлу все ще збігається з прийнятим записом. Оновлення пропускається, якщо кандидат містить замасковані заповнювачі секретів @@ -135,7 +135,7 @@ JSON. - [iMessage](/uk/channels/imessage) — `channels.imessage` - [Mattermost](/uk/channels/mattermost) — `channels.mattermost` - Усі канали використовують однаковий шаблон політики DM: + Усі канали використовують однаковий шаблон політики особистих повідомлень: ```json5 { @@ -153,7 +153,7 @@ JSON. - Задайте основну модель і необов’язкові резервні варіанти: + Встановіть основну модель і необов’язкові резервні варіанти: ```json5 { @@ -172,30 +172,31 @@ JSON. } ``` - - `agents.defaults.models` визначає каталог моделей і виконує роль allowlist для `/model`. + - `agents.defaults.models` визначає каталог моделей і слугує allowlist для `/model`. + - Використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи allowlist без видалення наявних моделей. Звичайні заміни, які призвели б до видалення записів, відхиляються, якщо не передати `--replace`. - Посилання на моделі використовують формат `provider/model` (наприклад, `anthropic/claude-opus-4-6`). - - `agents.defaults.imageMaxDimensionPx` керує зменшенням масштабу зображень у транскриптах/інструментах (типове значення `1200`); менші значення зазвичай зменшують використання vision-токенів у сценаріях із великою кількістю скриншотів. - - Див. [Models CLI](/uk/concepts/models) для перемикання моделей у чаті та [Model Failover](/uk/concepts/model-failover) для ротації автентифікації й поведінки резервного перемикання. - - Для користувацьких/self-hosted provider див. [Custom providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику. + - `agents.defaults.imageMaxDimensionPx` керує зменшенням розміру зображень у транскриптах/інструментах (типове значення `1200`); менші значення зазвичай зменшують використання vision-token у сценаріях із великою кількістю скриншотів. + - Див. [Models CLI](/uk/concepts/models), щоб перемикати моделі в чаті, і [Model Failover](/uk/concepts/model-failover) щодо ротації автентифікації та поведінки резервного перемикання. + - Для користувацьких/self-hosted провайдерів див. [Custom providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику. - Доступ до DM контролюється окремо для кожного каналу через `dmPolicy`: + Доступ до особистих повідомлень керується окремо для кожного каналу через `dmPolicy`: - - `"pairing"` (типово): невідомі відправники отримують одноразовий код сполучення для підтвердження - - `"allowlist"`: лише відправники з `allowFrom` (або зі сховища дозволів після сполучення) - - `"open"`: дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) - - `"disabled"`: ігнорувати всі DM + - `"pairing"` (типово): невідомі відправники отримують одноразовий код pairing для схвалення + - `"allowlist"`: лише відправники з `allowFrom` (або зі сховища парного allow) + - `"open"`: дозволити всі вхідні особисті повідомлення (потрібно `allowFrom: ["*"]`) + - `"disabled"`: ігнорувати всі особисті повідомлення - Для груп використовуйте `groupPolicy` + `groupAllowFrom` або специфічні для каналу allowlist. + Для груп використовуйте `groupPolicy` + `groupAllowFrom` або allowlist, специфічні для каналу. Див. [повний довідник](/uk/gateway/configuration-reference#dm-and-group-access) для деталей по кожному каналу. - - Повідомлення в групах типово **вимагають згадки**. Налаштуйте шаблони для кожного агента: + + Групові повідомлення типово **вимагають згадки**. Налаштуйте шаблони для кожного агента: ```json5 { @@ -217,15 +218,15 @@ JSON. } ``` - - **Metadata mentions**: нативні @-згадки (tap-to-mention у WhatsApp, @bot у Telegram тощо) - - **Text patterns**: безпечні regex-шаблони в `mentionPatterns` - - Див. [повний довідник](/uk/gateway/configuration-reference#group-chat-mention-gating) для перевизначень по каналах і режиму self-chat. + - **Metadata mentions**: нативні @-згадки (WhatsApp tap-to-mention, Telegram @bot тощо) + - **Text patterns**: безпечні шаблони regex у `mentionPatterns` + - Див. [повний довідник](/uk/gateway/configuration-reference#group-chat-mention-gating) для перевизначень на рівні каналів і режиму self-chat. - Використовуйте `agents.defaults.skills` для спільного базового набору, а потім перевизначайте - конкретних агентів через `agents.list[].skills`: + Використовуйте `agents.defaults.skills` для спільного базового набору, а потім перевизначайте конкретні + агенти через `agents.list[].skills`: ```json5 { @@ -242,15 +243,15 @@ JSON. } ``` - - Не вказуйте `agents.defaults.skills`, якщо за замовчуванням Skills не мають бути обмежені. + - Не вказуйте `agents.defaults.skills`, щоб типово не обмежувати Skills. - Не вказуйте `agents.list[].skills`, щоб успадкувати значення за замовчуванням. - - Встановіть `agents.list[].skills: []`, щоб не дозволяти жодних Skills. + - Установіть `agents.list[].skills: []`, щоб не було Skills. - Див. [Skills](/uk/tools/skills), [конфігурація Skills](/uk/tools/skills-config) і - [Довідник конфігурації](/uk/gateway/configuration-reference#agents-defaults-skills). + [Довідник із конфігурації](/uk/gateway/configuration-reference#agents-defaults-skills). - + Керуйте тим, наскільки агресивно gateway перезапускає канали, які виглядають неактивними: ```json5 @@ -273,15 +274,15 @@ JSON. } ``` - - Встановіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски монітора стану. - - `channelStaleEventThresholdMinutes` має бути більшим або дорівнювати інтервалу перевірки. - - Використовуйте `channels..healthMonitor.enabled` або `channels..accounts..healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу чи облікового запису без вимкнення глобального монітора. - - Див. [Health Checks](/uk/gateway/health) для операційної діагностики та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів. + - Встановіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски монітору стану. + - `channelStaleEventThresholdMinutes` має бути більшим або рівним інтервалу перевірки. + - Використовуйте `channels..healthMonitor.enabled` або `channels..accounts..healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу або облікового запису без вимкнення глобального моніторингу. + - Див. [Health Checks](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів. - - Сесії керують безперервністю розмови та ізоляцією: + + Сеанси керують безперервністю розмови та ізоляцією: ```json5 { @@ -302,14 +303,14 @@ JSON. ``` - `dmScope`: `main` (спільний) | `per-peer` | `per-channel-peer` | `per-account-channel-peer` - - `threadBindings`: глобальні значення за замовчуванням для маршрутизації сесій, прив’язаних до потоків (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`). - - Див. [Керування сесіями](/uk/concepts/session) щодо області дії, зв’язків ідентичностей і політики надсилання. + - `threadBindings`: глобальні значення за замовчуванням для маршрутизації сеансів, прив’язаних до гілок (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`). + - Див. [Керування сеансами](/uk/concepts/session) щодо області видимості, зв’язків ідентичності та політики надсилання. - Див. [повний довідник](/uk/gateway/configuration-reference#session) для всіх полів. - Запускайте сесії агентів в ізольованих середовищах sandbox: + Запускайте сеанси агента в ізольованих середовищах sandbox: ```json5 { @@ -326,14 +327,14 @@ JSON. Спочатку зберіть образ: `scripts/sandbox-setup.sh` - Див. [Ізоляція](/uk/gateway/sandboxing) для повного посібника і [повний довідник](/uk/gateway/configuration-reference#agentsdefaultssandbox) для всіх параметрів. + Див. [Sandboxing](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/configuration-reference#agentsdefaultssandbox) для всіх параметрів. Push через relay налаштовується в `openclaw.json`. - Вкажіть це в конфігурації gateway: + Установіть це в конфігурації gateway: ```json5 { @@ -342,7 +343,7 @@ JSON. apns: { relay: { baseUrl: "https://relay.example.com", - // Необов’язково. Типове значення: 10000 + // Необов’язково. Типово: 10000 timeoutMs: 10000, }, }, @@ -359,35 +360,35 @@ JSON. Що це робить: - - Дозволяє gateway надсилати `push.test`, сигнали пробудження та пробудження для повторного підключення через зовнішній relay. - - Використовує дозвіл на надсилання в межах реєстрації, який пересилається спареним застосунком iOS. Gateway не потребує relay-токена для всього розгортання. - - Прив’язує кожну реєстрацію через relay до ідентичності gateway, з якою було спарено застосунок iOS, тому інший gateway не може повторно використати збережену реєстрацію. - - Залишає локальні/ручні збірки iOS на прямих APNs. Надсилання через relay застосовується лише до офіційно поширюваних збірок, що зареєстровані через relay. + - Дозволяє gateway надсилати `push.test`, сигнали пробудження та сигнали повторного підключення через зовнішній relay. + - Використовує грант надсилання в межах реєстрації, який пересилає спарений застосунок iOS. Gateway не потрібен токен relay для всього розгортання. + - Прив’язує кожну реєстрацію через relay до ідентичності gateway, з якою був спарений застосунок iOS, тому інший gateway не може повторно використати збережену реєстрацію. + - Залишає локальні/ручні збірки iOS на прямому APNs. Надсилання через relay застосовується лише до офіційних розповсюджуваних збірок, які зареєструвалися через relay. - Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації та надсилання потрапляв до того самого розгортання relay. Наскрізний процес: 1. Установіть офіційну/TestFlight збірку iOS, скомпільовану з тим самим базовим URL relay. - 2. Налаштуйте `gateway.push.apns.relay.baseUrl` на gateway. - 3. Спарте застосунок iOS з gateway і дочекайтеся підключення обох сесій: Node та операторської. - 4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує payload `push.apns.register` через relay на спарений gateway. - 5. Gateway зберігає дескриптор relay і дозвіл на надсилання, а потім використовує їх для `push.test`, сигналів пробудження та пробуджень для повторного підключення. + 2. Налаштуйте `gateway.push.apns.relay.baseUrl` у gateway. + 3. Спарте застосунок iOS із gateway і дозвольте підключитися сеансам node та оператора. + 4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує корисне навантаження `push.apns.register` через relay до спареного gateway. + 5. Gateway зберігає дескриптор relay і грант надсилання, а потім використовує їх для `push.test`, сигналів пробудження та повторного підключення. Операційні примітки: - - Якщо ви перемикаєте застосунок iOS на інший gateway, перепідключіть застосунок, щоб він міг опублікувати нову реєстрацію relay, прив’язану до цього gateway. - - Якщо ви випускаєте нову збірку iOS, яка вказує на інше розгортання relay, застосунок оновлює свій кешований запис реєстрації relay замість повторного використання старого джерела relay. + - Якщо ви перемкнете застосунок iOS на інший gateway, повторно підключіть застосунок, щоб він міг опублікувати нову реєстрацію relay, прив’язану до цього gateway. + - Якщо ви випустите нову збірку iOS, яка вказує на інше розгортання relay, застосунок оновить кешовану реєстрацію relay замість повторного використання старого джерела relay. Примітка щодо сумісності: - - `OPENCLAW_APNS_RELAY_BASE_URL` і `OPENCLAW_APNS_RELAY_TIMEOUT_MS` все ще працюють як тимчасові перевизначення через env. - - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається запасним варіантом для розробки лише в loopback; не зберігайте HTTP URL relay у конфігурації. + - `OPENCLAW_APNS_RELAY_BASE_URL` і `OPENCLAW_APNS_RELAY_TIMEOUT_MS` усе ще працюють як тимчасові перевизначення через env. + - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається аварійним варіантом для розробки лише на loopback; не зберігайте URL relay з HTTP у конфігурації. - Див. [iOS App](/uk/platforms/ios#relay-backed-push-for-official-builds) для наскрізного процесу та [Authentication and trust flow](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay. + Див. [застосунок iOS](/uk/platforms/ios#relay-backed-push-for-official-builds) для наскрізного процесу та [Потік автентифікації й довіри](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay. - + ```json5 { agents: { @@ -403,12 +404,12 @@ JSON. - `every`: рядок тривалості (`30m`, `2h`). Установіть `0m`, щоб вимкнути. - `target`: `last` | `none` | `` (наприклад, `discord`, `matrix`, `telegram` або `whatsapp`) - - `directPolicy`: `allow` (типово) або `block` для цілей Heartbeat у стилі DM + - `directPolicy`: `allow` (типово) або `block` для цілей Heartbeat у стилі особистих повідомлень - Див. [Heartbeat](/uk/gateway/heartbeat) для повного посібника. - + ```json5 { cron: { @@ -423,14 +424,14 @@ JSON. } ``` - - `sessionRetention`: очищає завершені ізольовані сесії запуску з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути). - - `runLog`: очищає `cron/runs/.jsonl` за розміром і кількістю збережених рядків. - - Див. [Завдання Cron](/uk/automation/cron-jobs) для огляду функції та прикладів CLI. + - `sessionRetention`: видаляти завершені ізольовані сеанси запуску з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути). + - `runLog`: очищати `cron/runs/.jsonl` за розміром і кількістю рядків, що зберігаються. + - Див. [Cron jobs](/uk/automation/cron-jobs) для огляду можливостей і прикладів CLI. - - Увімкніть HTTP-ендпоїнти Webhook на Gateway: + + Увімкніть HTTP-ендпоїнти Webhook у Gateway: ```json5 { @@ -454,20 +455,20 @@ JSON. ``` Примітка щодо безпеки: - - Увесь вміст payload hook/webhook слід вважати недовіреним введенням. - - Використовуйте окремий `hooks.token`; не використовуйте спільний токен Gateway повторно. - - Автентифікація hook виконується лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в рядку запиту відхиляються. - - `hooks.path` не може бути `/`; використовуйте для вхідних webhook окремий підшлях, наприклад `/hooks`. - - Не вмикайте прапорці обходу небезпечного вмісту (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте вузькоспрямоване налагодження. - - Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити вибір ключів сесії з боку викликача. - - Для агентів, керованих hook, віддавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс sandboxing, де це можливо). + - Вважайте весь вміст корисного навантаження hook/Webhook недовіреним вводом. + - Використовуйте окремий `hooks.token`; не використовуйте повторно спільний токен Gateway. + - Автентифікація hook працює лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в рядку запиту відхиляються. + - `hooks.path` не може бути `/`; залишайте вхід Webhook на окремому підшляху, наприклад `/hooks`. + - Залишайте прапорці обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте вузькоспеціалізоване налагодження. + - Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також установіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити ключі сеансів, які може вибирати викликач. + - Для агентів, керованих через hook, надавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс sandboxing, де це можливо). Див. [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів зіставлення та інтеграції Gmail. - Запускайте кількох ізольованих агентів з окремими робочими просторами та сесіями: + Запускайте кілька ізольованих агентів з окремими робочими просторами та сеансами: ```json5 { @@ -502,12 +503,12 @@ JSON. } ``` - - **Один файл**: замінює об’єкт, що містить його - - **Масив файлів**: об’єднується deep-merge за порядком (пізніші мають пріоритет) - - **Сусідні ключі**: об’єднуються після includes (перевизначають включені значення) - - **Вкладені includes**: підтримуються до 10 рівнів вкладеності - - **Відносні шляхи**: обчислюються відносно файлу, що включає - - **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок розбору та циклічних includes + - **Один файл**: замінює об’єкт, у якому міститься + - **Масив файлів**: об’єднується через deep-merge у вказаному порядку (пізніші мають пріоритет) + - **Сусідні ключі**: об’єднуються після include (перевизначають включені значення) + - **Вкладені include**: підтримуються до 10 рівнів вкладеності + - **Відносні шляхи**: обчислюються відносно файла, який включає + - **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу та циклічних include @@ -516,27 +517,27 @@ JSON. Gateway відстежує `~/.openclaw/openclaw.json` і автоматично застосовує зміни — для більшості налаштувань ручний перезапуск не потрібен. -Прямі редагування файлу вважаються недовіреними, доки не пройдуть валідацію. Спостерігач чекає, -поки вщухне тимчасовий запис/перейменування з боку редактора, читає остаточний файл і відхиляє -некоректні зовнішні редагування, відновлюючи останню відому справну конфігурацію. Записи конфігурації, -виконані самим OpenClaw, проходять ту саму перевірку схеми перед записом; руйнівні перезаписи, +Прямі зміни файлу вважаються недовіреними, доки не пройдуть валідацію. Спостерігач чекає, +поки завершаться тимчасові записи/перейменування редактора, читає остаточний файл і відхиляє +недійсні зовнішні зміни, відновлюючи останню коректну конфігурацію. Записи конфігурації, +виконані самим OpenClaw, використовують ту саму схему перевірки перед записом; руйнівні перезаписи, наприклад видалення `gateway.mode` або зменшення файлу більш ніж удвічі, відхиляються і зберігаються як `.rejected.*` для перевірки. -Якщо ви бачите в журналах `Config auto-restored from last-known-good` або -`config reload restored last-known-good config`, перевірте відповідний файл -`.clobbered.*` поруч із `openclaw.json`, виправте відхилений payload, а потім виконайте -`openclaw config validate`. Див. [усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config) +Якщо ви бачите `Config auto-restored from last-known-good` або +`config reload restored last-known-good config` у журналах, перегляньте відповідний +файл `.clobbered.*` поруч із `openclaw.json`, виправте відхилене корисне навантаження, а потім виконайте +`openclaw config validate`. Див. [Усунення проблем Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config) для контрольного списку відновлення. ### Режими перезавантаження | Режим | Поведінка | | ---------------------- | ---------------------------------------------------------------------------------------- | -| **`hybrid`** (типово) | Безпечно застосовує зміни гарячим способом миттєво. Автоматично перезапускається для критичних змін. | -| **`hot`** | Гарячим способом застосовує лише безпечні зміни. Записує попередження, коли потрібен перезапуск — ви виконуєте його самі. | -| **`restart`** | Перезапускає Gateway за будь-якої зміни конфігурації, безпечної чи ні. | -| **`off`** | Вимикає відстеження файлу. Зміни набудуть чинності під час наступного ручного перезапуску. | +| **`hybrid`** (типово) | Миттєво гаряче застосовує безпечні зміни. Автоматично перезапускається для критичних. | +| **`hot`** | Гаряче застосовує лише безпечні зміни. Логує попередження, коли потрібен перезапуск — ви обробляєте це самі. | +| **`restart`** | Перезапускає Gateway при будь-якій зміні конфігурації, безпечній чи ні. | +| **`off`** | Вимикає відстеження файлу. Зміни набувають чинності при наступному ручному перезапуску. | ```json5 { @@ -546,46 +547,46 @@ Gateway відстежує `~/.openclaw/openclaw.json` і автоматично } ``` -### Що застосовується гарячим способом, а що потребує перезапуску +### Що застосовується гаряче, а що потребує перезапуску -Більшість полів застосовуються гарячим способом без простою. У режимі `hybrid` зміни, що потребують перезапуску, обробляються автоматично. +Більшість полів застосовуються гаряче без простою. У режимі `hybrid` зміни, що потребують перезапуску, обробляються автоматично. | Категорія | Поля | Потрібен перезапуск? | | ------------------ | ----------------------------------------------------------------- | -------------------- | | Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані канали та канали Plugin | Ні | | Агент і моделі | `agent`, `agents`, `models`, `routing` | Ні | | Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні | -| Сесії та повідомлення | `session`, `messages` | Ні | -| Інструменти та медіа | `tools`, `browser`, `skills`, `audio`, `talk` | Ні | +| Сеанси й повідомлення | `session`, `messages` | Ні | +| Інструменти й медіа | `tools`, `browser`, `skills`, `audio`, `talk` | Ні | | UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні | | Сервер Gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Так** | | Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** | -`gateway.reload` і `gateway.remote` є винятками — їх зміна **не** спричиняє перезапуск. +`gateway.reload` і `gateway.remote` — винятки: їхня зміна **не** спричиняє перезапуск. ## Config RPC (програмні оновлення) -RPC керувальної площини для запису (`config.apply`, `config.patch`, `update.run`) мають обмеження частоти: **3 запити за 60 секунд** для кожної пари `deviceId+clientIp`. Якщо ліміт перевищено, RPC повертає `UNAVAILABLE` з `retryAfterMs`. +RPC control plane для запису (`config.apply`, `config.patch`, `update.run`) мають обмеження швидкості: **3 запити за 60 секунд** на `deviceId+clientIp`. При спрацюванні обмеження RPC повертає `UNAVAILABLE` з `retryAfterMs`. Безпечний/типовий процес: -- `config.schema.lookup`: перевірити одне піддерево конфігурації для заданого шляху з неглибоким - вузлом схеми, відповідними метаданими підказок і стислими описами безпосередніх дочірніх елементів +- `config.schema.lookup`: перевірити одне піддерево конфігурації, обмежене шляхом, з поверхневим + вузлом схеми, відповідними метаданими підказок і підсумками безпосередніх дочірніх елементів - `config.get`: отримати поточний знімок + хеш -- `config.patch`: бажаний шлях для часткового оновлення +- `config.patch`: бажаний шлях часткового оновлення - `config.apply`: лише повна заміна конфігурації - `update.run`: явне самооновлення + перезапуск -Якщо ви не замінюєте всю конфігурацію, віддавайте перевагу `config.schema.lookup`, +Коли ви не замінюєте всю конфігурацію, надавайте перевагу `config.schema.lookup`, а потім `config.patch`. - Перевіряє, записує повну конфігурацію та перезапускає Gateway за один крок. + Перевіряє + записує повну конфігурацію та перезапускає Gateway за один крок. `config.apply` замінює **всю конфігурацію**. Використовуйте `config.patch` для часткових оновлень або `openclaw config set` для окремих ключів. @@ -593,13 +594,13 @@ RPC керувальної площини для запису (`config.apply`, ` Параметри: - - `raw` (string) — payload JSON5 для всієї конфігурації - - `baseHash` (необов’язково) — хеш конфігурації з `config.get` (обов’язковий, якщо конфігурація існує) - - `sessionKey` (необов’язково) — ключ сесії для сигналу пробудження після перезапуску - - `note` (необов’язково) — примітка для маркера перезапуску - - `restartDelayMs` (необов’язково) — затримка перед перезапуском (типово 2000) + - `raw` (string) — корисне навантаження JSON5 для всієї конфігурації + - `baseHash` (optional) — хеш конфігурації з `config.get` (обов’язковий, якщо конфігурація існує) + - `sessionKey` (optional) — ключ сеансу для ping пробудження після перезапуску + - `note` (optional) — примітка для sentinel перезапуску + - `restartDelayMs` (optional) — затримка перед перезапуском (типово 2000) - Запити на перезапуск об’єднуються, якщо один уже очікує або виконується, а між циклами перезапуску діє 30-секундна пауза. + Запити на перезапуск об’єднуються, якщо один уже очікує/виконується, і між циклами перезапуску діє 30-секундний період охолодження. ```bash openclaw gateway call config.get --params '{}' # capture payload.hash @@ -621,11 +622,11 @@ RPC керувальної площини для запису (`config.apply`, ` Параметри: - - `raw` (string) — JSON5 лише з тими ключами, які потрібно змінити - - `baseHash` (обов’язково) — хеш конфігурації з `config.get` - - `sessionKey`, `note`, `restartDelayMs` — ті самі, що й у `config.apply` + - `raw` (string) — JSON5 лише з ключами, які потрібно змінити + - `baseHash` (required) — хеш конфігурації з `config.get` + - `sessionKey`, `note`, `restartDelayMs` — такі самі, як у `config.apply` - Поведінка перезапуску збігається з `config.apply`: об’єднання очікуваних перезапусків плюс 30-секундна пауза між циклами перезапуску. + Поведінка перезапуску збігається з `config.apply`: об’єднання відкладених перезапусків і 30-секундний період охолодження між циклами перезапуску. ```bash openclaw gateway call config.patch --params '{ @@ -639,12 +640,12 @@ RPC керувальної площини для запису (`config.apply`, ` ## Змінні середовища -OpenClaw зчитує змінні середовища з батьківського процесу, а також з: +OpenClaw читає змінні середовища з батьківського процесу, а також з: -- `.env` з поточного робочого каталогу (якщо є) +- `.env` у поточному робочому каталозі (якщо є) - `~/.openclaw/.env` (глобальний резервний варіант) -Жоден із цих файлів не перевизначає наявні змінні середовища. Ви також можете задавати вбудовані змінні середовища в конфігурації: +Жоден із цих файлів не перевизначає вже наявні змінні середовища. Ви також можете встановлювати вбудовані змінні середовища в конфігурації: ```json5 { @@ -656,7 +657,7 @@ OpenClaw зчитує змінні середовища з батьківськ ``` - Якщо цю функцію ввімкнено й очікувані ключі не задано, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі: + Якщо це ввімкнено й очікувані ключі не встановлені, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі: ```json5 { @@ -666,7 +667,7 @@ OpenClaw зчитує змінні середовища з батьківськ } ``` -Еквівалент змінної середовища: `OPENCLAW_LOAD_SHELL_ENV=1` +Еквівалент через env var: `OPENCLAW_LOAD_SHELL_ENV=1` @@ -681,16 +682,16 @@ OpenClaw зчитує змінні середовища з батьківськ Правила: -- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*` -- Відсутні/порожні змінні викликають помилку під час завантаження -- Використовуйте `$${VAR}` для виведення літерала +- Збігаються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*` +- Відсутні/порожні змінні спричиняють помилку під час завантаження +- Екрануйте через `$${VAR}` для буквального виводу - Працює всередині файлів `$include` - Вбудована підстановка: `"${BASE}/v1"` → `"https://api.example.com/v1"` - Для полів, які підтримують об’єкти SecretRef, можна використовувати: + Для полів, що підтримують об’єкти SecretRef, можна використовувати: ```json5 { @@ -723,15 +724,15 @@ OpenClaw зчитує змінні середовища з батьківськ ``` Докладніше про SecretRef (включно з `secrets.providers` для `env`/`file`/`exec`) див. у [Керування секретами](/uk/gateway/secrets). -Підтримувані шляхи облікових даних наведено в [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface). +Підтримувані шляхи облікових даних перелічено в [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface). -Див. [Середовище](/uk/help/environment) для повного опису пріоритетів і джерел. +Див. [Середовище](/uk/help/environment) для повного порядку пріоритетів і джерел. ## Повний довідник -Повний довідник для кожного поля див. в **[Довіднику конфігурації](/uk/gateway/configuration-reference)**. +Повний довідник по полях див. у **[Довідник із конфігурації](/uk/gateway/configuration-reference)**. --- -_Пов’язане: [Приклади конфігурації](/uk/gateway/configuration-examples) · [Довідник конфігурації](/uk/gateway/configuration-reference) · [Doctor](/uk/gateway/doctor)_ +_Пов’язане: [Приклади конфігурації](/uk/gateway/configuration-examples) · [Довідник із конфігурації](/uk/gateway/configuration-reference) · [Doctor](/uk/gateway/doctor)_