diff --git a/docs/uk/gateway/config-agents.md b/docs/uk/gateway/config-agents.md index d3b5905b5..72a7c5eac 100644 --- a/docs/uk/gateway/config-agents.md +++ b/docs/uk/gateway/config-agents.md @@ -1,24 +1,24 @@ --- read_when: - Налаштування типових параметрів агента (моделі, thinking, робочий простір, Heartbeat, медіа, Skills) - - Налаштування маршрутизації та прив’язок між кількома агентами - - Налаштування сесії, доставки повідомлень і поведінки режиму talk -summary: Типові налаштування агента, маршрутизація між кількома агентами, сесія, повідомлення та конфігурація talk + - Налаштування маршрутизації між кількома агентами та прив’язок + - Налаштування сеансу, доставки повідомлень і поведінки режиму talk +summary: Типові параметри агента, маршрутизація між кількома агентами, сеанс, повідомлення та конфігурація talk title: Конфігурація — агенти x-i18n: - generated_at: "2026-04-25T03:44:16Z" + generated_at: "2026-04-25T06:22:38Z" model: gpt-5.4 provider: openai - source_hash: 7f90c51056f82494f893eaab9e3d2acf509c05096e5a1f64b33611ca34125c2b + source_hash: a3a67914120f567c1d0e4740a320cd285c21ddeb05cbffbec1b9c6ea1e950a6e source_path: gateway/config-agents.md workflow: 15 --- -Ключі конфігурації в межах агента під `agents.*`, `multiAgent.*`, `session.*`, +Ключі конфігурації з областю дії агента в `agents.*`, `multiAgent.*`, `session.*`, `messages.*` і `talk.*`. Для каналів, інструментів, середовища виконання Gateway та інших -ключів верхнього рівня див. [Довідник з конфігурації](/uk/gateway/configuration-reference). +ключів верхнього рівня див. [Довідник із конфігурації](/uk/gateway/configuration-reference). -## Типові налаштування агента +## Типові параметри агента ### `agents.defaults.workspace` @@ -32,7 +32,7 @@ x-i18n: ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, який показується в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, підіймаючись угору від робочого простору. +Необов’язковий корінь репозиторію, який показується в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, піднімаючись вгору від робочого простору. ```json5 { @@ -58,9 +58,9 @@ x-i18n: } ``` -- Опустіть `agents.defaults.skills`, щоб типово дозволити необмежені Skills. -- Опустіть `agents.list[].skills`, щоб успадкувати типові значення. -- Укажіть `agents.list[].skills: []`, щоб не було Skills. +- Не вказуйте `agents.defaults.skills`, якщо типово потрібні необмежені Skills. +- Не вказуйте `agents.list[].skills`, щоб успадкувати типові значення. +- Установіть `agents.list[].skills: []`, щоб вимкнути всі Skills. - Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він не об’єднується з типовими значеннями. @@ -76,9 +76,10 @@ x-i18n: ### `agents.defaults.contextInjection` -Керує тим, коли bootstrap-файли робочого простору вбудовуються в системний запит. Типове значення: `"always"`. +Керує тим, коли bootstrap-файли робочого простору додаються до системного запиту. Типове значення: `"always"`. -- `"continuation-skip"`: у безпечних ходах продовження (після завершеної відповіді асистента) повторне вбудовування bootstrap-даних робочого простору пропускається, що зменшує розмір запиту. Запуски Heartbeat і повторні спроби після Compaction все одно перебудовують контекст. +- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне додавання bootstrap-контексту робочого простору, що зменшує розмір запиту. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст. +- `"never"`: вимикає додавання bootstrap-файлів робочого простору та файлів контексту на кожному ході. Використовуйте це лише для агентів, які повністю керують життєвим циклом свого запиту (власні рушії контексту, нативні середовища виконання, що самі будують контекст, або спеціалізовані робочі процеси без bootstrap). Ходи Heartbeat і відновлення після compaction також пропускають додавання. ```json5 { @@ -88,7 +89,7 @@ x-i18n: ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів для кожного bootstrap-файлу робочого простору перед обрізанням. Типове значення: `12000`. +Максимальна кількість символів на bootstrap-файл робочого простору до обрізання. Типове значення: `12000`. ```json5 { @@ -98,7 +99,7 @@ x-i18n: ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що вбудовується з усіх bootstrap-файлів робочого простору. Типове значення: `60000`. +Максимальна загальна кількість символів, що додаються з усіх bootstrap-файлів робочого простору. Типове значення: `60000`. ```json5 { @@ -108,12 +109,12 @@ x-i18n: ### `agents.defaults.bootstrapPromptTruncationWarning` -Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається. +Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізано. Типове значення: `"once"`. -- `"off"`: ніколи не вбудовувати текст попередження в системний запит. -- `"once"`: вбудовувати попередження один раз для кожного унікального підпису обрізання (рекомендовано). -- `"always"`: вбудовувати попередження під час кожного запуску, якщо є обрізання. +- `"off"`: ніколи не додає текст попередження до системного запиту. +- `"once"`: додає попередження один раз для кожного унікального сигнатурного випадку обрізання (рекомендовано). +- `"always"`: додає попередження під час кожного запуску, якщо є обрізання. ```json5 { @@ -121,34 +122,34 @@ x-i18n: } ``` -### Карта володіння бюджетами контексту +### Карта відповідальності за бюджет контексту -В OpenClaw є кілька об’ємних бюджетів запиту/контексту, і вони -навмисно розділені між підсистемами, а не зведені до одного загального -параметра. +OpenClaw має кілька високонавантажених бюджетів запиту/контексту, і вони +навмисно розділені за підсистемами, замість того щоб проходити через один +універсальний параметр. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - звичайне вбудовування bootstrap-даних робочого простору. + звичайне додавання bootstrap-контексту робочого простору. - `agents.defaults.startupContext.*`: - одноразова стартова преамбула для `/new` і `/reset`, включно з недавніми - файлами `memory/*.md` за день. + одноразова вступна частина запуску `/new` і `/reset`, включно з нещодавніми + щоденними файлами `memory/*.md`. - `skills.limits.*`: - стиснений список Skills, вбудований у системний запит. + компактний список Skills, що додається до системного запиту. - `agents.defaults.contextLimits.*`: - обмежені витяги середовища виконання та вбудовані блоки, якими володіє runtime. + обмежені витяги середовища виконання та додані блоки, якими володіє середовище виконання. - `memory.qmd.limits.*`: - розмір фрагментів індексованого пошуку по пам’яті та їх вбудовування. + фрагмент індексованого пошуку пам’яті та розмір додавання. -Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший -бюджет: +Використовуйте відповідне перевизначення для конкретного агента лише тоді, коли +одному агенту потрібен інший бюджет: - `agents.list[].skillsLimits.maxSkillsPromptChars` - `agents.list[].contextLimits.*` #### `agents.defaults.startupContext` -Керує стартовою преамбулою першого ходу, яка вбудовується в порожні запуски `/new` і `/reset`. +Керує вступною частиною першого ходу, яка додається під час простих запусків `/new` і `/reset`. ```json5 { @@ -186,18 +187,18 @@ x-i18n: } ``` -- `memoryGetMaxChars`: типовий ліміт витягу `memory_get` перед додаванням - метаданих обрізання та повідомлення про продовження. -- `memoryGetDefaultLines`: типове вікно рядків `memory_get`, коли `lines` - пропущено. -- `toolResultMaxChars`: ліміт результату інструмента в реальному часі, що використовується для збережених результатів і +- `memoryGetMaxChars`: типовий ліміт витягу `memory_get` до додавання метаданих + обрізання та повідомлення про продовження. +- `memoryGetDefaultLines`: типове вікно рядків для `memory_get`, якщо `lines` + не вказано. +- `toolResultMaxChars`: ліміт результату інструмента в реальному часі, який використовується для збережених результатів і відновлення після переповнення. -- `postCompactionMaxChars`: ліміт витягу `AGENTS.md`, що використовується під час вбудовування +- `postCompactionMaxChars`: ліміт витягу AGENTS.md, що використовується під час додавання оновлення після Compaction. #### `agents.list[].contextLimits` -Перевизначення для окремого агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються +Перевизначення для конкретного агента для спільних параметрів `contextLimits`. Не вказані поля успадковуються з `agents.defaults.contextLimits`. ```json5 @@ -224,8 +225,8 @@ x-i18n: #### `skills.limits.maxSkillsPromptChars` -Глобальний ліміт для стисненого списку Skills, вбудованого в системний запит. Це -не впливає на читання файлів `SKILL.md` за потреби. +Глобальний ліміт для компактного списку Skills, що додається до системного запиту. Це +не впливає на читання файлів `SKILL.md` на вимогу. ```json5 { @@ -239,7 +240,7 @@ x-i18n: #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Перевизначення бюджету запиту Skills для окремого агента. +Перевизначення бюджету запиту для Skills для конкретного агента. ```json5 { @@ -261,7 +262,7 @@ x-i18n: Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень транскрипту/інструментів перед викликами провайдера. Типове значення: `1200`. -Менші значення зазвичай зменшують використання vision-токенів і розмір тіла запиту для сценаріїв із великою кількістю знімків екрана. +Менші значення зазвичай зменшують використання vision-токенів і розмір корисного навантаження запиту для сценаріїв із великою кількістю знімків екрана. Більші значення зберігають більше візуальних деталей. ```json5 @@ -272,7 +273,7 @@ x-i18n: ### `agents.defaults.userTimezone` -Часовий пояс для контексту системного запиту (не для часових позначок повідомлень). Якщо не задано, використовується часовий пояс хоста. +Часовий пояс для контексту системного запиту (не для часових міток повідомлень). Якщо не вказано, використовується часовий пояс хоста. ```json5 { @@ -322,7 +323,7 @@ x-i18n: }, params: { cacheRetention: "long" }, // глобальні типові параметри провайдера embeddedHarness: { - runtime: "pi", // pi | auto | registered harness id, e.g. codex + runtime: "pi", // pi | auto | ідентифікатор зареєстрованого harness, наприклад codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -340,52 +341,52 @@ x-i18n: ``` - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Рядкова форма задає лише основну модель. - - Об’єктна форма задає основну модель і впорядкований список моделей для перемикання при збої. + - Форма рядка задає лише основну модель. + - Форма об’єкта задає основну модель і впорядкований список резервних моделей. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується шляхом інструмента `image` як конфігурація його vision-моделі. - - Також використовується для резервної маршрутизації, коли вибрана/типова модель не може приймати вхідні зображення. + - Також використовується як маршрут резервного вибору, коли вибрана/типова модель не може приймати вхідні зображення. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/Plugin, що генерує зображення. - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-2` для OpenAI Images. - Якщо ви напряму вибираєте `provider/model`, також налаштуйте відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2`, `FAL_KEY` для `fal/*`). - - Якщо значення пропущено, `image_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку `provider-id`. + - Якщо не вказано, `image_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації музики і вбудованим інструментом `music_generate`. + - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`. - - Якщо значення пропущено, `music_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку `provider-id`. - - Якщо ви напряму вибираєте `provider/model`, також налаштуйте відповідну автентифікацію провайдера/API-ключ. + - Якщо не вказано, `music_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів. + - Якщо ви напряму вибираєте `provider/model`, також налаштуйте відповідну автентифікацію/API-ключ провайдера. - `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації відео і вбудованим інструментом `video_generate`. + - Використовується спільною можливістю генерації відео та вбудованим інструментом `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-ключ. - - Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. + - Якщо не вказано, `video_generate` усе одно може визначити типове значення провайдера з налаштованою автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів. + - Якщо ви напряму вибираєте `provider/model`, також налаштуйте відповідну автентифікацію/API-ключ провайдера. + - Вбудований провайдер генерації відео 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` для доступу за API-ключем або `openai-codex/gpt-5.5` для Codex OAuth). Якщо провайдера не вказано, OpenClaw спочатку пробує псевдонім, потім унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише після цього повертається до налаштованого типового провайдера (застаріла сумісна поведінка, тому краще вказувати явний `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення видаленого провайдера. -- `models`: налаштований каталог моделей і список дозволених значень для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера параметри, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `extra_body`/`extraBody`). - - Безпечні зміни: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відмовляється від замін, які видалили б наявні записи зі списку дозволених, якщо ви не передасте `--replace`. - - Потоки налаштування/онбордингу на рівні провайдера об’єднують вибрані моделі провайдера в цю мапу і зберігають уже налаштованих, не пов’язаних із цим, провайдерів. +- `elevatedDefault`: типовий рівень розширеного виводу для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`. +- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4` для доступу через API-ключ або `openai-codex/gpt-5.5` для Codex OAuth). Якщо опустити провайдера, OpenClaw спочатку пробує псевдонім, потім унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише після цього повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повертається до першого налаштованого провайдера/моделі замість показу застарілого типового значення видаленого провайдера. +- `models`: налаштований каталог моделей і список дозволених значень для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `extra_body`/`extraBody`). + - Безпечне редагування: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відмовляється від замін, які видалили б наявні записи списку дозволених значень, якщо не передати `--replace`. + - Потоки configure/onboarding з областю дії провайдера об’єднують вибрані моделі провайдера в цю мапу й зберігають уже налаштованих не пов’язаних провайдерів. - Для прямих моделей OpenAI Responses автоматично вмикається серверний Compaction. Використовуйте `params.responsesServerCompaction: false`, щоб припинити додавання `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Див. [Серверний Compaction OpenAI](/uk/providers/openai#server-side-compaction-responses-api). - `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`). -- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається через `agents.defaults.models["provider/model"].params` (для окремої моделі), а потім `agents.list[].params` (для відповідного `agent id`) перевизначає за ключем. Докладніше див. [Кешування запитів](/uk/reference/prompt-caching). -- `params.extra_body`/`params.extraBody`: розширений JSON для наскрізної передачі, який зливається з тілами запитів `api: "openai-completions"` для OpenAI-сумісних проксі. Якщо він конфліктує зі згенерованими ключами запиту, перемагає додаткове тіло; не нативні маршрути completions після цього все одно видаляють OpenAI-специфічний `store`. -- `embeddedHarness`: типова політика низькорівневого середовища виконання вбудованого агента. Якщо `runtime` пропущено, типово використовується OpenClaw Pi. Використовуйте `runtime: "pi"`, щоб примусово ввімкнути вбудований harness PI, `runtime: "auto"`, щоб дозволити зареєстрованим harness-ам Plugin перехоплювати підтримувані моделі, або ідентифікатор зареєстрованого harness-а, наприклад `runtime: "codex"`. Укажіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. Явні runtime-и Plugin, такі як `codex`, типово працюють у режимі fail closed, якщо в тій самій області перевизначення не задано `fallback: "pi"`. Зберігайте посилання на моделі в канонічному форматі `provider/model`; вибирайте Codex, Claude CLI, Gemini CLI та інші бекенди виконання через конфігурацію runtime, а не через застарілі префікси runtime-провайдера. Див. [Середовища виконання агента](/uk/concepts/agent-runtimes), щоб зрозуміти, чим це відрізняється від вибору провайдера/моделі. -- Записувачі конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення резервних варіантів), зберігають канонічну форму об’єкта і, коли можливо, зберігають наявні списки резервних моделей. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізована). Типове значення: 4. +- Пріоритет об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для моделі), потім `agents.list[].params` (відповідний `id` агента) перевизначає за ключем. Подробиці див. у [Кешування запитів](/uk/reference/prompt-caching). +- `params.extra_body`/`params.extraBody`: розширений JSON прямої передачі, що об’єднується з тілами запитів `api: "openai-completions"` для OpenAI-сумісних проксі. Якщо він конфліктує зі згенерованими ключами запиту, додаткове тіло має пріоритет; після цього не нативні маршрути completions усе одно прибирають специфічний для OpenAI параметр `store`. +- `embeddedHarness`: типова політика низькорівневого середовища виконання вбудованого агента. Якщо `runtime` не вказано, типовим є OpenClaw Pi. Використовуйте `runtime: "pi"`, щоб примусово вибрати вбудований harness PI, `runtime: "auto"`, щоб дозволити зареєстрованим Plugin harness перехоплювати підтримувані моделі, або зареєстрований ідентифікатор harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід на PI. Явні середовища виконання Plugin, як-от `codex`, типово завершуються із забороною, якщо в тій самій області перевизначення не встановити `fallback: "pi"`. Використовуйте канонічний формат посилань на моделі `provider/model`; вибирайте Codex, Claude CLI, Gemini CLI та інші бекенди виконання через конфігурацію середовища виконання, а не через застарілі префікси провайдерів середовища виконання. Див. [Середовища виконання агента](/uk/concepts/agent-runtimes), щоб зрозуміти, чим це відрізняється від вибору провайдера/моделі. +- Засоби запису конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення резервних значень), зберігають канонічну форму об’єкта й за можливості зберігають наявні списки резервних значень. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів у межах сеансів (кожен сеанс усе одно серіалізовано). Типове значення: 4. ### `agents.defaults.embeddedHarness` `embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента. -У більшості розгортань слід залишити типове середовище виконання OpenClaw Pi. +Більшість розгортань мають залишати типове середовище виконання OpenClaw Pi. Використовуйте це, коли довірений Plugin надає нативний harness, наприклад вбудований -harness сервера застосунку Codex. Для концептуальної моделі див. +harness сервера застосунку Codex. Для розуміння моделі див. [Середовища виконання агента](/uk/concepts/agent-runtimes). ```json5 @@ -402,14 +403,14 @@ harness сервера застосунку Codex. Для концептуаль } ``` -- `runtime`: `"auto"`, `"pi"` або ідентифікатор зареєстрованого harness-а Plugin. Вбудований Plugin Codex реєструє `codex`. -- `fallback`: `"pi"` або `"none"`. У режимі `runtime: "auto"` пропущений `fallback` типово дорівнює `"pi"`, щоб старі конфігурації могли й далі використовувати PI, коли жоден harness Plugin не перехоплює запуск. У режимі явного runtime Plugin, наприклад `runtime: "codex"`, пропущений `fallback` типово дорівнює `"none"`, тому відсутній harness спричиняє збій замість тихого використання PI. Перевизначення runtime не успадковують `fallback` із ширшої області; задайте `fallback: "pi"` разом з явним runtime, коли вам свідомо потрібна така сумісність. Помилки вибраного harness-а Plugin завжди показуються безпосередньо. +- `runtime`: `"auto"`, `"pi"` або ідентифікатор зареєстрованого Plugin harness. Вбудований Plugin Codex реєструє `codex`. +- `fallback`: `"pi"` або `"none"`. У режимі `runtime: "auto"` пропущене резервне значення типово дорівнює `"pi"`, щоб старі конфігурації могли й далі використовувати PI, коли жоден Plugin harness не перехоплює запуск. У режимі явного середовища виконання Plugin, наприклад `runtime: "codex"`, пропущене резервне значення типово дорівнює `"none"`, щоб відсутній harness призводив до помилки замість тихого використання PI. Перевизначення середовища виконання не успадковують `fallback` із ширшої області; задайте `fallback: "pi"` разом з явним `runtime`, коли навмисно хочете таку сумісність. Помилки вибраного Plugin harness завжди показуються напряму. - Перевизначення через змінні середовища: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` перевизначає `fallback` для цього процесу. -- Для розгортань лише з Codex задайте `model: "openai/gpt-5.5"` і `embeddedHarness.runtime: "codex"`. Ви також можете явно задати `embeddedHarness.fallback: "none"` для наочності; це типове значення для явних runtime-ів Plugin. -- Вибір harness-а фіксується для кожного `session id` після першого вбудованого запуску. Зміни конфігурації/оточення впливають на нові або скинуті сесії, а не на наявний транскрипт. Застарілі сесії з історією транскрипту, але без записаної фіксації, трактуються як прив’язані до PI. `/status` показує ефективний runtime, наприклад `Runtime: OpenClaw Pi Default` або `Runtime: OpenAI Codex`. -- Це керує лише вбудованим chat harness. Генерація медіа, vision, PDF, музика, відео і TTS, як і раніше, використовують свої налаштування провайдера/моделі. +- Для розгортань лише з Codex установіть `model: "openai/gpt-5.5"` і `embeddedHarness.runtime: "codex"`. Ви також можете явно встановити `embeddedHarness.fallback: "none"` для читабельності; це типове значення для явних середовищ виконання Plugin. +- Вибір harness фіксується для кожного `session id` після першого вбудованого запуску. Зміни конфігурації/змінних середовища впливають на нові або скинуті сеанси, але не на наявний транскрипт. Застарілі сеанси з історією транскрипту, але без записаної фіксації, вважаються прив’язаними до PI. `/status` показує фактичне середовище виконання, наприклад `Runtime: OpenClaw Pi Default` або `Runtime: OpenAI Codex`. +- Це керує лише вбудованим chat harness. Генерація медіа, vision, PDF, музика, відео та TTS і далі використовують свої налаштування провайдера/моделі. -**Вбудовані скорочені псевдоніми** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): +**Вбудовані скорочення-псевдоніми** (застосовуються лише коли модель є в `agents.defaults.models`): | Псевдонім | Модель | | ------------------- | -------------------------------------------------- | @@ -424,13 +425,13 @@ harness сервера застосунку Codex. Для концептуаль Ваші налаштовані псевдоніми завжди мають пріоритет над типовими. -Для моделей 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 не задано. +Для моделей Z.AI GLM-4.x автоматично вмикається режим thinking, якщо ви не встановите `--thinking off` або самі не визначите `agents.defaults.models["zai/"].params.thinking`. +Для моделей Z.AI за замовчуванням увімкнено `tool_stream` для потокової передачі викликів інструментів. Установіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути його. +Для моделей Anthropic Claude 4.6 типово використовується thinking `adaptive`, якщо не задано явний рівень thinking. ### `agents.defaults.cliBackends` -Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як резервний варіант, коли API-провайдери не працюють. +Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють. ```json5 { @@ -459,12 +460,12 @@ harness сервера застосунку Codex. Для концептуаль ``` - CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені. -- Сесії підтримуються, коли задано `sessionArg`. -- Наскрізна передача зображень підтримується, коли `imageArg` приймає шляхи до файлів. +- Сеанси підтримуються, якщо задано `sessionArg`. +- Передача зображень підтримується, якщо `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` -Замінює весь системний запит, зібраний OpenClaw, на фіксований рядок. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами. +Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для конкретного агента (`agents.list[].systemPromptOverride`). Значення для конкретного агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами. ```json5 { @@ -478,7 +479,7 @@ harness сервера застосунку Codex. Для концептуаль ### `agents.defaults.promptOverlays` -Незалежні від провайдера накладки запиту, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки між провайдерами; `personality` керує лише шаром дружнього стилю взаємодії. +Незалежні від провайдера накладки запитів, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки між провайдерами; `personality` керує лише шаром дружнього стилю взаємодії. ```json5 { @@ -495,8 +496,8 @@ harness сервера застосунку Codex. Для концептуаль ``` - `"friendly"` (типове значення) і `"on"` вмикають шар дружнього стилю взаємодії. -- `"off"` вимикає лише дружній шар; позначений контракт поведінки GPT-5 залишається ввімкненим. -- Застаріле `plugins.entries.openai.config.personality` усе ще зчитується, коли цей спільний параметр не задано. +- `"off"` вимикає лише дружній шар; позначений контракт поведінки GPT-5 залишається увімкненим. +- Застаріле `plugins.entries.openai.config.personality` усе ще зчитується, якщо цей спільний параметр не задано. ### `agents.defaults.heartbeat` @@ -510,9 +511,9 @@ harness сервера застосунку Codex. Для концептуаль every: "30m", // 0m вимикає model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // типове значення: true; false пропускає розділ Heartbeat у системному запиті - lightContext: false, // типове значення: false; true залишає лише HEARTBEAT.md із bootstrap-файлів робочого простору - isolatedSession: false, // типове значення: false; true запускає кожен heartbeat у новій сесії (без історії розмови) + includeSystemPromptSection: true, // типове значення: true; false прибирає розділ Heartbeat із системного запиту + lightContext: false, // типове значення: false; true залишає лише HEARTBEAT.md з bootstrap-файлів робочого простору + isolatedSession: false, // типове значення: false; true запускає кожен heartbeat у новому сеансі (без історії розмови) session: "main", to: "+15555550123", directPolicy: "allow", // allow (типово) | block @@ -527,15 +528,15 @@ harness сервера застосунку Codex. Для концептуаль } ``` -- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація за API-ключем) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути. -- `includeSystemPromptSection`: коли `false`, пропускає розділ Heartbeat у системному запиті й не вбудовує `HEARTBEAT.md` у bootstrap-контекст. Типове значення: `true`. -- `suppressToolErrorWarnings`: коли `true`, пригнічує корисне навантаження попереджень про помилки інструментів під час запусків heartbeat. -- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента heartbeat, після чого його буде перервано. Якщо не задано, використовується `agents.defaults.timeoutSeconds`. -- `directPolicy`: політика доставки напряму/у DM. `allow` (типово) дозволяє доставку до прямої цілі. `block` пригнічує доставку до прямої цілі й генерує `reason=dm-blocked`. -- `lightContext`: коли `true`, запуски heartbeat використовують полегшений bootstrap-контекст і залишають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору. -- `isolatedSession`: коли `true`, кожен heartbeat запускається в новій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один heartbeat приблизно зі ~100K до ~2-5K токенів. -- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, heartbeat запускаються **лише для цих агентів**. -- Heartbeat виконують повні ходи агента — коротші інтервали витрачають більше токенів. +- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація API-ключем) або `1h` (автентифікація OAuth). Установіть `0m`, щоб вимкнути. +- `includeSystemPromptSection`: якщо `false`, прибирає розділ Heartbeat із системного запиту та пропускає додавання `HEARTBEAT.md` до bootstrap-контексту. Типове значення: `true`. +- `suppressToolErrorWarnings`: якщо `true`, пригнічує корисні навантаження попереджень про помилки інструментів під час запусків Heartbeat. +- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента Heartbeat, після чого його буде перервано. Якщо не задано, використовується `agents.defaults.timeoutSeconds`. +- `directPolicy`: політика доставки напряму/в DM. `allow` (типово) дозволяє доставку безпосередньо цілі. `block` пригнічує доставку безпосередньо цілі та видає `reason=dm-blocked`. +- `lightContext`: якщо `true`, запуски Heartbeat використовують полегшений bootstrap-контекст і залишають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору. +- `isolatedSession`: якщо `true`, кожен Heartbeat запускається в новому сеансі без попередньої історії розмови. Такий самий шаблон ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує вартість токенів на один Heartbeat приблизно зі ~100K до ~2-5K токенів. +- Для конкретного агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, **запуски Heartbeat виконуються лише для цих агентів**. +- Heartbeat виконує повні ходи агента — коротші інтервали спалюють більше токенів. ### `agents.defaults.compaction` @@ -552,9 +553,9 @@ harness сервера застосунку Codex. Для концептуаль identifierPolicy: "strict", // strict | off | custom identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // використовується, коли identifierPolicy=custom qualityGuard: { enabled: true, maxRetries: 1 }, - postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне вбудовування + postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне додавання model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для compaction - notifyUser: true, // надсилати короткі сповіщення користувачу, коли compaction починається і завершується (типове значення: false) + notifyUser: true, // надсилати короткі сповіщення користувачу, коли compaction починається й завершується (типове значення: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -567,21 +568,21 @@ harness сервера застосунку Codex. Для концептуаль } ``` -- `mode`: `default` або `safeguard` (підсумовування частинами для довгої історії). Див. [Compaction](/uk/concepts/compaction). -- `provider`: id зареєстрованого Plugin провайдера compaction. Якщо задано, замість вбудованого LLM-підсумовування викликається `summarize()` цього провайдера. У разі збою відбувається повернення до вбудованого варіанта. Установлення провайдера примусово задає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). +- `mode`: `default` або `safeguard` (підсумовування довгих історій частинами). Див. [Compaction](/uk/concepts/compaction). +- `provider`: `id` зареєстрованого Plugin провайдера compaction. Якщо задано, замість вбудованого підсумовування LLM викликається `summarize()` провайдера. У разі помилки повертається до вбудованого варіанта. Установлення провайдера примусово вмикає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). - `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції compaction, після чого OpenClaw її перериває. Типове значення: `900`. -- `keepRecentTokens`: бюджет точки відсікання Pi для збереження найсвіжішого хвоста транскрипту дослівно. Ручний `/compact` враховує це, коли значення явно задано; інакше ручний compaction є жорсткою контрольною точкою. +- `keepRecentTokens`: бюджет точки зрізу Pi для буквального збереження найновішого хвоста транскрипту. Ручний `/compact` враховує це, коли значення явно задано; інакше ручний compaction є жорсткою контрольною точкою. - `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування compaction. -- `identifierInstructions`: необов’язковий власний текст про збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. -- `qualityGuard`: перевірки із повторною спробою для неправильно сформованого виводу в підсумках safeguard. Увімкнено типово в режимі safeguard; задайте `enabled: false`, щоб пропустити перевірку. -- `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 для збереження довготривалої пам’яті. Пропускається, якщо робочий простір доступний лише для читання. +- `identifierInstructions`: необов’язковий власний текст для збереження ідентифікаторів, що використовується, коли `identifierPolicy=custom`. +- `qualityGuard`: перевірки з повторною спробою при некоректному виводі для підсумків safeguard. Типово ввімкнено в режимі safeguard; установіть `enabled: false`, щоб пропустити аудит. +- `postCompactionSections`: необов’язкові назви розділів AGENTS.md рівня H2/H3 для повторного додавання після compaction. Типове значення: `["Session Startup", "Red Lines"]`; установіть `[]`, щоб вимкнути повторне додавання. Якщо параметр не задано або явно встановлено цю типову пару, старіші заголовки `Every Session`/`Safety` також приймаються як застарілий резервний варіант. +- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування compaction. Використовуйте це, коли основний сеанс має залишатися на одній моделі, а підсумки compaction мають працювати на іншій; якщо не задано, compaction використовує основну модель сеансу. +- `notifyUser`: якщо `true`, надсилає користувачу короткі сповіщення, коли compaction починається і коли він завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб compaction залишався безшумним. +- `memoryFlush`: тихий агентний хід перед автоматичним compaction для збереження довготривалих спогадів. Пропускається, якщо робочий простір доступний лише для читання. ### `agents.defaults.contextPruning` -Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. +Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сеансу на диску. ```json5 { @@ -589,7 +590,7 @@ harness сервера застосунку Codex. Для концептуаль defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // тривалість (ms/s/m/h), одиниця типово: хвилини + ttl: "1h", // тривалість (ms/s/m/h), типова одиниця: хвилини keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -606,22 +607,22 @@ harness сервера застосунку Codex. Для концептуаль - `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього оновлення кешу). -- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім, за потреби, повністю очищує старіші результати інструментів. +- `ttl` визначає, як часто обрізання можна запускати знову (після останнього торкання кешу). +- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім за потреби повністю очищає старіші результати інструментів. **М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині. -**Повне очищення** замінює весь результат інструмента заповнювачем. +**Повне очищення** замінює весь результат інструмента на заповнювач. Примітки: -- Блоки зображень ніколи не обрізаються й не очищуються. -- Співвідношення базуються на кількості символів (приблизно), а не на точних кількостях токенів. -- Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається. +- Блоки зображень ніколи не обрізаються і не очищаються. +- Співвідношення обчислюються за символами (приблизно), а не за точною кількістю токенів. +- Якщо повідомлень асистента менше, ніж `keepLastAssistants`, обрізання пропускається. -Докладніше про поведінку див. [Обрізання сесії](/uk/concepts/session-pruning). +Подробиці поведінки див. у [Обрізання сеансів](/uk/concepts/session-pruning). ### Потокова передача блоками @@ -639,13 +640,13 @@ harness сервера застосунку Codex. Для концептуаль } ``` -- Для каналів, відмінних від Telegram, щоб увімкнути відповіді блоками, потрібно явно задати `*.blockStreaming: true`. -- Перевизначення для каналів: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типове значення `minChars: 1500`. -- `humanDelay`: випадкова пауза між відповідями блоками. `natural` = 800–2500 мс. Перевизначення для окремого агента: `agents.list[].humanDelay`. +- Для каналів, відмінних від Telegram, щоб увімкнути блокові відповіді, потрібно явно вказати `*.blockStreaming: true`. +- Перевизначення для каналів: `channels..blockStreamingCoalesce` (і варіанти для конкретного облікового запису). Для Signal/Slack/Discord/Google Chat типове значення `minChars: 1500`. +- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500 мс. Перевизначення для конкретного агента: `agents.list[].humanDelay`. -Докладніше про поведінку та розбиття на частини див. [Потокова передача](/uk/concepts/streaming). +Подробиці поведінки й розбиття на частини див. у [Потокова передача](/uk/concepts/streaming). -### Індикатори набору +### Індикатори набору тексту ```json5 { @@ -659,15 +660,15 @@ harness сервера застосунку Codex. Для концептуаль ``` - Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. -- Перевизначення на рівні сесії: `session.typingMode`, `session.typingIntervalSeconds`. +- Перевизначення для конкретного сеансу: `session.typingMode`, `session.typingIntervalSeconds`. -Див. [Індикатори набору](/uk/concepts/typing-indicators). +Див. [Індикатори набору тексту](/uk/concepts/typing-indicators). ### `agents.defaults.sandbox` -Необов’язкова ізоляція для вбудованого агента. Повний посібник див. у [Ізоляція](/uk/gateway/sandboxing). +Необов’язкова ізоляція sandbox для вбудованого агента. Повний посібник див. у [Ізоляція sandbox](/uk/gateway/sandboxing). ```json5 { @@ -770,44 +771,44 @@ harness сервера застосунку Codex. Для концептуаль - `ssh`: універсальне віддалене середовище виконання на основі SSH - `openshell`: середовище виконання OpenShell -Коли вибрано `backend: "openshell"`, специфічні для середовища виконання налаштування переносяться до +Коли вибрано `backend: "openshell"`, налаштування, специфічні для середовища виконання, переносяться до `plugins.entries.openshell.config`. **Конфігурація SSH-бекенда:** - `target`: ціль SSH у форматі `user@host[:port]` - `command`: команда клієнта SSH (типове значення: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів відповідно до області видимості -- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, передані до OpenSSH +- `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів за областю дії +- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, які передаються в OpenSSH - `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRefs, які OpenClaw матеріалізує у тимчасові файли під час виконання -- `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH +- `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хостів OpenSSH -**Пріоритет автентифікації SSH:** +**Пріоритет SSH-автентифікації:** - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data` на основі SecretRef визначаються з активного знімка середовища виконання secrets до початку сесії sandbox +- Значення `*Data`, що спираються на SecretRef, визначаються з активного знімка середовища виконання секретів до початку сеансу sandbox **Поведінка SSH-бекенда:** - один раз ініціалізує віддалений робочий простір після створення або повторного створення -- далі підтримує віддалений робочий простір SSH як канонічний -- маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH -- не синхронізує віддалені зміни назад на хост автоматично +- потім зберігає віддалений робочий простір SSH як канонічний +- маршрутизує `exec`, файлові інструменти та шляхи до медіа через SSH +- не синхронізує автоматично віддалені зміни назад на хост - не підтримує браузерні контейнери sandbox **Доступ до робочого простору:** -- `none`: робочий простір sandbox відповідно до області видимості в `~/.openclaw/sandboxes` -- `ro`: робочий простір sandbox у `/workspace`, робочий простір агента змонтовано лише для читання в `/agent` -- `rw`: робочий простір агента змонтовано для читання й запису в `/workspace` +- `none`: робочий простір sandbox за областю дії в `~/.openclaw/sandboxes` +- `ro`: робочий простір sandbox у `/workspace`, робочий простір агента монтується лише для читання в `/agent` +- `rw`: робочий простір агента монтується для читання й запису в `/workspace` -**Область видимості:** +**Область дії:** -- `session`: окремий контейнер + робочий простір для кожної сесії -- `agent`: один контейнер + робочий простір для кожного агента (типово) -- `shared`: спільний контейнер і робочий простір (без ізоляції між сесіями) +- `session`: окремий контейнер і робочий простір для кожного сеансу +- `agent`: один контейнер і робочий простір для кожного агента (типово) +- `shared`: спільний контейнер і робочий простір (без ізоляції між сеансами) **Конфігурація Plugin OpenShell:** @@ -837,30 +838,30 @@ harness сервера застосунку Codex. Для концептуаль **Режим OpenShell:** -- `mirror`: ініціалізує віддалений простір із локального перед `exec`, синхронізує назад після `exec`; локальний робочий простір залишається канонічним -- `remote`: один раз ініціалізує віддалений простір під час створення sandbox, після чого віддалений робочий простір залишається канонічним +- `mirror`: перед `exec` ініціалізує віддалене середовище з локального, після `exec` синхронізує назад; локальний робочий простір залишається канонічним +- `remote`: один раз ініціалізує віддалене середовище, коли створюється sandbox, а потім зберігає віддалений робочий простір як канонічний -У режимі `remote` зміни на локальному хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку ініціалізації. -Транспортом є SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією. +У режимі `remote` зміни на локальному хості, зроблені поза OpenClaw, не синхронізуються автоматично до sandbox після кроку ініціалізації. +Транспортом є SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою синхронізацією mirror. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного мережевого доступу, доступного для запису кореня та користувача root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, записуваного кореня та користувача root. -**Контейнери типово мають `network: "none"`** — установіть `"bridge"` (або користувацьку bridge-мережу), якщо агенту потрібен вихідний доступ. +**Для контейнерів типово використовується `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. `"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний режим). +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний обхід). -**Вхідні вкладення** розміщуються у `media/inbound/*` в активному робочому просторі. +**Вхідні вкладення** розміщуються в `media/inbound/*` в активному робочому просторі. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремого агента об’єднуються. +**`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 додається до системного запиту. Не потребує `browser.enabled` у `openclaw.json`. +Доступ спостерігача noVNC типово використовує автентифікацію VNC, і OpenClaw видає URL із короткоживучим токеном (замість розкриття пароля у спільному URL). -- `allowHostControl: false` (типово) блокує для сесій sandbox націлювання на браузер хоста. -- `network` типово дорівнює `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна зв’язність bridge. +- `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` і налаштовані для контейнерних хостів: +- `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` @@ -880,28 +881,28 @@ harness сервера застосунку Codex. Для концептуаль - `--disable-extensions` (типово ввімкнено) - `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu` типово ввімкнені, і їх можна вимкнути через - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо цього потребує використання WebGL/3D. + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо для використання WebGL/3D це потрібно. - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш робочий процес залежить від них. - `--renderer-process-limit=2` можна змінити через `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати - типовий ліміт процесів Chromium. + типове обмеження кількості процесів Chromium. - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. - - Типові значення є базовими для образу контейнера; використовуйте власний образ браузера з власною - точкою входу, щоб змінити типові параметри контейнера. + - Типові значення — це базова конфігурація образу контейнера; використовуйте власний образ браузера з власною + entrypoint, щоб змінити типові параметри контейнера. -Ізоляція браузера та `sandbox.docker.binds` доступні лише для Docker. +Ізоляція браузера та `sandbox.docker.binds` підтримуються лише для Docker. -Збірка образів: +Зібрати образи: ```bash scripts/sandbox-setup.sh # основний образ sandbox scripts/sandbox-browser-setup.sh # необов’язковий образ браузера ``` -### `agents.list` (перевизначення для окремого агента) +### `agents.list` (перевизначення для конкретного агента) ```json5 { @@ -914,11 +915,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // або { primary, fallbacks } - thinkingDefault: "high", // перевизначення рівня thinking для окремого агента - reasoningDefault: "on", // перевизначення видимості reasoning для окремого агента - fastModeDefault: false, // перевизначення швидкого режиму для окремого агента + thinkingDefault: "high", // перевизначення рівня thinking для конкретного агента + reasoningDefault: "on", // перевизначення видимості reasoning для конкретного агента + fastModeDefault: false, // перевизначення fast mode для конкретного агента embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // перевизначає відповідні defaults.models params за ключем + params: { cacheRetention: "none" }, // перевизначає за ключем відповідні params у defaults.models skills: ["docs-search"], // замінює agents.defaults.skills, якщо задано identity: { name: "Samantha", @@ -950,27 +951,27 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `id`: стабільний id агента (обов’язково). -- `default`: коли встановлено кілька, перший має пріоритет (записується попередження). Якщо не встановлено жодного, типовим є перший елемент списку. -- `model`: рядкова форма перевизначає лише `primary`; об’єктна форма `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні резервні варіанти). Завдання Cron, які перевизначають лише `primary`, усе одно успадковують типові резервні варіанти, якщо ви не задасте `fallbacks: []`. -- `params`: параметри потоку для окремого агента, що зливаються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень на рівні агента, таких як `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. -- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо пропущено, агент успадковує `agents.defaults.skills`, якщо той задано; явний список замінює типові значення, а не зливається з ними, а `[]` означає відсутність Skills. -- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення для окремого повідомлення або сесії. Вибраний профіль провайдера/моделі керує тим, які значення є припустимими; для Google Gemini значення `adaptive` зберігає динамічний thinking, керований провайдером (`thinkingLevel` пропущено на Gemini 3/3.1, `thinkingBudget: -1` на Gemini 2.5). -- `reasoningDefault`: необов’язкове типове значення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для окремого повідомлення або сесії. -- `fastModeDefault`: необов’язкове типове значення швидкого режиму для окремого агента (`true | false`). Застосовується, коли не задано перевизначення fast-mode для окремого повідомлення або сесії. -- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex" }`, щоб зробити один агент лише Codex, тоді як інші агенти зберігатимуть типовий резервний PI у режимі `auto`. -- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` разом із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сесії harness ACP. +- `id`: стабільний ідентифікатор агента (обов’язково). +- `default`: якщо задано для кількох агентів, перемагає перший (записується попередження). Якщо не задано ні для кого, типовим стає перший запис у списку. +- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні резервні значення). Завдання Cron, які перевизначають лише `primary`, усе одно успадковують типові `fallbacks`, якщо не встановити `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` для цього агента, коли не встановлено перевизначення для конкретного повідомлення або сеансу. Вибраний профіль провайдера/моделі визначає, які значення припустимі; для Google Gemini `adaptive` зберігає динамічний thinking, яким керує провайдер (`thinkingLevel` не передається в Gemini 3/3.1, `thinkingBudget: -1` у Gemini 2.5). +- `reasoningDefault`: необов’язкове типове значення видимості reasoning для конкретного агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для конкретного повідомлення або сеансу. +- `fastModeDefault`: необов’язкове типове значення fast mode для конкретного агента (`true | false`). Застосовується, коли не задано перевизначення fast mode для конкретного повідомлення або сеансу. +- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для конкретного агента. Використовуйте `{ runtime: "codex" }`, щоб зробити один агент лише Codex, тоді як інші агенти зберігатимуть типовий резервний PI у режимі `auto`. +- `runtime`: необов’язковий дескриптор середовища виконання для конкретного агента. Використовуйте `type: "acp"` разом із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово працювати в сеансах ACP harness. - `identity.avatar`: шлях відносно робочого простору, URL `http(s)` або URI `data:`. -- `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. -- `subagents.allowAgents`: список дозволених id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). -- Захист успадкування sandbox: якщо сесія ініціатора працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. -- `subagents.requireAgentId`: коли `true`, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типове значення: false). +- `identity` виводить типові значення: `ackReaction` із `emoji`, `mentionPatterns` із `name`/`emoji`. +- `subagents.allowAgents`: список дозволених ідентифікаторів агентів для `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 { @@ -987,29 +988,29 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -### Поля збігу прив’язки +### Поля відповідності прив’язок -- `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` (необов’язково; залежить від каналу) -- `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }` +- `match.guildId` / `match.teamId` (необов’язково; специфічно для каналу) +- `acp` (необов’язково; лише для `type: "acp"`): `{ mode, label, cwd, backend }` -**Детермінований порядок збігу:** +**Детермінований порядок відповідності:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (точний збіг, без peer/guild/team) -5. `match.accountId: "*"` (для всього каналу) +5. `match.accountId: "*"` (на рівні каналу) 6. Типовий агент -У межах кожного рівня перемагає перший відповідний запис `bindings`. +У межах кожного рівня перемагає перший відповідний запис у `bindings`. -Для записів `type: "acp"` OpenClaw визначає збіг за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує порядок рівнів route-прив’язок, наведений вище. +Для записів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів прив’язки маршруту. -### Профілі доступу для окремого агента +### Профілі доступу для конкретного агента @@ -1104,11 +1105,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б -Детальніше про пріоритети див. [Sandbox і інструменти Multi-Agent](/uk/tools/multi-agent-sandbox-tools). +Подробиці пріоритетів див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). --- -## Сесія +## Сеанс ```json5 { @@ -1130,7 +1131,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // пропускати відгалуження від батьківської гілки вище цього ліміту токенів (0 вимикає) + parentForkMaxTokens: 100000, // пропускати відгалуження від батьківського потоку вище за цю кількість токенів (0 вимикає) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", @@ -1142,10 +1143,10 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б }, threadBindings: { enabled: true, - idleHours: 24, // типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає) - maxAgeHours: 0, // типовий жорсткий максимальний вік у годинах (`0` вимикає) + idleHours: 24, // типове автоматичне зняття фокуса після бездіяльності в годинах (`0` вимикає) + maxAgeHours: 0, // типове жорстке максимальне обмеження віку в годинах (`0` вимикає) }, - mainKey: "main", // застаріле поле (runtime завжди використовує "main") + mainKey: "main", // застаріле (runtime завжди використовує "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1155,37 +1156,37 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` - + -- **`scope`**: базова стратегія групування сесій для контекстів групового чату. - - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу. - - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли потрібен спільний контекст). +- **`scope`**: базова стратегія групування сеансів для контекстів групових чатів. + - `per-sender` (типово): кожен відправник отримує ізольований сеанс у межах контексту каналу. + - `global`: усі учасники в контексті каналу спільно використовують один сеанс (використовуйте лише тоді, коли потрібен спільний контекст). - **`dmScope`**: як групуються DM. - - `main`: усі DM використовують спільну головну сесію. - - `per-peer`: ізоляція за id відправника між каналами. - - `per-channel-peer`: ізоляція для кожної пари канал + відправник (рекомендовано для багатокористувацьких inbox). + - `main`: усі DM використовують спільний основний сеанс. + - `per-peer`: ізоляція за ідентифікатором відправника між каналами. + - `per-channel-peer`: ізоляція для кожної пари канал + відправник (рекомендовано для вхідних скриньок із кількома користувачами). - `per-account-channel-peer`: ізоляція для кожної пари обліковий запис + канал + відправник (рекомендовано для кількох облікових записів). -- **`identityLinks`**: мапа канонічних id до peer із префіксом провайдера для спільного використання сесії між каналами. -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва параметри, спрацьовує той, що завершується раніше. +- **`identityLinks`**: мапа канонічних ідентифікаторів на peers із префіксами провайдерів для спільного використання сеансів між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, перемагає той варіант, що спливає раніше. - **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`. -- **`parentForkMaxTokens`**: максимальна кількість `totalTokens` у батьківській сесії, дозволена під час створення розгалуженої сесії потоку (типове значення `100000`). - - Якщо значення `totalTokens` у батьківській сесії вище за це, OpenClaw запускає нову сесію потоку замість успадкування історії транскрипту батьківської сесії. - - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти відгалуження від батьківської сесії. -- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для головного кошика прямого чату. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів відповіді між агентами під час обміну агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжок ping-pong. -- **`sendPolicy`**: збіг за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перший deny має пріоритет. -- **`maintenance`**: очищення сховища сесій + керування строками зберігання. - - `mode`: `warn` лише генерує попередження; `enforce` застосовує очищення. - - `pruneAfter`: граничний вік для застарілих записів (типове значення `30d`). +- **`parentForkMaxTokens`**: максимальна кількість `totalTokens` у батьківському сеансі, дозволена під час створення відгалуженого сеансу потоку (типове значення `100000`). + - Якщо `totalTokens` батьківського сеансу перевищує це значення, OpenClaw запускає новий сеанс потоку замість успадкування історії транскрипту батьківського сеансу. + - Установіть `0`, щоб вимкнути цей запобіжник і завжди дозволяти відгалуження від батьківського сеансу. +- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного кошика прямих чатів. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість ходів зворотної відповіді між агентами під час обміну агент-до-агента (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжки ping-pong. +- **`sendPolicy`**: відповідність за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. +- **`maintenance`**: очищення сховища сеансів і керування зберіганням. + - `mode`: `warn` лише виводить попередження; `enforce` застосовує очищення. + - `pruneAfter`: поріг віку для застарілих записів (типове значення `30d`). - `maxEntries`: максимальна кількість записів у `sessions.json` (типове значення `500`). - - `rotateBytes`: ротує `sessions.json`, коли він перевищує цей розмір (типове значення `10mb`). - - `resetArchiveRetention`: строк зберігання архівів транскриптів `*.reset.`. Типово дорівнює `pruneAfter`; задайте `false`, щоб вимкнути. - - `maxDiskBytes`: необов’язковий бюджет дискового простору для каталогу сесій. У режимі `warn` він записує попередження в журнал; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. - - `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово дорівнює `80%` від `maxDiskBytes`. -- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до потоків. + - `rotateBytes`: ротує `sessions.json`, коли його розмір перевищує це значення (типове значення `10mb`). + - `resetArchiveRetention`: термін зберігання архівів транскриптів `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий бюджет місця на диску для каталогу сеансів. У режимі `warn` лише записує попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сеанси. + - `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово `80%` від `maxDiskBytes`. +- **`threadBindings`**: глобальні типові значення для функцій сеансів, прив’язаних до потоків. - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає; провайдери можуть перевизначати) - - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати) + - `idleHours`: типове автоматичне зняття фокуса після бездіяльності в годинах (`0` вимикає; провайдери можуть перевизначати) + - `maxAgeHours`: типове жорстке максимальне обмеження віку в годинах (`0` вимикає; провайдери можуть перевизначати) @@ -1225,34 +1226,34 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Визначення значення (найконкретніше має пріоритет): обліковий запис → канал → глобальне. `""` вимикає і зупиняє каскадування. `"auto"` виводить `[{identity.name}]`. +Визначення (перемагає найспецифічніше): обліковий запис → канал → глобальне значення. `""` вимикає і зупиняє каскад. `"auto"` виводить `[{identity.name}]`. -**Змінні шаблону:** +**Шаблонні змінні:** -| Змінна | Опис | Приклад | -| ----------------- | ------------------------ | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | -| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва провайдера | `anthropic` | -| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Назва identity агента | (те саме, що `"auto"`) | +| Змінна | Опис | Приклад | +| ----------------- | ---------------------------- | --------------------------- | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | +| `{provider}` | Назва провайдера | `anthropic` | +| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | +| `{identity.name}` | Ім’я ідентичності агента | (те саме, що й `"auto"`) | -Змінні нечутливі до регістру. `{think}` є псевдонімом для `{thinkingLevel}`. +Змінні нечутливі до регістру. `{think}` — це псевдонім для `{thinkingLevel}`. ### Реакція підтвердження -- Типово береться з `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. +- Типово дорівнює `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. - Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення з identity. +- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення identity. - Область дії: `group-mentions` (типово), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: видаляє підтвердження після відповіді в Slack, Discord і Telegram. +- `removeAckAfterReply`: прибирає реакцію підтвердження після відповіді в Slack, Discord і Telegram. - `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram. У Slack і Discord, якщо значення не задано, реакції статусу залишаються ввімкненими, коли активні реакції підтвердження. - У Telegram задайте це явно як `true`, щоб увімкнути реакції статусу життєвого циклу. + У Telegram, щоб увімкнути реакції статусу життєвого циклу, явно встановіть `true`. ### Debounce для вхідних повідомлень -Об’єднує швидкі вхідні текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Команди керування оминають debounce. +Об’єднує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення скидаються негайно. Команди керування оминають debounce. ### TTS (перетворення тексту на мовлення) @@ -1302,11 +1303,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `auto` керує типовим режимом автоматичного TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні налаштування, а `/tts status` показує ефективний стан. +- `auto` керує типовим режимом автоматичного TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначити локальні налаштування, а `/tts status` показує фактичний стан. - `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку. -- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (увімкнення за згодою). -- API-ключі резервно беруться з `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. -- Вбудовані провайдери мовлення належать Plugin. Якщо задано `plugins.allow`, включіть кожен Plugin провайдера TTS, який ви хочете використовувати, наприклад `microsoft` для Edge TTS. Застарілий id провайдера `edge` приймається як псевдонім для `microsoft`. +- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (явне ввімкнення). +- Для API-ключів використовуються резервні значення `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. +- Вбудовані мовленнєві провайдери належать Plugin. Якщо задано `plugins.allow`, включіть кожен Plugin провайдера TTS, який хочете використовувати, наприклад `microsoft` для Edge TTS. Застарілий ідентифікатор провайдера `edge` приймається як псевдонім для `microsoft`. - `providers.openai.baseUrl` перевизначає кінцеву точку OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. - Коли `providers.openai.baseUrl` вказує на кінцеву точку, відмінну від OpenAI, OpenClaw розглядає її як OpenAI-сумісний TTS-сервер і послаблює перевірку моделі/голосу. @@ -1314,7 +1315,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ## Talk -Типові налаштування для режиму Talk (macOS/iOS/Android). +Типові значення для режиму Talk (macOS/iOS/Android). ```json5 { @@ -1338,18 +1339,18 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька провайдерів Talk. -- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) використовуються лише для сумісності й автоматично мігруються в `talk.providers.`. -- Ідентифікатори голосів резервно беруться з `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. -- `providers.*.apiKey` приймає звичайні текстові рядки або об’єкти SecretRef. -- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли ключ API для Talk не налаштовано. +- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кількох провайдерів Talk. +- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності й автоматично мігруються в `talk.providers.`. +- Для ідентифікаторів голосу використовуються резервні значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. +- `providers.*.apiKey` приймає рядки відкритого тексту або об’єкти SecretRef. +- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли API-ключ Talk не налаштовано. - `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви. -- `silenceTimeoutMs` керує тим, скільки режим Talk чекає після тиші користувача, перш ніж надіслати транскрипт. Якщо не задано, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). +- `silenceTimeoutMs` визначає, скільки часу режим Talk чекає після тиші користувача, перш ніж надіслати транскрипт. Якщо не задано, зберігається типове для платформи вікно паузи (`700 ms` на macOS і Android, `900 ms` на iOS). --- -## Пов’язані матеріали +## Пов’язане -- [Довідник з конфігурації](/uk/gateway/configuration-reference) — усі інші ключі конфігурації +- [Довідник із конфігурації](/uk/gateway/configuration-reference) — усі інші ключі конфігурації - [Конфігурація](/uk/gateway/configuration) — поширені завдання та швидке налаштування - [Приклади конфігурації](/uk/gateway/configuration-examples) diff --git a/docs/uk/install/nix.md b/docs/uk/install/nix.md index 77430c213..2e4b358cd 100644 --- a/docs/uk/install/nix.md +++ b/docs/uk/install/nix.md @@ -1,73 +1,71 @@ --- read_when: - - Вам потрібні відтворювані інсталяції з можливістю rollback + - Вам потрібні відтворювані встановлення з можливістю відкату назад - Ви вже використовуєте Nix/NixOS/Home Manager - - Ви хочете, щоб усе було закріплено та керувалося декларативно -summary: Декларативне встановлення OpenClaw за допомогою Nix + - Ви хочете, щоб усе було зафіксовано та керувалося декларативно +summary: Встановіть OpenClaw декларативно за допомогою Nix title: Nix x-i18n: - generated_at: "2026-04-05T18:08:06Z" + generated_at: "2026-04-25T06:22:40Z" model: gpt-5.4 provider: openai - source_hash: 14e1e73533db1350d82d3a786092b4328121a082dfeeedee7c7574021dada546 + source_hash: 7980e48d9fac49396d9dd06cf8516d572c97def1764db94cf66879d81d63694c source_path: install/nix.md workflow: 15 --- -# Встановлення через Nix - -Установіть OpenClaw декларативно за допомогою **[nix-openclaw](https://github.com/openclaw/nix-openclaw)** — Home Manager module з усім необхідним у комплекті. +Встановіть OpenClaw декларативно за допомогою **[nix-openclaw](https://github.com/openclaw/nix-openclaw)** — Home Manager module з усім необхідним у комплекті. -Репозиторій [nix-openclaw](https://github.com/openclaw/nix-openclaw) є джерелом істини для встановлення через Nix. Ця сторінка — короткий огляд. +Репозиторій [nix-openclaw](https://github.com/openclaw/nix-openclaw) є єдиним джерелом істини для встановлення через Nix. Ця сторінка — короткий огляд. -## Що ви отримаєте +## Що ви отримуєте -- Gateway + застосунок macOS + інструменти (whisper, spotify, cameras) — усе зафіксовано +- Gateway + застосунок для macOS + інструменти (whisper, spotify, cameras) — усе зафіксовано - Сервіс launchd, який переживає перезавантаження -- Система plugins з декларативною конфігурацією -- Миттєвий rollback: `home-manager switch --rollback` +- Система Plugin із декларативною конфігурацією +- Миттєвий відкат: `home-manager switch --rollback` ## Швидкий старт - - Якщо Nix ще не встановлено, дотримуйтеся інструкцій [інсталятора Determinate Nix](https://github.com/DeterminateSystems/nix-installer). + + Якщо Nix ще не встановлено, дотримуйтесь інструкцій [інсталятора Determinate Nix](https://github.com/DeterminateSystems/nix-installer). - Використовуйте шаблон agent-first з репозиторію nix-openclaw: + Використайте шаблон agent-first із репозиторію nix-openclaw: ```bash mkdir -p ~/code/openclaw-local - # Скопіюйте templates/agent-first/flake.nix з репозиторію nix-openclaw + # Copy templates/agent-first/flake.nix from the nix-openclaw repo ``` - Налаштуйте токен вашого бота повідомлень і API-ключ провайдера моделей. Звичайні файли в `~/.secrets/` цілком підходять. + Налаштуйте токен вашого бота для обміну повідомленнями та API-ключ постачальника моделей. Звичайні файли в `~/.secrets/` цілком підійдуть. - + ```bash home-manager switch ``` - Переконайтеся, що сервіс launchd працює і ваш бот відповідає на повідомлення. + Переконайтеся, що сервіс launchd запущений і ваш бот відповідає на повідомлення. -Повні параметри module і приклади див. в [README nix-openclaw](https://github.com/openclaw/nix-openclaw). +Дивіться [README nix-openclaw](https://github.com/openclaw/nix-openclaw), щоб отримати повний список опцій модуля та приклади. -## Поведінка runtime в режимі Nix +## Поведінка середовища виконання в режимі Nix -Коли задано `OPENCLAW_NIX_MODE=1` (автоматично з nix-openclaw), OpenClaw переходить у детермінований режим, який вимикає сценарії auto-install. +Коли встановлено `OPENCLAW_NIX_MODE=1` (автоматично з nix-openclaw), OpenClaw переходить у детермінований режим, який вимикає потоки автоматичного встановлення. -Ви також можете задати це вручну: +Ви також можете встановити це вручну: ```bash export OPENCLAW_NIX_MODE=1 ``` -У macOS GUI-застосунок не успадковує змінні середовища shell автоматично. Натомість увімкніть режим Nix через defaults: +У macOS GUI-застосунок не успадковує автоматично змінні середовища оболонки. Натомість увімкніть режим Nix через defaults: ```bash defaults write ai.openclaw.mac openclaw.nixMode -bool true @@ -75,22 +73,34 @@ defaults write ai.openclaw.mac openclaw.nixMode -bool true ### Що змінюється в режимі Nix -- Сценарії auto-install і self-mutation вимкнені -- Відсутні залежності показують повідомлення про виправлення, специфічні для Nix -- UI показує банер режиму Nix лише для читання +- Потоки автоматичного встановлення та самозміни вимкнено +- Відсутні залежності показують повідомлення про виправлення саме для Nix +- В інтерфейсі відображається банер режиму Nix лише для читання -### Шляхи до конфігурації та state +### Шляхи конфігурації та стану -OpenClaw читає конфігурацію JSON5 з `OPENCLAW_CONFIG_PATH` і зберігає змінні дані в `OPENCLAW_STATE_DIR`. Під час роботи під Nix задавайте їх явно на розташування, якими керує Nix, щоб runtime state і конфігурація не потрапляли до незмінного store. +OpenClaw читає конфігурацію JSON5 з `OPENCLAW_CONFIG_PATH` і зберігає змінні дані в `OPENCLAW_STATE_DIR`. Під час роботи під Nix установлюйте їх явно на керовані Nix розташування, щоб стан середовища виконання та конфігурація не зберігалися в незмінному сховищі. | Змінна | Типове значення | | --------------------- | --------------------------------------- | | `OPENCLAW_HOME` | `HOME` / `USERPROFILE` / `os.homedir()` | -| `OPENCLAW_STATE_DIR` | `~/.openclaw` | -| `OPENCLAW_CONFIG_PATH` | `$OPENCLAW_STATE_DIR/openclaw.json` | +| `OPENCLAW_STATE_DIR` | `~/.openclaw` | +| `OPENCLAW_CONFIG_PATH`| `$OPENCLAW_STATE_DIR/openclaw.json` | + +### Виявлення PATH сервісу + +Сервіс Gateway launchd/systemd автоматично виявляє двійкові файли профілю Nix, тож +Plugin та інструменти, які виконують виклики до виконуваних файлів, установлених через `nix`, +працюють без ручного налаштування PATH: + +- Коли встановлено `NIX_PROFILES`, кожен запис додається до PATH сервісу з + пріоритетом справа наліво (це відповідає пріоритету оболонки Nix — крайній праворуч має перевагу). +- Коли `NIX_PROFILES` не встановлено, як запасний варіант додається `~/.nix-profile/bin`. + +Це застосовується як до середовищ сервісів launchd у macOS, так і до systemd у Linux. ## Пов’язане -- [nix-openclaw](https://github.com/openclaw/nix-openclaw) -- повний посібник із налаштування -- [Wizard](/start/wizard) -- налаштування CLI без Nix -- [Docker](/install/docker) -- налаштування в контейнері +- [nix-openclaw](https://github.com/openclaw/nix-openclaw) — повний посібник із налаштування +- [Wizard](/uk/start/wizard) — налаштування CLI без Nix +- [Docker](/uk/install/docker) — налаштування в контейнері