diff --git a/docs/uk/concepts/active-memory.md b/docs/uk/concepts/active-memory.md
index bc43f1ad9..5a6d36f3c 100644
--- a/docs/uk/concepts/active-memory.md
+++ b/docs/uk/concepts/active-memory.md
@@ -1,27 +1,27 @@
---
read_when:
- Ви хочете зрозуміти, для чого потрібна Active Memory
- - Ви хочете ввімкнути Active Memory для розмовного агента
+ - Ви хочете увімкнути Active Memory для розмовного агента
- Ви хочете налаштувати поведінку Active Memory, не вмикаючи її всюди
-summary: Підлеглий агент блокувальної пам’яті, що належить Plugin, який впроваджує релевантну пам’ять в інтерактивні сеанси чату
+summary: Плагінний блокувальний під-агент пам’яті, який впроваджує релевантну пам’ять в інтерактивні сеанси чату
title: Active Memory
x-i18n:
- generated_at: "2026-04-18T19:33:21Z"
+ generated_at: "2026-04-21T06:04:48Z"
model: gpt-5.4
provider: openai
- source_hash: 30fb5d12f1f2e3845d95b90925814faa5c84240684ebd4325c01598169088432
+ source_hash: 1a41ec10a99644eda5c9f73aedb161648e0a5c9513680743ad92baa57417d9ce
source_path: concepts/active-memory.md
workflow: 15
---
# Active Memory
-Active Memory — це необов’язковий підлеглий агент блокувальної пам’яті, що належить Plugin і запускається
-перед основною відповіддю для відповідних розмовних сеансів.
+Active Memory — це необов’язковий плагінний блокувальний під-агент пам’яті, який запускається
+перед основною відповіддю для придатних розмовних сеансів.
-Він існує тому, що більшість систем пам’яті є функціональними, але реактивними. Вони покладаються на
-основного агента, який має вирішити, коли шукати в пам’яті, або на те, що користувач скаже щось
-на кшталт «запам’ятай це» чи «пошукай у пам’яті». На той момент мить, коли пам’ять
+Він існує, тому що більшість систем пам’яті є потужними, але реактивними. Вони покладаються на
+основного агента, який має вирішити, коли шукати в пам’яті, або на користувача, який має сказати щось
+на кшталт «запам’ятай це» чи «пошукай у пам’яті». До цього моменту мить, коли пам’ять
могла б зробити відповідь природною, уже минула.
Active Memory дає системі одну обмежену можливість підняти релевантну пам’ять
@@ -29,8 +29,8 @@ Active Memory дає системі одну обмежену можливіст
## Вставте це у свого агента
-Вставте це у свого агента, якщо хочете ввімкнути Active Memory із
-самодостатнім, безпечним за замовчуванням налаштуванням:
+Вставте це у свого агента, якщо хочете ввімкнути Active Memory за допомогою
+самодостатньої конфігурації з безпечними значеннями за замовчуванням:
```json5
{
@@ -56,9 +56,10 @@ Active Memory дає системі одну обмежену можливіст
}
```
-Це вмикає Plugin для агента `main`, за замовчуванням обмежує його
-сеансами у стилі прямих повідомлень, дозволяє спочатку успадковувати модель поточного сеансу
-і використовує налаштовану резервну модель лише тоді, коли явна або успадкована модель недоступна.
+Це вмикає плагін для агента `main`, за замовчуванням обмежує його сеансами
+у стилі прямих повідомлень, дозволяє спочатку успадковувати модель поточного сеансу,
+і використовує налаштовану резервну модель лише якщо немає
+ані явно заданої, ані успадкованої моделі.
Після цього перезапустіть Gateway:
@@ -66,7 +67,7 @@ Active Memory дає системі одну обмежену можливіст
openclaw gateway
```
-Щоб переглядати це наживо в розмові:
+Щоб переглянути це наживо в розмові:
```text
/verbose on
@@ -75,11 +76,11 @@ openclaw gateway
## Увімкнення active memory
-Найбезпечніше налаштування таке:
+Найбезпечніше налаштування:
-1. увімкнути Plugin
+1. увімкнути плагін
2. націлити його на одного розмовного агента
-3. залишити журналювання ввімкненим лише на час налаштування
+3. залишати журналювання увімкненим лише під час налаштування
Почніть із цього в `openclaw.json`:
@@ -114,24 +115,24 @@ openclaw gateway
Що це означає:
-- `plugins.entries.active-memory.enabled: true` вмикає Plugin
-- `config.agents: ["main"]` підключає до active memory лише агента `main`
-- `config.allowedChatTypes: ["direct"]` за замовчуванням залишає active memory увімкненою лише для сеансів у стилі прямих повідомлень
-- якщо `config.model` не задано, active memory спочатку успадковує модель поточного сеансу
-- `config.modelFallback` за бажанням задає вашу власну резервну provider/model для відновлення пам’яті
-- `config.promptStyle: "balanced"` використовує стандартний універсальний стиль prompt для режиму `recent`
-- active memory усе одно запускається лише у відповідних інтерактивних постійних чат-сеансах
+- `plugins.entries.active-memory.enabled: true` вмикає плагін
+- `config.agents: ["main"]` підключає до Active Memory лише агента `main`
+- `config.allowedChatTypes: ["direct"]` за замовчуванням залишає Active Memory увімкненим лише для сеансів у стилі прямих повідомлень
+- якщо `config.model` не задано, Active Memory спочатку успадковує модель поточного сеансу
+- `config.modelFallback` за потреби надає власну резервну модель постачальника/модель для відновлення пам’яті
+- `config.promptStyle: "balanced"` використовує типовий універсальний стиль підказки для режиму `recent`
+- Active Memory усе одно запускається лише в придатних інтерактивних постійних чат-сеансах
## Рекомендації щодо швидкодії
-Найпростіше налаштування — залишити `config.model` незаданим і дозволити Active Memory використовувати
-ту саму модель, яку ви вже використовуєте для звичайних відповідей. Це найнадійніша поведінка за замовчуванням,
-оскільки вона дотримується ваших поточних налаштувань provider, авторизації та моделі.
+Найпростіше налаштування — залишити `config.model` незаданим і дозволити Active Memory
+використовувати ту саму модель, яку ви вже використовуєте для звичайних відповідей. Це найбезпечніша типова поведінка,
+оскільки вона дотримується ваших наявних уподобань щодо постачальника, авторизації та моделі.
-Якщо ви хочете, щоб Active Memory здавалася швидшою, використовуйте виділену inference-модель
-замість запозичення основної моделі чату.
+Якщо ви хочете, щоб Active Memory працювала швидше, використовуйте виділену inference-модель
+замість запозичення основної чат-моделі.
-Приклад налаштування зі швидким provider:
+Приклад конфігурації зі швидким постачальником:
```json5
models: {
@@ -158,22 +159,22 @@ plugins: {
Варіанти швидких моделей, які варто розглянути:
-- `cerebras/gpt-oss-120b` для швидкої виділеної моделі відновлення пам’яті з вузькою поверхнею інструментів
-- ваша звичайна модель сеансу, якщо залишити `config.model` незаданим
-- низьколатентна резервна модель, така як `google/gemini-3-flash`, якщо ви хочете окрему модель відновлення пам’яті без зміни основної моделі чату
+- `cerebras/gpt-oss-120b` як швидку виділену модель відновлення пам’яті з вузькою поверхнею інструментів
+- вашу звичайну модель сеансу, якщо залишити `config.model` незаданим
+- резервну модель з низькою затримкою, таку як `google/gemini-3-flash`, якщо ви хочете окрему модель відновлення пам’яті без зміни основної чат-моделі
-Чому Cerebras є сильним варіантом, орієнтованим на швидкість, для Active Memory:
+Чому Cerebras є сильним варіантом для Active Memory, орієнтованим на швидкодію:
- поверхня інструментів Active Memory вузька: вона викликає лише `memory_search` і `memory_get`
- якість відновлення пам’яті важлива, але затримка важливіша, ніж для основного шляху відповіді
-- окремий швидкий provider дозволяє не прив’язувати затримку відновлення пам’яті до вашого основного chat provider
+- виділений швидкий постачальник дозволяє не прив’язувати затримку відновлення пам’яті до вашого основного чат-постачальника
-Якщо ви не хочете окрему оптимізовану на швидкість модель, залиште `config.model` незаданим
+Якщо вам не потрібна окрема модель, оптимізована під швидкість, залиште `config.model` незаданим
і дозвольте Active Memory успадковувати модель поточного сеансу.
### Налаштування Cerebras
-Додайте запис provider ось так:
+Додайте запис постачальника на кшталт цього:
```json5
models: {
@@ -188,7 +189,7 @@ models: {
}
```
-Потім націльте на нього Active Memory:
+Потім спрямуйте на нього Active Memory:
```json5
plugins: {
@@ -205,17 +206,17 @@ plugins: {
Застереження:
-- переконайтеся, що ключ API Cerebras справді має доступ до вибраної вами моделі, оскільки сама лише видимість `/v1/models` не гарантує доступу до `chat/completions`
+- переконайтеся, що ключ API Cerebras справді має доступ до вибраної вами моделі, тому що сама лише видимість `/v1/models` не гарантує доступу до `chat/completions`
## Як це побачити
-Active memory впроваджує прихований ненадійний префікс prompt для моделі. Вона
+Active Memory впроваджує прихований недовірений префікс підказки для моделі. Вона
не показує сирі теги `...` у
-звичайній відповіді, видимій клієнту.
+звичайній видимій клієнту відповіді.
## Перемикач сеансу
-Використовуйте команду Plugin, коли хочете призупинити або відновити active memory для
+Використовуйте команду плагіна, якщо хочете призупинити або відновити Active Memory для
поточного чат-сеансу без редагування конфігурації:
```text
@@ -224,11 +225,11 @@ Active memory впроваджує прихований ненадійний п
/active-memory on
```
-Це діє на рівні сеансу. Воно не змінює
-`plugins.entries.active-memory.enabled`, націлювання агента чи іншу глобальну
+Це прив’язано до сеансу. Це не змінює
+`plugins.entries.active-memory.enabled`, націлювання на агента чи іншу глобальну
конфігурацію.
-Якщо ви хочете, щоб команда записувала конфігурацію та призупиняла або відновлювала active memory для
+Якщо ви хочете, щоб команда записувала конфігурацію та призупиняла або відновлювала Active Memory для
всіх сеансів, використовуйте явну глобальну форму:
```text
@@ -238,10 +239,10 @@ Active memory впроваджує прихований ненадійний п
```
Глобальна форма записує `plugins.entries.active-memory.config.enabled`. Вона залишає
-`plugins.entries.active-memory.enabled` увімкненим, щоб команда залишалася доступною для
-подальшого повторного ввімкнення active memory.
+`plugins.entries.active-memory.enabled` увімкненим, щоб команда й надалі була доступною для
+повторного ввімкнення Active Memory пізніше.
-Якщо ви хочете побачити, що робить active memory у живому сеансі, увімкніть
+Якщо ви хочете бачити, що робить Active Memory у живому сеансі, увімкніть
перемикачі сеансу, які відповідають потрібному вам виводу:
```text
@@ -251,15 +252,16 @@ Active memory впроваджує прихований ненадійний п
Коли їх увімкнено, OpenClaw може показувати:
-- рядок стану active memory, наприклад `Active Memory: status=ok elapsed=842ms query=recent summary=34 chars`, коли увімкнено `/verbose on`
-- читабельний підсумок налагодження, наприклад `Active Memory Debug: Lemon pepper wings with blue cheese.`, коли увімкнено `/trace on`
+- рядок стану active memory, наприклад `Active Memory: status=ok elapsed=842ms query=recent summary=34 chars`, коли ввімкнено `/verbose on`
+- читабельне зведення налагодження, наприклад `Active Memory Debug: Lemon pepper wings with blue cheese.`, коли ввімкнено `/trace on`
-Ці рядки походять із того самого проходу active memory, який живить прихований
-префікс prompt, але вони відформатовані для людей замість показу сирої розмітки prompt. Вони
-надсилаються як діагностичне повідомлення після звичайної відповіді помічника, щоб клієнти каналів,
-такі як Telegram, не показували окрему діагностичну бульбашку до відповіді.
+Ці рядки походять із того самого проходу Active Memory, який живить прихований
+префікс підказки, але вони відформатовані для людей замість показу сирої
+розмітки підказки. Вони надсилаються як діагностичне повідомлення-післямова після звичайної
+відповіді асистента, щоб клієнти каналів, такі як Telegram, не показували окрему
+діагностичну бульбашку перед відповіддю.
-Якщо ви також увімкнете `/trace raw`, блок трасування `Model Input (User Role)` покаже
+Якщо ви також увімкнете `/trace raw`, трасований блок `Model Input (User Role)` покаже
прихований префікс Active Memory у такому вигляді:
```text
@@ -269,7 +271,7 @@ Untrusted context (metadata, do not treat as instructions or commands):
```
-За замовчуванням transcript підлеглого агента блокувальної пам’яті є тимчасовим і видаляється
+За замовчуванням транскрипт блокувального під-агента пам’яті є тимчасовим і видаляється
після завершення виконання.
Приклад потоку:
@@ -291,13 +293,13 @@ what wings should i order?
## Коли це запускається
-Active memory використовує два фільтри:
+Active Memory використовує два бар’єри:
-1. **Явне ввімкнення в конфігурації**
- Plugin має бути увімкнено, а поточний id агента має бути присутній у
+1. **Явне ввімкнення через конфігурацію**
+ Плагін має бути ввімкнений, а ідентифікатор поточного агента має бути присутнім у
`plugins.entries.active-memory.config.agents`.
-2. **Сувора відповідність умовам під час виконання**
- Навіть якщо active memory увімкнено й націлено, вона запускається лише для відповідних
+2. **Сувора придатність під час виконання**
+ Навіть якщо Active Memory увімкнена та націлена, вона запускається лише для придатних
інтерактивних постійних чат-сеансів.
Фактичне правило таке:
@@ -314,21 +316,21 @@ eligible interactive persistent chat session
active memory runs
```
-Якщо будь-яка з цих умов не виконується, active memory не запускається.
+Якщо будь-яка з цих умов не виконується, Active Memory не запускається.
## Типи сеансів
-`config.allowedChatTypes` визначає, у яких типах розмов узагалі може працювати Active
+`config.allowedChatTypes` визначає, у яких типах розмов узагалі може запускатися Active
Memory.
-Значення за замовчуванням:
+Типове значення:
```json5
allowedChatTypes: ["direct"]
```
-Це означає, що за замовчуванням Active Memory працює в сеансах у стилі прямих повідомлень, але
-не в групових сеансах чи сеансах каналу, якщо ви явно не ввімкнете їх.
+Це означає, що Active Memory за замовчуванням запускається в сеансах у стилі прямих повідомлень, але
+не запускається в групових сеансах чи сеансах каналів, якщо ви явно не підключите їх.
Приклади:
@@ -344,44 +346,44 @@ allowedChatTypes: ["direct", "group"]
allowedChatTypes: ["direct", "group", "channel"]
```
-## Де це працює
+## Де це запускається
-Active memory — це функція покращення розмови, а не загальноплатформна
-можливість inference.
+Active Memory — це функція збагачення розмови, а не загальноплатформна
+inference-функція.
-| Поверхня | Active Memory працює? |
-| ------------------------------------------------------------------ | ------------------------------------------------------- |
-| Постійні сеанси Control UI / вебчату | Так, якщо Plugin увімкнено і агент націлено |
-| Інші інтерактивні сеанси каналів на тому самому шляху постійного чату | Так, якщо Plugin увімкнено і агент націлено |
-| Headless одноразові запуски | Ні |
-| Heartbeat/фонові запуски | Ні |
-| Загальні внутрішні шляхи `agent-command` | Ні |
-| Виконання підлеглих агентів/внутрішніх допоміжних засобів | Ні |
+| Поверхня | Active Memory запускається? |
+| -------------------------------------------------------------------- | ------------------------------------------------------- |
+| Постійні сеанси Control UI / вебчату | Так, якщо плагін увімкнено і агент націлено |
+| Інші інтерактивні сеанси каналів на тому самому шляху постійного чату | Так, якщо плагін увімкнено і агент націлено |
+| Безголові одноразові запуски | Ні |
+| Запуски Heartbeat/фонові запуски | Ні |
+| Загальні внутрішні шляхи `agent-command` | Ні |
+| Виконання під-агентів/внутрішніх допоміжних процесів | Ні |
## Навіщо це використовувати
Використовуйте active memory, коли:
-- сеанс є постійним і орієнтованим на користувача
-- агент має значущу довготривалу пам’ять, у якій можна шукати
-- безперервність і персоналізація важливіші за чисту детермінованість prompt
+- сеанс є постійним і призначеним для користувача
+- агент має значущу довгострокову пам’ять для пошуку
+- безперервність і персоналізація важливіші за сиру детермінованість підказок
-Вона особливо добре працює для:
+Це особливо добре працює для:
-- сталих уподобань
+- стабільних уподобань
- повторюваних звичок
-- довгострокового контексту користувача, який має природно з’являтися
+- довгострокового контексту користувача, який має природно спливати
-Вона погано підходить для:
+Це погано підходить для:
- автоматизації
- внутрішніх воркерів
- одноразових API-завдань
-- місць, де прихована персоналізація виглядала б неочікувано
+- місць, де прихована персоналізація була б несподіваною
## Як це працює
-Структура під час виконання така:
+Форма виконання така:
```mermaid
flowchart LR
@@ -392,32 +394,32 @@ flowchart LR
I --> M["Main Reply"]
```
-Підлеглий агент блокувальної пам’яті може використовувати лише:
+Блокувальний під-агент пам’яті може використовувати лише:
- `memory_search`
- `memory_get`
-Якщо з’єднання слабке, він має повернути `NONE`.
+Якщо з’єднання слабке, він має повертати `NONE`.
## Режими запиту
-`config.queryMode` визначає, яку частину розмови бачить підлеглий агент блокувальної пам’яті.
+`config.queryMode` визначає, який обсяг розмови бачить блокувальний під-агент пам’яті.
-## Стилі prompt
+## Стилі підказок
-`config.promptStyle` визначає, наскільки охоче або суворо підлеглий агент блокувальної пам’яті
+`config.promptStyle` визначає, наскільки охоче або суворо блокувальний під-агент пам’яті
вирішує, чи повертати пам’ять.
Доступні стилі:
-- `balanced`: універсальний варіант за замовчуванням для режиму `recent`
-- `strict`: найменш охочий; найкраще підходить, коли ви хочете якомога менше впливу від сусіднього контексту
-- `contextual`: найбільш дружній до безперервності; найкраще підходить, коли історія розмови має мати більше значення
-- `recall-heavy`: охочіше піднімає пам’ять за слабшими, але все ще правдоподібними збігами
-- `precision-heavy`: агресивно віддає перевагу `NONE`, якщо збіг не є очевидним
-- `preference-only`: оптимізований для фаворитів, звичок, рутин, смаків і повторюваних особистих фактів
+- `balanced`: універсальний типовий варіант для режиму `recent`
+- `strict`: найменш охочий; найкращий, коли ви хочете дуже мало впливу від сусіднього контексту
+- `contextual`: найбільш дружній до безперервності; найкращий, коли історія розмови має мати більше значення
+- `recall-heavy`: більш охоче піднімає пам’ять за слабших, але все ще правдоподібних збігів
+- `precision-heavy`: агресивно надає перевагу `NONE`, якщо збіг не є очевидним
+- `preference-only`: оптимізований для улюбленого, звичок, рутин, смаків і повторюваних особистих фактів
-Відображення за замовчуванням, коли `config.promptStyle` не задано:
+Типове зіставлення, коли `config.promptStyle` не задано:
```text
message -> strict
@@ -425,7 +427,7 @@ recent -> balanced
full -> contextual
```
-Якщо ви явно задаєте `config.promptStyle`, саме це перевизначення має пріоритет.
+Якщо ви явно задасте `config.promptStyle`, цей перевизначений варіант матиме пріоритет.
Приклад:
@@ -452,47 +454,47 @@ explicit plugin model
modelFallback: "google/gemini-3-flash"
```
-Якщо не вдається визначити явну, успадковану або налаштовану резервну модель, Active Memory
+Якщо не вдається визначити ані явну, ані успадковану, ані налаштовану резервну модель, Active Memory
пропускає відновлення пам’яті для цього ходу.
`config.modelFallbackPolicy` збережено лише як застаріле поле сумісності
для старіших конфігурацій. Воно більше не змінює поведінку під час виконання.
-## Розширені аварійні варіанти
+## Розширені аварійні обхідні механізми
Ці параметри навмисно не входять до рекомендованого налаштування.
-`config.thinking` може перевизначити рівень thinking підлеглого агента блокувальної пам’яті:
+`config.thinking` може перевизначити рівень thinking для блокувального під-агента пам’яті:
```json5
thinking: "medium"
```
-За замовчуванням:
+Типове значення:
```json5
thinking: "off"
```
Не вмикайте це за замовчуванням. Active Memory працює на шляху відповіді, тож додатковий
-час на thinking напряму збільшує видиму для користувача затримку.
+час на thinking безпосередньо збільшує видиму для користувача затримку.
-`config.promptAppend` додає додаткові інструкції оператора після стандартного prompt Active
+`config.promptAppend` додає додаткові операторські інструкції після типової підказки Active
Memory і перед контекстом розмови:
```json5
promptAppend: "Prefer stable long-term preferences over one-off events."
```
-`config.promptOverride` замінює стандартний prompt Active Memory. OpenClaw
-усе одно додає контекст розмови після нього:
+`config.promptOverride` замінює типову підказку Active Memory. OpenClaw
+усе одно додає контекст розмови після неї:
```json5
promptOverride: "You are a memory search agent. Return NONE or one compact user fact."
```
-Налаштування prompt не рекомендується, якщо тільки ви не тестуєте навмисно
-інший контракт відновлення пам’яті. Стандартний prompt налаштовано так, щоб повертати або `NONE`,
+Налаштування підказок не рекомендується, якщо тільки ви навмисно не тестуєте
+інший контракт відновлення пам’яті. Типова підказка налаштована так, щоб повертати або `NONE`,
або компактний контекст фактів про користувача для основної моделі.
### `message`
@@ -500,48 +502,48 @@ promptOverride: "You are a memory search agent. Return NONE or one compact user
Надсилається лише останнє повідомлення користувача.
```text
-Лише останнє повідомлення користувача
+Latest user message only
```
Використовуйте це, коли:
-- вам потрібна найшвидша поведінка
-- вам потрібен найсильніший ухил у бік відновлення сталих уподобань
+- вам потрібна найвища швидкодія
+- вам потрібен найсильніший ухил у бік відновлення стабільних уподобань
- наступні ходи не потребують контексту розмови
-Рекомендований timeout:
+Рекомендований тайм-аут:
- починайте приблизно з `3000` до `5000` мс
### `recent`
-Надсилається останнє повідомлення користувача плюс невеликий хвіст нещодавньої розмови.
+Надсилається останнє повідомлення користувача разом із невеликим хвостом недавньої розмови.
```text
-Хвіст нещодавньої розмови:
+Recent conversation tail:
user: ...
assistant: ...
user: ...
-Останнє повідомлення користувача:
+Latest user message:
...
```
Використовуйте це, коли:
-- ви хочете кращий баланс між швидкістю та прив’язкою до контексту розмови
-- запитання-продовження часто залежать від кількох останніх ходів
+- вам потрібен кращий баланс між швидкодією та прив’язкою до контексту розмови
+- наступні запитання часто залежать від кількох останніх ходів
-Рекомендований timeout:
+Рекомендований тайм-аут:
- починайте приблизно з `15000` мс
### `full`
-Підлеглому агенту блокувальної пам’яті надсилається вся розмова.
+До блокувального під-агента пам’яті надсилається вся розмова.
```text
-Повний контекст розмови:
+Full conversation context:
user: ...
assistant: ...
user: ...
@@ -551,31 +553,31 @@ user: ...
Використовуйте це, коли:
- найвища якість відновлення пам’яті важливіша за затримку
-- розмова містить важливі налаштування далеко вище у гілці
+- розмова містить важливу підготовчу інформацію далеко вище в потоці
-Рекомендований timeout:
+Рекомендований тайм-аут:
-- суттєво збільшуйте його порівняно з `message` або `recent`
-- починайте приблизно з `15000` мс або вище залежно від розміру гілки
+- суттєво збільште його порівняно з `message` або `recent`
+- починайте приблизно з `15000` мс або вище залежно від розміру потоку
-Загалом timeout має збільшуватися разом із розміром контексту:
+Загалом тайм-аут має зростати разом із розміром контексту:
```text
message < recent < full
```
-## Збереження transcript
+## Збереження транскриптів
-Запуски підлеглого агента блокувальної пам’яті Active Memory створюють справжній `session.jsonl`
-під час виклику підлеглого агента блокувальної пам’яті.
+Запуски блокувального під-агента пам’яті Active Memory створюють справжній транскрипт `session.jsonl`
+під час виклику блокувального під-агента пам’яті.
-За замовчуванням цей transcript є тимчасовим:
+За замовчуванням цей транскрипт є тимчасовим:
-- він записується в тимчасовий каталог
-- він використовується лише для запуску підлеглого агента блокувальної пам’яті
+- він записується до тимчасового каталогу
+- він використовується лише для запуску блокувального під-агента пам’яті
- він видаляється одразу після завершення запуску
-Якщо ви хочете зберігати ці transcript підлеглого агента блокувальної пам’яті на диску для налагодження або
+Якщо ви хочете зберігати ці транскрипти блокувального під-агента пам’яті на диску для налагодження або
перевірки, явно ввімкніть збереження:
```json5
@@ -595,8 +597,9 @@ message < recent < full
}
```
-Коли це ввімкнено, active memory зберігає transcript в окремому каталозі в
-теці sessions цільового агента, а не в шляху transcript основної розмови з користувачем.
+Коли це ввімкнено, active memory зберігає транскрипти в окремому каталозі в теці
+сеансів цільового агента, а не в основному шляху транскриптів розмови
+користувача.
Типова структура концептуально виглядає так:
@@ -608,13 +611,13 @@ agents//sessions/active-memory/.jso
Використовуйте це обережно:
-- transcript підлеглого агента блокувальної пам’яті можуть швидко накопичуватися в активних сеансах
-- режим запиту `full` може дублювати великий обсяг контексту розмови
-- ці transcript містять прихований контекст prompt і відновлені спогади
+- транскрипти блокувального під-агента пам’яті можуть швидко накопичуватися в активних сеансах
+- режим запиту `full` може дублювати велику кількість контексту розмови
+- ці транскрипти містять прихований контекст підказки та відновлені спогади
## Конфігурація
-Уся конфігурація active memory розташована тут:
+Уся конфігурація active memory розміщується тут:
```text
plugins.entries.active-memory
@@ -624,34 +627,34 @@ plugins.entries.active-memory
| Ключ | Тип | Значення |
| --------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `enabled` | `boolean` | Вмикає сам Plugin |
-| `config.agents` | `string[]` | Id агентів, які можуть використовувати active memory |
-| `config.model` | `string` | Необов’язкове посилання на модель підлеглого агента блокувальної пам’яті; якщо не задано, active memory використовує модель поточного сеансу |
-| `config.queryMode` | `"message" \| "recent" \| "full"` | Визначає, яку частину розмови бачить підлеглий агент блокувальної пам’яті |
-| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Визначає, наскільки охоче або суворо підлеглий агент блокувальної пам’яті вирішує, чи повертати пам’ять |
-| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive"` | Розширене перевизначення thinking для підлеглого агента блокувальної пам’яті; за замовчуванням `off` для швидкодії |
-| `config.promptOverride` | `string` | Розширена повна заміна prompt; не рекомендується для звичайного використання |
-| `config.promptAppend` | `string` | Розширені додаткові інструкції, що додаються до стандартного або перевизначеного prompt |
-| `config.timeoutMs` | `number` | Жорсткий timeout для підлеглого агента блокувальної пам’яті, обмежений 120000 мс |
-| `config.maxSummaryChars` | `number` | Максимальна загальна кількість символів, дозволена в підсумку active-memory |
+| `enabled` | `boolean` | Вмикає сам плагін |
+| `config.agents` | `string[]` | Ідентифікатори агентів, які можуть використовувати active memory |
+| `config.model` | `string` | Необов’язкове посилання на модель блокувального під-агента пам’яті; якщо не задано, active memory використовує модель поточного сеансу |
+| `config.queryMode` | `"message" \| "recent" \| "full"` | Визначає, який обсяг розмови бачить блокувальний під-агент пам’яті |
+| `config.promptStyle` | `"balanced" \| "strict" \| "contextual" \| "recall-heavy" \| "precision-heavy" \| "preference-only"` | Визначає, наскільки охоче або суворо блокувальний під-агент пам’яті вирішує, чи повертати пам’ять |
+| `config.thinking` | `"off" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "adaptive" \| "max"` | Розширене перевизначення thinking для блокувального під-агента пам’яті; типове значення `off` для швидкодії |
+| `config.promptOverride` | `string` | Розширена повна заміна підказки; не рекомендується для звичайного використання |
+| `config.promptAppend` | `string` | Розширені додаткові інструкції, додані після типової або перевизначеної підказки |
+| `config.timeoutMs` | `number` | Жорсткий тайм-аут для блокувального під-агента пам’яті, обмежений 120000 мс |
+| `config.maxSummaryChars` | `number` | Максимальна загальна кількість символів, дозволена в зведенні active-memory |
| `config.logging` | `boolean` | Виводить журнали active memory під час налаштування |
-| `config.persistTranscripts` | `boolean` | Зберігає transcript підлеглого агента блокувальної пам’яті на диску замість видалення тимчасових файлів |
-| `config.transcriptDir` | `string` | Відносний каталог transcript підлеглого агента блокувальної пам’яті в теці sessions агента |
+| `config.persistTranscripts` | `boolean` | Зберігає транскрипти блокувального під-агента пам’яті на диску замість видалення тимчасових файлів |
+| `config.transcriptDir` | `string` | Відносний каталог транскриптів блокувального під-агента пам’яті в теці сеансів агента |
Корисні поля для налаштування:
| Ключ | Тип | Значення |
| ----------------------------- | -------- | ------------------------------------------------------------- |
-| `config.maxSummaryChars` | `number` | Максимальна загальна кількість символів, дозволена в підсумку active-memory |
-| `config.recentUserTurns` | `number` | Попередні ходи користувача, які слід включати, коли `queryMode` має значення `recent` |
-| `config.recentAssistantTurns` | `number` | Попередні ходи помічника, які слід включати, коли `queryMode` має значення `recent` |
-| `config.recentUserChars` | `number` | Максимум символів на один нещодавній хід користувача |
-| `config.recentAssistantChars` | `number` | Максимум символів на один нещодавній хід помічника |
-| `config.cacheTtlMs` | `number` | Повторне використання кешу для повторюваних однакових запитів |
+| `config.maxSummaryChars` | `number` | Максимальна загальна кількість символів, дозволена в зведенні active-memory |
+| `config.recentUserTurns` | `number` | Попередні ходи користувача, які слід включити, коли `queryMode` має значення `recent` |
+| `config.recentAssistantTurns` | `number` | Попередні ходи асистента, які слід включити, коли `queryMode` має значення `recent` |
+| `config.recentUserChars` | `number` | Максимум символів на один недавній хід користувача |
+| `config.recentAssistantChars` | `number` | Максимум символів на один недавній хід асистента |
+| `config.cacheTtlMs` | `number` | Повторне використання кешу для повторюваних ідентичних запитів |
## Рекомендоване налаштування
-Починайте з `recent`.
+Почніть із `recent`.
```json5
{
@@ -673,90 +676,91 @@ plugins.entries.active-memory
}
```
-Якщо ви хочете перевіряти живу поведінку під час налаштування, використовуйте `/verbose on` для
-звичайного рядка стану та `/trace on` для підсумку налагодження active-memory замість
+Якщо ви хочете перевіряти поведінку наживо під час налаштування, використовуйте `/verbose on` для
+звичайного рядка стану та `/trace on` для зведення налагодження active-memory замість
пошуку окремої команди налагодження active-memory. У чат-каналах ці
-діагностичні рядки надсилаються після основної відповіді помічника, а не до неї.
+діагностичні рядки надсилаються після основної відповіді асистента, а не перед нею.
Потім переходьте до:
-- `message`, якщо вам потрібна менша затримка
-- `full`, якщо ви вирішите, що додатковий контекст вартий повільнішого підлеглого агента блокувальної пам’яті
+- `message`, якщо хочете нижчу затримку
+- `full`, якщо вирішите, що додатковий контекст вартий повільнішого блокувального під-агента пам’яті
## Налагодження
Якщо active memory не з’являється там, де ви очікуєте:
-1. Підтвердьте, що Plugin увімкнено в `plugins.entries.active-memory.enabled`.
-2. Підтвердьте, що поточний id агента вказано в `config.agents`.
-3. Підтвердьте, що ви тестуєте через інтерактивний постійний чат-сеанс.
-4. Увімкніть `config.logging: true` і перегляньте журнали Gateway.
-5. Переконайтеся, що сам пошук у пам’яті працює, за допомогою `openclaw memory status --deep`.
+1. Переконайтеся, що плагін увімкнений у `plugins.entries.active-memory.enabled`.
+2. Переконайтеся, що ідентифікатор поточного агента вказаний у `config.agents`.
+3. Переконайтеся, що ви тестуєте через інтерактивний постійний чат-сеанс.
+4. Увімкніть `config.logging: true` і стежте за журналами Gateway.
+5. Переконайтеся, що сам пошук пам’яті працює, за допомогою `openclaw memory status --deep`.
Якщо збіги пам’яті шумні, посильте обмеження:
- `maxSummaryChars`
-Якщо active memory занадто повільна:
+Якщо active memory працює надто повільно:
- зменште `queryMode`
- зменште `timeoutMs`
-- зменште кількість нещодавніх ходів
-- зменште ліміти символів на один хід
+- зменште кількість недавніх ходів
+- зменште ліміти символів на хід
## Поширені проблеми
-### Provider ембедингів неочікувано змінився
+### Постачальник embeddings неочікувано змінився
Active Memory використовує звичайний конвеєр `memory_search` у
-`agents.defaults.memorySearch`. Це означає, що налаштування provider ембедингів є вимогою лише тоді, коли
-ваше налаштування `memorySearch` потребує ембедингів для потрібної вам поведінки.
+`agents.defaults.memorySearch`. Це означає, що налаштування постачальника embeddings є
+вимогою лише тоді, коли ваша конфігурація `memorySearch` потребує embeddings для бажаної
+поведінки.
На практиці:
-- явне налаштування provider **потрібне**, якщо ви хочете provider, який не
+- явне налаштування постачальника **обов’язкове**, якщо вам потрібен постачальник, який не
визначається автоматично, наприклад `ollama`
-- явне налаштування provider **потрібне**, якщо автовизначення не знаходить
- жодного придатного provider ембедингів для вашого середовища
-- явне налаштування provider **наполегливо рекомендується**, якщо ви хочете детермінований
- вибір provider замість підходу «перемагає перший доступний»
-- явне налаштування provider зазвичай **не потрібне**, якщо автовизначення вже
- знаходить потрібний вам provider і цей provider стабільний у вашому середовищі розгортання
+- явне налаштування постачальника **обов’язкове**, якщо автоматичне визначення не знаходить
+ жодного придатного постачальника embeddings для вашого середовища
+- явне налаштування постачальника **дуже рекомендоване**, якщо вам потрібен детермінований
+ вибір постачальника замість «перший доступний перемагає»
+- явне налаштування постачальника зазвичай **не обов’язкове**, якщо автоматичне визначення вже
+ знаходить потрібного вам постачальника і цей постачальник є стабільним у вашому розгортанні
-Якщо `memorySearch.provider` не задано, OpenClaw автоматично визначає перший доступний
-provider ембедингів.
+Якщо `memorySearch.provider` не задано, OpenClaw автоматично визначає першого доступного
+постачальника embeddings.
У реальних розгортаннях це може збивати з пантелику:
-- новий доступний ключ API може змінити те, який provider використовує пошук у пам’яті
-- одна команда або діагностична поверхня можуть створювати враження, що вибраний provider
- відрізняється від шляху, який фактично використовується під час живої синхронізації пам’яті або
- початкового запуску пошуку
-- хостингові provider можуть завершуватися помилками квоти або rate-limit, які проявляються
- лише коли Active Memory починає виконувати запити на відновлення пам’яті перед кожною відповіддю
+- новий доступний API-ключ може змінити те, який постачальник використовується для пошуку в пам’яті
+- одна команда або діагностична поверхня може показувати вибраного постачальника
+ інакше, ніж той шлях, у який ви фактично потрапляєте під час живої синхронізації пам’яті або
+ початкового етапу пошуку
+- хостовані постачальники можуть завершуватися помилками квоти або обмеження швидкості, які проявляються лише
+ після того, як Active Memory починає виконувати пошуки відновлення пам’яті перед кожною відповіддю
-Active Memory усе ще може працювати без ембедингів, коли `memory_search` може працювати
+Active Memory усе ще може працювати без embeddings, коли `memory_search` може працювати
у деградованому режимі лише з лексичним пошуком, що зазвичай трапляється, коли не вдається
-визначити жодного provider ембедингів.
+визначити жодного постачальника embeddings.
-Не припускайте, що той самий резервний механізм спрацює у випадку помилок виконання provider, таких як
-вичерпання квоти, rate limits, помилки мережі/provider або відсутні локальні/віддалені
-моделі після того, як provider уже було вибрано.
+Не припускайте, що той самий резервний механізм спрацює для збоїв у роботі постачальника, таких як вичерпання квоти,
+обмеження швидкості, мережеві/провайдерські помилки або відсутність локальних/віддалених
+моделей після того, як постачальника вже було вибрано.
На практиці:
-- якщо не вдається визначити provider ембедингів, `memory_search` може деградувати до
+- якщо не вдається визначити жодного постачальника embeddings, `memory_search` може деградувати до
лише лексичного відновлення
-- якщо provider ембедингів визначено, але він завершується помилкою під час виконання, OpenClaw наразі
- не гарантує лексичний резервний механізм для цього запиту
-- якщо вам потрібен детермінований вибір provider, зафіксуйте
+- якщо постачальника embeddings визначено, а потім він завершується помилкою під час виконання, OpenClaw
+ наразі не гарантує лексичний резервний механізм для цього запиту
+- якщо вам потрібен детермінований вибір постачальника, зафіксуйте
`agents.defaults.memorySearch.provider`
-- якщо вам потрібен failover provider у разі помилок виконання, явно налаштуйте
+- якщо вам потрібне перемикання на резервного постачальника у разі помилок під час виконання, явно налаштуйте
`agents.defaults.memorySearch.fallback`
-Якщо ви залежите від відновлення пам’яті на основі ембедингів, мультимодального індексування або конкретного
-локального/віддаленого provider, явно зафіксуйте provider замість того, щоб покладатися на
-автовизначення.
+Якщо ви залежите від відновлення пам’яті на основі embeddings, мультимодального індексування або конкретного
+локального/віддаленого постачальника, явно зафіксуйте постачальника замість того, щоб покладатися на
+автоматичне визначення.
Поширені приклади фіксації:
@@ -805,8 +809,8 @@ Ollama:
}
```
-Якщо ви очікуєте failover provider у разі помилок виконання, таких як
-вичерпання квоти, недостатньо лише зафіксувати provider. Також налаштуйте явний резервний варіант:
+Якщо ви очікуєте перемикання на резервного постачальника у разі помилок під час виконання, таких як вичерпання квоти,
+лише фіксації постачальника недостатньо. Також налаштуйте явний резервний варіант:
```json5
{
@@ -821,31 +825,30 @@ Ollama:
}
```
-### Налагодження проблем із provider
+### Налагодження проблем із постачальником
-Якщо Active Memory повільна, порожня або здається, що неочікувано перемикає provider:
+Якщо Active Memory працює повільно, не повертає результатів або ніби неочікувано перемикає постачальників:
-- переглядайте журнали Gateway під час відтворення проблеми; шукайте рядки на кшталт
+- стежте за журналами Gateway під час відтворення проблеми; шукайте рядки на кшталт
`active-memory: ... start|done`, `memory sync failed (search-bootstrap)` або
- специфічні для provider помилки ембедингів
-- увімкніть `/trace on`, щоб показувати в сеансі підсумок налагодження Active Memory, що належить Plugin
-- увімкніть `/verbose on`, якщо ви також хочете бачити звичайний рядок стану
+ помилки embeddings, пов’язані з конкретним постачальником
+- увімкніть `/trace on`, щоб показувати в сеансі зведення налагодження Active Memory, яким володіє плагін
+- увімкніть `/verbose on`, якщо також хочете бачити звичайний рядок стану
`🧩 Active Memory: ...` після кожної відповіді
-- запустіть `openclaw memory status --deep`, щоб перевірити поточний
- backend пошуку в пам’яті та стан індексу
-- перевірте `agents.defaults.memorySearch.provider` і пов’язані auth/config, щоб
- переконатися, що provider, який ви очікуєте, справді може визначатися під час виконання
-- якщо ви використовуєте `ollama`, переконайтеся, що налаштовану модель ембедингів встановлено, наприклад через
- `ollama list`
+- запустіть `openclaw memory status --deep`, щоб перевірити поточний бекенд пошуку в пам’яті
+ і стан індексу
+- перевірте `agents.defaults.memorySearch.provider` і пов’язану авторизацію/конфігурацію, щоб
+ переконатися, що постачальник, якого ви очікуєте, справді може бути визначений під час виконання
+- якщо ви використовуєте `ollama`, переконайтеся, що налаштовану модель embeddings установлено, наприклад через `ollama list`
Приклад циклу налагодження:
```text
-1. Запустіть Gateway і переглядайте його журнали
-2. У чат-сеансі виконайте /trace on
-3. Надішліть одне повідомлення, яке має активувати Active Memory
-4. Порівняйте видимий у чаті рядок налагодження з рядками в журналі Gateway
-5. Якщо вибір provider неоднозначний, явно зафіксуйте agents.defaults.memorySearch.provider
+1. Start the gateway and watch its logs
+2. In the chat session, run /trace on
+3. Send one message that should trigger Active Memory
+4. Compare the chat-visible debug line with the gateway log lines
+5. If provider choice is ambiguous, pin agents.defaults.memorySearch.provider explicitly
```
Приклад:
@@ -863,7 +866,7 @@ Ollama:
}
```
-Або, якщо ви хочете ембединги Gemini:
+Або, якщо ви хочете embeddings Gemini:
```json5
{
@@ -877,8 +880,8 @@ Ollama:
}
```
-Після зміни provider перезапустіть Gateway і виконайте новий тест із
-`/trace on`, щоб рядок налагодження Active Memory відображав новий шлях ембедингів.
+Після зміни постачальника перезапустіть Gateway і виконайте новий тест із
+`/trace on`, щоб рядок налагодження Active Memory відображав новий шлях embeddings.
## Пов’язані сторінки
diff --git a/docs/uk/concepts/model-providers.md b/docs/uk/concepts/model-providers.md
index 93b0f3d2a..cb7fe876d 100644
--- a/docs/uk/concepts/model-providers.md
+++ b/docs/uk/concepts/model-providers.md
@@ -1,41 +1,41 @@
---
read_when:
- - Потрібен довідник із налаштування моделей для кожного провайдера окремо
- - Вам потрібні приклади конфігурацій або команд онбордингу CLI для провайдерів моделей
-summary: Огляд провайдерів моделей із прикладами конфігурацій + потоками CLI
-title: Провайдери моделей
+ - Вам потрібен довідник із налаштування моделей для кожного постачальника окремо
+ - Вам потрібні приклади конфігурацій або команди онбордингу CLI для постачальників моделей
+summary: Огляд постачальника моделей із прикладами конфігурацій + потоками CLI
+title: Постачальники моделей
x-i18n:
- generated_at: "2026-04-21T05:21:16Z"
+ generated_at: "2026-04-21T06:04:45Z"
model: gpt-5.4
provider: openai
- source_hash: aafd4d0da950a4ccdec64f85cf485a7da95da6a858588d43be3f7ac5fd0e05b7
+ source_hash: e433dfd51d1721832480089cb35ab1243e5c873a587f9968e14744840cb912cf
source_path: concepts/model-providers.md
workflow: 15
---
-# Провайдери моделей
+# Постачальники моделей
-Ця сторінка охоплює **провайдерів LLM/моделей** (а не канали чату на кшталт WhatsApp/Telegram).
-Правила вибору моделей див. у [/concepts/models](/uk/concepts/models).
+Ця сторінка охоплює **постачальників LLM/моделей** (а не канали чату, як-от WhatsApp/Telegram).
+Правила вибору моделей дивіться в [/concepts/models](/uk/concepts/models).
## Швидкі правила
- Посилання на моделі використовують формат `provider/model` (приклад: `opencode/claude-opus-4-6`).
-- Якщо ви встановите `agents.defaults.models`, це стане списком дозволених значень.
+- Якщо ви задаєте `agents.defaults.models`, це стає списком дозволених значень.
- Допоміжні команди CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `.
-- Резервні правила під час виконання, cooldown-проби та збереження session-override
- задокументовані в [/concepts/model-failover](/uk/concepts/model-failover).
-- `models.providers.*.models[].contextWindow` — це власні метадані моделі;
- `models.providers.*.models[].contextTokens` — це фактичне обмеження під час виконання.
-- Провайдерські Plugin можуть впроваджувати каталоги моделей через `registerProvider({ catalog })`;
- OpenClaw об’єднує цей вивід у `models.providers` перед записом
+- Резервні правила рантайму, зондування cooldown і збереження session-override
+ задокументовано в [/concepts/model-failover](/uk/concepts/model-failover).
+- `models.providers.*.models[].contextWindow` — це нативні метадані моделі;
+ `models.providers.*.models[].contextTokens` — це фактичне обмеження рантайму.
+- Плагіни постачальників можуть інʼєктувати каталоги моделей через `registerProvider({ catalog })`;
+ OpenClaw обʼєднує цей вивід у `models.providers` перед записом
`models.json`.
-- Маніфести провайдерів можуть оголошувати `providerAuthEnvVars` і
- `providerAuthAliases`, щоб загальні auth-проби на основі env і варіанти провайдерів
- не потребували завантаження середовища виконання Plugin. Решта мапи env-змінних у core тепер
- потрібна лише для не-Plugin/core провайдерів і кількох випадків загального пріоритету, таких
- як онбординг Anthropic зі схемою API-key-first.
-- Провайдерські Plugin також можуть володіти поведінкою провайдера під час виконання через
+- Маніфести постачальників можуть оголошувати `providerAuthEnvVars` і
+ `providerAuthAliases`, щоб загальні перевірки автентифікації на основі env і варіанти постачальників
+ не потребували завантаження рантайму Plugin. Решта мапи env-змінних у ядрі тепер
+ використовується лише для постачальників ядра/не Plugin і кількох випадків із загальним пріоритетом, таких
+ як онбординг Anthropic із пріоритетом API-ключа.
+- Плагіни постачальників також можуть володіти поведінкою рантайму постачальника через
`normalizeModelId`, `normalizeTransport`, `normalizeConfig`,
`applyNativeStreamingUsageCompat`, `resolveConfigApiKey`,
`resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`,
@@ -50,223 +50,188 @@ x-i18n:
`matchesContextOverflowError`, `classifyFailoverReason`,
`isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`,
`augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`,
- `supportsAdaptiveThinking`,
+ `supportsAdaptiveThinking`, `supportsMaxThinking`,
`resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`,
`prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, і
`onModelSelected`.
-- Примітка: `capabilities` провайдера під час виконання — це спільні метадані раннера (сімейство провайдера,
- особливості transcript/tooling, підказки щодо transport/cache). Це не те саме, що [публічна модель capability](/uk/plugins/architecture#public-capability-model),
+- Примітка: рантаймові `capabilities` постачальника — це спільні метадані раннера (сімейство постачальника,
+ особливості transcript/tooling, підказки для transport/cache). Це не те
+ саме, що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model),
яка описує, що реєструє Plugin (текстовий inference, мовлення тощо).
-- Вбудований провайдер `codex` поєднаний із вбудованим harness агента Codex.
- Використовуйте `codex/gpt-*`, коли вам потрібні login під керуванням Codex, виявлення моделей,
- нативне відновлення thread і виконання на сервері застосунку. Звичайні посилання `openai/gpt-*`
- і надалі використовують провайдера OpenAI та звичайний transport провайдера OpenClaw.
- Розгортання лише з Codex можуть вимкнути автоматичний резервний перехід до PI через
+- Вбудований постачальник `codex` поєднаний із вбудованим агентним harness Codex.
+ Використовуйте `codex/gpt-*`, коли вам потрібні вхід, що належить Codex, виявлення моделей,
+ нативне відновлення thread і виконання app-server. Звичайні посилання `openai/gpt-*`
+ і далі використовують постачальника OpenAI та звичайний transport постачальника OpenClaw.
+ У розгортаннях лише з Codex можна вимкнути автоматичний резервний перехід на PI за допомогою
`agents.defaults.embeddedHarness.fallback: "none"`; див.
[Codex Harness](/uk/plugins/codex-harness).
-## Поведінка провайдера, якою володіє Plugin
+## Поведінка постачальника, якою володіє Plugin
-Тепер провайдерські Plugin можуть володіти більшістю специфічної для провайдера логіки, тоді як OpenClaw зберігає
+Плагіни постачальників тепер можуть володіти більшістю логіки, специфічної для постачальника, тоді як OpenClaw зберігає
загальний цикл inference.
-Типовий поділ:
+Типовий розподіл:
-- `auth[].run` / `auth[].runNonInteractive`: провайдер володіє потоками онбордингу/login
- для `openclaw onboard`, `openclaw models auth` і безголового налаштування
-- `wizard.setup` / `wizard.modelPicker`: провайдер володіє мітками вибору auth,
- застарілими псевдонімами, підказками щодо списку дозволених значень для онбордингу та записами налаштування в засобах вибору онбордингу/моделей
-- `catalog`: провайдер з’являється в `models.providers`
-- `normalizeModelId`: провайдер нормалізує застарілі/preview ідентифікатори моделей перед
+- `auth[].run` / `auth[].runNonInteractive`: постачальник володіє потоками
+ онбордингу/входу для `openclaw onboard`, `openclaw models auth` і безголового налаштування
+- `wizard.setup` / `wizard.modelPicker`: постачальник володіє мітками вибору автентифікації,
+ застарілими псевдонімами, підказками щодо allowlist під час онбордингу та записами налаштування
+ у вибірниках онбордингу/моделей
+- `catalog`: постачальник зʼявляється в `models.providers`
+- `normalizeModelId`: постачальник нормалізує застарілі/preview ідентифікатори моделей перед
пошуком або канонізацією
-- `normalizeTransport`: провайдер нормалізує `api` / `baseUrl` сімейства transport
- перед загальним складанням моделі; OpenClaw спочатку перевіряє відповідний провайдер,
- а потім інші провайдерські Plugin, здатні працювати з цим hook, доки один із них справді не змінить
- transport
-- `normalizeConfig`: провайдер нормалізує конфігурацію `models.providers.` перед
- її використанням під час виконання; OpenClaw спочатку перевіряє відповідний провайдер, а потім інші
- провайдерські Plugin, здатні працювати з цим hook, доки один із них справді не змінить конфігурацію. Якщо жоден
- provider hook не переписує конфігурацію, вбудовані допоміжні засоби сімейства Google все одно
- нормалізують підтримувані записи провайдерів Google.
-- `applyNativeStreamingUsageCompat`: провайдер застосовує переписування compat для native streaming-usage на основі endpoint для конфігурованих провайдерів
-- `resolveConfigApiKey`: провайдер визначає auth env-marker для конфігурованих провайдерів
- без примусового повного завантаження auth під час виконання. `amazon-bedrock` також має
- тут вбудований розпізнавач AWS env-marker, хоча auth Bedrock під час виконання використовує
- типовий ланцюжок AWS SDK.
-- `resolveSyntheticAuth`: провайдер може показувати доступність локального/self-hosted або іншого
- auth на основі конфігурації без збереження секретів у відкритому вигляді
-- `shouldDeferSyntheticProfileAuth`: провайдер може позначати збережені синтетичні profile-заповнювачі
- як нижчі за пріоритетом, ніж auth на основі env/конфігурації
-- `resolveDynamicModel`: провайдер приймає ідентифікатори моделей, яких ще немає в локальному
+- `normalizeTransport`: постачальник нормалізує `api` / `baseUrl` сімейства transport
+ перед загальним складанням моделі; OpenClaw спочатку перевіряє відповідного постачальника,
+ потім інші плагіни постачальників, здатні працювати через hook, доки один із них
+ фактично не змінить transport
+- `normalizeConfig`: постачальник нормалізує конфігурацію `models.providers.` перед
+ використанням рантаймом; OpenClaw спочатку перевіряє відповідного постачальника, а потім інші
+ плагіни постачальників, здатні працювати через hook, доки один із них фактично не змінить конфігурацію. Якщо жоден
+ hook постачальника не переписує конфігурацію, вбудовані допоміжні засоби сімейства Google
+ усе ще нормалізують підтримувані записи постачальників Google.
+- `applyNativeStreamingUsageCompat`: постачальник застосовує сумісні переписування native streaming-usage для постачальників конфігурації залежно від endpoint
+- `resolveConfigApiKey`: постачальник визначає автентифікацію env-marker для постачальників конфігурації
+ без примусового завантаження повної рантаймової автентифікації. `amazon-bedrock` також має
+ тут вбудований резолвер AWS env-marker, хоча рантаймова автентифікація Bedrock використовує
+ стандартний ланцюг AWS SDK.
+- `resolveSyntheticAuth`: постачальник може повідомляти про доступність локальної/self-hosted або іншої
+ автентифікації, що спирається на конфігурацію, без збереження секретів у відкритому тексті
+- `shouldDeferSyntheticProfileAuth`: постачальник може позначати збережені заповнювачі synthetic profile
+ як такі, що мають нижчий пріоритет, ніж автентифікація на основі env/config
+- `resolveDynamicModel`: постачальник приймає ідентифікатори моделей, яких іще немає в локальному
статичному каталозі
-- `prepareDynamicModel`: провайдеру потрібне оновлення метаданих перед повторною спробою
+- `prepareDynamicModel`: постачальнику потрібно оновлення метаданих перед повторною спробою
динамічного визначення
-- `normalizeResolvedModel`: провайдеру потрібні переписування transport або base URL
-- `contributeResolvedModelCompat`: провайдер додає compat-прапорці для своїх
- vendor-моделей, навіть коли вони надходять через інший сумісний transport
-- `capabilities`: провайдер публікує особливості transcript/tooling/provider-family
-- `normalizeToolSchemas`: провайдер очищує схеми інструментів до того, як вбудований
- раннер їх побачить
-- `inspectToolSchemas`: провайдер показує специфічні для transport попередження схем
+- `normalizeResolvedModel`: постачальнику потрібні переписування transport або базового URL
+- `contributeResolvedModelCompat`: постачальник додає прапорці сумісності для своїх
+ моделей постачальника, навіть коли вони надходять через інший сумісний transport
+- `capabilities`: постачальник публікує особливості transcript/tooling/provider-family
+- `normalizeToolSchemas`: постачальник очищає схеми інструментів перед тим, як їх побачить вбудований
+ раннер
+- `inspectToolSchemas`: постачальник показує попередження схем, специфічні для transport,
після нормалізації
-- `resolveReasoningOutputMode`: провайдер вибирає контракти виводу reasoning — native чи tagged
-- `prepareExtraParams`: провайдер задає типові значення або нормалізує параметри запиту для кожної моделі
-- `createStreamFn`: провайдер замінює звичайний шлях stream повністю
- користувацьким transport
-- `wrapStreamFn`: провайдер застосовує обгортки сумісності заголовків/тіла/моделі запиту
-- `resolveTransportTurnState`: провайдер постачає нативні заголовки або метадані transport
- для кожного ходу
-- `resolveWebSocketSessionPolicy`: провайдер постачає нативні заголовки сесії WebSocket
+- `resolveReasoningOutputMode`: постачальник обирає native чи tagged
+ контракти виводу reasoning
+- `prepareExtraParams`: постачальник задає типові значення або нормалізує параметри запиту для кожної моделі
+- `createStreamFn`: постачальник замінює звичайний шлях потоку повністю
+ кастомним transport
+- `wrapStreamFn`: постачальник застосовує обгортки сумісності для заголовків/тіла/моделі запиту
+- `resolveTransportTurnState`: постачальник надає нативні заголовки transport
+ або метадані для кожного ходу
+- `resolveWebSocketSessionPolicy`: постачальник надає нативні заголовки сесії WebSocket
або політику cool-down сесії
-- `createEmbeddingProvider`: провайдер володіє поведінкою embedding для пам’яті, коли вона
- має належати провайдерському Plugin, а не core-перемикачу embedding
-- `formatApiKey`: провайдер форматує збережені auth profile у
- рядок `apiKey` під час виконання, якого очікує transport
-- `refreshOAuth`: провайдер володіє оновленням OAuth, коли спільних
- засобів оновлення `pi-ai` недостатньо
-- `buildAuthDoctorHint`: провайдер додає підказки щодо виправлення, коли оновлення OAuth
- зазнає невдачі
-- `matchesContextOverflowError`: провайдер розпізнає специфічні для провайдера
- помилки переповнення context-window, які загальні евристики можуть пропустити
-- `classifyFailoverReason`: провайдер зіставляє специфічні для провайдера необроблені помилки transport/API
- з причинами резервного переходу, такими як rate limit або overload
-- `isCacheTtlEligible`: провайдер визначає, які upstream-ідентифікатори моделей підтримують TTL кешу prompt
-- `buildMissingAuthMessage`: провайдер замінює загальну помилку сховища auth
- на специфічну для провайдера підказку щодо відновлення
-- `suppressBuiltInModel`: провайдер приховує застарілі upstream-рядки та може повертати
- помилку під керуванням vendor для прямих збоїв визначення
-- `augmentModelCatalog`: провайдер додає синтетичні/фінальні рядки каталогу після
- виявлення та злиття конфігурації
-- `isBinaryThinking`: провайдер володіє UX двійкового thinking — увімк./вимк.
-- `supportsXHighThinking`: провайдер вмикає `xhigh` для вибраних моделей
-- `supportsAdaptiveThinking`: провайдер вмикає `adaptive` для вибраних моделей
-- `resolveDefaultThinkingLevel`: провайдер володіє типовою політикою `/think` для
+- `createEmbeddingProvider`: постачальник володіє поведінкою embedding для памʼяті, коли вона
+ має належати плагіну постачальника, а не центральному перемикачу embedding у ядрі
+- `formatApiKey`: постачальник форматує збережені профілі автентифікації у
+ рядок рантайму `apiKey`, якого очікує transport
+- `refreshOAuth`: постачальник володіє оновленням OAuth, коли спільних засобів оновлення `pi-ai`
+ недостатньо
+- `buildAuthDoctorHint`: постачальник додає підказку з відновлення, коли оновлення OAuth
+ не вдається
+- `matchesContextOverflowError`: постачальник розпізнає помилки переповнення
+ вікна контексту, специфічні для постачальника, які загальні евристики не побачили б
+- `classifyFailoverReason`: постачальник зіставляє сирі помилки transport/API, специфічні для постачальника,
+ із причинами резервного переходу, такими як rate limit або overload
+- `isCacheTtlEligible`: постачальник визначає, які upstream ідентифікатори моделей підтримують prompt-cache TTL
+- `buildMissingAuthMessage`: постачальник замінює загальну помилку auth-store
+ на підказку відновлення, специфічну для постачальника
+- `suppressBuiltInModel`: постачальник приховує застарілі upstream-рядки й може повертати
+ помилку, що належить постачальнику, для прямих збоїв визначення
+- `augmentModelCatalog`: постачальник додає synthetic/final рядки каталогу після
+ виявлення й обʼєднання конфігурації
+- `isBinaryThinking`: постачальник володіє UX двійкового thinking увімк./вимк.
+- `supportsXHighThinking`: постачальник вмикає `xhigh` для вибраних моделей
+- `supportsAdaptiveThinking`: постачальник вмикає `adaptive` для вибраних моделей
+- `supportsMaxThinking`: постачальник вмикає `max` для вибраних моделей
+- `resolveDefaultThinkingLevel`: постачальник володіє типовою політикою `/think` для
сімейства моделей
-- `applyConfigDefaults`: провайдер застосовує специфічні для провайдера глобальні типові значення
- під час матеріалізації конфігурації залежно від режиму auth, env або сімейства моделей
-- `isModernModelRef`: провайдер володіє зіставленням бажаної моделі для live/smoke
-- `prepareRuntimeAuth`: провайдер перетворює налаштовані облікові дані на короткоживучий
- токен для виконання
-- `resolveUsageAuth`: провайдер визначає облікові дані usage/quota для `/usage`
- і пов’язаних поверхонь status/reporting
-- `fetchUsageSnapshot`: провайдер володіє отриманням/розбором endpoint usage, тоді як
- core і далі володіє оболонкою підсумку та форматуванням
-- `onModelSelected`: провайдер виконує побічні ефекти після вибору моделі, наприклад
- telemetry або bookkeeping сесії під керуванням провайдера
+- `applyConfigDefaults`: постачальник застосовує глобальні типові значення, специфічні для постачальника,
+ під час матеріалізації конфігурації на основі режиму автентифікації, env або сімейства моделей
+- `isModernModelRef`: постачальник володіє зіставленням бажаних моделей для live/smoke
+- `prepareRuntimeAuth`: постачальник перетворює налаштовані облікові дані на короткоживучий
+ рантаймовий токен
+- `resolveUsageAuth`: постачальник визначає облікові дані використання/квоти для `/usage`
+ та повʼязаних поверхонь status/reporting
+- `fetchUsageSnapshot`: постачальник володіє отриманням/парсингом endpoint використання, тоді як
+ ядро все ще володіє оболонкою підсумку та форматуванням
+- `onModelSelected`: постачальник виконує побічні ефекти після вибору моделі, наприклад
+ телеметрію або ведення сесії, що належить постачальнику
Поточні вбудовані приклади:
-- `anthropic`: резервний механізм прямої сумісності вперед для Claude 4.6, підказки з відновлення auth, отримання
- endpoint usage, метадані cache-TTL/provider-family і глобальні
- типові значення конфігурації з урахуванням auth
-- `amazon-bedrock`: зіставлення переповнення контексту під керуванням провайдера та класифікація
- причин резервного переходу для специфічних помилок Bedrock `throttle`/`not-ready`, а також
- спільне сімейство повторного відтворення `anthropic-by-model` для захистів політики replay лише для Claude на трафіку Anthropic
-- `anthropic-vertex`: захисти політики replay лише для Claude на трафіку повідомлень Anthropic
-- `openrouter`: наскрізні ідентифікатори моделей, обгортки запитів, підказки щодо provider capability,
- очищення thought-signature Gemini на проксійованому трафіку Gemini, впровадження reasoning через проксі
- через сімейство stream `openrouter-thinking`, пересилання метаданих маршрутизації
- і політика cache-TTL
-- `github-copilot`: онбординг/login пристрою, резервний механізм прямої сумісності вперед для моделей,
- підказки transcript для Claude-thinking, обмін токенів під час виконання та отримання endpoint usage
-- `openai`: резервний механізм прямої сумісності вперед для GPT-5.4, пряма нормалізація
- transport OpenAI, підказки відсутньої auth з урахуванням Codex, придушення Spark, синтетичні
- рядки каталогу OpenAI/Codex, політика thinking/live-model, нормалізація псевдонімів usage-token
- (сімейства `input` / `output` і `prompt` / `completion`), спільне
- сімейство stream `openai-responses-defaults` для нативних обгорток OpenAI/Codex,
- метадані provider-family, реєстрація вбудованого провайдера генерації зображень
- для `gpt-image-1` і реєстрація вбудованого провайдера генерації відео
- для `sora-2`
-- `google` і `google-gemini-cli`: резервний механізм прямої сумісності вперед для Gemini 3.1,
- нативна перевірка replay Gemini, очищення bootstrap replay, режим
- виводу reasoning з тегами, зіставлення сучасних моделей, реєстрація вбудованого провайдера
- генерації зображень для моделей Gemini image-preview і вбудована
- реєстрація провайдера генерації відео для моделей Veo; OAuth Gemini CLI також
- володіє форматуванням токенів auth-profile, розбором usage-token і отриманням
- endpoint квот для поверхонь usage
-- `moonshot`: спільний transport, нормалізація payload thinking під керуванням Plugin
-- `kilocode`: спільний transport, заголовки запитів під керуванням Plugin, нормалізація payload reasoning,
- очищення thought-signature проксійованого Gemini та політика cache-TTL
-- `zai`: резервний механізм прямої сумісності вперед для GLM-5, типові значення `tool_stream`, політика cache-TTL,
- політика binary-thinking/live-model і auth usage + отримання квот;
- невідомі ідентифікатори `glm-5*` синтезуються з вбудованого шаблону `glm-4.7`
-- `xai`: нативна нормалізація transport Responses, переписування псевдонімів `/fast` для
- швидких варіантів Grok, типовий `tool_stream`, очищення tool-schema /
- reasoning-payload, специфічне для xAI, і вбудована реєстрація провайдера генерації відео
- для `grok-imagine-video`
-- `mistral`: метадані capability під керуванням Plugin
-- `opencode` і `opencode-go`: метадані capability під керуванням Plugin плюс
- очищення thought-signature проксійованого Gemini
-- `alibaba`: каталог генерації відео під керуванням Plugin для прямих посилань на моделі Wan,
- таких як `alibaba/wan2.6-t2v`
-- `byteplus`: каталоги під керуванням Plugin плюс вбудована реєстрація провайдера генерації відео
- для моделей Seedance text-to-video/image-to-video
-- `fal`: вбудована реєстрація провайдера генерації відео для розміщених сторонніх
- моделей, реєстрація провайдера генерації зображень для моделей FLUX плюс вбудована
- реєстрація провайдера генерації відео для розміщених сторонніх відеомоделей
+- `anthropic`: резервний режим прямої сумісності вперед для Claude 4.6, підказки щодо відновлення автентифікації, отримання endpoint використання, метадані cache-TTL/сімейства постачальника та глобальні типові налаштування конфігурації з урахуванням автентифікації
+- `amazon-bedrock`: зіставлення переповнення контексту під керуванням постачальника та класифікація причин резервного переходу для специфічних для Bedrock помилок throttle/not-ready, а також спільне сімейство відтворення `anthropic-by-model` для захистів replay-policy лише для Claude на трафіку Anthropic
+- `anthropic-vertex`: захисти replay-policy лише для Claude на трафіку Anthropic-message
+- `openrouter`: наскрізні ідентифікатори моделей, обгортки запитів, підказки можливостей постачальника, санітизація thought-signature Gemini на проксійованому трафіку Gemini, інʼєкція reasoning через проксі через сімейство потоків `openrouter-thinking`, пересилання метаданих маршрутизації та політика cache-TTL
+- `github-copilot`: онбординг/вхід через пристрій, резервний режим сумісності вперед для моделей, підказки transcript для Claude-thinking, обмін рантаймових токенів та отримання endpoint використання
+- `openai`: резервний режим сумісності вперед для GPT-5.4, нормалізація прямого transport OpenAI, підказки щодо відсутньої автентифікації з урахуванням Codex, придушення Spark, synthetic рядки каталогу OpenAI/Codex, політика thinking/live-model, нормалізація псевдонімів токенів використання (`input` / `output` і сімейства `prompt` / `completion`), спільне сімейство потоків `openai-responses-defaults` для нативних обгорток OpenAI/Codex, метадані сімейства постачальника, реєстрація вбудованого постачальника генерації зображень для `gpt-image-1` і реєстрація вбудованого постачальника генерації відео для `sora-2`
+- `google` і `google-gemini-cli`: резервний режим сумісності вперед для Gemini 3.1, нативна перевірка відтворення Gemini, санітизація bootstrap replay, режим виводу reasoning із тегами, зіставлення сучасних моделей, реєстрація вбудованого постачальника генерації зображень для моделей Gemini image-preview і реєстрація вбудованого постачальника генерації відео для моделей Veo; Gemini CLI OAuth також володіє форматуванням токенів профілю автентифікації, парсингом токенів використання та отриманням endpoint квот для поверхонь використання
+- `moonshot`: спільний transport, нормалізація thinking payload під керуванням Plugin
+- `kilocode`: спільний transport, заголовки запитів під керуванням Plugin, нормалізація reasoning payload, санітизація thought-signature proxy-Gemini та політика cache-TTL
+- `zai`: резервний режим сумісності вперед для GLM-5, типові значення `tool_stream`, політика cache-TTL, політика binary-thinking/live-model та автентифікація використання + отримання квот; невідомі ідентифікатори `glm-5*` синтезуються з вбудованого шаблону `glm-4.7`
+- `xai`: нативна нормалізація transport Responses, переписування псевдонімів `/fast` для швидких варіантів Grok, типовий `tool_stream`, очищення tool-schema / reasoning-payload, специфічне для xAI, і реєстрація вбудованого постачальника генерації відео для `grok-imagine-video`
+- `mistral`: метадані можливостей під керуванням Plugin
+- `opencode` і `opencode-go`: метадані можливостей під керуванням Plugin плюс санітизація thought-signature proxy-Gemini
+- `alibaba`: каталог генерації відео під керуванням Plugin для прямих посилань на моделі Wan, таких як `alibaba/wan2.6-t2v`
+- `byteplus`: каталоги під керуванням Plugin плюс реєстрація вбудованого постачальника генерації відео для моделей Seedance text-to-video/image-to-video
+- `fal`: реєстрація вбудованого постачальника генерації відео для розміщених сторонніх моделей, реєстрація постачальника генерації зображень для моделей FLUX image плюс реєстрація вбудованого постачальника генерації відео для розміщених сторонніх відеомоделей
- `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`,
`stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` і `volcengine`:
лише каталоги під керуванням Plugin
-- `qwen`: каталоги під керуванням Plugin для текстових моделей плюс спільні
- реєстрації провайдерів media-understanding і генерації відео для його
- мультимодальних поверхонь; генерація відео Qwen використовує стандартні відеоendpoint-и DashScope з
- вбудованими моделями Wan, такими як `wan2.6-t2v` і `wan2.7-r2v`
-- `runway`: реєстрація провайдера генерації відео під керуванням Plugin для нативних
- моделей на основі завдань Runway, таких як `gen4.5`
-- `minimax`: каталоги під керуванням Plugin, вбудована реєстрація провайдера генерації відео
- для моделей Hailuo, вбудована реєстрація провайдера генерації зображень
- для `image-01`, вибір політики replay гібридного Anthropic/OpenAI та логіка auth/snapshot usage
-- `together`: каталоги під керуванням Plugin плюс вбудована реєстрація провайдера генерації відео
- для відеомоделей Wan
-- `xiaomi`: каталоги під керуванням Plugin плюс логіка auth/snapshot usage
+- `qwen`: каталоги текстових моделей під керуванням Plugin плюс спільні реєстрації постачальників media-understanding і video-generation для його мультимодальних поверхонь; генерація відео Qwen використовує стандартні video endpoint DashScope із вбудованими моделями Wan, такими як `wan2.6-t2v` і `wan2.7-r2v`
+- `runway`: реєстрація постачальника генерації відео під керуванням Plugin для нативних моделей Runway на основі задач, таких як `gen4.5`
+- `minimax`: каталоги під керуванням Plugin, реєстрація вбудованого постачальника генерації відео для моделей Hailuo, реєстрація вбудованого постачальника генерації зображень для `image-01`, гібридний вибір replay-policy Anthropic/OpenAI і логіка автентифікації/знімка використання
+- `together`: каталоги під керуванням Plugin плюс реєстрація вбудованого постачальника генерації відео для моделей Wan video
+- `xiaomi`: каталоги під керуванням Plugin плюс логіка автентифікації/знімка використання
-Вбудований Plugin `openai` тепер володіє обома ідентифікаторами провайдера: `openai` і
+Вбудований Plugin `openai` тепер володіє обома ідентифікаторами постачальника: `openai` і
`openai-codex`.
-Це охоплює провайдерів, які все ще вписуються у звичайні transport OpenClaw. Провайдер,
-якому потрібен повністю користувацький виконавець запитів, — це окрема, глибша поверхня розширення.
+Це охоплює постачальників, які все ще вкладаються у звичайні transport OpenClaw. Постачальник,
+якому потрібен повністю кастомний виконавець запитів, — це окрема, глибша поверхня розширення.
## Ротація API-ключів
-- Підтримує загальну ротацію провайдерів для вибраних провайдерів.
+- Підтримує загальну ротацію постачальників для вибраних постачальників.
- Налаштуйте кілька ключів через:
- `OPENCLAW_LIVE__KEY` (одне live-перевизначення, найвищий пріоритет)
- `_API_KEYS` (список через кому або крапку з комою)
- `_API_KEY` (основний ключ)
- `_API_KEY_*` (нумерований список, наприклад `_API_KEY_1`)
-- Для провайдерів Google також включено `GOOGLE_API_KEY` як резервний варіант.
+- Для постачальників Google `GOOGLE_API_KEY` також включається як резервний варіант.
- Порядок вибору ключів зберігає пріоритет і прибирає дублікати значень.
-- Запити повторюються з наступним ключем лише у відповідь на обмеження швидкості
- (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many
+- Запити повторюються з наступним ключем лише у відповідь на rate-limit помилки (наприклад
+ `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many
concurrent requests`, `ThrottlingException`, `concurrency limit reached`,
- `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт usage).
-- Збої, не пов’язані з обмеженням швидкості, завершуються негайно; ротація ключів не виконується.
-- Коли всі можливі ключі зазнають невдачі, повертається фінальна помилка з останньої спроби.
+ `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання).
+- Помилки, не повʼязані з rate-limit, завершуються негайно; ротація ключів не виконується.
+- Коли всі кандидати ключів вичерпано, повертається фінальна помилка з останньої спроби.
-## Вбудовані провайдери (каталог pi-ai)
+## Вбудовані постачальники (каталог pi-ai)
-OpenClaw постачається з каталогом pi‑ai. Для цих провайдерів **не потрібна**
-конфігурація `models.providers`; достатньо налаштувати auth і вибрати модель.
+OpenClaw постачається з каталогом pi‑ai. Для цих постачальників **не потрібна**
+конфігурація `models.providers`; достатньо налаштувати автентифікацію й вибрати модель.
### OpenAI
-- Провайдер: `openai`
-- Auth: `OPENAI_API_KEY`
-- Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення)
+- Постачальник: `openai`
+- Автентифікація: `OPENAI_API_KEY`
+- Необовʼязкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення)
- Приклади моделей: `openai/gpt-5.4`, `openai/gpt-5.4-pro`
- CLI: `openclaw onboard --auth-choice openai-api-key`
-- Типовий transport — `auto` (спочатку WebSocket, потім резервний SSE)
+- Типовий transport — `auto` (спочатку WebSocket, резервно SSE)
- Перевизначення для окремої моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
-- Прогрівання OpenAI Responses WebSocket типово ввімкнене через `params.openaiWsWarmup` (`true`/`false`)
+- Розігрівання OpenAI Responses WebSocket типово ввімкнене через `params.openaiWsWarmup` (`true`/`false`)
- Пріоритетну обробку OpenAI можна ввімкнути через `agents.defaults.models["openai/"].params.serviceTier`
-- `/fast` і `params.fastMode` напряму зіставляють запити `openai/*` Responses з `service_tier=priority` на `api.openai.com`
+- `/fast` і `params.fastMode` зіставляють прямі запити Responses `openai/*` з `service_tier=priority` на `api.openai.com`
- Використовуйте `params.serviceTier`, якщо вам потрібен явний рівень замість спільного перемикача `/fast`
- Приховані заголовки атрибуції OpenClaw (`originator`, `version`,
- `User-Agent`) застосовуються лише до нативного трафіку OpenAI до `api.openai.com`, а не до
+ `User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не до
загальних OpenAI-сумісних проксі
-- Нативні маршрути OpenAI також зберігають `store` Responses, підказки кешу prompt і
- формування payload сумісності reasoning OpenAI; проксійовані маршрути цього не роблять
-- `openai/gpt-5.3-codex-spark` навмисно приглушено в OpenClaw, оскільки live API OpenAI його відхиляє; Spark вважається лише Codex
+- Нативні маршрути OpenAI також зберігають `store` Responses, підказки prompt-cache і
+ формування payload сумісності reasoning OpenAI; проксі-маршрути — ні
+- `openai/gpt-5.3-codex-spark` навмисно придушено в OpenClaw, оскільки live OpenAI API його відхиляє; Spark вважається доступним лише для Codex
```json5
{
@@ -276,14 +241,14 @@ OpenClaw постачається з каталогом pi‑ai. Для цих
### Anthropic
-- Провайдер: `anthropic`
-- Auth: `ANTHROPIC_API_KEY`
-- Необов’язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (одне перевизначення)
+- Постачальник: `anthropic`
+- Автентифікація: `ANTHROPIC_API_KEY`
+- Необовʼязкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (одне перевизначення)
- Приклад моделі: `anthropic/claude-opus-4-6`
- CLI: `openclaw onboard --auth-choice apiKey`
-- Прямі публічні запити Anthropic також підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком з auth через API-ключ і OAuth, надісланим до `api.anthropic.com`; OpenClaw зіставляє це з `service_tier` Anthropic (`auto` vs `standard_only`)
-- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож OpenClaw вважає повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику.
-- Setup-token Anthropic і далі доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw віддає перевагу повторному використанню Claude CLI і `claude -p`, коли це можливо.
+- Прямі публічні запити Anthropic також підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком, автентифікованим API-ключем і OAuth, надісланим до `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`)
+- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI і `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику.
+- Setup-token Anthropic залишається доступним як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли це доступно.
```json5
{
@@ -293,20 +258,20 @@ OpenClaw постачається з каталогом pi‑ai. Для цих
### OpenAI Code (Codex)
-- Провайдер: `openai-codex`
-- Auth: OAuth (ChatGPT)
+- Постачальник: `openai-codex`
+- Автентифікація: OAuth (ChatGPT)
- Приклад моделі: `openai-codex/gpt-5.4`
- CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex`
-- Типовий transport — `auto` (спочатку WebSocket, потім резервний SSE)
+- Типовий transport — `auto` (спочатку WebSocket, резервно SSE)
- Перевизначення для окремої моделі через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
- `params.serviceTier` також пересилається в нативних запитах Codex Responses (`chatgpt.com/backend-api`)
- Приховані заголовки атрибуції OpenClaw (`originator`, `version`,
- `User-Agent`) додаються лише до нативного трафіку Codex до
+ `User-Agent`) додаються лише до нативного трафіку Codex на
`chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних проксі
-- Використовує той самий спільний перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority`
+- Використовує той самий перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority`
- `openai-codex/gpt-5.3-codex-spark` залишається доступною, коли каталог OAuth Codex її показує; залежить від entitlement
-- `openai-codex/gpt-5.4` зберігає нативні `contextWindow = 1050000` і типові під час виконання `contextTokens = 272000`; перевизначайте фактичне обмеження під час виконання через `models.providers.openai-codex.models[].contextTokens`
-- Примітка щодо політики: OAuth OpenAI Codex офіційно підтримується для зовнішніх інструментів/процесів на кшталт OpenClaw.
+- `openai-codex/gpt-5.4` зберігає нативні `contextWindow = 1050000` і типовий рантаймовий `contextTokens = 272000`; перевизначте обмеження рантайму через `models.providers.openai-codex.models[].contextTokens`
+- Примітка щодо політики: OpenAI Codex OAuth прямо підтримується для зовнішніх інструментів/робочих процесів, таких як OpenClaw.
```json5
{
@@ -326,17 +291,17 @@ OpenClaw постачається з каталогом pi‑ai. Для цих
}
```
-### Інші розміщені варіанти в підписковому стилі
+### Інші розміщені варіанти в стилі підписки
-- [Qwen Cloud](/uk/providers/qwen): поверхня провайдера Qwen Cloud плюс зіставлення endpoint-ів Alibaba DashScope і Coding Plan
+- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud плюс зіставлення endpoint Alibaba DashScope і Coding Plan
- [MiniMax](/uk/providers/minimax): доступ через OAuth або API-ключ MiniMax Coding Plan
-- [GLM Models](/uk/providers/glm): Z.AI Coding Plan або загальні API endpoint-и
+- [GLM Models](/uk/providers/glm): endpoint Z.AI Coding Plan або загальні API endpoint
### OpenCode
-- Auth: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`)
-- Провайдер середовища виконання Zen: `opencode`
-- Провайдер середовища виконання Go: `opencode-go`
+- Автентифікація: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`)
+- Постачальник рантайму Zen: `opencode`
+- Постачальник рантайму Go: `opencode-go`
- Приклади моделей: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5`
- CLI: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`
@@ -348,89 +313,87 @@ OpenClaw постачається з каталогом pi‑ai. Для цих
### Google Gemini (API-ключ)
-- Провайдер: `google`
-- Auth: `GEMINI_API_KEY`
-- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення)
+- Постачальник: `google`
+- Автентифікація: `GEMINI_API_KEY`
+- Необовʼязкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний варіант `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення)
- Приклади моделей: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview`
-- Сумісність: застаріла конфігурація OpenClaw з `google/gemini-3.1-flash-preview` нормалізується до `google/gemini-3-flash-preview`
+- Сумісність: застарілу конфігурацію OpenClaw з `google/gemini-3.1-flash-preview` нормалізовано до `google/gemini-3-flash-preview`
- CLI: `openclaw onboard --auth-choice gemini-api-key`
- Прямі запуски Gemini також приймають `agents.defaults.models["google/"].params.cachedContent`
- (або застарілий `cached_content`) для пересилання нативного для провайдера
- дескриптора `cachedContents/...`; потрапляння в кеш Gemini відображаються як OpenClaw `cacheRead`
+ (або застарілий `cached_content`) для пересилання нативного для постачальника
+ дескриптора `cachedContents/...`; cache hits Gemini відображаються як OpenClaw `cacheRead`
### Google Vertex і Gemini CLI
-- Провайдери: `google-vertex`, `google-gemini-cli`
-- Auth: Vertex використовує gcloud ADC; Gemini CLI використовує власний потік OAuth
-- Застереження: OAuth Gemini CLI в OpenClaw — це неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте неважливий обліковий запис, якщо вирішите продовжити.
+- Постачальники: `google-vertex`, `google-gemini-cli`
+- Автентифікація: Vertex використовує gcloud ADC; Gemini CLI використовує власний потік OAuth
+- Застереження: OAuth Gemini CLI в OpenClaw є неофіційною інтеграцією. Деякі користувачі повідомляли про обмеження облікових записів Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте неважливий обліковий запис, якщо вирішите продовжити.
- OAuth Gemini CLI постачається як частина вбудованого Plugin `google`.
- Спочатку встановіть Gemini CLI:
- `brew install gemini-cli`
- або `npm install -g @google/gemini-cli`
- Увімкнення: `openclaw plugins enable google`
- Вхід: `openclaw models auth login --provider google-gemini-cli --set-default`
- - Типова модель: `google-gemini-cli/gemini-3-flash-preview`
+ - Модель за замовчуванням: `google-gemini-cli/gemini-3-flash-preview`
- Примітка: вам **не потрібно** вставляти client id або secret у `openclaw.json`. Потік входу CLI зберігає
- токени в профілях auth на хості Gateway.
- - Якщо запити не працюють після входу, встановіть `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості Gateway.
- - JSON-відповіді Gemini CLI розбираються з `response`; usage резервно береться з
+ токени в профілях автентифікації на хості Gateway.
+ - Якщо після входу запити не працюють, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості Gateway.
+ - JSON-відповіді Gemini CLI парсяться з `response`; використання резервно береться з
`stats`, а `stats.cached` нормалізується в OpenClaw `cacheRead`.
### Z.AI (GLM)
-- Провайдер: `zai`
-- Auth: `ZAI_API_KEY`
+- Постачальник: `zai`
+- Автентифікація: `ZAI_API_KEY`
- Приклад моделі: `zai/glm-5.1`
- CLI: `openclaw onboard --auth-choice zai-api-key`
- Псевдоніми: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*`
- - `zai-api-key` автоматично визначає відповідний endpoint Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово задають конкретну поверхню
+ - `zai-api-key` автоматично виявляє відповідний endpoint Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово вибирають конкретну поверхню
### Vercel AI Gateway
-- Провайдер: `vercel-ai-gateway`
-- Auth: `AI_GATEWAY_API_KEY`
+- Постачальник: `vercel-ai-gateway`
+- Автентифікація: `AI_GATEWAY_API_KEY`
- Приклад моделі: `vercel-ai-gateway/anthropic/claude-opus-4.6`
- CLI: `openclaw onboard --auth-choice ai-gateway-api-key`
### Kilo Gateway
-- Провайдер: `kilocode`
-- Auth: `KILOCODE_API_KEY`
+- Постачальник: `kilocode`
+- Автентифікація: `KILOCODE_API_KEY`
- Приклад моделі: `kilocode/kilo/auto`
- CLI: `openclaw onboard --auth-choice kilocode-api-key`
-- Base URL: `https://api.kilo.ai/api/gateway/`
-- Статичний резервний каталог постачається з `kilocode/kilo/auto`; live
- виявлення через `https://api.kilo.ai/api/gateway/models` може додатково розширити каталог
- під час виконання.
+- Базовий URL: `https://api.kilo.ai/api/gateway/`
+- Статичний резервний каталог постачається з `kilocode/kilo/auto`; live-виявлення
+ `https://api.kilo.ai/api/gateway/models` може додатково розширити рантаймовий
+ каталог.
- Точна upstream-маршрутизація за `kilocode/kilo/auto` належить Kilo Gateway,
а не жорстко закодована в OpenClaw.
-Див. [/providers/kilocode](/uk/providers/kilocode) для подробиць налаштування.
+Деталі налаштування дивіться в [/providers/kilocode](/uk/providers/kilocode).
-### Інші вбудовані провайдерські Plugin
+### Інші вбудовані плагіни постачальників
- OpenRouter: `openrouter` (`OPENROUTER_API_KEY`)
- Приклад моделі: `openrouter/auto`
- OpenClaw застосовує задокументовані заголовки атрибуції застосунку OpenRouter лише тоді, коли
запит справді спрямований на `openrouter.ai`
-- Специфічні для OpenRouter маркери Anthropic `cache_control` так само обмежуються
+- Специфічні для OpenRouter маркери Anthropic `cache_control` так само обмежені
перевіреними маршрутами OpenRouter, а не довільними URL проксі
-- OpenRouter залишається на OpenAI-сумісному шляху у стилі проксі, тому нативне
- формування запитів, притаманне лише OpenAI (`serviceTier`, Responses `store`,
- підказки кешу prompt, payload сумісності reasoning OpenAI), не пересилається
-- Посилання OpenRouter на основі Gemini зберігають лише очищення thought-signature для проксійованого Gemini;
- нативна перевірка replay Gemini та переписування bootstrap залишаються вимкненими
+- OpenRouter залишається на проксі-шляху в стилі OpenAI-сумісності, тому формування запитів, притаманне лише нативному OpenAI (`serviceTier`, `store` у Responses,
+ підказки prompt-cache, payload сумісності reasoning OpenAI), не пересилається
+- Посилання OpenRouter на основі Gemini зберігають лише шлях санітизації thought-signature proxy-Gemini; нативна перевірка відтворення Gemini і переписування bootstrap лишаються вимкненими
- Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`)
- Приклад моделі: `kilocode/kilo/auto`
-- Посилання Kilo на основі Gemini зберігають той самий шлях очищення
- thought-signature для проксійованого Gemini; `kilocode/kilo/auto` та інші підказки,
- де reasoning проксі не підтримується, пропускають впровадження reasoning через проксі
+- Посилання Kilo на основі Gemini зберігають той самий шлях
+ санітизації thought-signature proxy-Gemini; `kilocode/kilo/auto` та інші підказки proxy-reasoning-unsupported
+ пропускають інʼєкцію reasoning через проксі
- MiniMax: `minimax` (API-ключ) і `minimax-portal` (OAuth)
-- Auth: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal`
+- Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal`
- Приклад моделі: `minimax/MiniMax-M2.7` або `minimax-portal/MiniMax-M2.7`
-- Налаштування онбордингу/API-ключа MiniMax записує явні визначення моделей M2.7 з
- `input: ["text", "image"]`; вбудований каталог провайдера зберігає chat-посилання
- лише текстовими, доки не буде матеріалізовано конфігурацію цього провайдера
+- Онбординг/налаштування API-ключа MiniMax записує явні визначення моделей M2.7 з
+ `input: ["text", "image"]`; вбудований каталог постачальника тримає посилання чату
+ лише текстовими, доки не буде матеріалізовано конфігурацію цього постачальника
- Moonshot: `moonshot` (`MOONSHOT_API_KEY`)
- Приклад моделі: `moonshot/kimi-k2.6`
- Kimi Coding: `kimi` (`KIMI_API_KEY` або `KIMICODE_API_KEY`)
@@ -442,7 +405,7 @@ OpenClaw постачається з каталогом pi‑ai. Для цих
- NVIDIA: `nvidia` (`NVIDIA_API_KEY`)
- Приклад моделі: `nvidia/nvidia/llama-3.1-nemotron-70b-instruct`
- StepFun: `stepfun` / `stepfun-plan` (`STEPFUN_API_KEY`)
-- Приклад моделі: `stepfun/step-3.5-flash`, `stepfun-plan/step-3.5-flash-2603`
+- Приклади моделей: `stepfun/step-3.5-flash`, `stepfun-plan/step-3.5-flash-2603`
- Together: `together` (`TOGETHER_API_KEY`)
- Приклад моделі: `together/moonshotai/Kimi-K2.5`
- Venice: `venice` (`VENICE_API_KEY`)
@@ -457,9 +420,9 @@ OpenClaw постачається з каталогом pi‑ai. Для цих
- Приклад моделі: `byteplus-plan/ark-code-latest`
- xAI: `xai` (`XAI_API_KEY`)
- Нативні вбудовані запити xAI використовують шлях xAI Responses
- - `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`,
+ - `/fast` або `params.fastMode: true` переписують `grok-3`, `grok-3-mini`,
`grok-4` і `grok-4-0709` на їхні варіанти `*-fast`
- - `tool_stream` типово ввімкнено; встановіть
+ - `tool_stream` типово ввімкнено; задайте
`agents.defaults.models["xai/"].params.tool_stream` у `false`, щоб
вимкнути його
- Mistral: `mistral` (`MISTRAL_API_KEY`)
@@ -467,27 +430,28 @@ OpenClaw постачається з каталогом pi‑ai. Для цих
- CLI: `openclaw onboard --auth-choice mistral-api-key`
- Groq: `groq` (`GROQ_API_KEY`)
- Cerebras: `cerebras` (`CEREBRAS_API_KEY`)
- - Моделі GLM на Cerebras використовують ідентифікатори `zai-glm-4.7` і `zai-glm-4.6`.
- - Base URL, сумісний з OpenAI: `https://api.cerebras.ai/v1`.
+ - Моделі GLM у Cerebras використовують ідентифікатори `zai-glm-4.7` і `zai-glm-4.6`.
+ - Базовий URL у форматі OpenAI-compatible: `https://api.cerebras.ai/v1`.
- GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`)
- Приклад моделі Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Див. [Hugging Face (Inference)](/uk/providers/huggingface).
-## Провайдери через `models.providers` (custom/base URL)
+## Постачальники через `models.providers` (кастомний/base URL)
-Використовуйте `models.providers` (або `models.json`), щоб додати **власні** провайдери або
-OpenAI/Anthropic‑сумісні проксі.
+Використовуйте `models.providers` (або `models.json`), щоб додати **кастомних** постачальників або
+OpenAI/Anthropic-compatible проксі.
-Багато з наведених нижче вбудованих провайдерських Plugin уже публікують типовий каталог.
+Багато вбудованих плагінів постачальників нижче вже публікують типовий каталог.
Використовуйте явні записи `models.providers.` лише тоді, коли хочете перевизначити
типовий base URL, заголовки або список моделей.
### Moonshot AI (Kimi)
-Moonshot постачається як вбудований провайдерський Plugin. Типово використовуйте вбудований провайдер,
-а явний запис `models.providers.moonshot` додавайте лише тоді, коли потрібно перевизначити base URL або метадані моделі:
+Moonshot постачається як вбудований Plugin постачальника. Типово використовуйте
+вбудованого постачальника й додавайте явний запис `models.providers.moonshot` лише тоді, коли
+потрібно перевизначити base URL або метадані моделі:
-- Провайдер: `moonshot`
-- Auth: `MOONSHOT_API_KEY`
+- Постачальник: `moonshot`
+- Автентифікація: `MOONSHOT_API_KEY`
- Приклад моделі: `moonshot/kimi-k2.6`
- CLI: `openclaw onboard --auth-choice moonshot-api-key` або `openclaw onboard --auth-choice moonshot-api-key-cn`
@@ -524,10 +488,10 @@ Moonshot постачається як вбудований провайдерс
### Kimi Coding
-Kimi Coding використовує Anthropic-сумісний endpoint Moonshot AI:
+Kimi Coding використовує Anthropic-compatible endpoint Moonshot AI:
-- Провайдер: `kimi`
-- Auth: `KIMI_API_KEY`
+- Постачальник: `kimi`
+- Автентифікація: `KIMI_API_KEY`
- Приклад моделі: `kimi/kimi-code`
```json5
@@ -539,14 +503,14 @@ Kimi Coding використовує Anthropic-сумісний endpoint Moonsho
}
```
-Застарілий ідентифікатор моделі `kimi/k2p5` і надалі приймається для сумісності.
+Застарілий `kimi/k2p5` і далі приймається як ідентифікатор моделі для сумісності.
### Volcano Engine (Doubao)
Volcano Engine (火山引擎) надає доступ до Doubao та інших моделей у Китаї.
-- Провайдер: `volcengine` (coding: `volcengine-plan`)
-- Auth: `VOLCANO_ENGINE_API_KEY`
+- Постачальник: `volcengine` (coding: `volcengine-plan`)
+- Автентифікація: `VOLCANO_ENGINE_API_KEY`
- Приклад моделі: `volcengine-plan/ark-code-latest`
- CLI: `openclaw onboard --auth-choice volcengine-api-key`
@@ -558,13 +522,13 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши
}
```
-Онбординг типово використовує coding-поверхню, але загальний каталог `volcengine/*`
+Онбординг типово використовує поверхню coding, але загальний каталог `volcengine/*`
реєструється одночасно.
-У засобах вибору моделей для онбордингу/налаштування вибір auth Volcengine надає перевагу обом
-рядкам `volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажені,
+У вибірниках моделей onboarding/configure для варіанта автентифікації Volcengine надається перевага як рядкам
+`volcengine/*`, так і `volcengine-plan/*`. Якщо ці моделі ще не завантажено,
OpenClaw повертається до нефільтрованого каталогу замість показу порожнього
-засобу вибору в межах провайдера.
+вибірника в межах постачальника.
Доступні моделі:
@@ -582,12 +546,12 @@ OpenClaw повертається до нефільтрованого катал
- `volcengine-plan/kimi-k2-thinking`
- `volcengine-plan/glm-4.7`
-### BytePlus (міжнародний)
+### BytePlus (Міжнародний)
BytePlus ARK надає міжнародним користувачам доступ до тих самих моделей, що й Volcano Engine.
-- Провайдер: `byteplus` (coding: `byteplus-plan`)
-- Auth: `BYTEPLUS_API_KEY`
+- Постачальник: `byteplus` (coding: `byteplus-plan`)
+- Автентифікація: `BYTEPLUS_API_KEY`
- Приклад моделі: `byteplus-plan/ark-code-latest`
- CLI: `openclaw onboard --auth-choice byteplus-api-key`
@@ -599,13 +563,13 @@ BytePlus ARK надає міжнародним користувачам дост
}
```
-Онбординг типово використовує coding-поверхню, але загальний каталог `byteplus/*`
+Онбординг типово використовує поверхню coding, але загальний каталог `byteplus/*`
реєструється одночасно.
-У засобах вибору моделей для онбордингу/налаштування вибір auth BytePlus надає перевагу обом
-рядкам `byteplus/*` і `byteplus-plan/*`. Якщо ці моделі ще не завантажені,
+У вибірниках моделей onboarding/configure для варіанта автентифікації BytePlus надається перевага як рядкам
+`byteplus/*`, так і `byteplus-plan/*`. Якщо ці моделі ще не завантажено,
OpenClaw повертається до нефільтрованого каталогу замість показу порожнього
-засобу вибору в межах провайдера.
+вибірника в межах постачальника.
Доступні моделі:
@@ -623,10 +587,10 @@ OpenClaw повертається до нефільтрованого катал
### Synthetic
-Synthetic надає Anthropic-сумісні моделі через провайдер `synthetic`:
+Synthetic надає Anthropic-compatible моделі через постачальника `synthetic`:
-- Провайдер: `synthetic`
-- Auth: `SYNTHETIC_API_KEY`
+- Постачальник: `synthetic`
+- Автентифікація: `SYNTHETIC_API_KEY`
- Приклад моделі: `synthetic/hf:MiniMaxAI/MiniMax-M2.5`
- CLI: `openclaw onboard --auth-choice synthetic-api-key`
@@ -651,37 +615,37 @@ Synthetic надає Anthropic-сумісні моделі через прова
### MiniMax
-MiniMax налаштовується через `models.providers`, оскільки використовує власні endpoint-и:
+MiniMax налаштовується через `models.providers`, оскільки використовує кастомні endpoint:
-- MiniMax OAuth (глобальний): `--auth-choice minimax-global-oauth`
+- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth`
- MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth`
-- API-ключ MiniMax (глобальний): `--auth-choice minimax-global-api`
+- API-ключ MiniMax (Global): `--auth-choice minimax-global-api`
- API-ключ MiniMax (CN): `--auth-choice minimax-cn-api`
-- Auth: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або
+- Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або
`MINIMAX_API_KEY` для `minimax-portal`
-Див. [/providers/minimax](/uk/providers/minimax) для подробиць налаштування, варіантів моделей і фрагментів конфігурації.
+Деталі налаштування, варіанти моделей і фрагменти конфігурації дивіться в [/providers/minimax](/uk/providers/minimax).
-На Anthropic-сумісному шляху потокової передачі MiniMax OpenClaw вимикає thinking
-типово, якщо ви явно його не встановите, а `/fast on` переписує
+На Anthropic-compatible шляху потокової передачі MiniMax OpenClaw типово вимикає thinking,
+якщо ви явно його не задасте, а `/fast on` переписує
`MiniMax-M2.7` на `MiniMax-M2.7-highspeed`.
-Поділ capability під керуванням Plugin:
+Розподіл можливостей під керуванням Plugin:
-- Типові значення тексту/чату залишаються на `minimax/MiniMax-M2.7`
+- Типові значення text/chat залишаються на `minimax/MiniMax-M2.7`
- Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01`
-- Розуміння зображень — це `MiniMax-VL-01` під керуванням Plugin на обох auth-шляхах MiniMax
-- Вебпошук залишається на ідентифікаторі провайдера `minimax`
+- Розуміння зображень — це `MiniMax-VL-01`, яким на обох шляхах автентифікації MiniMax керує Plugin
+- Вебпошук лишається на ідентифікаторі постачальника `minimax`
### LM Studio
-LM Studio постачається як вбудований провайдерський Plugin, який використовує нативний API:
+LM Studio постачається як вбудований Plugin постачальника, який використовує нативний API:
-- Провайдер: `lmstudio`
-- Auth: `LM_API_TOKEN`
-- Типовий base URL для inference: `http://localhost:1234/v1`
+- Постачальник: `lmstudio`
+- Автентифікація: `LM_API_TOKEN`
+- Базовий URL inference за замовчуванням: `http://localhost:1234/v1`
-Потім установіть модель (замініть на один з ідентифікаторів, повернутих `http://localhost:1234/api/v1/models`):
+Потім задайте модель (замініть на один з ідентифікаторів, які повертає `http://localhost:1234/api/v1/models`):
```json5
{
@@ -693,14 +657,14 @@ LM Studio постачається як вбудований провайдер
OpenClaw використовує нативні `/api/v1/models` і `/api/v1/models/load` LM Studio
для виявлення + автозавантаження, а `/v1/chat/completions` — типово для inference.
-Див. [/providers/lmstudio](/uk/providers/lmstudio) для налаштування та усунення несправностей.
+Налаштування й усунення несправностей дивіться в [/providers/lmstudio](/uk/providers/lmstudio).
### Ollama
-Ollama постачається як вбудований провайдерський Plugin і використовує нативний API Ollama:
+Ollama постачається як вбудований Plugin постачальника й використовує нативний API Ollama:
-- Провайдер: `ollama`
-- Auth: не потрібна (локальний сервер)
+- Постачальник: `ollama`
+- Автентифікація: не потрібна (локальний сервер)
- Приклад моделі: `ollama/llama3.3`
- Встановлення: [https://ollama.com/download](https://ollama.com/download)
@@ -717,27 +681,26 @@ ollama pull llama3.3
}
```
-Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте її через
-`OLLAMA_API_KEY`, а вбудований провайдерський Plugin додає Ollama безпосередньо до
-`openclaw onboard` і засобу вибору моделей. Див. [/providers/ollama](/uk/providers/ollama)
-для онбордингу, хмарного/локального режиму та користувацької конфігурації.
+Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте це через
+`OLLAMA_API_KEY`, а вбудований Plugin постачальника додає Ollama безпосередньо в
+`openclaw onboard` і вибірник моделей. Онбординг, хмарний/локальний режим і кастомну конфігурацію дивіться в [/providers/ollama](/uk/providers/ollama).
### vLLM
-vLLM постачається як вбудований провайдерський Plugin для локальних/self-hosted OpenAI-сумісних
-серверів:
+vLLM постачається як вбудований Plugin постачальника для локальних/self-hosted
+OpenAI-compatible серверів:
-- Провайдер: `vllm`
-- Auth: необов’язкова (залежить від вашого сервера)
-- Типовий base URL: `http://127.0.0.1:8000/v1`
+- Постачальник: `vllm`
+- Автентифікація: необовʼязкова (залежить від вашого сервера)
+- Базовий URL за замовчуванням: `http://127.0.0.1:8000/v1`
-Щоб явно ввімкнути автоматичне локальне виявлення (підійде будь-яке значення, якщо ваш сервер не вимагає auth):
+Щоб увімкнути локальне автодослідження (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікацію):
```bash
export VLLM_API_KEY="vllm-local"
```
-Потім установіть модель (замініть на один з ідентифікаторів, повернутих `/v1/models`):
+Потім задайте модель (замініть на один з ідентифікаторів, які повертає `/v1/models`):
```json5
{
@@ -747,25 +710,25 @@ export VLLM_API_KEY="vllm-local"
}
```
-Докладніше див. у [/providers/vllm](/uk/providers/vllm).
+Подробиці дивіться в [/providers/vllm](/uk/providers/vllm).
### SGLang
-SGLang постачається як вбудований провайдерський Plugin для швидких self-hosted
-OpenAI-сумісних серверів:
+SGLang постачається як вбудований Plugin постачальника для швидких self-hosted
+OpenAI-compatible серверів:
-- Провайдер: `sglang`
-- Auth: необов’язкова (залежить від вашого сервера)
-- Типовий base URL: `http://127.0.0.1:30000/v1`
+- Постачальник: `sglang`
+- Автентифікація: необовʼязкова (залежить від вашого сервера)
+- Базовий URL за замовчуванням: `http://127.0.0.1:30000/v1`
-Щоб явно ввімкнути автоматичне локальне виявлення (підійде будь-яке значення, якщо ваш сервер не
-вимагає auth):
+Щоб увімкнути локальне автодослідження (підійде будь-яке значення, якщо ваш сервер не
+вимагає автентифікацію):
```bash
export SGLANG_API_KEY="sglang-local"
```
-Потім установіть модель (замініть на один з ідентифікаторів, повернутих `/v1/models`):
+Потім задайте модель (замініть на один з ідентифікаторів, які повертає `/v1/models`):
```json5
{
@@ -775,11 +738,11 @@ export SGLANG_API_KEY="sglang-local"
}
```
-Докладніше див. у [/providers/sglang](/uk/providers/sglang).
+Подробиці дивіться в [/providers/sglang](/uk/providers/sglang).
### Локальні проксі (LM Studio, vLLM, LiteLLM тощо)
-Приклад (OpenAI‑сумісний):
+Приклад (OpenAI-compatible):
```json5
{
@@ -814,20 +777,20 @@ export SGLANG_API_KEY="sglang-local"
Примітки:
-- Для користувацьких провайдерів `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` необов’язкові.
- Якщо їх пропущено, OpenClaw типово використовує:
+- Для кастомних постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` необовʼязкові.
+ Якщо їх не задано, OpenClaw типово використовує:
- `reasoning: false`
- `input: ["text"]`
- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
- `contextWindow: 200000`
- `maxTokens: 8192`
-- Рекомендовано: задавайте явні значення, що відповідають лімітам вашого проксі/моделі.
-- Для `api: "openai-completions"` на не-нативних endpoint-ах (будь-який непорожній `baseUrl`, чий хост не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникати помилок провайдера 400 для непідтримуваних ролей `developer`.
-- Маршрути OpenAI-сумісного типу через проксі також пропускають нативне формування
- запитів, притаманне лише OpenAI: без `service_tier`, без `store` Responses, без підказок кешу prompt, без
+- Рекомендовано: задайте явні значення, які відповідають обмеженням вашого проксі/моделі.
+- Для `api: "openai-completions"` на не нативних endpoint (будь-який непорожній `baseUrl`, чий хост не є `api.openai.com`), OpenClaw примусово задає `compat.supportsDeveloperRole: false`, щоб уникати помилок постачальника 400 для непідтримуваних ролей `developer`.
+- Проксі-маршрути в стилі OpenAI-compatible також пропускають нативне формування запитів лише для OpenAI:
+ без `service_tier`, без `store` у Responses, без підказок prompt-cache, без
формування payload сумісності reasoning OpenAI і без прихованих заголовків атрибуції OpenClaw.
-- Якщо `baseUrl` порожній/пропущений, OpenClaw зберігає типову поведінку OpenAI (яка веде до `api.openai.com`).
-- З міркувань безпеки явне `compat.supportsDeveloperRole: true` усе одно перевизначається на не-нативних endpoint-ах `openai-completions`.
+- Якщо `baseUrl` порожній/не вказаний, OpenClaw зберігає типову поведінку OpenAI (яка резолвиться в `api.openai.com`).
+- Для безпеки явне `compat.supportsDeveloperRole: true` усе одно перевизначається на не нативних endpoint `openai-completions`.
## Приклади CLI
@@ -839,9 +802,9 @@ openclaw models list
Див. також: [/gateway/configuration](/uk/gateway/configuration) для повних прикладів конфігурації.
-## Пов’язані сторінки
+## Повʼязане
- [Models](/uk/concepts/models) — конфігурація моделей і псевдоніми
-- [Model Failover](/uk/concepts/model-failover) — ланцюжки резервного переходу та поведінка повторних спроб
+- [Model Failover](/uk/concepts/model-failover) — ланцюги резервного переходу й поведінка повторних спроб
- [Configuration Reference](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделей
-- [Providers](/uk/providers) — посібники з налаштування для кожного провайдера
+- [Providers](/uk/providers) — посібники з налаштування для кожного постачальника окремо
diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md
index 71fa15d4c..956d072e0 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-21T04:43:46Z"
+ generated_at: "2026-04-21T06:04:46Z"
model: gpt-5.4
provider: openai
- source_hash: 1ce4b2cc50eead5411134eead2e7943ec5dab3b1a9d6772adcd422a721df5071
+ source_hash: f82a9a150a862c20863c187ac5c118b74aeac624e99849cf4c6e3fb56629423e
source_path: gateway/configuration-reference.md
workflow: 15
---
-# Довідник з конфігурації
+# Довідник із конфігурації
-Основний довідник з конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Конфігурація](/uk/gateway/configuration).
+Основний довідник із конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration).
-На цій сторінці описано основні поверхні конфігурації OpenClaw і наведено посилання назовні, коли підсистема має власний глибший довідник. Вона **не** намагається вбудувати на одній сторінці кожен каталог команд, що належить каналу/Plugin, або кожен глибокий параметр пам’яті/QMD.
+Ця сторінка охоплює основні поверхні конфігурації OpenClaw і дає посилання назовні, коли підсистема має власний, глибший довідник. Вона **не** намагається вбудувати на одній сторінці кожен каталог команд, що належить каналу/Plugin, або кожен глибокий параметр пам’яті/QMD.
Джерело істини в коді:
-- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, із метаданими bundled/plugin/channel, об’єднаними за наявності
-- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів детального перегляду
-- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш config-doc відносно поточної поверхні схеми
+- `openclaw config schema` виводить живу JSON Schema, яка використовується для валідації та Control UI, із метаданими bundled/Plugin/channel, об’єднаними за наявності
+- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів деталізації
+- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш config-doc щодо поточної поверхні схеми
Окремі глибокі довідники:
-- [Довідник з конфігурації пам’яті](/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 каталогу команд
+- [Довідник із конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації Dreaming у `plugins.entries.memory-core.config.dreaming`
+- [Слеш-команди](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд
- сторінки відповідного каналу/Plugin для поверхонь команд, специфічних для каналу
-Формат конфігурації — **JSON5** (дозволено коментарі + кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано.
+Формат конфігурації — **JSON5** (дозволені коментарі + кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено.
---
## Канали
-Кожен канал запускається автоматично, коли існує його секція конфігурації (якщо не вказано `enabled: false`).
+Кожен канал запускається автоматично, коли існує його розділ конфігурації (якщо не вказано `enabled: false`).
### Доступ до DM і груп
-Усі канали підтримують політики DM і політики груп:
+Усі канали підтримують політики DM і групові політики:
-| Політика DM | Поведінка |
-| ------------------- | --------------------------------------------------------------- |
+| Політика DM | Поведінка |
+| ------------------- | -------------------------------------------------------------- |
| `pairing` (типово) | Невідомі відправники отримують одноразовий код сполучення; власник має схвалити |
-| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволів сполучення) |
-| `open` | Дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) |
-| `disabled` | Ігнорувати всі вхідні DM |
+| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволів після сполучення) |
+| `open` | Дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) |
+| `disabled` | Ігнорувати всі вхідні DM |
-| Політика груп | Поведінка |
-| --------------------- | ------------------------------------------------------ |
-| `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволів |
-| `open` | Обійти списки дозволів груп (обмеження за згадками все одно застосовується) |
-| `disabled` | Блокувати всі повідомлення груп/кімнат |
+| Групова політика | Поведінка |
+| --------------------- | ----------------------------------------------------- |
+| `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволених |
+| `open` | Обійти списки дозволених для груп (обмеження за згадуванням усе ще застосовується) |
+| `disabled` | Блокувати всі повідомлення груп/кімнат |
-`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` провайдера не встановлено.
-Коди сполучення дійсні протягом 1 години. Кількість очікуваних запитів на сполучення DM обмежена **3 на канал**.
-Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (відмова за замовчуванням) із попередженням під час запуску.
+`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` у провайдера не встановлено.
+Коди сполучення спливають через 1 годину. Кількість очікуваних запитів на сполучення DM обмежена **3 на канал**.
+Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (fail-closed) із попередженням під час запуску.
-### Перевизначення моделі для каналу
+### Перевизначення моделей для каналів
-Використовуйте `channels.modelByChannel`, щоб жорстко прив’язати конкретні ID каналів до моделі. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Прив’язка каналу застосовується, коли сеанс ще не має перевизначення моделі (наприклад, установленого через `/model`).
+Використовуйте `channels.modelByChannel`, щоб прив’язати конкретні ID каналів до моделі. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналу застосовується, коли сесія ще не має перевизначення моделі (наприклад, установленого через `/model`).
```json5
{
@@ -87,7 +87,7 @@ x-i18n:
### Значення каналів за замовчуванням і Heartbeat
-Використовуйте `channels.defaults` для спільної поведінки політики груп і Heartbeat між провайдерами:
+Використовуйте `channels.defaults` для спільної групової політики та поведінки Heartbeat у різних провайдерів:
```json5
{
@@ -105,15 +105,15 @@ x-i18n:
}
```
-- `channels.defaults.groupPolicy`: резервна політика груп, коли `groupPolicy` на рівні провайдера не встановлено.
-- `channels.defaults.contextVisibility`: режим видимості додаткового контексту за замовчуванням для всіх каналів. Значення: `all` (типово, включати весь контекст цитат/гілок/історії), `allowlist` (включати контекст лише від відправників зі списку дозволів), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення для окремого каналу: `channels..contextVisibility`.
-- `channels.defaults.heartbeat.showOk`: включати статуси справних каналів у вивід Heartbeat.
-- `channels.defaults.heartbeat.showAlerts`: включати деградовані/помилкові статуси у вивід Heartbeat.
+- `channels.defaults.groupPolicy`: резервна групова політика, коли `groupPolicy` на рівні провайдера не встановлено.
+- `channels.defaults.contextVisibility`: режим видимості додаткового контексту за замовчуванням для всіх каналів. Значення: `all` (типово, включати весь контекст цитат/гілок/історії), `allowlist` (включати контекст лише від відправників зі списку дозволених), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення для каналу: `channels..contextVisibility`.
+- `channels.defaults.heartbeat.showOk`: включати стани справних каналів у вивід Heartbeat.
+- `channels.defaults.heartbeat.showAlerts`: включати стани деградації/помилок у вивід Heartbeat.
- `channels.defaults.heartbeat.useIndicator`: відображати компактний вивід Heartbeat у стилі індикатора.
### WhatsApp
-WhatsApp працює через вебканал Gateway (Baileys Web). Він запускається автоматично, коли існує прив’язаний сеанс.
+WhatsApp працює через вебканал Gateway (Baileys Web). Він запускається автоматично, коли існує прив’язана сесія.
```json5
{
@@ -124,7 +124,7 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він
textChunkLimit: 4000,
chunkMode: "length", // length | newline
mediaMaxMb: 50,
- sendReadReceipts: true, // сині галочки (false у режимі self-chat)
+ sendReadReceipts: true, // blue ticks (false in self-chat mode)
groups: {
"*": { requireMention: true },
},
@@ -164,9 +164,9 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він
}
```
-- Команди на вихід типово використовують обліковий запис `default`, якщо він існує; інакше — перший налаштований ID облікового запису (після сортування).
-- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, якщо він відповідає налаштованому ID облікового запису.
-- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується командою `openclaw doctor` до `whatsapp/default`.
+- Вихідні команди типово використовують обліковий запис `default`, якщо він є; інакше — перший налаштований ідентифікатор облікового запису (у відсортованому порядку).
+- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, якщо збігається з налаштованим ідентифікатором облікового запису.
+- Застарілий каталог автентифікації Baileys для одного облікового запису переноситься командою `openclaw doctor` до `whatsapp/default`.
- Перевизначення для окремого облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`.
@@ -226,12 +226,12 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він
```
- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; символьні посилання відхиляються), із резервним варіантом `TELEGRAM_BOT_TOKEN` для типового облікового запису.
-- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому ID облікового запису.
-- У багатооблікових конфігураціях (2+ ID облікових записів) установіть явний типовий обліковий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього немає або значення некоректне.
-- `configWrites: false` блокує ініційовані Telegram записи конфігурації (міграції ID supergroup, `/config set|unset`).
+- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, якщо збігається з налаштованим ідентифікатором облікового запису.
+- У конфігураціях із кількома обліковими записами (2+ ідентифікатори облікових записів) задайте явний типовий обліковий запис (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо його немає або він недійсний.
+- `configWrites: false` блокує ініційовані з Telegram записування конфігурації (міграції ID супергруп, `/config set|unset`).
- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
-- Попередній перегляд потоків Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах).
-- Політика повторів: див. [Політика повторів](/uk/concepts/retry).
+- Попередній перегляд потоків у Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах).
+- Політика повторних спроб: див. [Політика повторних спроб](/uk/concepts/retry).
### Discord
@@ -297,7 +297,7 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він
enabled: true,
idleHours: 24,
maxAgeHours: 0,
- spawnSubagentSessions: false, // opt-in для sessions_spawn({ thread: true })
+ spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true })
},
voice: {
enabled: true,
@@ -334,33 +334,33 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він
```
- Токен: `channels.discord.token`, із резервним варіантом `DISCORD_BOT_TOKEN` для типового облікового запису.
-- Прямі вихідні виклики, які надають явний Discord `token`, використовують цей токен для виклику; налаштування повторів/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку стану runtime.
-- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому ID облікового запису.
-- Для цілей доставки використовуйте `user:` (DM) або `channel:` (канал guild); звичайні числові ID відхиляються.
-- Slug-и guild мають нижній регістр, а пробіли в них замінюються на `-`; ключі каналів використовують slug-ім’я (без `#`). Надавайте перевагу ID guild.
-- Повідомлення, створені ботом, типово ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно фільтруються).
+- Прямі вихідні виклики, які передають явний Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку середовища виконання.
+- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо збігається з налаштованим ідентифікатором облікового запису.
+- Використовуйте `user:` (DM) або `channel:` (канал guild) для цілей доставки; прості числові ID відхиляються.
+- Slug-и guild мають нижній регістр, а пробіли замінюються на `-`; ключі каналів використовують slug-овану назву (без `#`). Переважно використовуйте ID guild.
+- Повідомлення, створені ботом, типово ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення від ботів, які згадують бота (власні повідомлення все одно фільтруються).
- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення на рівні каналу) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (за винятком @everyone/@here).
-- `maxLinesPerMessage` (типово 17) розбиває довгі за висотою повідомлення, навіть якщо вони не перевищують 2000 символів.
+- `maxLinesPerMessage` (типово 17) розбиває високі повідомлення, навіть якщо вони коротші за 2000 символів.
- `channels.discord.threadBindings` керує маршрутизацією, прив’язаною до гілок Discord:
- - `enabled`: перевизначення Discord для функцій сеансів, прив’язаних до гілок (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, а також пов’язана доставка/маршрутизація)
+ - `enabled`: перевизначення Discord для функцій сесій, прив’язаних до гілок (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язана доставка/маршрутизація)
- `idleHours`: перевизначення Discord для автоматичного зняття фокуса через неактивність у годинах (`0` вимикає)
- `maxAgeHours`: перевизначення Discord для жорсткого максимального віку в годинах (`0` вимикає)
- - `spawnSubagentSessions`: перемикач opt-in для автоматичного створення/прив’язки гілок у `sessions_spawn({ thread: true })`
+ - `spawnSubagentSessions`: перемикач увімкнення для автоматичного створення/прив’язки гілок через `sessions_spawn({ thread: true })`
- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і гілок (використовуйте id каналу/гілки в `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
- `channels.discord.ui.components.accentColor` задає колір акценту для контейнерів Discord components v2.
- `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`: нативна для Discord доставка схвалень exec і авторизація тих, хто може схвалювати.
- - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto схвалення exec активуються, коли тих, хто може схвалювати, можна визначити через `approvers` або `commands.ownerAllowFrom`.
- - `approvers`: ID користувачів Discord, яким дозволено схвалювати запити exec. Якщо не вказано, використовується `commands.ownerAllowFrom`.
- - `agentFilter`: необов’язковий список дозволених ID агентів. Не вказуйте, щоб пересилати схвалення для всіх агентів.
- - `sessionFilter`: необов’язкові шаблони ключів сеансів (підрядок або regex).
- - `target`: куди надсилати запити на схвалення. `"dm"` (типово) надсилає в DM тим, хто може схвалювати, `"channel"` надсилає у вихідний канал, `"both"` надсилає в обидва місця. Коли target включає `"channel"`, кнопки можуть використовувати лише визначені особи, що можуть схвалювати.
- - `cleanupAfterResolve`: якщо `true`, видаляє DM зі схваленням після схвалення, відхилення або тайм-ауту.
+- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` напряму передаються в параметри DAVE `@discordjs/voice` (типово `true` і `24`).
+- OpenClaw також намагається відновити прийом голосу, виходячи з голосової сесії та приєднуючись повторно після повторюваних збоїв дешифрування.
+- `channels.discord.streaming` — це канонічний ключ режиму потоку. Застарілі значення `streamMode` і логічні значення `streaming` мігруються автоматично.
+- `channels.discord.autoPresence` відображає доступність під час виконання в присутність бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу.
+- `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваними іменами/тегами (режим сумісності break-glass).
+- `channels.discord.execApprovals`: нативна для Discord доставка погоджень exec і авторизація осіб, що погоджують.
+ - `enabled`: `true`, `false` або `"auto"` (типово). В auto-режимі погодження exec активуються, коли осіб, що погоджують, можна визначити через `approvers` або `commands.ownerAllowFrom`.
+ - `approvers`: ID користувачів Discord, яким дозволено погоджувати exec-запити. Якщо поле пропущено, використовується `commands.ownerAllowFrom`.
+ - `agentFilter`: необов’язковий список дозволених ID агентів. Пропустіть, щоб передавати погодження для всіх агентів.
+ - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex).
+ - `target`: куди надсилати запити на погодження. `"dm"` (типово) надсилає в DM особам, що погоджують, `"channel"` надсилає у вихідний канал, `"both"` надсилає в обидва місця. Коли target містить `"channel"`, кнопками можуть користуватися лише визначені особи, що погоджують.
+ - `cleanupAfterResolve`: коли `true`, видаляє DM із погодженнями після погодження, відхилення або тайм-ауту.
**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (із `guilds..users` для всіх повідомлень).
@@ -393,11 +393,11 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він
}
```
-- JSON облікового запису служби: вбудований (`serviceAccount`) або на основі файла (`serviceAccountFile`).
-- Також підтримується SecretRef облікового запису служби (`serviceAccountRef`).
+- JSON службового облікового запису: вбудований (`serviceAccount`) або через файл (`serviceAccountFile`).
+- Також підтримується SecretRef службового облікового запису (`serviceAccountRef`).
- Резервні змінні середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`.
-- Для цілей доставки використовуйте `spaces/` або `users/`.
-- `channels.googlechat.dangerouslyAllowNameMatching` повторно вмикає зіставлення за змінюваним email principal (аварійний режим сумісності).
+- Використовуйте `spaces/` або `users/` для цілей доставки.
+- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваними email-principal (режим сумісності break-glass).
### Slack
@@ -464,35 +464,35 @@ WhatsApp працює через вебканал Gateway (Baileys Web). Він
}
```
-- **Socket mode** потребує і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для резервного варіанта через змінні середовища типового облікового запису).
-- **HTTP mode** потребує `botToken` плюс `signingSecret` (у корені або для окремого облікового запису).
-- `botToken`, `appToken`, `signingSecret` і `userToken` приймають звичайні текстові
+- **Socket mode** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як резервні змінні середовища для типового облікового запису).
+- **HTTP mode** вимагає `botToken` плюс `signingSecret` (у корені або для окремого облікового запису).
+- `botToken`, `appToken`, `signingSecret` і `userToken` приймають прості текстові
рядки або об’єкти SecretRef.
-- Знімки облікових записів Slack показують поля джерела/стану для кожного облікового
- даного, такі як `botTokenSource`, `botTokenStatus`, `appTokenStatus`, а в HTTP mode —
+- Знімки облікових записів Slack показують поля джерела/статусу для окремих
+ облікових даних, такі як `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у HTTP mode,
`signingSecretStatus`. `configured_unavailable` означає, що обліковий запис
- налаштовано через SecretRef, але поточний шлях команди/runtime не зміг
+ налаштований через SecretRef, але поточний шлях команди/середовища виконання не зміг
визначити значення секрету.
-- `configWrites: false` блокує записи конфігурації, ініційовані Slack.
-- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому ID облікового запису.
+- `configWrites: false` блокує ініційовані зі Slack записування конфігурації.
+- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо збігається з налаштованим ідентифікатором облікового запису.
- `channels.slack.streaming.mode` — канонічний ключ режиму потоку Slack. `channels.slack.streaming.nativeTransport` керує нативним транспортом потоків Slack. Застарілі значення `streamMode`, логічні значення `streaming` і `nativeStreaming` мігруються автоматично.
-- Для цілей доставки використовуйте `user:` (DM) або `channel:`.
+- Використовуйте `user:` (DM) або `channel:` для цілей доставки.
**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`).
-**Ізоляція сеансів гілок:** `thread.historyScope` — окремо для кожної гілки (типово) або спільно для каналу. `thread.inheritParent` копіює транскрипт батьківського каналу в нові гілки.
+**Ізоляція сесій у гілках:** `thread.historyScope` — окремо для кожної гілки (типово) або спільно для каналу. `thread.inheritParent` копіює стенограму батьківського каналу в нові гілки.
-- Нативний потоковий режим Slack разом зі статусом гілки Slack у стилі асистента "is typing..." потребують цілі відповіді у гілці. DM верхнього рівня типово залишаються поза гілками, тому вони використовують `typingReaction` або звичайну доставку замість попереднього перегляду в стилі гілки.
-- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте shortcode емодзі Slack, наприклад `"hourglass_flowing_sand"`.
-- `channels.slack.execApprovals`: нативна для Slack доставка схвалень exec і авторизація тих, хто може схвалювати. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`).
+- Нативний стримінг Slack разом зі статусом гілки Slack у стилі помічника "is typing..." вимагають цілі відповіді у гілці. DM верхнього рівня типово залишаються поза гілками, тому вони використовують `typingReaction` або звичайну доставку замість попереднього перегляду у стилі гілки.
+- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`.
+- `channels.slack.execApprovals`: нативна для Slack доставка погоджень exec і авторизація осіб, що погоджують. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`).
-| Група дій | Типово | Примітки |
-| ----------- | -------- | ------------------------- |
-| reactions | увімкнено | React + список реакцій |
-| messages | увімкнено | Читання/надсилання/редагування/видалення |
-| pins | увімкнено | Закріплення/відкріплення/список |
-| memberInfo | увімкнено | Інформація про учасника |
-| emojiList | увімкнено | Список власних емодзі |
+| Група дій | Типово | Примітки |
+| ------------ | -------- | ------------------------ |
+| reactions | увімкнено | Реагування + список реакцій |
+| messages | увімкнено | Читання/надсилання/редагування/видалення |
+| pins | увімкнено | Закріплення/відкріплення/список |
+| memberInfo | увімкнено | Інформація про учасника |
+| emojiList | увімкнено | Список користувацьких emoji |
### Mattermost
@@ -516,7 +516,7 @@ Mattermost постачається як Plugin: `openclaw plugins install @open
native: true, // opt-in
nativeSkills: true,
callbackPath: "/api/channels/mattermost/command",
- // Необов’язковий явний URL для розгортань через reverse proxy / публічних розгортань
+ // Optional explicit URL for reverse-proxy/public deployments
callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
},
textChunkLimit: 4000,
@@ -526,23 +526,23 @@ Mattermost постачається як Plugin: `openclaw plugins install @open
}
```
-Режими чату: `oncall` (відповідати на @-згадки, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса-тригера).
+Режими чату: `oncall` (відповідати на @-згадування, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса тригера).
-Коли нативні команди Mattermost увімкнено:
+Коли нативні команди Mattermost увімкнені:
- `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повним URL.
-- `commands.callbackUrl` має вказувати на endpoint Gateway OpenClaw і бути досяжним із сервера Mattermost.
-- Нативні callback-и slash-команд автентифікуються за допомогою токенів для кожної
- команди, які Mattermost повертає під час реєстрації slash-команди. Якщо реєстрація не вдається або жодну
- команду не активовано, OpenClaw відхиляє callback-и з повідомленням
+- `commands.callbackUrl` має вказувати на endpoint Gateway OpenClaw і бути доступним із сервера Mattermost.
+- Нативні зворотні виклики slash-команд автентифікуються за допомогою токенів
+ для кожної команди, які Mattermost повертає під час реєстрації slash-команд. Якщо реєстрація не вдається або жодну
+ команду не активовано, OpenClaw відхиляє зворотні виклики з помилкою
`Unauthorized: invalid command token.`
-- Для приватних/tailnet/внутрішніх хостів callback-ів Mattermost може вимагати, щоб
- `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен callback-а.
+- Для приватних/tailnet/внутрішніх хостів зворотних викликів Mattermost може вимагати,
+ щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен зворотного виклику.
Використовуйте значення хоста/домену, а не повні URL.
-- `channels.mattermost.configWrites`: дозволяє або забороняє записи конфігурації, ініційовані Mattermost.
+- `channels.mattermost.configWrites`: дозволяти або забороняти ініційовані з Mattermost записування конфігурації.
- `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в каналах.
-- `channels.mattermost.groups..requireMention`: перевизначення обмеження згадками для окремого каналу (`"*"` для типового значення).
-- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому ID облікового запису.
+- `channels.mattermost.groups..requireMention`: перевизначення обмеження за згадуванням для окремого каналу (`"*"` для типового значення).
+- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо збігається з налаштованим ідентифікатором облікового запису.
### Signal
@@ -551,7 +551,7 @@ Mattermost постачається як Plugin: `openclaw plugins install @open
channels: {
signal: {
enabled: true,
- account: "+15555550123", // необов’язкова прив’язка облікового запису
+ account: "+15555550123", // optional account binding
dmPolicy: "pairing",
allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
configWrites: true,
@@ -566,12 +566,12 @@ Mattermost постачається як Plugin: `openclaw plugins install @open
**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`).
- `channels.signal.account`: прив’язати запуск каналу до конкретної ідентичності облікового запису Signal.
-- `channels.signal.configWrites`: дозволити або заборонити записи конфігурації, ініційовані Signal.
-- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому ID облікового запису.
+- `channels.signal.configWrites`: дозволяти або забороняти ініційовані із Signal записування конфігурації.
+- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо збігається з налаштованим ідентифікатором облікового запису.
### BlueBubbles
-BlueBubbles — рекомендований шлях для iMessage (на базі Plugin, налаштовується в `channels.bluebubbles`).
+BlueBubbles — рекомендований шлях для iMessage (на основі Plugin, налаштовується в `channels.bluebubbles`).
```json5
{
@@ -586,14 +586,14 @@ BlueBubbles — рекомендований шлях для iMessage (на ба
}
```
-- Основні шляхи ключів, які тут охоплено: `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).
+- Основні шляхи ключів, охоплені тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`.
+- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, якщо збігається з налаштованим ідентифікатором облікового запису.
+- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних ACP-сесій. Використовуйте BlueBubbles handle або рядок цілі (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings).
- Повну конфігурацію каналу BlueBubbles задокументовано в [BlueBubbles](/uk/channels/bluebubbles).
### iMessage
-OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Daemon або порт не потрібні.
+OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон або порт не потрібні.
```json5
{
@@ -617,17 +617,17 @@ OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Daemon або
}
```
-- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він відповідає налаштованому ID облікового запису.
+- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо збігається з налаштованим ідентифікатором облікового запису.
-- Потрібен Full Disk Access до бази даних Messages.
-- Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів.
-- `cliPath` може вказувати на SSH-обгортку; установіть `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP.
+- Потрібен Full Disk Access до БД Messages.
+- Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб перелічити чати.
+- `cliPath` може вказувати на SSH-обгортку; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP.
- `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (типово: `/Users/*/Library/Messages/Attachments`).
- SCP використовує сувору перевірку ключа хоста, тому переконайтеся, що ключ хоста ретранслятора вже існує в `~/.ssh/known_hosts`.
-- `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).
+- `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).
-
+
```bash
#!/usr/bin/env bash
@@ -638,7 +638,7 @@ exec ssh -T gateway-host imsg "$@"
### Matrix
-Matrix працює через розширення і налаштовується в `channels.matrix`.
+Matrix працює через extension і налаштовується в `channels.matrix`.
```json5
{
@@ -668,25 +668,25 @@ Matrix працює через розширення і налаштовуєть
}
```
-- Автентифікація за токеном використовує `accessToken`; автентифікація за паролем використовує `userId` + `password`.
-- `channels.matrix.proxy` спрямовує HTTP-трафік Matrix через явний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначити це через `channels.matrix.accounts..proxy`.
-- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/внутрішні homeserver-и. `proxy` і цей opt-in для мережі — незалежні механізми керування.
-- `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у багатооблікових конфігураціях.
-- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати та нові запрошення у стилі DM ігноруються, доки ви не встановите `autoJoin: "allowlist"` разом із `autoJoinAllowlist` або `autoJoin: "always"`.
-- `channels.matrix.execApprovals`: нативна для Matrix доставка схвалень exec і авторизація тих, хто може схвалювати.
- - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto схвалення exec активуються, коли тих, хто може схвалювати, можна визначити через `approvers` або `commands.ownerAllowFrom`.
- - `approvers`: ID користувачів Matrix (наприклад `@owner:example.org`), яким дозволено схвалювати запити exec.
- - `agentFilter`: необов’язковий список дозволених ID агентів. Не вказуйте, щоб пересилати схвалення для всіх агентів.
- - `sessionFilter`: необов’язкові шаблони ключів сеансів (підрядок або regex).
- - `target`: куди надсилати запити на схвалення. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`.
+- Автентифікація токеном використовує `accessToken`; автентифікація паролем використовує `userId` + `password`.
+- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначати це через `channels.matrix.accounts..proxy`.
+- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/внутрішні homeserver. `proxy` і цей opt-in для мережі — незалежні механізми керування.
+- `channels.matrix.defaultAccount` вибирає пріоритетний обліковий запис у конфігураціях із кількома обліковими записами.
+- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати й нові запрошення у стилі DM ігноруються, доки ви не встановите `autoJoin: "allowlist"` разом із `autoJoinAllowlist` або `autoJoin: "always"`.
+- `channels.matrix.execApprovals`: нативна для Matrix доставка погоджень exec і авторизація осіб, що погоджують.
+ - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto погодження exec активуються, коли осіб, що погоджують, можна визначити через `approvers` або `commands.ownerAllowFrom`.
+ - `approvers`: ID користувачів Matrix (наприклад, `@owner:example.org`), яким дозволено погоджувати exec-запити.
+ - `agentFilter`: необов’язковий список дозволених ID агентів. Пропустіть, щоб передавати погодження для всіх агентів.
+ - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex).
+ - `target`: куди надсилати запити на погодження. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`.
- Перевизначення для окремого облікового запису: `channels.matrix.accounts..execApprovals`.
-- `channels.matrix.dm.sessionScope` керує тим, як DM Matrix групуються в сеанси: `per-user` (типово) спільний за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату.
-- Перевірки стану Matrix і живі пошуки в каталозі використовують ту саму політику проксі, що й трафік runtime.
-- Повну конфігурацію Matrix, правила вибору цілей і приклади налаштування задокументовано в [Matrix](/uk/channels/matrix).
+- `channels.matrix.dm.sessionScope` керує тим, як DM у Matrix групуються в сесії: `per-user` (типово) спільне групування за маршрутизованим peer, а `per-room` ізолює кожну DM-кімнату.
+- Перевірки статусу Matrix і live-пошуки в каталозі використовують ту саму політику проксі, що й трафік під час виконання.
+- Повну конфігурацію Matrix, правила націлювання та приклади налаштування задокументовано в [Matrix](/uk/channels/matrix).
### Microsoft Teams
-Microsoft Teams працює через розширення і налаштовується в `channels.msteams`.
+Microsoft Teams працює через extension і налаштовується в `channels.msteams`.
```json5
{
@@ -701,12 +701,12 @@ Microsoft Teams працює через розширення і налаштов
}
```
-- Основні шляхи ключів, які тут охоплено: `channels.msteams`, `channels.msteams.configWrites`.
-- Повну конфігурацію Teams (облікові дані, webhook, політика DM/груп, перевизначення для окремих команд/каналів) задокументовано в [Microsoft Teams](/uk/channels/msteams).
+- Основні шляхи ключів, охоплені тут: `channels.msteams`, `channels.msteams.configWrites`.
+- Повну конфігурацію Teams (облікові дані, webhook, політика DM/груп, перевизначення для окремих team/channel) задокументовано в [Microsoft Teams](/uk/channels/msteams).
### IRC
-IRC працює через розширення і налаштовується в `channels.irc`.
+IRC працює через extension і налаштовується в `channels.irc`.
```json5
{
@@ -727,13 +727,13 @@ 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).
+- Основні шляхи ключів, охоплені тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`.
+- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо збігається з налаштованим ідентифікатором облікового запису.
+- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/обмеження за згадуванням) задокументовано в [IRC](/uk/channels/irc).
### Багатообліковість (усі канали)
-Запускайте кілька облікових записів на канал (кожен зі своїм `accountId`):
+Запускайте кілька облікових записів на канал (кожен із власним `accountId`):
```json5
{
@@ -755,27 +755,27 @@ IRC працює через розширення і налаштовується
```
- `default` використовується, коли `accountId` пропущено (CLI + маршрутизація).
-- Токени з середовища застосовуються лише до облікового запису **default**.
-- Базові налаштування каналу застосовуються до всіх облікових записів, якщо їх не перевизначено для окремого облікового запису.
+- Токени зі змінних середовища застосовуються лише до облікового запису **default**.
+- Базові налаштування каналу застосовуються до всіх облікових записів, якщо не перевизначені для окремого облікового запису.
- Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен обліковий запис до іншого агента.
-- Якщо ви додаєте не-default обліковий запис через `openclaw channels add` (або через онбординг каналу), поки все ще перебуваєте в однoобліковій конфігурації каналу верхнього рівня, OpenClaw спочатку переносить значення верхнього рівня для одного облікового запису, пов’язані з цим обліковим записом, у карту облікових записів каналу, щоб початковий обліковий запис і далі працював. Більшість каналів переміщують їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default-ціль.
-- Наявні прив’язки лише на рівні каналу (без `accountId`) і далі відповідають обліковому запису default; прив’язки на рівні облікового запису залишаються необов’язковими.
-- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня для одного облікового запису, пов’язані з цим обліковим записом, у підвищений обліковий запис, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default-ціль.
+- Якщо ви додаєте не-default обліковий запис через `openclaw channels add` (або під час онбордингу каналу), поки ще використовуєте однооблікову конфігурацію каналу верхнього рівня, OpenClaw спочатку підвищує однооблікові значення верхнього рівня, прив’язані до облікового запису, у map облікових записів каналу, щоб початковий обліковий запис продовжив працювати. Для більшості каналів вони переміщуються в `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default-ціль.
+- Наявні прив’язки лише до каналу (без `accountId`) і далі відповідають обліковому запису default; прив’язки з областю облікового запису лишаються необов’язковими.
+- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи однооблікові значення верхнього рівня, прив’язані до облікового запису, у підвищений обліковий запис, вибраний для цього каналу. Для більшості каналів використовується `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default-ціль.
-### Інші канали розширень
+### Інші extension-канали
-Багато каналів розширень налаштовуються як `channels.` і задокументовані на своїх окремих сторінках каналів (наприклад, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch).
-Див. повний індекс каналів: [Канали](/uk/channels).
+Багато extension-каналів налаштовуються як `channels.` і задокументовані на своїх окремих сторінках каналів (наприклад, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch).
+Див. повний індекс каналів: [Channels](/uk/channels).
-### Обмеження згадками в груповому чаті
+### Обмеження за згадуванням у групових чатах
-Повідомлення в групах типово **вимагають згадки** (метадані згадки або безпечні regex-патерни). Це застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage.
+Повідомлення в групах типово **вимагають згадування** (згадування в метаданих або безпечні regex-шаблони). Застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage.
-**Типи згадок:**
+**Типи згадувань:**
-- **Згадки в метаданих**: нативні @-згадки платформи. Ігноруються в режимі self-chat WhatsApp.
-- **Текстові патерни**: безпечні regex-патерни в `agents.list[].groupChat.mentionPatterns`. Некоректні патерни та небезпечні вкладені повторення ігноруються.
-- Обмеження згадками застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один патерн).
+- **Згадування в метаданих**: нативні @-згадування платформи. Ігноруються в режимі self-chat WhatsApp.
+- **Текстові шаблони**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Недійсні шаблони та небезпечні вкладені повторення ігноруються.
+- Обмеження за згадуванням примусово застосовується лише тоді, коли виявлення можливе (нативні згадування або принаймні один шаблон).
```json5
{
@@ -788,9 +788,9 @@ IRC працює через розширення і налаштовується
}
```
-`messages.groupChat.historyLimit` задає глобальне значення за замовчуванням. Канали можуть перевизначати його через `channels..historyLimit` (або на рівні окремого облікового запису). Установіть `0`, щоб вимкнути.
+`messages.groupChat.historyLimit` задає глобальне значення за замовчуванням. Канали можуть перевизначати його через `channels..historyLimit` (або для окремого облікового запису). Установіть `0`, щоб вимкнути.
-#### Обмеження історії DM
+#### Ліміти історії DM
```json5
{
@@ -805,13 +805,13 @@ IRC працює через розширення і налаштовується
}
```
-Порядок визначення: перевизначення для конкретного DM → типове значення провайдера → без обмеження (зберігається все).
+Порядок визначення: перевизначення для окремого DM → типове значення провайдера → без обмеження (зберігається все).
Підтримується: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`.
#### Режим self-chat
-Додайте свій власний номер у `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадки, відповідає лише на текстові патерни):
+Додайте власний номер у `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадування, відповідає лише на текстові шаблони):
```json5
{
@@ -832,7 +832,7 @@ IRC працює через розширення і налаштовується
}
```
-### Команди (обробка команд чату)
+### Команди (обробка команд у чаті)
```json5
{
@@ -859,44 +859,44 @@ IRC працює через розширення і налаштовується
}
```
-
+
-- Цей блок налаштовує поверхні команд. Поточний вбудований + bundled каталог команд див. у [Slash Commands](/uk/tools/slash-commands).
-- Ця сторінка — **довідник за ключами конфігурації**, а не повний каталог команд. Команди, що належать каналу/Plugin, такі як QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, задокументовані на сторінках відповідних каналів/Plugin, а також у [Slash Commands](/uk/tools/slash-commands).
-- Текстові команди мають бути **окремими** повідомленнями з початковим `/`.
-- `native: "auto"` вмикає нативні команди для Discord/Telegram, але залишає Slack вимкненим.
-- `nativeSkills: "auto"` вмикає нативні команди Skills для Discord/Telegram, але залишає Slack вимкненим.
+- Цей блок налаштовує поверхні команд. Для поточного вбудованого + bundled каталогу команд див. [Слеш-команди](/uk/tools/slash-commands).
+- Ця сторінка — **довідник за ключами конфігурації**, а не повний каталог команд. Команди, що належать каналу/Plugin, як-от QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, задокументовані на сторінках їхніх каналів/Plugin, а також у [Слеш-командах](/uk/tools/slash-commands).
+- Текстові команди мають бути **окремими** повідомленнями, що починаються з `/`.
+- `native: "auto"` вмикає нативні команди для Discord/Telegram, а для Slack залишає вимкненими.
+- `nativeSkills: "auto"` вмикає нативні команди Skills для Discord/Telegram, а для Slack залишає вимкненими.
- Перевизначення для окремого каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди.
- Перевизначайте реєстрацію нативних команд Skills для окремого каналу через `channels..commands.nativeSkills`.
- `channels.telegram.customCommands` додає додаткові записи меню бота Telegram.
-- `bash: true` вмикає `! ` для shell хоста. Потребує `tools.elevated.enabled` і відправника в `tools.elevated.allowFrom.`.
-- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів gateway `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; доступний лише для читання `/config show` і надалі доступний звичайним клієнтам operator з правами запису.
+- `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` ігноруються).
+- `plugins: true` вмикає `/plugins` для пошуку Plugin, встановлення та керування ввімкненням/вимкненням.
+- `channels..configWrites` керує мутаціями конфігурації для окремого каналу (типово: true).
+- Для каналів із кількома обліковими записами `channels..accounts..configWrites` також керує записами, спрямованими на цей обліковий запис (наприклад, `/allowlist --config --account ` або `/config set channels..accounts....`).
+- `restart: false` вимикає дії `/restart` і інструмента перезапуску Gateway. Типово: `true`.
+- `ownerAllowFrom` — це явний список дозволених власників для команд/інструментів лише для власника. Він окремий від `allowFrom`.
+- `ownerDisplay: "hash"` хешує id власників у системному запиті. Установіть `ownerDisplaySecret`, щоб керувати хешуванням.
+- `allowFrom` налаштовується окремо для кожного провайдера. Якщо його встановлено, це **єдине** джерело авторизації (списки дозволених каналів/сполучення і `useAccessGroups` ігноруються).
- `useAccessGroups: false` дозволяє командам обходити політики груп доступу, коли `allowFrom` не встановлено.
-- Відповідність документації команд:
- - вбудований + bundled каталог: [Slash Commands](/uk/tools/slash-commands)
- - поверхні команд, специфічні для каналів: [Канали](/uk/channels)
+- Карта документації команд:
+ - вбудований + bundled каталог: [Слеш-команди](/uk/tools/slash-commands)
+ - поверхні команд, специфічні для каналів: [Channels](/uk/channels)
- команди QQ Bot: [QQ Bot](/uk/channels/qqbot)
- команди сполучення: [Pairing](/uk/channels/pairing)
- команда картки LINE: [LINE](/uk/channels/line)
- - memory Dreaming: [Dreaming](/uk/concepts/dreaming)
+ - Dreaming пам’яті: [Dreaming](/uk/concepts/dreaming)
---
-## Значення агентів за замовчуванням
+## Типові значення агентів
### `agents.defaults.workspace`
-Типово: `~/.openclaw/workspace`.
+Типове значення: `~/.openclaw/workspace`.
```json5
{
@@ -906,7 +906,7 @@ IRC працює через розширення і налаштовується
### `agents.defaults.repoRoot`
-Необов’язковий корінь репозиторію, який показується в рядку Runtime system prompt. Якщо не встановлено, OpenClaw автоматично визначає його, піднімаючись угору від workspace.
+Необов’язковий корінь репозиторію, що показується в рядку Runtime системного запиту. Якщо не встановлено, OpenClaw автоматично визначає його, підіймаючись угору від робочого простору.
```json5
{
@@ -924,23 +924,23 @@ IRC працює через розширення і налаштовується
agents: {
defaults: { skills: ["github", "weather"] },
list: [
- { id: "writer" }, // успадковує github, weather
- { id: "docs", skills: ["docs-search"] }, // замінює значення за замовчуванням
- { id: "locked-down", skills: [] }, // без Skills
+ { id: "writer" }, // inherits github, weather
+ { id: "docs", skills: ["docs-search"] }, // replaces defaults
+ { id: "locked-down", skills: [] }, // no skills
],
},
}
```
-- Не вказуйте `agents.defaults.skills`, щоб типово не обмежувати Skills.
-- Не вказуйте `agents.list[].skills`, щоб успадкувати значення за замовчуванням.
-- Установіть `agents.list[].skills: []`, щоб не було Skills.
-- Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він
- не об’єднується зі значеннями за замовчуванням.
+- Пропустіть `agents.defaults.skills`, щоб Skills типово були без обмежень.
+- Пропустіть `agents.list[].skills`, щоб успадкувати типові значення.
+- Установіть `agents.list[].skills: []`, щоб не було жодних Skills.
+- Непорожній список `agents.list[].skills` є кінцевим набором для цього агента; він
+ не об’єднується з типовими значеннями.
### `agents.defaults.skipBootstrap`
-Вимикає автоматичне створення bootstrap-файлів workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).
+Вимикає автоматичне створення bootstrap-файлів робочого простору (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`).
```json5
{
@@ -950,9 +950,9 @@ IRC працює через розширення і налаштовується
### `agents.defaults.contextInjection`
-Керує тим, коли bootstrap-файли workspace вставляються в system prompt. Типово: `"always"`.
+Керує тим, коли bootstrap-файли робочого простору вбудовуються в системний запит. Типове значення: `"always"`.
-- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторну вставку bootstrap workspace, зменшуючи розмір prompt. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст.
+- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді помічника) пропускають повторне вбудовування bootstrap-файлів робочого простору, зменшуючи розмір запиту. Запуски Heartbeat і повторні спроби після Compaction однаково перебудовують контекст.
```json5
{
@@ -962,7 +962,7 @@ IRC працює через розширення і налаштовується
### `agents.defaults.bootstrapMaxChars`
-Максимальна кількість символів на файл bootstrap workspace перед обрізанням. Типово: `12000`.
+Максимум символів на bootstrap-файл робочого простору перед обрізанням. Типове значення: `12000`.
```json5
{
@@ -972,7 +972,7 @@ IRC працює через розширення і налаштовується
### `agents.defaults.bootstrapTotalMaxChars`
-Максимальна загальна кількість символів, що вставляються з усіх bootstrap-файлів workspace. Типово: `60000`.
+Максимальна загальна кількість символів, що вбудовуються в усі bootstrap-файли робочого простору. Типове значення: `60000`.
```json5
{
@@ -982,12 +982,12 @@ IRC працює через розширення і налаштовується
### `agents.defaults.bootstrapPromptTruncationWarning`
-Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається.
-Типово: `"once"`.
+Керує видимим агенту текстом попередження, коли bootstrap-контекст обрізається.
+Типове значення: `"once"`.
-- `"off"`: ніколи не вставляти текст попередження в system prompt.
-- `"once"`: вставляти попередження один раз для кожного унікального підпису обрізання (рекомендовано).
-- `"always"`: вставляти попередження при кожному запуску, коли є обрізання.
+- `"off"`: ніколи не вбудовувати текст попередження в системний запит.
+- `"once"`: вбудовувати попередження один раз для кожного унікального підпису обрізання (рекомендовано).
+- `"always"`: вбудовувати попередження на кожному запуску, коли є обрізання.
```json5
{
@@ -995,24 +995,24 @@ IRC працює через розширення і налаштовується
}
```
-### Карта відповідальності за бюджети контексту
+### Карта власності бюджетів контексту
-OpenClaw має кілька великих бюджетів prompt/контексту, і вони
-навмисно розділені за підсистемами, а не проходять через один загальний
-параметр.
+OpenClaw має кілька великих бюджетів запиту/контексту, і вони
+навмисно розділені між підсистемами, а не проходять через один загальний
+регулятор.
- `agents.defaults.bootstrapMaxChars` /
`agents.defaults.bootstrapTotalMaxChars`:
- звичайна вставка bootstrap workspace.
+ звичайне вбудовування bootstrap робочого простору.
- `agents.defaults.startupContext.*`:
- одноразовий початковий пролог для `/new` і `/reset`, включно з недавніми щоденними
- файлами `memory/*.md`.
+ одноразова стартова преамбула `/new` і `/reset`, включно з нещодавніми
+ файлами `memory/*.md` за день.
- `skills.limits.*`:
- компактний список Skills, вставлений у system prompt.
+ компактний список Skills, вбудований у системний запит.
- `agents.defaults.contextLimits.*`:
- обмежені витяги runtime і вставлені блоки, що належать runtime.
+ обмежені витяги під час виконання та вбудовані блоки, що належать runtime.
- `memory.qmd.limits.*`:
- розмір фрагментів індексованого пошуку по пам’яті та їх вставки.
+ розмір фрагментів індексованого пошуку в пам’яті та їх вбудовування.
Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший
бюджет:
@@ -1022,7 +1022,7 @@ OpenClaw має кілька великих бюджетів prompt/контек
#### `agents.defaults.startupContext`
-Керує початковим прологом першого ходу, що вставляється в порожні запуски `/new` і `/reset`.
+Керує стартовою преамбулою першого ходу, яка вбудовується в прості запуски `/new` і `/reset`.
```json5
{
@@ -1043,7 +1043,7 @@ OpenClaw має кілька великих бюджетів prompt/контек
#### `agents.defaults.contextLimits`
-Спільні значення за замовчуванням для обмежених поверхонь контексту runtime.
+Спільні типові значення для обмежених поверхонь runtime-контексту.
```json5
{
@@ -1064,13 +1064,14 @@ OpenClaw має кілька великих бюджетів prompt/контек
метаданих обрізання та повідомлення про продовження.
- `memoryGetDefaultLines`: типове вікно рядків `memory_get`, коли `lines`
пропущено.
-- `toolResultMaxChars`: обмеження для живого результату інструмента, яке використовується для збережених результатів і
+- `toolResultMaxChars`: обмеження живого результату інструмента, що використовується для збережених результатів і
відновлення після переповнення.
-- `postCompactionMaxChars`: обмеження витягу AGENTS.md, яке використовується під час вставки оновлення після Compaction.
+- `postCompactionMaxChars`: обмеження витягу AGENTS.md, що використовується під час вбудовування
+ оновлення після Compaction.
#### `agents.list[].contextLimits`
-Перевизначення для окремого агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються
+Перевизначення для окремого агента для спільних регуляторів `contextLimits`. Пропущені поля успадковуються
з `agents.defaults.contextLimits`.
```json5
@@ -1097,7 +1098,7 @@ OpenClaw має кілька великих бюджетів prompt/контек
#### `skills.limits.maxSkillsPromptChars`
-Глобальне обмеження для компактного списку Skills, вставленого в system prompt. Це
+Глобальне обмеження для компактного списку Skills, вбудованого в системний запит. Це
не впливає на читання файлів `SKILL.md` за потреби.
```json5
@@ -1112,7 +1113,7 @@ OpenClaw має кілька великих бюджетів prompt/контек
#### `agents.list[].skillsLimits.maxSkillsPromptChars`
-Перевизначення бюджету prompt для Skills для окремого агента.
+Перевизначення бюджету запиту Skills для окремого агента.
```json5
{
@@ -1131,11 +1132,11 @@ OpenClaw має кілька великих бюджетів prompt/контек
### `agents.defaults.imageMaxDimensionPx`
-Максимальний розмір у пікселях для найдовшого боку зображення в блоках зображень transcript/tool перед викликами провайдера.
-Типово: `1200`.
+Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень стенограми/інструментів перед викликами провайдера.
+Типове значення: `1200`.
-Нижчі значення зазвичай зменшують використання vision-токенів і розмір payload запиту для запусків із великою кількістю знімків екрана.
-Вищі значення зберігають більше візуальних деталей.
+Менші значення зазвичай зменшують використання vision-token і розмір тіла запиту під час запусків із великою кількістю скриншотів.
+Більші значення зберігають більше візуальних деталей.
```json5
{
@@ -1145,7 +1146,7 @@ OpenClaw має кілька великих бюджетів prompt/контек
### `agents.defaults.userTimezone`
-Часовий пояс для контексту system prompt (не для часових позначок повідомлень). Використовує часовий пояс хоста як резервний варіант.
+Часовий пояс для контексту системного запиту (не для часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста.
```json5
{
@@ -1155,7 +1156,7 @@ OpenClaw має кілька великих бюджетів prompt/контек
### `agents.defaults.timeFormat`
-Формат часу в system prompt. Типово: `auto` (налаштування ОС).
+Формат часу в системному запиті. Типове значення: `auto` (налаштування ОС).
```json5
{
@@ -1193,7 +1194,7 @@ OpenClaw має кілька великих бюджетів prompt/контек
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5.4-mini"],
},
- params: { cacheRetention: "long" }, // глобальні типові параметри провайдера
+ params: { cacheRetention: "long" }, // global default provider params
embeddedHarness: {
runtime: "auto", // auto | pi | registered harness id, e.g. codex
fallback: "pi", // pi | none
@@ -1214,45 +1215,45 @@ OpenClaw має кілька великих бюджетів prompt/контек
- `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- Форма рядка задає лише основну модель.
- - Форма об’єкта задає основну модель плюс упорядковані резервні моделі для failover.
+ - Форма об’єкта задає основну модель плюс упорядковані моделі для failover.
- `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-1` для OpenAI Images.
- - Якщо ви напряму вибираєте `provider/model`, також налаштуйте відповідну автентифікацію/API key провайдера (наприклад `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`).
- - Якщо не вказано, `image_generate` усе одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім — решту зареєстрованих провайдерів генерації зображень у порядку ID провайдера.
+ - Якщо ви вибираєте `provider/model` напряму, також налаштуйте відповідну автентифікацію/API-ключ провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`).
+ - Якщо поле пропущено, `image_generate` усе одно може визначити типове значення провайдера на основі автентифікації. Спочатку він пробує поточного типового провайдера, а потім — решту зареєстрованих провайдерів генерації зображень у порядку id провайдера.
- `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`.
- Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`.
- - Якщо не вказано, `music_generate` усе одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім — решту зареєстрованих провайдерів генерації музики в порядку ID провайдера.
- - Якщо ви напряму вибираєте `provider/model`, також налаштуйте відповідну автентифікацію/API key провайдера.
+ - Якщо поле пропущено, `music_generate` усе одно може визначити типове значення провайдера на основі автентифікації. Спочатку він пробує поточного типового провайдера, а потім — решту зареєстрованих провайдерів генерації музики в порядку id провайдера.
+ - Якщо ви вибираєте `provider/model` напряму, також налаштуйте відповідну автентифікацію/API-ключ провайдера.
- `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`.
- Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`.
- - Якщо не вказано, `video_generate` усе одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім — решту зареєстрованих провайдерів генерації відео в порядку ID провайдера.
- - Якщо ви напряму вибираєте `provider/model`, також налаштуйте відповідну автентифікацію/API key провайдера.
- - Bundled провайдер генерації відео Qwen підтримує не більш як 1 вихідне відео, 1 вхідне зображення, 4 вхідні відео, тривалість до 10 секунд, а також параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` і `watermark`.
+ - Якщо поле пропущено, `video_generate` усе одно може визначити типове значення провайдера на основі автентифікації. Спочатку він пробує поточного типового провайдера, а потім — решту зареєстрованих провайдерів генерації відео в порядку id провайдера.
+ - Якщо ви вибираєте `provider/model` напряму, також налаштуйте відповідну автентифікацію/API-ключ провайдера.
+ - Bundled провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`.
- `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`).
- Використовується інструментом `pdf` для маршрутизації моделі.
- - Якщо не вказано, інструмент PDF повертається до `imageModel`, а потім — до визначеної моделі сеансу/типової моделі.
-- `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику.
-- `pdfMaxPages`: типова максимальна кількість сторінок, яку враховує режим резервного витягування в інструменті `pdf`.
+ - Якщо поле пропущено, інструмент PDF використовує резервно `imageModel`, а потім визначену модель сесії/типову модель.
+- `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передається під час виклику.
+- `pdfMaxPages`: типова максимальна кількість сторінок, яку враховує резервний режим витягування в інструменті `pdf`.
- `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. Типово: `"off"`.
-- `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типово: `"on"`.
-- `model.primary`: формат `provider/model` (наприклад `openai/gpt-5.4`). Якщо ви пропускаєте провайдера, OpenClaw спочатку пробує псевдонім, потім — унікальний збіг серед налаштованих провайдерів для цього точного ID моделі, і лише потім повертається до налаштованого типового провайдера (застаріла сумісна поведінка, тому надавайте перевагу явному `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення від видаленого провайдера.
-- `models`: налаштований каталог моделей і список дозволів для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`).
-- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад `{ cacheRetention: "long" }`).
-- Пріоритет об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається через `agents.defaults.models["provider/model"].params` (для окремої моделі), а потім `agents.list[].params` (для відповідного ID агента) перевизначає за ключем. Докладніше див. [Prompt Caching](/uk/reference/prompt-caching).
-- `embeddedHarness`: типова низькорівнева політика runtime для вбудованого агента. Використовуйте `runtime: "auto"`, щоб дозволити зареєстрованим harness у Plugin заявляти підтримувані моделі, `runtime: "pi"`, щоб примусово використовувати вбудований harness PI, або зареєстрований ID harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI.
-- Засоби запису конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта та, за можливості, зберігають наявні списки fallback.
-- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сеансами (кожен сеанс усе одно виконується послідовно). Типово: 4.
+- `elevatedDefault`: типовий рівень elevated-виводу для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типово: `"on"`.
+- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4`). Якщо пропустити провайдера, OpenClaw спочатку пробує alias, потім унікальний збіг налаштованого провайдера для цього точного id моделі, і лише після цього повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переключається на першу налаштовану пару провайдер/модель замість того, щоб показувати застаріле типове значення від видаленого провайдера.
+- `models`: налаштований каталог моделей і список дозволених для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`).
+- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`).
+- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), після чого `agents.list[].params` (для відповідного id агента) перевизначає за ключем. Докладніше див. [Prompt Caching](/uk/reference/prompt-caching).
+- `embeddedHarness`: типова політика низькорівневого runtime вбудованого агента. Використовуйте `runtime: "auto"`, щоб зареєстровані Plugin harness перехоплювали підтримувані моделі, `runtime: "pi"`, щоб примусово використовувати вбудований harness PI, або зареєстрований id harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід на PI.
+- Засоби запису конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта та, коли можливо, зберігають наявні списки fallback.
+- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). Типово: 4.
### `agents.defaults.embeddedHarness`
-`embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента.
-У більшості розгортань слід залишити типове значення `{ runtime: "auto", fallback: "pi" }`.
+`embeddedHarness` керує тим, який низькорівневий виконавець обробляє ходи вбудованого агента.
+У більшості розгортань варто залишити типове значення `{ runtime: "auto", fallback: "pi" }`.
Використовуйте це, коли довірений Plugin надає нативний harness, наприклад bundled
harness app-server Codex.
@@ -1270,15 +1271,15 @@ harness app-server Codex.
}
```
-- `runtime`: `"auto"`, `"pi"` або ID зареєстрованого harness у Plugin. Bundled Plugin Codex реєструє `codex`.
-- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований harness PI як сумісний резервний варіант. `"none"` спричиняє помилку, якщо вибір harness у Plugin відсутній або не підтримується, замість того щоб мовчки використовувати PI.
-- Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає резервний перехід до PI для цього процесу.
-- Для розгортань лише з Codex задайте `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`.
-- Це керує лише вбудованим chat harness. Генерація медіа, vision, PDF, музика, відео та TTS і далі використовують свої налаштування провайдера/моделі.
+- `runtime`: `"auto"`, `"pi"` або id зареєстрованого Plugin harness. Bundled Plugin Codex реєструє `codex`.
+- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований harness PI як сумісний резервний варіант. `"none"` призводить до помилки, якщо вибраний Plugin harness відсутній або не підтримується, замість тихого переходу на PI.
+- Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає резервний перехід на PI для цього процесу.
+- Для розгортань лише з Codex установіть `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`.
+- Це керує лише вбудованим chat harness. Генерація медіа, vision, PDF, музика, відео і TTS усе ще використовують власні налаштування провайдера/моделі.
-**Вбудовані скорочені псевдоніми** (застосовуються лише тоді, коли модель є в `agents.defaults.models`):
+**Скорочені вбудовані alias** (застосовуються лише коли модель є в `agents.defaults.models`):
-| Псевдонім | Модель |
+| Alias | Модель |
| ------------------- | -------------------------------------- |
| `opus` | `anthropic/claude-opus-4-6` |
| `sonnet` | `anthropic/claude-sonnet-4-6` |
@@ -1289,11 +1290,11 @@ harness app-server Codex.
| `gemini-flash` | `google/gemini-3-flash-preview` |
| `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` |
-Ваші налаштовані псевдоніми завжди мають пріоритет над типовими.
+Ваші налаштовані alias завжди мають пріоритет над типовими.
-Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не задасте `--thinking off` або не визначите `agents.defaults.models["zai/"].params.thinking` самостійно.
-Моделі Z.AI типово вмикають `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`
@@ -1326,12 +1327,12 @@ harness app-server Codex.
```
- CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені.
-- Сеанси підтримуються, коли задано `sessionArg`.
+- Сесії підтримуються, якщо задано `sessionArg`.
- Передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів.
### `agents.defaults.systemPromptOverride`
-Замінює весь system prompt, зібраний OpenClaw, на фіксований рядок. Задається на рівні значень за замовчуванням (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілами ігнорується. Корисно для контрольованих експериментів із prompt.
+Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на рівні типових значень (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілами ігнорується. Корисно для контрольованих експериментів із запитами.
```json5
{
@@ -1372,15 +1373,15 @@ harness app-server Codex.
}
```
-- `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 виконує повні ходи агента — коротші інтервали спалюють більше токенів.
+- `every`: рядок тривалості (ms/s/m/h). Типово: `30m` (автентифікація API-ключем) або `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-контекст і зберігають із bootstrap-файлів робочого простору лише `HEARTBEAT.md`.
+- `isolatedSession`: коли true, кожен запуск Heartbeat виконується в новій сесії без попередньої історії розмов. Та сама схема ізоляції, що й у Cron `sessionTarget: "isolated"`. Зменшує витрати токенів на один Heartbeat приблизно зі ~100K до ~2-5K токенів.
+- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо `heartbeat` визначено хоча б для одного агента, Heartbeat запускаються **лише для цих агентів**.
+- Heartbeat запускає повні ходи агента — коротші інтервали спалюють більше токенів.
### `agents.defaults.compaction`
@@ -1411,18 +1412,18 @@ 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`.
+- `provider`: id зареєстрованого Plugin провайдера Compaction. Якщо задано, замість вбудованого LLM-підсумовування викликається `summarize()` провайдера. У разі збою використовується вбудований механізм. Установлення провайдера примусово задає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction).
+- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції Compaction, після чого OpenClaw її перериває. Типове значення: `900`.
- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування Compaction.
- `identifierInstructions`: необов’язковий власний текст про збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`.
-- `postCompactionSections`: необов’язкові назви секцій H2/H3 з AGENTS.md, які повторно вставляються після Compaction. Типово: `["Session Startup", "Red Lines"]`; установіть `[]`, щоб вимкнути повторну вставку. Якщо значення не задано або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як застарілий резервний варіант.
-- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування Compaction. Використовуйте це, коли основний сеанс має залишатися на одній моделі, а підсумки Compaction — виконуватися на іншій; якщо не задано, Compaction використовує основну модель сеансу.
-- `notifyUser`: якщо `true`, надсилає користувачу короткі повідомлення, коли Compaction починається і коли завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб Compaction залишався непомітним.
-- `memoryFlush`: тихий агентний хід перед автоматичним Compaction для збереження довготривалої пам’яті. Пропускається, якщо workspace доступний лише для читання.
+- `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`: тихий agentic-хід перед автоматичним Compaction для збереження тривалих спогадів. Пропускається, якщо робочий простір доступний лише для читання.
### `agents.defaults.contextPruning`
-Обрізає **старі результати інструментів** з контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сеансу на диску.
+Очищує **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску.
```json5
{
@@ -1446,25 +1447,25 @@ harness app-server Codex.
-- `mode: "cache-ttl"` вмикає проходи обрізання.
-- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього звернення до кешу).
-- Обрізання спочатку м’яко скорочує надто великі результати інструментів, а потім, за потреби, повністю очищає старіші результати інструментів.
+- `mode: "cache-ttl"` вмикає проходи очищення.
+- `ttl` визначає, як часто очищення можна виконати знову (після останнього торкання кешу).
+- Очищення спочатку м’яко обрізає завеликі результати інструментів, а потім, якщо потрібно, повністю очищує старіші результати інструментів.
-**М’яке скорочення** зберігає початок і кінець та вставляє `...` посередині.
+**М’яке обрізання** зберігає початок і кінець та вставляє посередині `...`.
-**Повне очищення** замінює весь результат інструмента на заповнювач.
+**Повне очищення** замінює весь результат інструмента плейсхолдером.
Примітки:
-- Блоки зображень ніколи не скорочуються й не очищаються.
-- Співвідношення базуються на кількості символів (приблизно), а не на точній кількості токенів.
-- Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається.
+- Блоки зображень ніколи не обрізаються й не очищуються.
+- Коефіцієнти базуються на кількості символів (приблизно), а не на точній кількості токенів.
+- Якщо є менше ніж `keepLastAssistants` повідомлень помічника, очищення пропускається.
-Докладніше про поведінку див. у [Session Pruning](/uk/concepts/session-pruning).
+Подробиці поведінки див. у [Session Pruning](/uk/concepts/session-pruning).
-### Блокове потокове передавання
+### Блоковий стримінг
```json5
{
@@ -1480,13 +1481,13 @@ 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).
-### Індикатори набору тексту
+### Індикатори введення
```json5
{
@@ -1499,8 +1500,8 @@ harness app-server Codex.
}
```
-- Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки.
-- Перевизначення для сеансу: `session.typingMode`, `session.typingIntervalSeconds`.
+- Типові значення: `instant` для прямих чатів/згадувань, `message` для незгаданих групових чатів.
+- Перевизначення для сесії: `session.typingMode`, `session.typingIntervalSeconds`.
Див. [Typing Indicators](/uk/concepts/typing-indicators).
@@ -1603,52 +1604,52 @@ 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 відповідного scope
-- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, передані в OpenSSH
-- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, який OpenClaw матеріалізує у тимчасові файли під час runtime
-- `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH
+- `target`: SSH-ціль у форматі `user@host[:port]`
+- `command`: команда SSH-клієнта (типово: `ssh`)
+- `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів за scope
+- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, які передаються в OpenSSH
+- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує у тимчасові файли під час виконання
+- `strictHostKeyChecking` / `updateHostKeys`: регулятори політики ключів хоста OpenSSH
-**Пріоритет автентифікації SSH:**
+**Пріоритет SSH-автентифікації:**
- `identityData` має пріоритет над `identityFile`
- `certificateData` має пріоритет над `certificateFile`
- `knownHostsData` має пріоритет над `knownHostsFile`
-- Значення `*Data`, що використовують SecretRef, визначаються з активного знімка runtime секретів перед запуском sandbox-сеансу
+- Значення `*Data` на основі SecretRef визначаються з активного знімка runtime секретів перед початком sandbox-сесії
**Поведінка backend SSH:**
-- один раз ініціалізує віддалений workspace після створення або повторного створення
-- потім зберігає віддалений SSH-workspace як канонічний
-- спрямовує `exec`, файлові інструменти та шляхи медіа через SSH
+- один раз ініціалізує віддалений робочий простір після створення або повторного створення
+- потім зберігає віддалений робочий простір SSH як канонічний
+- маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH
- не синхронізує віддалені зміни назад на хост автоматично
- не підтримує браузерні контейнери sandbox
-**Доступ до workspace:**
+**Доступ до робочого простору:**
-- `none`: workspace sandbox для кожного scope у `~/.openclaw/sandboxes`
-- `ro`: workspace sandbox у `/workspace`, workspace агента монтується лише для читання в `/agent`
-- `rw`: workspace агента монтується для читання й запису в `/workspace`
+- `none`: робочий простір sandbox для відповідного scope у `~/.openclaw/sandboxes`
+- `ro`: робочий простір sandbox у `/workspace`, робочий простір агента монтується лише для читання в `/agent`
+- `rw`: робочий простір агента монтується для читання/запису в `/workspace`
**Scope:**
-- `session`: окремий контейнер + workspace для кожного сеансу
-- `agent`: один контейнер + workspace на агента (типово)
-- `shared`: спільний контейнер і workspace (без ізоляції між сеансами)
+- `session`: окремий контейнер + робочий простір на сесію
+- `agent`: один контейнер + робочий простір на агента (типово)
+- `shared`: спільний контейнер і робочий простір (без ізоляції між сесіями)
**Конфігурація Plugin OpenShell:**
@@ -1678,30 +1679,30 @@ harness app-server Codex.
**Режим OpenShell:**
-- `mirror`: ініціалізує віддалене середовище з локального перед `exec`, синхронізує назад після `exec`; локальний workspace залишається канонічним
-- `remote`: ініціалізує віддалене середовище один раз під час створення sandbox, потім віддалений workspace залишається канонічним
+- `mirror`: перед `exec` ініціалізує віддалене середовище з локального, після `exec` синхронізує назад; локальний робочий простір залишається канонічним
+- `remote`: один раз ініціалізує віддалене середовище під час створення sandbox, після чого віддалений робочий простір залишається канонічним
-У режимі `remote` локальні редагування на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після початкового етапу.
-Транспортом є SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою sync у режимі mirror.
+У режимі `remote` локальні редагування на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після початкової ініціалізації.
+Транспортом є SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією.
-**`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` (break-glass).
-**Вхідні вкладення** розміщуються в `media/inbound/*` в активному workspace.
+**Вхідні вкладення** розміщуються в `media/inbound/*` активного робочого простору.
-**`docker.binds`** монтує додаткові каталоги хоста; глобальні bind-монтування та bind-монтування для окремого агента об’єднуються.
+**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремого агента зливаються.
-**Ізольований браузер** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вставляється в system prompt. Не потребує `browser.enabled` в `openclaw.json`.
-Доступ спостерігача через noVNC типово використовує автентифікацію VNC, а OpenClaw видає URL з короткоживучим токеном (замість того, щоб показувати пароль у спільному URL).
+**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в системний запит. Не потребує `browser.enabled` у `openclaw.json`.
+Доступ спостерігача через noVNC типово використовує VNC-автентифікацію, а OpenClaw видає URL із короткоживучим токеном (замість показу пароля в спільному URL).
-- `allowHostControl: false` (типово) блокує для ізольованих сеансів націлювання на браузер хоста.
-- `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` і налаштовані для хостів із контейнерами:
+- `allowHostControl: false` (типово) блокує націлювання sandbox-сесій на браузер хоста.
+- `network` типово має значення `openclaw-sandbox-browser` (виділена мережа bridge). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна зв’язність bridge.
+- `cdpSourceRange` необов’язково обмежує вхідний CDP-трафік на межі контейнера до діапазону CIDR (наприклад `172.21.0.1/32`).
+- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо задано (включно з `[]`), це замінює `docker.binds` для контейнера браузера.
+- Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для хостів із контейнерами:
- `--remote-debugging-address=127.0.0.1`
- `--remote-debugging-port=`
- `--user-data-dir=${HOME}/.chrome`
@@ -1718,24 +1719,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` знову вмикає розширення, якщо ваш робочий процес
+ від них залежить.
- `--renderer-process-limit=2` можна змінити через
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати
типове обмеження процесів Chromium.
- - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли увімкнено `noSandbox`.
- - Значення за замовчуванням — це базова конфігурація образу контейнера; використовуйте власний образ браузера з власною
- точкою входу, щоб змінити типові параметри контейнера.
+ - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`.
+ - Типові значення є базовими для образу контейнера; щоб змінити типові значення контейнера,
+ використовуйте власний образ браузера з власним entrypoint.
-Ізоляція браузера та `sandbox.docker.binds` працюють лише з Docker.
+Ізоляція браузера та `sandbox.docker.binds` доступні лише для Docker.
-Зібрати образи:
+Збирання образів:
```bash
scripts/sandbox-setup.sh # основний образ sandbox
@@ -1792,26 +1793,26 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
```
- `id`: стабільний id агента (обов’язково).
-- `default`: якщо задано кілька, перший має пріоритет (записується попередження). Якщо не задано жодного, типовим стає перший елемент списку.
-- `model`: рядкова форма перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback). Cron-задачі, які перевизначають лише `primary`, усе одно успадковують типові fallback, якщо ви не вкажете `fallbacks: []`.
-- `params`: параметри потоку для окремого агента, що об’єднуються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для специфічних для агента перевизначень, як-от `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей.
-- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо не вказано, агент успадковує `agents.defaults.skills`, якщо воно задане; явний список замінює типові значення замість об’єднання, а `[]` означає відсутність Skills.
-- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не задано перевизначення для окремого повідомлення або сеансу.
-- `reasoningDefault`: необов’язкове типове значення видимості reasoning для окремого агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для окремого повідомлення або сеансу.
-- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, коли не задано перевизначення fast mode для окремого повідомлення або сеансу.
-- `embeddedHarness`: необов’язкове перевизначення низькорівневої політики harness для окремого агента. Використовуйте `{ runtime: "codex", fallback: "none" }`, щоб зробити один агент лише для Codex, поки інші агенти зберігають типовий fallback PI.
-- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` з типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати ACP harness-сеанси.
-- `identity.avatar`: шлях відносно workspace, URL `http(s)` або URI `data:`.
+- `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`: необов’язкове типове значення 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`: шлях відносно робочого простору, URL `http(s)` або URI `data:`.
- `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`.
- `subagents.allowAgents`: список дозволених id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент).
-- Захист успадкування sandbox: якщо сеанс запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які виконувалися б без sandbox.
-- `subagents.requireAgentId`: якщо true, блокує виклики `sessions_spawn`, які не задають `agentId` (примушує до явного вибору профілю; типово: false).
+- Захист успадкування sandbox: якщо сесія-запитувач працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б поза sandbox.
+- `subagents.requireAgentId`: коли true, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типово: false).
---
## Маршрутизація між агентами
-Запускайте кількох ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent).
+Запускайте кілька ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent).
```json5
{
@@ -1830,12 +1831,12 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
### Поля зіставлення прив’язок
-- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній `type` типово означає route), `acp` для постійних ACP-прив’язок розмов.
+- `type` (необов’язково): `route` для звичайної маршрутизації (якщо `type` відсутній, використовується 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 }`
**Детермінований порядок зіставлення:**
@@ -1846,11 +1847,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
5. `match.accountId: "*"` (на весь канал)
6. Типовий агент
-У межах кожного рівня перший відповідний запис у `bindings` має пріоритет.
+У межах кожного рівня перемагає перший відповідний запис `bindings`.
-Для записів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів маршрутної прив’язки.
+Для записів із `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведену вище рівневу черговість route-прив’язок.
-### Профілі доступу для окремого агента
+### Профілі доступу для окремих агентів
@@ -1870,7 +1871,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
-
+
```json5
{
@@ -1899,7 +1900,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
-
+
```json5
{
@@ -1945,11 +1946,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
-Докладніше про пріоритети див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools).
+Подробиці про пріоритети див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools).
---
-## Сеанс
+## Сесія
```json5
{
@@ -1996,37 +1997,37 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
}
```
-
+
-- **`scope`**: базова стратегія групування сеансів для контекстів групового чату.
- - `per-sender` (типово): кожен відправник отримує ізольований сеанс у межах контексту каналу.
- - `global`: усі учасники в контексті каналу спільно використовують один сеанс (використовуйте лише тоді, коли спільний контекст справді потрібен).
+- **`scope`**: базова стратегія групування сесій для контекстів групового чату.
+ - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу.
+ - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли спільний контекст справді потрібен).
- **`dmScope`**: як групуються DM.
- - `main`: усі DM спільно використовують основний сеанс.
+ - `main`: усі DM спільно використовують основну сесію.
- `per-peer`: ізоляція за id відправника між каналами.
- - `per-channel-peer`: ізоляція для кожної пари канал + відправник (рекомендовано для вхідних скриньок із кількома користувачами).
- - `per-account-channel-peer`: ізоляція для кожної трійки обліковий запис + канал + відправник (рекомендовано для багатообліковості).
-- **`identityLinks`**: зіставляє канонічні id із peer-ідентифікаторами з префіксом провайдера для спільного використання сеансів між каналами.
-- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, спрацьовує той, який настає раніше.
-- **`resetByType`**: перевизначення для окремих типів (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`.
-- **`parentForkMaxTokens`**: максимальний `totalTokens` батьківського сеансу, дозволений під час створення форкнутого сеансу гілки (типово `100000`).
- - Якщо `totalTokens` батьківського сеансу перевищує це значення, OpenClaw починає новий сеанс гілки замість успадкування історії транскрипту батьківського сеансу.
- - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти форкування від батьківського сеансу.
+ - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для спільних inbox із кількома користувачами).
+ - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для багатообліковості).
+- **`identityLinks`**: зіставлення канонічних id із peer, що мають префікс провайдера, для спільного використання сесій між каналами.
+- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, спрацьовує те, що закінчиться раніше.
+- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застаріле `dm` приймається як alias для `direct`.
+- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківської сесії, дозволене під час створення форкнутої сесії гілки (типово `100000`).
+ - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw запускає нову сесію гілки замість успадкування історії стенограми батьківської сесії.
+ - Установіть `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`).
+- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів відповіді між агентами під час обміну агент-до-агента (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжок ping-pong.
+- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет.
+- **`maintenance`**: керування очищенням сховища сесій + зберіганням.
+ - `mode`: `warn` лише видає попередження; `enforce` застосовує очищення.
+ - `pruneAfter`: віковий поріг для застарілих записів (типово `30d`).
- `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`).
- - `rotateBytes`: ротує `sessions.json`, коли його розмір перевищує це значення (типово `10mb`).
- - `resetArchiveRetention`: термін зберігання архівів транскрипту `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути.
- - `maxDiskBytes`: необов’язковий жорсткий бюджет дискового простору для каталогу сеансів. У режимі `warn` записує попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сеанси.
+ - `rotateBytes`: ротація `sessions.json`, коли він перевищує цей розмір (типово `10mb`).
+ - `resetArchiveRetention`: строк зберігання архівів стенограм `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути.
+ - `maxDiskBytes`: необов’язковий жорсткий бюджет диска для каталогу сесій. У режимі `warn` записує попередження в журнал; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії.
- `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово `80%` від `maxDiskBytes`.
-- **`threadBindings`**: глобальні типові значення для функцій сеансів, прив’язаних до гілок.
+- **`threadBindings`**: глобальні типові значення для функцій сесій, прив’язаних до гілок.
- `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`)
- `idleHours`: типове автоматичне зняття фокуса через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати)
- - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати)
+ - `maxAgeHours`: типове жорстке максимальне значення віку в годинах (`0` вимикає; провайдери можуть перевизначати)
@@ -2066,9 +2067,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
Перевизначення для окремого каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`.
-Визначення значення (найспецифічніше має пріоритет): обліковий запис → канал → глобальне. `""` вимикає й зупиняє каскадування. `"auto"` виводить `[{identity.name}]`.
+Порядок визначення (найспецифічніше має пріоритет): обліковий запис → канал → глобальне значення. `""` вимикає й зупиняє каскадування. `"auto"` виводить `[{identity.name}]`.
-**Змінні шаблону:**
+**Шаблонні змінні:**
| Змінна | Опис | Приклад |
| ----------------- | ------------------------ | --------------------------- |
@@ -2076,24 +2077,24 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` |
| `{provider}` | Назва провайдера | `anthropic` |
| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` |
-| `{identity.name}` | Назва identity агента | (те саме, що й `"auto"`) |
+| `{identity.name}` | Назва identity агента | (те саме, що `"auto"`) |
-Змінні нечутливі до регістру. `{think}` — псевдонім для `{thinkingLevel}`.
+Змінні нечутливі до регістру. `{think}` — alias для `{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.
-- `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу у Slack, Discord і Telegram.
- У Slack і Discord відсутнє значення зберігає реакції статусу увімкненими, коли активні реакції-підтвердження.
- У Telegram установіть це значення явно в `true`, щоб увімкнути реакції статусу життєвого циклу.
+- `removeAckAfterReply`: видаляє реакцію підтвердження після відповіді в Slack, Discord і Telegram.
+- `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram.
+ У Slack і Discord, якщо не задано, реакції статусу лишаються ввімкненими, коли активні реакції підтвердження.
+ У Telegram для ввімкнення реакцій статусу життєвого циклу потрібно явно встановити `true`.
-### Inbound debounce
+### Вхідний debounce
-Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди обходять debounce.
+Об’єднує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення скидаються негайно. Керувальні команди обходять debounce.
### TTS (text-to-speech)
@@ -2138,10 +2139,10 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
- `auto` керує типовим режимом auto-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує фактичний стан.
- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумовування.
-- `modelOverrides` типово увімкнено; `modelOverrides.allowProvider` типово має значення `false` (потрібен явний opt-in).
-- API key як резервний варіант використовують `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`.
+- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово має значення `false` (потрібне явне ввімкнення).
+- API-ключі резервно беруться з `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`.
- `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`.
-- Коли `openai.baseUrl` вказує на endpoint, що не належить OpenAI, OpenClaw трактує його як сумісний з OpenAI TTS-сервер і послаблює перевірку моделі/голосу.
+- Коли `openai.baseUrl` вказує на endpoint, що не належить OpenAI, OpenClaw трактує його як OpenAI-сумісний TTS-сервер і послаблює перевірку моделі/голосу.
---
@@ -2171,13 +2172,13 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
}
```
-- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кілька провайдерів Talk.
+- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька провайдерів Talk.
- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) підтримуються лише для сумісності та автоматично мігруються в `talk.providers.`.
-- Для ID голосів як резервний варіант використовуються `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`.
+- Voice ID резервно беруться з `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`.
- `providers.*.apiKey` приймає прості текстові рядки або об’єкти SecretRef.
-- Резервний варіант `ELEVENLABS_API_KEY` застосовується лише тоді, коли API key Talk не налаштовано.
+- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли ключ API для Talk не налаштовано.
- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви.
-- `silenceTimeoutMs` визначає, скільки часу режим Talk чекає після тиші користувача перед надсиланням транскрипту. Якщо значення не задано, зберігається типове для платформи вікно паузи (`700 ms на macOS і Android, 900 ms на iOS`).
+- `silenceTimeoutMs` керує тим, скільки режим Talk чекає після тиші користувача, перш ніж надіслати стенограму. Якщо не задано, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`).
---
@@ -2185,37 +2186,37 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
### Профілі інструментів
-`tools.profile` задає базовий список дозволів перед `tools.allow`/`tools.deny`:
+`tools.profile` задає базовий список дозволених перед `tools.allow`/`tools.deny`:
-Локальний онбординг типово виставляє для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються).
+Локальний онбординг типово задає новим локальним конфігураціям `tools.profile: "coding"`, якщо значення не встановлено (наявні явні профілі зберігаються).
| Профіль | Містить |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `minimal` | лише `session_status` |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `minimal` | лише `session_status` |
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` |
-| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
-| `full` | Без обмежень (те саме, що й без значення) |
+| `messaging`| `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
+| `full` | Без обмежень (те саме, що й без встановлення) |
### Групи інструментів
-| Група | Інструменти |
-| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як псевдонім для `exec`) |
-| `group: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 має пріоритет). Нечутлива до регістру, підтримує wildcard-и `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено.
+Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Нечутлива до регістру, підтримує wildcard `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено.
```json5
{
@@ -2241,7 +2242,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
### `tools.elevated`
-Керує підвищеним доступом exec поза sandbox:
+Керує elevated-доступом до exec поза sandbox:
```json5
{
@@ -2258,8 +2259,8 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
```
- Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати.
-- `/elevated on|off|ask|full` зберігає стан для кожного сеансу; вбудовані директиви застосовуються до одного повідомлення.
-- Підвищений `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціль exec — `node`).
+- `/elevated on|off|ask|full` зберігає стан для кожної сесії; вбудовані директиви застосовуються до одного повідомлення.
+- Elevated `exec` обходить sandboxing і використовує налаштований шлях виходу (`gateway` типово, або `node`, коли ціллю exec є `node`).
### `tools.exec`
@@ -2283,8 +2284,8 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
### `tools.loopDetection`
-Перевірки безпеки циклів інструментів типово **вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення.
-Налаштування можна визначати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`.
+Перевірки безпеки циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення.
+Параметри можна задавати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`.
```json5
{
@@ -2306,12 +2307,12 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
```
- `historySize`: максимальна історія викликів інструментів, що зберігається для аналізу циклів.
-- `warningThreshold`: поріг повторюваного патерна без прогресу для попереджень.
-- `criticalThreshold`: вищий поріг повторень для блокування критичних циклів.
-- `globalCircuitBreakerThreshold`: поріг жорсткої зупинки для будь-якого запуску без прогресу.
+- `warningThreshold`: поріг повторюваного шаблону без прогресу для попереджень.
+- `criticalThreshold`: вищий поріг повторення для блокування критичних циклів.
+- `globalCircuitBreakerThreshold`: жорсткий поріг зупинки для будь-якого виконання без прогресу.
- `detectors.genericRepeat`: попереджати про повторні виклики того самого інструмента з тими самими аргументами.
-- `detectors.knownPollNoProgress`: попереджати/блокувати відомі poll-інструменти (`process.poll`, `command_status` тощо).
-- `detectors.pingPong`: попереджати/блокувати чергування парних патернів без прогресу.
+- `detectors.knownPollNoProgress`: попереджати/блокувати відомі інструменти опитування (`process.poll`, `command_status` тощо).
+- `detectors.pingPong`: попереджати/блокувати чергування парних шаблонів без прогресу.
- Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, валідація завершується помилкою.
### `tools.web`
@@ -2395,15 +2396,15 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
- `capabilities`: необов’язковий список (`image`, `audio`, `video`). Типові значення: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio.
- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису.
-- У разі помилки виконується перехід до наступного запису.
+- У разі помилки використовується наступний запис.
-Автентифікація провайдера використовує стандартний порядок: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`.
+Автентифікація провайдера дотримується стандартного порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`.
**Поля async completion:**
-- `asyncCompletion.directSend`: коли `true`, завершені асинхронні задачі `music_generate`
- і `video_generate` спочатку намагаються доставитися безпосередньо в канал. Типово: `false`
- (застарілий шлях пробудження сеансу запитувача/доставки моделі).
+- `asyncCompletion.directSend`: коли `true`, завершені async-завдання `music_generate`
+ і `video_generate` спочатку намагаються доставити результат напряму в канал. Типове значення: `false`
+ (застарілий шлях пробудження сесії запитувача/доставки через модель).
@@ -2422,9 +2423,9 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
### `tools.sessions`
-Керує тим, які сеанси можуть бути ціллю для інструментів сеансів (`sessions_list`, `sessions_history`, `sessions_send`).
+Керує тим, на які сесії можна націлювати інструменти сесій (`sessions_list`, `sessions_history`, `sessions_send`).
-Типово: `tree` (поточний сеанс + сеанси, породжені ним, наприклад subagents).
+Типове значення: `tree` (поточна сесія + сесії, породжені нею, наприклад субагенти).
```json5
{
@@ -2439,11 +2440,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
Примітки:
-- `self`: лише ключ поточного сеансу.
-- `tree`: поточний сеанс + сеанси, породжені поточним сеансом (subagents).
-- `agent`: будь-який сеанс, що належить поточному id агента (може включати інших користувачів, якщо ви запускаєте сеанси per-sender під тим самим id агента).
-- `all`: будь-який сеанс. Націлювання між агентами все одно потребує `tools.agentToAgent`.
-- Обмеження sandbox: коли поточний сеанс працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`.
+- `self`: лише ключ поточної сесії.
+- `tree`: поточна сесія + сесії, породжені поточною сесією (субагенти).
+- `agent`: будь-яка сесія, що належить поточному id агента (може включати інших користувачів, якщо ви використовуєте per-sender-сесії під тим самим id агента).
+- `all`: будь-яка сесія. Націлювання між агентами все одно вимагає `tools.agentToAgent`.
+- Обмеження sandbox: коли поточна сесія працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`.
### `tools.sessions_spawn`
@@ -2468,15 +2469,15 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
Примітки:
- Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє.
-- Файли матеріалізуються в дочірньому workspace у `.openclaw/attachments//` разом із `.manifest.json`.
-- Вміст вкладень автоматично редагується під час збереження транскрипту.
-- Входи base64 перевіряються суворою перевіркою алфавіту/відступів і захистом розміру до декодування.
+- Файли матеріалізуються в робочому просторі дочірньої сесії в `.openclaw/attachments//` разом із `.manifest.json`.
+- Вміст вкладень автоматично редагується в збереженні стенограми.
+- Входи Base64 перевіряються за допомогою суворих перевірок алфавіту/доповнення та захисту розміру до декодування.
- Права доступу до файлів: `0700` для каталогів і `0600` для файлів.
-- Очищення виконується згідно з політикою `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише тоді, коли `retainOnSessionKeep: true`.
+- Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`.
### `tools.experimental`
-Прапори експериментальних вбудованих інструментів. Типово вимкнено, якщо не застосовується правило автоматичного ввімкнення strict-agentic GPT-5.
+Експериментальні прапорці вбудованих інструментів. Типово вимкнені, якщо не застосовується правило автоматичного ввімкнення для strict-agentic GPT-5.
```json5
{
@@ -2491,8 +2492,8 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
Примітки:
- `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи.
-- Типово: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску родини OpenAI або OpenAI Codex GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цим сценарієм, або `false`, щоб залишити його вимкненим навіть для запусків strict-agentic GPT-5.
-- Коли інструмент увімкнено, system prompt також додає вказівки щодо використання, щоб модель застосовувала його лише для суттєвої роботи й тримала не більш як один крок у стані `in_progress`.
+- Типове значення: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цією областю, або `false`, щоб лишити його вимкненим навіть для strict-agentic запусків GPT-5.
+- Коли інструмент увімкнено, системний запит також додає вказівки з використання, щоб модель застосовувала його лише для суттєвої роботи й тримала не більш ніж один крок у стані `in_progress`.
### `agents.defaults.subagents`
@@ -2512,16 +2513,16 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б
}
```
-- `model`: типова модель для запущених subagents. Якщо не вказано, subagents успадковують модель викликача.
-- `allowAgents`: типовий список дозволених id агентів-цілей для `sessions_spawn`, коли агент-запитувач не задає власне `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент).
-- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента не задає `runTimeoutSeconds`. `0` означає відсутність тайм-ауту.
-- Політика інструментів для subagent: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
+- `model`: типова модель для створених субагентів. Якщо не задано, субагенти успадковують модель викликача.
+- `allowAgents`: типовий список дозволених id цільових агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент).
+- `runTimeoutSeconds`: типовий timeout (у секундах) для `sessions_spawn`, коли виклик інструмента не передає `runTimeoutSeconds`. `0` означає без timeout.
+- Політика інструментів для окремого субагента: `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
{
@@ -2550,45 +2551,45 @@ OpenClaw використовує вбудований каталог модел
}
```
-- Використовуйте `authHeader: true` + `headers` для власних потреб автентифікації.
-- Перевизначайте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий псевдонім змінної середовища).
-- Пріоритет об’єднання для однакових ID провайдерів:
- - Непорожні значення `baseUrl` з `models.json` агента мають пріоритет.
- - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті config/auth-profile.
- - Значення `apiKey` провайдера, якими керує SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-ref, `secretref-managed` для file/exec-ref) замість збереження визначених секретів.
- - Значення заголовків провайдера, якими керує SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-ref, `secretref-managed` для file/exec-ref).
- - Порожні або відсутні `apiKey`/`baseUrl` агента використовують резервне значення з `models.providers` у конфігурації.
- - Для однакових моделей `contextWindow`/`maxTokens` використовують вище значення між явною конфігурацією та неявними значеннями каталогу.
- - Для однакових моделей `contextTokens` зберігає явний ліміт runtime, якщо він присутній; використовуйте його, щоб обмежити фактичний контекст без зміни нативних метаданих моделі.
- - Використовуйте `models.mode: "replace"`, якщо хочете, щоб конфігурація повністю переписала `models.json`.
- - Збереження маркерів є авторитетним за джерелом: маркери записуються з активного знімка конфігурації джерела (до визначення), а не з визначених значень секретів runtime.
+- Використовуйте `authHeader: true` + `headers` для користувацьких потреб автентифікації.
+- Перевизначайте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий alias змінної середовища).
+- Пріоритет злиття для відповідних id провайдерів:
+ - Непорожні значення `baseUrl` з agent `models.json` мають пріоритет.
+ - Непорожні значення `apiKey` з агента мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті config/auth-profile.
+ - Значення `apiKey` для провайдера під керуванням SecretRef оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження визначених секретів.
+ - Значення заголовків провайдера під керуванням SecretRef оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань).
+ - Порожні або відсутні `apiKey`/`baseUrl` у агента резервно беруться з `models.providers` у конфігурації.
+ - Для однакових моделей `contextWindow`/`maxTokens` використовують більше значення між явною конфігурацією та неявними значеннями каталогу.
+ - Для однакових моделей `contextTokens` зберігає явне runtime-обмеження, якщо воно задане; використовуйте його, щоб обмежити ефективний контекст без зміни нативних метаданих моделі.
+ - Використовуйте `models.mode: "replace"`, якщо хочете, щоб конфігурація повністю перезаписувала `models.json`.
+ - Збереження маркерів є авторитетним щодо джерела: маркери записуються з активного знімка конфігурації джерела (до визначення), а не з визначених runtime-значень секретів.
-### Деталі полів провайдера
+### Докладно про поля провайдера
- `models.mode`: поведінка каталогу провайдерів (`merge` або `replace`).
-- `models.providers`: карта власних провайдерів, ключована за id провайдера.
+- `models.providers`: map користувацьких провайдерів із ключами за id провайдера.
- `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо).
-- `models.providers.*.apiKey`: облікові дані провайдера (надавайте перевагу SecretRef/підстановці з env).
+- `models.providers.*.apiKey`: облікові дані провайдера (краще використовувати SecretRef/підстановку env).
- `models.providers.*.auth`: стратегія автентифікації (`api-key`, `token`, `oauth`, `aws-sdk`).
-- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вставляє `options.num_ctx` у запити (типово: `true`).
-- `models.providers.*.authHeader`: примусово передає облікові дані в заголовку `Authorization`, коли це потрібно.
+- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` додає `options.num_ctx` у запити (типово: `true`).
+- `models.providers.*.authHeader`: примусово передавати облікові дані в заголовку `Authorization`, коли це потрібно.
- `models.providers.*.baseUrl`: базовий URL API upstream.
-- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації через proxy/tenant.
-- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів провайдера моделей.
- - `request.headers`: додаткові заголовки (об’єднуються з типовими значеннями провайдера). Значення приймають SecretRef.
+- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації proxy/tenant.
+- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів провайдера моделі.
+ - `request.headers`: додаткові заголовки (зливаються з типовими для провайдера). Значення приймають SecretRef.
- `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value`, необов’язковим `prefix`).
- - `request.proxy`: перевизначення HTTP-proxy. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`.
+ - `request.proxy`: перевизначення HTTP-проксі. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`.
- `request.tls`: перевизначення TLS для прямих з’єднань. Поля: `ca`, `cert`, `key`, `passphrase` (усі приймають SecretRef), `serverName`, `insecureSkipVerify`.
- - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS визначається в приватні, CGNAT або подібні діапазони, через захист HTTP fetch провайдера (opt-in оператора для довірених self-hosted endpoint OpenAI-compatible). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-захист fetch. Типово `false`.
+ - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS визначається в приватні, CGNAT або подібні діапазони, через SSRF-захист HTTP-fetch провайдера (operator opt-in для довірених self-hosted OpenAI-сумісних endpoint). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-захист fetch. Типово `false`.
- `models.providers.*.models`: явні записи каталогу моделей провайдера.
- `models.providers.*.models.*.contextWindow`: метадані нативного вікна контексту моделі.
-- `models.providers.*.models.*.contextTokens`: необов’язкове обмеження контексту runtime. Використовуйте це, коли хочете менший фактичний бюджет контексту, ніж нативний `contextWindow` моделі.
-- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` з непорожнім ненативним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це значення в `false` під час runtime. Порожній/пропущений `baseUrl` зберігає типову поведінку OpenAI.
-- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-compatible chat endpoint, які приймають лише рядки. Коли `true`, OpenClaw сплющує масиви чисто текстового `messages[].content` у прості рядки перед надсиланням запиту.
-- `plugins.entries.amazon-bedrock.config.discovery`: корінь налаштувань авто-виявлення Bedrock.
+- `models.providers.*.models.*.contextTokens`: необов’язкове runtime-обмеження контексту. Використовуйте це, коли хочете менший ефективний бюджет контексту, ніж нативне `contextWindow` моделі.
+- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім не-нативним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це в `false` під час runtime. Порожній/пропущений `baseUrl` зберігає типову поведінку OpenAI.
+- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-сумісних chat-endpoint, що приймають лише рядки. Коли `true`, OpenClaw сплощує масиви чисто текстового `messages[].content` у звичайні рядки перед надсиланням запиту.
+- `plugins.entries.amazon-bedrock.config.discovery`: кореневий розділ налаштувань авто-виявлення Bedrock.
- `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне виявлення.
- `plugins.entries.amazon-bedrock.config.discovery.region`: регіон AWS для виявлення.
-- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр id провайдера для цільового виявлення.
+- `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.defaultMaxTokens`: резервна максимальна кількість вихідних токенів для виявлених моделей.
@@ -2646,7 +2647,7 @@ OpenClaw використовує вбудований каталог модел
}
```
-Установіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або `opencode-go/...` для каталогу Go. Скорочення: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`.
+Установіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або посилання `opencode-go/...` для каталогу Go. Скорочений варіант: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`.
@@ -2663,11 +2664,11 @@ OpenClaw використовує вбудований каталог модел
}
```
-Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` — прийнятні псевдоніми. Скорочення: `openclaw onboard --auth-choice zai-api-key`.
+Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` приймаються як alias. Скорочений варіант: `openclaw onboard --auth-choice zai-api-key`.
- Загальний endpoint: `https://api.z.ai/api/paas/v4`
- Endpoint для кодування (типовий): `https://api.z.ai/api/coding/paas/v4`
-- Для загального endpoint визначте власного провайдера з перевизначенням base URL.
+- Для загального endpoint визначте користувацького провайдера з перевизначенням base URL.
@@ -2708,9 +2709,9 @@ OpenClaw використовує вбудований каталог модел
Для endpoint у Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`.
-Нативні endpoint Moonshot заявляють сумісність використання потокової передачі на спільному
-транспорті `openai-completions`, і OpenClaw визначає це за можливостями endpoint,
-а не лише за вбудованим id провайдера.
+Нативні endpoint Moonshot оголошують сумісність використання стримінгу на спільному
+транспорті `openai-completions`, і OpenClaw спирається тут на можливості endpoint,
+а не лише на id вбудованого провайдера.
@@ -2728,7 +2729,7 @@ OpenClaw використовує вбудований каталог модел
}
```
-Сумісний з Anthropic, вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`.
+Anthropic-сумісний, вбудований провайдер. Скорочений варіант: `openclaw onboard --auth-choice kimi-code-api-key`.
@@ -2767,7 +2768,7 @@ OpenClaw використовує вбудований каталог модел
}
```
-Base URL має не містити `/v1` (клієнт Anthropic додає його). Скорочення: `openclaw onboard --auth-choice synthetic-api-key`.
+Base URL має бути без `/v1` (клієнт Anthropic додає його). Скорочений варіант: `openclaw onboard --auth-choice synthetic-api-key`.
@@ -2807,11 +2808,11 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й
}
```
-Установіть `MINIMAX_API_KEY`. Скорочення:
+Установіть `MINIMAX_API_KEY`. Скорочені варіанти:
`openclaw onboard --auth-choice minimax-global-api` або
`openclaw onboard --auth-choice minimax-cn-api`.
Каталог моделей типово містить лише M2.7.
-На Anthropıc-compatible шляху потокової передачі OpenClaw типово вимикає thinking MiniMax,
+На Anthropic-сумісному шляху стримінгу OpenClaw типово вимикає thinking MiniMax,
якщо ви явно не задасте `thinking` самостійно. `/fast on` або
`params.fastMode: true` переписує `MiniMax-M2.7` на
`MiniMax-M2.7-highspeed`.
@@ -2820,7 +2821,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й
-Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; зберігайте merged hosted-моделі як fallback.
+Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; залишайте hosted-моделі злитими для fallback.
@@ -2851,14 +2852,14 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й
}
```
-- `allowBundled`: необов’язковий список дозволів лише для bundled Skills (керовані/робочі Skills не зачіпаються).
+- `allowBundled`: необов’язковий список дозволених лише для bundled Skills (керовані/workspace Skills не зачіпаються).
- `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет).
-- `install.preferBrew`: коли true, віддавати перевагу інсталяторам Homebrew, якщо `brew`
+- `install.preferBrew`: коли true, надавати перевагу інсталяторам Homebrew, якщо `brew`
доступний, перш ніж переходити до інших типів інсталяторів.
-- `install.nodeManager`: перевага менеджера Node для специфікацій `metadata.openclaw.install`
+- `install.nodeManager`: бажаний node-інсталятор для специфікацій `metadata.openclaw.install`
(`npm` | `pnpm` | `yarn` | `bun`).
- `entries..enabled: false` вимикає Skill, навіть якщо він bundled/встановлений.
-- `entries..apiKey`: зручний спосіб для Skills, що оголошують основну env-змінну (простий текстовий рядок або об’єкт SecretRef).
+- `entries..apiKey`: спрощений запис для Skills, які оголошують основну env-змінну (простий рядок або об’єкт SecretRef).
---
@@ -2886,41 +2887,41 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й
}
```
-- Завантажується з `~/.openclaw/extensions`, `/.openclaw/extensions` і `plugins.load.paths`.
-- Виявлення приймає нативні Plugins OpenClaw, а також сумісні пакети Codex і пакети Claude, включно з пакетами Claude стандартного компонування без manifest.
-- **Зміни конфігурації потребують перезапуску gateway.**
-- `allow`: необов’язковий список дозволів (завантажуються лише перелічені Plugins). `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-ів, наданих пакетами.
-- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремого запуску фонових subagent.
-- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"`, лише якщо свідомо хочете дозволити будь-яку модель.
-- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (перевіряється схемою нативного Plugin OpenClaw, якщо вона доступна).
+- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions` і `plugins.load.paths`.
+- Виявлення приймає нативні Plugin OpenClaw, а також сумісні bundles Codex і Claude, включно з bundles Claude стандартного layout без manifest.
+- **Зміни конфігурації потребують перезапуску Gateway.**
+- `allow`: необов’язковий список дозволених (завантажуються лише перелічені Plugin). `deny` має пріоритет.
+- `plugins.entries..apiKey`: спрощене поле API-ключа на рівні Plugin (коли Plugin це підтримує).
+- `plugins.entries..env`: map env-змінних у межах Plugin.
+- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` і ігнорує поля зі зміною запиту з застарілого `before_agent_start`, зберігаючи при цьому застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hook Plugin і підтримуваних каталогів hook, наданих bundle.
+- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для кожного запуску фонових субагентів.
+- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень субагента. Використовуйте `"*"` лише тоді, коли свідомо хочете дозволити будь-яку модель.
+- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (перевіряється схемою нативного Plugin OpenClaw, коли вона доступна).
- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl.
- - `apiKey`: API key Firecrawl (приймає SecretRef). Використовує резервне значення з `plugins.entries.firecrawl.config.webSearch.apiKey`, legacy `tools.web.fetch.firecrawl.apiKey` або env-змінної `FIRECRAWL_API_KEY`.
+ - `apiKey`: API-ключ Firecrawl (приймає SecretRef). Резервно береться з `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілого `tools.web.fetch.firecrawl.apiKey` або env-змінної `FIRECRAWL_API_KEY`.
- `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`).
- - `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`).
+ - `onlyMainContent`: витягувати зі сторінок лише основний вміст (типово: `true`).
- `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні).
- - `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`: налаштування memory Dreaming. Фази та пороги див. у [Dreaming](/uk/concepts/dreaming).
- - `enabled`: головний перемикач Dreaming (типово `false`).
- - `frequency`: Cron-розклад для кожного повного проходу Dreaming (типово `"0 3 * * *"`).
+ - `timeoutSeconds`: timeout scrape-запиту в секундах (типово: `60`).
+- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (Grok web search).
+ - `enabled`: увімкнути провайдера X Search.
+ - `model`: модель Grok для пошуку (наприклад, `"grok-4-1-fast"`).
+- `plugins.entries.memory-core.config.dreaming`: налаштування dreaming пам’яті. Фази й пороги див. у [Dreaming](/uk/concepts/dreaming).
+ - `enabled`: головний перемикач dreaming (типово `false`).
+ - `frequency`: Cron-частота для кожного повного проходу dreaming (типово `"0 3 * * *"`).
- політика фаз і пороги — це деталі реалізації (не користувацькі ключі конфігурації).
-- Повна конфігурація memory міститься в [Довіднику з конфігурації пам’яті](/uk/reference/memory-config):
+- Повна конфігурація пам’яті міститься в [Memory configuration reference](/uk/reference/memory-config):
- `agents.defaults.memorySearch.*`
- `memory.backend`
- `memory.citations`
- `memory.qmd.*`
- `plugins.entries.memory-core.config.dreaming`
-- Увімкнені Plugins пакета Claude також можуть додавати вбудовані типові значення Pi з `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі конфігурації OpenClaw.
-- `plugins.slots.memory`: вибрати id активного Plugin пам’яті або `"none"`, щоб вимкнути Plugins пам’яті.
-- `plugins.slots.contextEngine`: вибрати id активного Plugin рушія контексту; типово `"legacy"`, доки ви не встановите й не виберете інший рушій.
-- `plugins.installs`: метадані встановлення, якими керує CLI і які використовує `openclaw plugins update`.
+- Увімкнені Plugin Claude bundle також можуть додавати вбудовані типові значення Pi із `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі конфігурації OpenClaw.
+- `plugins.slots.memory`: вибрати id активного Plugin пам’яті або `"none"`, щоб вимкнути Plugin пам’яті.
+- `plugins.slots.contextEngine`: вибрати id активного Plugin механізму контексту; типово `"legacy"`, доки ви не встановите й не виберете інший механізм.
+- `plugins.installs`: метадані встановлення, керовані CLI й використовувані `openclaw plugins update`.
- Містить `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`.
- - Розглядайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI замість ручного редагування.
+ - Сприймайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI над ручним редагуванням.
Див. [Plugins](/uk/tools/plugin).
@@ -2963,29 +2964,29 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й
```
- `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`.
-- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо значення не задано, тому навігація браузера типово залишається суворою.
+- `ssrfPolicy.dangerouslyAllowPrivateNetwork` у разі відсутності значення вимкнено, тому навігація браузера типово лишається суворою.
- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли свідомо довіряєте навігації браузера в приватній мережі.
-- У суворому режимі endpoint-и віддалених профілів CDP (`profiles.*.cdpUrl`) підлягають такому самому блокуванню приватної мережі під час перевірок доступності/виявлення.
-- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як legacy-псевдонім.
+- У суворому режимі endpoint віддалених профілів CDP (`profiles.*.cdpUrl`) підлягають тому самому блокуванню приватної мережі під час перевірок доступності/виявлення.
+- `ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як застарілий alias.
- У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків.
- Віддалені профілі працюють лише в режимі attach-only (start/stop/reset вимкнені).
- `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`.
Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S),
- коли провайдер надає вам прямий URL WebSocket DevTools.
-- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися на
- вибраному хості або через під’єднаний browser Node.
-- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний
+ коли провайдер надає вам прямий URL DevTools WebSocket.
+- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися
+ на вибраному хості або через підключений browser Node.
+- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлюватися на конкретний
профіль браузера на базі Chromium, наприклад Brave або Edge.
- Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP:
- дії на основі snapshot/ref замість націлювання за CSS-selector, hook-и
- завантаження одного файла, без перевизначень тайм-ауту діалогів, без `wait --load networkidle`,
- а також без `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій.
+ дії на основі snapshot/ref замість націлювання через CSS-селектори, hooks
+ завантаження по одному файлу, без перевизначення timeout для діалогів, без `wait --load networkidle`,
+ а також без `responsebody`, експорту PDF, перехоплення завантажень чи пакетних дій.
- Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно
задавайте `cdpUrl` лише для віддаленого CDP.
-- Порядок авто-виявлення: типовий браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
-- Сервіс керування: лише loopback (порт визначається з `gateway.port`, типово `18791`).
-- `extraArgs` додає додаткові прапори запуску до локального старту Chromium (наприклад
- `--disable-gpu`, розмір вікна або прапори налагодження).
+- Порядок автовиявлення: типовий браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
+- Control service: лише loopback (порт визначається з `gateway.port`, типово `18791`).
+- `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад,
+ `--disable-gpu`, розмір вікна або debug-прапорці).
---
@@ -3004,7 +3005,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й
```
- `seamColor`: колір акценту для chrome нативного UI застосунку (відтінок бульбашки Talk Mode тощо).
-- `assistant`: перевизначення identity для Control UI. Використовує active agent identity як резервний варіант.
+- `assistant`: перевизначення identity для Control UI. Резервно береться з identity активного агента.
---
@@ -3071,66 +3072,66 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й
}
```
-
+
-- `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`.
-- `port`: один мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`.
+- `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`.
-- **Legacy-псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хоста (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
-- **Примітка для Docker**: типовий bind `loopback` слухає `127.0.0.1` усередині контейнера. За мережі Docker bridge (`-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"`. Майстер онбордингу типово генерує 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** джерело proxy; reverse proxy loopback на тому ж хості не задовольняють auth trusted-proxy.
-- `gateway.auth.allowTailscale`: коли `true`, заголовки identity Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). Endpoint-и HTTP API **не** використовують цю auth за заголовками Tailscale; вони дотримуються звичайного режиму HTTP auth gateway. Цей безтокеновий потік передбачає, що хост 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).
-- Спроби auth для WS із походження браузера завжди обмежуються, причому звільнення для loopback вимкнено (додатковий захист від brute force localhost із браузера).
-- На loopback ці блокування з походження браузера ізольовані за нормалізованим значенням `Origin`,
- тому повторні невдачі з одного localhost origin не блокують автоматично
+- **Застарілі 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**: типово обов’язкова. Non-loopback bind вимагає автентифікації gateway. На практиці це означає спільний token/password або reverse proxy з awareness identity з `gateway.auth.mode: "trusted-proxy"`. Майстер онбордингу типово генерує token.
+- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Процеси запуску та встановлення/відновлення сервісу завершуються помилкою, коли налаштовані обидва значення, а mode не задано.
+- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних налаштувань local loopback; цей варіант навмисно не пропонується в запитах онбордингу.
+- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з awareness identity і довіряти заголовкам identity від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **non-loopback** джерело proxy; 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. Цей потік без token припускає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`.
+- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб auth. Застосовується для кожного IP клієнта і кожної області auth (shared-secret і device-token відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`.
+ - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом збою. Тому паралельні неправильні спроби від того самого клієнта можуть спрацювати на обмежувач уже на другому запиті, замість того щоб обидві одночасно пройшли як звичайні невідповідності.
+ - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; установіть `false`, коли свідомо хочете також обмежувати localhost-трафік (для тестових налаштувань або суворих proxy-розгортань).
+- Спроби auth для WS з браузерного походження завжди обмежуються без винятку для loopback (додатковий захист від brute force localhost із браузера).
+- На loopback ці блокування для браузерних походжень ізолюються за нормалізованим значенням `Origin`,
+ тому повторні збої з одного localhost-origin не блокують автоматично
інший origin.
-- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічний доступ, потребує auth).
-- `controlUi.allowedOrigins`: явний список дозволених 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`: аварійне перевизначення на стороні клієнта, яке дозволяє незашифрований `ws://` до довірених IP приватної мережі; типово незашифрований трафік і далі дозволено лише для loopback.
+- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічний, потребує auth).
+- `controlUi.allowedOrigins`: явний список дозволених browser-origin для WebSocket-підключень Gateway. Обов’язково, коли очікуються браузерні клієнти з non-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`: клієнтське break-glass-перевизначення, яке дозволяє plaintext `ws://` до довірених IP приватної мережі; типово plaintext лишається дозволеним лише для loopback.
- `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway.
-- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL для зовнішнього APNs relay, який використовують офіційні/TestFlight-збірки iOS після публікації в gateway реєстрацій на базі relay. Цей URL має збігатися з URL relay, зібраним в iOS-збірку.
-- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання gateway→relay у мілісекундах. Типово `10000`.
-- Реєстрації на базі relay делегуються конкретній identity gateway. Спарений застосунок iOS викликає `gateway.identity.get`, включає цю identity в реєстрацію relay і передає в gateway дозвіл на надсилання в межах реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію.
-- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення через env для наведеної вище конфігурації relay.
-- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний вихід лише для розробки для loopback HTTP URL relay. Продакшн URL relay мають залишатися на HTTPS.
-- `gateway.channelHealthCheckMinutes`: інтервал монітора стану каналів у хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типово: `5`.
-- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета у хвилинах. Тримайте його більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`.
-- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor для каналу/облікового запису за ковзну годину. Типово: `10`.
-- `channels..healthMonitor.enabled`: opt-out для окремого каналу від перезапусків health-monitor при збереженні глобального монітора увімкненим.
-- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису в багатооблікових каналах. Якщо задано, воно має пріоритет над перевизначенням на рівні каналу.
+- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL для зовнішнього APNs relay, який використовують офіційні/TestFlight збірки iOS після публікації relay-backed реєстрацій у gateway. Цей URL має збігатися з URL relay, вбудованим у iOS-збірку.
+- `gateway.push.apns.relay.timeoutMs`: timeout у мілісекундах для надсилання від 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`: escape hatch лише для розробки для loopback HTTP URL relay. У production URL relay мають лишатися на HTTPS.
+- `gateway.channelHealthCheckMinutes`: інтервал монітора стану каналів у хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типове значення: `5`.
+- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого socket у хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`.
+- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor на канал/обліковий запис у ковзній годині. Типове значення: `10`.
+- `channels..healthMonitor.enabled`: відмова від перезапусків health-monitor для окремого каналу, зберігаючи глобальний монітор увімкненим.
+- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису в багатооблікових каналах. Якщо задано, має пріоритет над перевизначенням на рівні каналу.
- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано.
-- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef, але не визначено, визначення завершується із закритою відмовою (без маскування резервним віддаленим варіантом).
-- `trustedProxies`: IP reverse proxy, які завершують TLS або вставляють заголовки forwarded-client. Додавайте лише proxy, які ви контролюєте. Записи loopback і далі допустимі для конфігурацій same-host 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-списку.
+- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і їх не вдалося визначити, визначення завершується в fail-closed (без маскування резервним віддаленим варіантом).
+- `trustedProxies`: IP reverse proxy, які завершують TLS або вставляють заголовки пересланого клієнта. Додавайте лише proxy, які ви контролюєте. Записи loopback усе ще дійсні для налаштувань proxy на тому ж хості/локального виявлення (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`.
+- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо відсутній `X-Forwarded-For`. Типово `false` для fail-closed-поведінки.
+- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список заборон).
+- `gateway.tools.allow`: видалити назви інструментів із типового HTTP-списку заборон.
-### OpenAI-compatible endpoint-и
+### OpenAI-сумісні endpoint
- Chat Completions: типово вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`.
- Responses API: `gateway.http.endpoints.responses.enabled`.
-- Захист Responses для URL-входів:
+- Захист URL-входу для Responses:
- `gateway.http.endpoints.responses.maxUrlParts`
- `gateway.http.endpoints.responses.files.urlAllowlist`
- `gateway.http.endpoints.responses.images.urlAllowlist`
- Порожні allowlist-и трактуються як не задані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false`
- і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання за URL.
+ Порожні списки дозволених трактуються як відсутні; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false`
+ і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL.
- Необов’язковий заголовок захисту відповіді:
- - `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для HTTPS origin, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts))
+ - `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для HTTPS-origin, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts))
-### Ізоляція кількох інстансів
+### Ізоляція кількох екземплярів
-Запускайте кілька gateway на одному хості з унікальними портами та каталогами стану:
+Запускайте кілька gateway на одному хості з унікальними портами й каталогами стану:
```bash
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
@@ -3138,7 +3139,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,9 +3161,9 @@ openclaw gateway --port 19001
- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`).
- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для локального/dev використання.
-- `certPath`: шлях файлової системи до файла TLS-сертифіката.
-- `keyPath`: шлях файлової системи до файла приватного ключа TLS; обмежте права доступу.
-- `caPath`: необов’язковий шлях до пакета CA для перевірки клієнтів або власних ланцюжків довіри.
+- `certPath`: шлях у файловій системі до файлу TLS-сертифіката.
+- `keyPath`: шлях у файловій системі до файлу приватного ключа TLS; обмежте права доступу.
+- `caPath`: необов’язковий шлях до bundle CA для перевірки клієнта або власних ланцюгів довіри.
### `gateway.reload`
@@ -3178,13 +3179,13 @@ openclaw gateway --port 19001
}
```
-- `mode`: керує тим, як редагування конфігурації застосовуються під час runtime.
- - `"off"`: ігнорувати зміни наживо; зміни потребують явного перезапуску.
+- `mode`: керує тим, як зміни конфігурації застосовуються під час runtime.
+ - `"off"`: ігнорувати live-редагування; зміни потребують явного перезапуску.
- `"restart"`: завжди перезапускати процес gateway після зміни конфігурації.
- - `"hot"`: застосовувати зміни в межах процесу без перезапуску.
- - `"hybrid"` (типово): спочатку пробувати hot reload; якщо потрібно, переходити до перезапуску.
-- `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число).
-- `deferralTimeoutMs`: максимальний час у мс очікування завершення поточних операцій перед примусовим перезапуском (типово: `300000` = 5 хвилин).
+ - `"hot"`: застосовувати зміни в процесі без перезапуску.
+ - `"hybrid"` (типово): спочатку пробувати hot reload; за потреби переходити до перезапуску.
+- `debounceMs`: debounce-вікно в мс перед застосуванням змін конфігурації (невід’ємне ціле число).
+- `deferralTimeoutMs`: максимальний час очікування в мс для поточних операцій перед примусовим перезапуском (типово: `300000` = 5 хвилин).
---
@@ -3222,46 +3223,46 @@ openclaw gateway --port 19001
```
Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
-Токени hook у query-string відхиляються.
+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.
+- Якщо `hooks.allowRequestSessionKey=true`, обмежуйте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`).
+- Якщо 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`).
+ - `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` і sessionKey у mapping, керованих шаблоном, задавати `sessionKey` (типово: `false`).
+- `transform` може вказувати на модуль JS/TS, який повертає дію hook.
+ - `transform.module` має бути відносним шляхом і лишатися в межах `hooks.transformsDir` (абсолютні шляхи й traversal відхиляються).
+- `agentId` маршрутизує до конкретного агента; невідомі ID резервно спрямовуються до типового.
+- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити всі, `[]` = заборонити всі).
+- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook-агента без явного `sessionKey`.
+- `allowRequestSessionKey`: дозволити викликачам `/hooks/agent` і session key у mapping, керованих шаблоном, задавати `sessionKey` (типово: `false`).
- `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`.
- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово має значення `last`.
-- `model` перевизначає LLM для цього запуску hook (має бути дозволена, якщо каталог моделей задано).
+- `model` перевизначає LLM для цього запуску hook (має бути дозволена, якщо налаштовано каталог моделей).
### Інтеграція Gmail
- Вбудований preset Gmail використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`.
-- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes` так, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`.
-- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість типового шаблонізованого значення.
+- Якщо ви зберігаєте таку маршрутизацію по окремих повідомленнях, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes`, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`.
+- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість шаблонного типового значення.
```json5
{
@@ -3301,18 +3302,18 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
}
```
-- Обслуговує HTML/CSS/JS, які може редагувати агент, і A2UI через HTTP на порту Gateway:
+- Обслуговує HTML/CSS/JS, які редагує агент, і A2UI через HTTP на порту Gateway:
- `http://:/__openclaw__/canvas/`
- `http://:/__openclaw__/a2ui/`
- Лише локально: залишайте `gateway.bind: "loopback"` (типово).
-- 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/`.
+- Для non-loopback bind: маршрути canvas потребують auth Gateway (token/password/trusted-proxy), так само як інші HTTP-поверхні Gateway.
+- Node WebView зазвичай не надсилають auth-заголовки; після сполучення й підключення Node Gateway рекламує URL можливостей із областю Node для доступу до canvas/A2UI.
+- URL можливостей прив’язуються до активної WS-сесії Node і швидко спливають. Резервне визначення за IP не використовується.
+- Вбудовує клієнт live-reload у відданий HTML.
+- Автоматично створює стартовий `index.html`, коли каталог порожній.
+- Також обслуговує A2UI на `/__openclaw__/a2ui/`.
- Зміни потребують перезапуску gateway.
-- Вимкніть live reload для великих каталогів або при помилках `EMFILE`.
+- Вимикайте live reload для великих каталогів або за помилок `EMFILE`.
---
@@ -3330,9 +3331,9 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
}
```
-- `minimal` (типово): не включає `cliPath` + `sshPort` у записи TXT.
+- `minimal` (типово): не включає `cliPath` + `sshPort` у TXT-записи.
- `full`: включає `cliPath` + `sshPort`.
-- Ім’я хоста типово `openclaw`. Перевизначається через `OPENCLAW_MDNS_HOSTNAME`.
+- Ім’я хоста типово `openclaw`. Перевизначайте через `OPENCLAW_MDNS_HOSTNAME`.
### Wide-area (DNS-SD)
@@ -3344,7 +3345,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
}
```
-Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS у Tailscale.
+Записує unicast-зону DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS у Tailscale.
Налаштування: `openclaw dns setup --apply`.
@@ -3369,14 +3370,14 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
}
```
-- Вбудовані env-змінні застосовуються лише тоді, коли в середовищі процесу відсутній ключ.
-- Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні).
+- Вбудовані env-змінні застосовуються лише тоді, коли в середовищі процесу бракує цього ключа.
+- Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден не перевизначає наявні змінні).
- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell.
- Повний порядок пріоритетів див. у [Environment](/uk/help/environment).
### Підстановка env-змінних
-Посилайтеся на env-змінні в будь-якому рядку конфігурації за допомогою `${VAR_NAME}`:
+Посилайтеся на env-змінні в будь-якому рядку конфігурації через `${VAR_NAME}`:
```json5
{
@@ -3386,16 +3387,16 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
}
```
-- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`.
+- Відповідають лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`.
- Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації.
-- Екрануйте через `$${VAR}`, щоб отримати буквальний `${VAR}`.
+- Екрануйте як `$${VAR}`, щоб отримати буквальний `${VAR}`.
- Працює з `$include`.
---
-## Секрети
+## Secrets
-Посилання на секрети є додатковими: прості текстові значення й далі працюють.
+Посилання SecretRef є додатковими: прості текстові значення також працюють.
### `SecretRef`
@@ -3409,17 +3410,17 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
- шаблон `provider`: `^[a-z][a-z0-9_-]{0,63}$`
- шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$`
-- `id` для `source: "file"`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`)
+- `source: "file"` `id`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`)
- шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
-- `id` для `source: "exec"` не повинен містити сегменти шляху `.` або `..`, розділені `/` (наприклад `a/../b` відхиляється)
+- `id` для `source: "exec"` не повинні містити сегменти шляху `.` або `..`, розділені `/` (наприклад `a/../b` відхиляється)
### Підтримувана поверхня облікових даних
-- Канонічна матриця: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface)
+- Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface)
- `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`.
-- Посилання в `auth-profiles.json` включені у визначення runtime та охоплення аудитом.
+- Посилання в `auth-profiles.json` включено до runtime-визначення та покриття аудиту.
-### Конфігурація провайдерів секретів
+### Конфігурація провайдерів Secret
```json5
{
@@ -3449,13 +3450,13 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
Примітки:
-- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має бути `"value"`).
-- Провайдер `exec` потребує абсолютний шлях `command` і використовує payload-и протоколу через stdin/stdout.
-- Типово шляхи команд-символьних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символьні посилання з перевіркою визначеного цільового шляху.
-- Якщо налаштовано `trustedDirs`, перевірка trusted-dir застосовується до визначеного цільового шляху.
+- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue значення `id` має бути `"value"`).
+- Провайдер `exec` вимагає абсолютний шлях `command` і використовує payload протоколу через stdin/stdout.
+- Типово шляхи команд-символьних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання, перевіряючи при цьому шлях до визначеної цілі.
+- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до шляху визначеної цілі.
- Середовище дочірнього процесу `exec` типово мінімальне; явно передавайте потрібні змінні через `passEnv`.
-- Посилання на секрети визначаються під час активації у snapshot в пам’яті, після чого шляхи запитів читають лише snapshot.
-- Під час активації застосовується фільтрація активної поверхні: невизначені посилання на увімкнених поверхнях спричиняють помилку запуску/reload, тоді як неактивні поверхні пропускаються з діагностикою.
+- Посилання Secret визначаються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок.
+- Під час активації застосовується фільтрація активної поверхні: невизначені посилання на увімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою.
---
@@ -3478,12 +3479,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 беруться з визначених snapshot у пам’яті; застарілі статичні записи `auth.json` очищаються при виявленні.
-- Застарілий імпорт OAuth — із `~/.openclaw/credentials/oauth.json`.
+- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних.
+- Профілі в режимі OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілю auth на основі SecretRef.
+- Статичні runtime-облікові дані надходять із визначених знімків у пам’яті; застарілі статичні записи `auth.json` очищаються після виявлення.
+- Застарілий імпорт OAuth виконується з `~/.openclaw/credentials/oauth.json`.
- Див. [OAuth](/uk/concepts/oauth).
-- Поведінка runtime секретів і інструменти `audit/configure/apply`: [Керування секретами](/uk/gateway/secrets).
+- Поведінка runtime для Secrets та інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets).
### `auth.cooldowns`
@@ -3506,23 +3507,23 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
```
- `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні
- billing/помилки недостатнього кредиту (типово: `5`). Явний текст billing усе ще
- може потрапити сюди навіть на відповідях `401`/`403`, але текстові
- matchers, специфічні для провайдера, залишаються обмеженими провайдером, якому вони належать (наприклад OpenRouter
- `Key limit exceeded`). Придатні для повтору повідомлення `402` usage-window або
- про ліміт витрат organization/workspace залишаються в шляху `rate_limit`.
-- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин billing backoff для окремих провайдерів.
-- `billingMaxHours`: максимальна межа в годинах для експоненційного зростання billing backoff (типово: `24`).
+ billing/помилки недостатнього кредиту (типово: `5`). Явний billing-текст
+ усе одно може потрапити сюди навіть у відповідях `401`/`403`, але provider-specific
+ текстові зіставлення лишаються обмеженими провайдером, якому вони належать (наприклад OpenRouter
+ `Key limit exceeded`). Повторювані HTTP `402` з вікном використання або
+ повідомлення про ліміт витрат організації/робочого простору натомість лишаються на шляху `rate_limit`.
+- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff billing для окремих провайдерів.
+- `billingMaxHours`: межа в годинах для експоненційного зростання backoff billing (типово: `24`).
- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для високовпевнених збоїв `auth_permanent` (типово: `10`).
-- `authPermanentMaxMinutes`: максимальна межа в хвилинах для зростання backoff `auth_permanent` (типово: `60`).
+- `authPermanentMaxMinutes`: межа в хвилинах для зростання backoff `auth_permanent` (типово: `60`).
- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників backoff (типово: `24`).
-- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера для помилок перевантаження перед переходом до fallback моделі (типово: `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`.
+- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок перевантаження перед переходом до fallback моделі (типово: `1`). Сюди потрапляють provider-busy форми, як-от `ModelNotReadyException`.
+- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`).
+- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок rate-limit перед переходом до fallback моделі (типово: `1`). До цього кошика rate-limit входить provider-shaped текст, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`.
---
-## Логування
+## Журналювання
```json5
{
@@ -3539,8 +3540,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-розгортань використовуйте зовнішню ротацію журналів.
---
@@ -3577,20 +3578,20 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
}
```
-- `enabled`: головний перемикач виводу інструментування (типово: `true`).
-- `flags`: масив рядків-прапорів, що вмикає цільовий вивід журналу (підтримує wildcard-и, як-от `"telegram.*"` або `"*"`).
-- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислі сеанси, поки сеанс залишається в стані обробки.
+- `enabled`: головний перемикач для виводу інструментування (типово: `true`).
+- `flags`: масив рядків-прапорців, що вмикають цільовий вивід журналу (підтримує wildcard, як-от `"telegram.*"` або `"*"`).
+- `stuckSessionWarnMs`: віковий поріг у мс для виведення попереджень про завислу сесію, поки сесія лишається в стані обробки.
- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`).
- `otel.endpoint`: URL колектора для експорту OTel.
- `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`.
-- `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel.
+- `otel.headers`: додаткові HTTP/gRPC-метадані заголовків, що надсилаються з запитами експорту OTel.
- `otel.serviceName`: назва сервісу для атрибутів ресурсу.
-- `otel.traces` / `otel.metrics` / `otel.logs`: вмикають експорт трас, метрик або журналів.
-- `otel.sampleRate`: частота вибірки трас `0`–`1`.
-- `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс.
-- `cacheTrace.enabled`: записує snapshot-и trace кешу для вбудованих запусків (типово: `false`).
-- `cacheTrace.filePath`: вихідний шлях для JSONL trace кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`).
-- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід trace кешу (усі типово: `true`).
+- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або log.
+- `otel.sampleRate`: частота вибірки trace `0`–`1`.
+- `otel.flushIntervalMs`: інтервал періодичного скидання telemetry у мс.
+- `cacheTrace.enabled`: журналювати знімки trace кешу для вбудованих запусків (типово: `false`).
+- `cacheTrace.filePath`: шлях виводу для cache trace JSONL (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`).
+- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід cache trace (усі типово: `true`).
---
@@ -3612,12 +3613,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.stableDelayHours`: мінімальна затримка в годинах перед автозастосуванням stable-каналу (типово: `6`; максимум: `168`).
+- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (типово: `12`; максимум: `168`).
+- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу, у годинах (типово: `1`; максимум: `24`).
---
@@ -3651,21 +3652,21 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
```
- `enabled`: глобальний feature gate для ACP (типово: `false`).
-- `dispatch.enabled`: незалежний gate для dispatch ходів сеансу ACP (типово: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання.
-- `backend`: id типового backend runtime ACP (має відповідати зареєстрованому Plugin runtime ACP).
-- `defaultAgent`: резервний id цільового агента ACP, коли spawn не задає явну ціль.
-- `allowedAgents`: список дозволених id агентів для сеансів runtime ACP; порожнє значення означає відсутність додаткових обмежень.
-- `maxConcurrentSessions`: максимальна кількість одночасно активних сеансів ACP.
-- `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту.
-- `stream.maxChunkChars`: максимальний розмір chunk перед поділом проєкції потокового блока.
-- `stream.repeatSuppression`: пригнічує повторювані рядки статусу/інструментів у межах ходу (типово: `true`).
-- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до завершальних подій ходу.
+- `dispatch.enabled`: незалежний gate для диспетчеризації ходів ACP-сесій (типово: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання.
+- `backend`: id типового backend runtime ACP (має збігатися із зареєстрованим Plugin runtime ACP).
+- `defaultAgent`: резервний id цільового агента ACP, коли spawn не вказує явну ціль.
+- `allowedAgents`: список дозволених id агентів для runtime-сесій ACP; порожнє значення означає відсутність додаткових обмежень.
+- `maxConcurrentSessions`: максимальна кількість одночасно активних ACP-сесій.
+- `stream.coalesceIdleMs`: idle-вікно скидання в мс для потокового тексту.
+- `stream.maxChunkChars`: максимальний розмір шматка перед розбиттям проєкції потокового блоку.
+- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів на хід (типово: `true`).
+- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до термінальних подій ходу.
- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`).
-- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, що проєктується за один хід ACP.
-- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлення ACP.
-- `stream.tagVisibility`: запис, що зіставляє назви теґів із логічними перевизначеннями видимості для потокових подій.
-- `runtime.ttlMinutes`: idle TTL у хвилинах для worker-ів сеансу ACP перед можливим очищенням.
-- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час bootstrap середовища runtime ACP.
+- `stream.maxOutputChars`: максимальна кількість символів виводу помічника, що проєктується за хід ACP.
+- `stream.maxSessionUpdateChars`: максимальна кількість символів для рядків статусу/оновлень ACP, що проєктуються.
+- `stream.tagVisibility`: запис назв тегів у перевизначення видимості типу boolean для потокових подій.
+- `runtime.ttlMinutes`: idle TTL у хвилинах для воркерів ACP-сесій до моменту, коли вони стають придатними для очищення.
+- `runtime.installCommand`: необов’язкова команда встановлення, яку слід виконати під час bootstrap середовища runtime ACP.
---
@@ -3681,17 +3682,17 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
}
```
-- `cli.banner.taglineMode` керує стилем слогана банера:
- - `"random"` (типово): змінні кумедні/сезонні слогани.
- - `"default"`: фіксований нейтральний слоган (`All your chats, one OpenClaw.`).
- - `"off"`: без тексту слогана (назва/версія банера все одно показується).
-- Щоб приховати весь банер (а не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`.
+- `cli.banner.taglineMode` керує стилем tagline банера:
+ - `"random"` (типово): ротаційні кумедні/сезонні tagline.
+ - `"default"`: фіксований нейтральний tagline (`All your chats, one OpenClaw.`).
+ - `"off"`: без тексту tagline (назва/версія банера все одно показуються).
+- Щоб приховати весь банер (а не лише tagline), установіть env `OPENCLAW_HIDE_BANNER=1`.
---
## Wizard
-Метадані, які записують потоки керованого налаштування CLI (`onboard`, `configure`, `doctor`):
+Метадані, які записуються потоками керованого налаштування CLI (`onboard`, `configure`, `doctor`):
```json5
{
@@ -3709,15 +3710,15 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
## Identity
-Див. поля identity в `agents.list` у розділі [Значення агентів за замовчуванням](#agent-defaults).
+Див. поля identity у `agents.list` у розділі [Типові значення агентів](#agent-defaults).
---
-## Bridge (legacy, вилучено)
+## Bridge (застарілий, видалений)
-Поточні збірки більше не містять TCP bridge. Node підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде вилучено; `openclaw doctor --fix` може прибрати невідомі ключі).
+Поточні збірки більше не містять TCP bridge. Nodes підключаються через WebSocket Gateway. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі).
-
+
```json
{
@@ -3755,11 +3756,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, що використовується для доставки Cron через POST до Webhook (`delivery.mode = "webhook"`); якщо пропущено, заголовок auth не надсилається.
-- `webhook`: застарілий резервний URL Webhook (http/https), який використовується лише для збережених задач, що все ще мають `notify: true`.
+- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків Cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених стенограм Cron. Типове значення: `24h`; установіть `false`, щоб вимкнути.
+- `runLog.maxBytes`: максимальний розмір файлу журналу на запуск (`cron/runs/.jsonl`) перед очищенням. Типове значення: `2_000_000` байтів.
+- `runLog.keepLines`: кількість найновіших рядків, що зберігаються, коли спрацьовує очищення журналу запусків. Типове значення: `2000`.
+- `webhookToken`: bearer token, який використовується для доставлення Cron через webhook POST (`delivery.mode = "webhook"`); якщо пропущено, заголовок auth не надсилається.
+- `webhook`: застарілий резервний URL webhook (http/https), який використовується лише для збережених завдань, що досі мають `notify: true`.
### `cron.retry`
@@ -3775,11 +3776,11 @@ 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"`. Пропустіть, щоб повторювати всі тимчасові типи.
+- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань у разі тимчасових помилок (типово: `3`; діапазон: `0`–`10`).
+- `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів).
+- `retryOn`: типи помилок, що запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати всі тимчасові типи.
-Застосовується лише до одноразових задач Cron. Повторювані задачі використовують окрему обробку збоїв.
+Застосовується лише до одноразових Cron-завдань. Повторювані завдання використовують окрему обробку помилок.
### `cron.failureAlert`
@@ -3797,11 +3798,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
}
```
-- `enabled`: увімкнути сповіщення про збої для задач Cron (типово: `false`).
-- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мінімум: `1`).
-- `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для тієї самої задачі (невід’ємне ціле число).
-- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` робить POST до налаштованого Webhook.
-- `accountId`: необов’язковий ID облікового запису або каналу для обмеження доставки сповіщення.
+- `enabled`: увімкнути сповіщення про помилки для Cron-завдань (типово: `false`).
+- `after`: кількість послідовних збоїв перед надсиланням сповіщення (додатне ціле число, мінімум: `1`).
+- `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число).
+- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST до налаштованого webhook.
+- `accountId`: необов’язковий id облікового запису або каналу для обмеження області доставки сповіщення.
### `cron.failureDestination`
@@ -3818,51 +3819,51 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
}
```
-- Типове місце призначення для сповіщень про збої Cron для всіх задач.
-- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних цілі.
+- Типова ціль для сповіщень про помилки Cron для всіх завдань.
+- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних про ціль.
- `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки.
-- `to`: явна ціль announce або URL Webhook. Обов’язково для режиму webhook.
+- `to`: явна ціль announce або URL webhook. Обов’язкове для режиму webhook.
- `accountId`: необов’язкове перевизначення облікового запису для доставки.
-- `delivery.failureDestination` для окремої задачі перевизначає це глобальне типове значення.
-- Коли не задано ні глобальне місце призначення збою, ні місце призначення для окремої задачі, задачі, які вже доставляють через `announce`, у разі збою використовують як резервний варіант цю основну ціль announce.
-- `delivery.failureDestination` підтримується лише для задач із `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` задачі не дорівнює `"webhook"`.
+- `delivery.failureDestination` для окремого завдання перевизначає це глобальне типове значення.
+- Коли не задано ні глобальну, ні окрему для завдання ціль помилки, завдання, які вже доставляють через `announce`, у разі помилки резервно використовують цю основну ціль announce.
+- `delivery.failureDestination` підтримується лише для завдань із `sessionTarget="isolated"`, якщо тільки основне `delivery.mode` завдання не дорівнює `"webhook"`.
-Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [фонові задачі](/uk/automation/tasks).
+Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [background tasks](/uk/automation/tasks).
---
## Змінні шаблону моделі медіа
-Заповнювачі шаблону, що розгортаються в `tools.media.models[].args`:
+Плейсхолдери шаблонів, які розгортаються в `tools.media.models[].args`:
-| Змінна | Опис |
-| ----------------- | ------------------------------------------------- |
-| `{{Body}}` | Повне тіло вхідного повідомлення |
-| `{{RawBody}}` | Сире тіло (без обгорток історії/відправника) |
-| `{{BodyStripped}}`| Тіло без згадок у групі |
-| `{{From}}` | Ідентифікатор відправника |
-| `{{To}}` | Ідентифікатор призначення |
-| `{{MessageSid}}` | ID повідомлення каналу |
-| `{{SessionId}}` | UUID поточного сеансу |
-| `{{IsNewSession}}`| `"true"`, коли створено новий сеанс |
-| `{{MediaUrl}}` | Псевдо-URL вхідного медіа |
-| `{{MediaPath}}` | Локальний шлях до медіа |
-| `{{MediaType}}` | Тип медіа (image/audio/document/…) |
-| `{{Transcript}}` | Аудіотранскрипт |
-| `{{Prompt}}` | Визначений media prompt для записів CLI |
-| `{{MaxChars}}` | Визначена максимальна кількість вихідних символів для записів CLI |
-| `{{ChatType}}` | `"direct"` або `"group"` |
-| `{{GroupSubject}}`| Тема групи (best effort) |
-| `{{GroupMembers}}`| Попередній список учасників групи (best effort) |
-| `{{SenderName}}` | Відображуване ім’я відправника (best effort) |
-| `{{SenderE164}}` | Номер телефону відправника (best effort) |
-| `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) |
+| Змінна | Опис |
+| ------------------ | ------------------------------------------------- |
+| `{{Body}}` | Повний текст вхідного повідомлення |
+| `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) |
+| `{{BodyStripped}}` | Текст без згадувань у групі |
+| `{{From}}` | Ідентифікатор відправника |
+| `{{To}}` | Ідентифікатор призначення |
+| `{{MessageSid}}` | ID повідомлення каналу |
+| `{{SessionId}}` | UUID поточної сесії |
+| `{{IsNewSession}}` | `"true"`, коли створено нову сесію |
+| `{{MediaUrl}}` | Псевдо-URL вхідного медіа |
+| `{{MediaPath}}` | Локальний шлях до медіа |
+| `{{MediaType}}` | Тип медіа (image/audio/document/…) |
+| `{{Transcript}}` | Аудіостенограма |
+| `{{Prompt}}` | Визначений media-prompt для записів CLI |
+| `{{MaxChars}}` | Визначена максимальна кількість символів виводу для записів CLI |
+| `{{ChatType}}` | `"direct"` або `"group"` |
+| `{{GroupSubject}}` | Тема групи (best effort) |
+| `{{GroupMembers}}` | Попередній перегляд учасників групи (best effort) |
+| `{{SenderName}}` | Відображуване ім’я відправника (best effort) |
+| `{{SenderE164}}` | Номер телефону відправника (best effort) |
+| `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) |
---
-## Include-и конфігурації (`$include`)
+## Включення конфігурації (`$include`)
-Розділіть конфігурацію на кілька файлів:
+Розділяйте конфігурацію на кілька файлів:
```json5
// ~/.openclaw/openclaw.json
@@ -3875,15 +3876,15 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `.
}
```
-**Поведінка об’єднання:**
+**Поведінка злиття:**
-- Один файл: замінює об’єкт-контейнер.
-- Масив файлів: глибоко об’єднується за порядком (пізніші перевизначають раніші).
-- Сусідні ключі: об’єднуються після include-ів (перевизначають включені значення).
-- Вкладені include-и: до 10 рівнів глибини.
-- Шляхи: визначаються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли вони все одно визначаються в межах цієї границі.
-- Помилки: чіткі повідомлення для відсутніх файлів, помилок парсингу та циклічних include-ів.
+- Один файл: замінює об’єкт, у якому міститься.
+- Масив файлів: глибоко зливається по порядку (пізніші значення перевизначають раніші).
+- Сусідні ключі: зливаються після включень (перевизначають включені значення).
+- Вкладені включення: до 10 рівнів глибини.
+- Шляхи: визначаються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли після визначення все одно залишаються в межах цієї границі.
+- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок парсингу та циклічних включень.
---
-_Пов’язано: [Конфігурація](/uk/gateway/configuration) · [Приклади конфігурації](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_
+_Пов’язане: [Configuration](/uk/gateway/configuration) · [Configuration Examples](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_
diff --git a/docs/uk/plugins/architecture.md b/docs/uk/plugins/architecture.md
index cd7ad5640..40dc3162e 100644
--- a/docs/uk/plugins/architecture.md
+++ b/docs/uk/plugins/architecture.md
@@ -1,195 +1,195 @@
---
read_when:
- - Створення або налагодження нативних плагінів OpenClaw
- - Розуміння моделі можливостей плагіна або меж володіння
- - Робота над конвеєром завантаження плагінів або реєстром
- - Реалізація гачків середовища виконання провайдера або плагінів каналів
+ - Створення або налагодження нативних Plugin OpenClaw
+ - Розуміння моделі можливостей Plugin або меж володіння
+ - Робота над конвеєром завантаження Plugin або реєстром
+ - Реалізація хуків середовища виконання постачальника або Plugin каналів
sidebarTitle: Internals
-summary: 'Внутрішня будова Plugin: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби середовища виконання'
-title: Внутрішня будова Plugin
+summary: 'Внутрішні компоненти Plugin: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби середовища виконання'
+title: Внутрішні компоненти Plugin
x-i18n:
- generated_at: "2026-04-21T05:21:20Z"
+ generated_at: "2026-04-21T06:04:48Z"
model: gpt-5.4
provider: openai
- source_hash: 38b763841ae27137c2f2d080a3cb17ca11ee20e60dd2a95b4d6bed7dcb75e2ae
+ source_hash: 05b612f75189ba32f8c92e5a261241abdf9ad8d4a685c1d8da0cf9605d7158b7
source_path: plugins/architecture.md
workflow: 15
---
-# Внутрішня будова Plugin
+# Внутрішні компоненти Plugin
- Це **поглиблений довідник з архітектури**. Практичні посібники дивіться тут:
- - [Установлення та використання плагінів](/uk/tools/plugin) — посібник для користувача
- - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний матеріал зі створення плагіна
- - [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями
- - [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — створення провайдера моделей
- - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпортів та API реєстрації
+ Це **довідник з глибокої архітектури**. Практичні посібники див. тут:
+ - [Встановлення та використання Plugin](/uk/tools/plugin) — посібник для користувача
+ - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний матеріал зі створення plugin
+ - [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями
+ - [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення постачальника моделей
+ - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпорту та API реєстрації
-Ця сторінка описує внутрішню архітектуру системи плагінів OpenClaw.
+На цій сторінці описано внутрішню архітектуру системи plugin в OpenClaw.
## Публічна модель можливостей
-Можливості — це публічна модель **нативних плагінів** усередині OpenClaw. Кожен
-нативний плагін OpenClaw реєструється для одного або кількох типів можливостей:
+Можливості — це публічна модель **нативних plugin** всередині OpenClaw. Кожен
+нативний plugin OpenClaw реєструється для одного або кількох типів можливостей:
-| Можливість | Метод реєстрації | Приклади плагінів |
-| --------------------- | ---------------------------------------------- | ------------------------------------ |
-| Текстовий inference | `api.registerProvider(...)` | `openai`, `anthropic` |
-| Backend inference CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` |
-| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` |
-| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` |
-| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` |
-| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` |
-| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` |
-| Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` |
-| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` |
-| Отримання вебданих | `api.registerWebFetchProvider(...)` | `firecrawl` |
-| Вебпошук | `api.registerWebSearchProvider(...)` | `google` |
-| Канал / повідомлення | `api.registerChannel(...)` | `msteams`, `matrix` |
+| Можливість | Метод реєстрації | Приклади plugin |
+| --------------------- | ----------------------------------------------- | ----------------------------------- |
+| Текстовий inference | `api.registerProvider(...)` | `openai`, `anthropic` |
+| Бекенд inference CLI | `api.registerCliBackend(...)` | `openai`, `anthropic` |
+| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` |
+| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` |
+| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` |
+| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` |
+| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` |
+| Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` |
+| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` |
+| Отримання вебданих | `api.registerWebFetchProvider(...)` | `firecrawl` |
+| Вебпошук | `api.registerWebSearchProvider(...)` | `google` |
+| Канал / обмін повідомленнями | `api.registerChannel(...)` | `msteams`, `matrix` |
-Плагін, який реєструє нуль можливостей, але надає hooks, інструменти або
-сервіси, є **застарілим hook-only** плагіном. Цей шаблон і далі повністю підтримується.
+Plugin, який реєструє нуль можливостей, але надає хуки, інструменти або
+сервіси, є **застарілим plugin лише з хуками**. Цей шаблон усе ще повністю підтримується.
### Позиція щодо зовнішньої сумісності
-Модель можливостей уже впроваджена в ядрі й сьогодні використовується
-вбудованими/нативними плагінами, але сумісність із зовнішніми плагінами все ще
-потребує чіткішої межі, ніж «це експортовано, отже це незмінне».
+Модель можливостей уже впроваджена в core і сьогодні використовується
+вбудованими/нативними plugin, але сумісність із зовнішніми plugin усе ще
+потребує вищої планки, ніж "це експортовано, отже це незмінний контракт".
Поточні рекомендації:
-- **наявні зовнішні плагіни:** зберігайте працездатність інтеграцій на основі hooks; вважайте
+- **наявні зовнішні plugin:** зберігайте працездатність інтеграцій на основі хуків; вважайте
це базовим рівнем сумісності
-- **нові вбудовані/нативні плагіни:** віддавайте перевагу явній реєстрації можливостей замість
- vendor-specific звернень усередину або нових дизайнів лише з hooks
-- **зовнішні плагіни, що переходять на реєстрацію можливостей:** це дозволено, але
+- **нові вбудовані/нативні plugin:** віддавайте перевагу явній реєстрації можливостей, а не
+ vendor-специфічним зверненням углиб системи чи новим дизайнам лише з хуками
+- **зовнішні plugin, що переходять на реєстрацію можливостей:** це дозволено, але
вважайте допоміжні поверхні, специфічні для можливостей, такими, що еволюціонують, якщо в документації
контракт явно не позначено як стабільний
Практичне правило:
-- API реєстрації можливостей — це бажаний напрям
-- застарілі hooks залишаються найбезпечнішим шляхом без порушення сумісності для зовнішніх плагінів під час
+- API реєстрації можливостей — це бажаний напрямок
+- застарілі хуки залишаються найбезпечнішим шляхом без порушень сумісності для зовнішніх plugin під час
переходу
-- не всі експортовані допоміжні підшляхи однаково важливі; віддавайте перевагу вузькому задокументованому
- контракту, а не випадково експортованим допоміжним засобам
+- не всі експортовані допоміжні підшляхи однакові; віддавайте перевагу вузькому задокументованому
+ контракту, а не випадковим експортованим допоміжним елементам
-### Форми плагінів
+### Форми plugin
-OpenClaw класифікує кожен завантажений плагін за формою на основі його фактичної
-поведінки під час реєстрації, а не лише статичних метаданих:
+OpenClaw класифікує кожен завантажений plugin за формою на основі його
+фактичної поведінки під час реєстрації, а не лише статичних метаданих:
-- **plain-capability** -- реєструє рівно один тип можливості (наприклад,
- плагін лише для провайдера, як-от `mistral`)
-- **hybrid-capability** -- реєструє кілька типів можливостей (наприклад,
+- **plain-capability** — реєструє рівно один тип можливості (наприклад,
+ plugin лише для постачальника, як-от `mistral`)
+- **hybrid-capability** — реєструє кілька типів можливостей (наприклад,
`openai` володіє текстовим inference, мовленням, розумінням медіа та
генерацією зображень)
-- **hook-only** -- реєструє лише hooks (типізовані або власні), без можливостей,
+- **hook-only** — реєструє лише хуки (типізовані або користувацькі), без можливостей,
інструментів, команд чи сервісів
-- **non-capability** -- реєструє інструменти, команди, сервіси або маршрути, але не
- можливості
+- **non-capability** — реєструє інструменти, команди, сервіси або маршрути, але без
+ можливостей
-Скористайтеся `openclaw plugins inspect `, щоб переглянути форму плагіна та
+Використовуйте `openclaw plugins inspect `, щоб побачити форму plugin і
розподіл можливостей. Докладніше див. у [довіднику CLI](/cli/plugins#inspect).
-### Застарілі hooks
+### Застарілі хуки
-Hook `before_agent_start` і далі підтримується як шлях сумісності для
-плагінів типу hook-only. Від нього все ще залежать застарілі реальні плагіни.
+Хук `before_agent_start` залишається підтримуваним як шлях сумісності для
+plugin лише з хуками. Реальні застарілі plugin досі від нього залежать.
-Напрям:
+Напрямок:
- зберігати його працездатність
- документувати його як застарілий
-- для роботи з перевизначенням моделі/провайдера віддавати перевагу `before_model_resolve`
+- для перевизначення моделі/постачальника віддавати перевагу `before_model_resolve`
- для зміни prompt віддавати перевагу `before_prompt_build`
-- видаляти лише після зниження реального використання та коли покриття фікстурами доведе безпечність міграції
+- прибирати лише тоді, коли реальне використання зменшиться, а покриття фікстурами підтвердить безпечність міграції
### Сигнали сумісності
-Коли ви запускаєте `openclaw doctor` або `openclaw plugins inspect `, ви можете побачити
-одну з таких позначок:
+Під час виконання `openclaw doctor` або `openclaw plugins inspect ` ви можете побачити
+один із таких ярликів:
-| Сигнал | Значення |
-| -------------------------- | ------------------------------------------------------------ |
-| **config valid** | Конфігурація коректно розбирається, і плагіни успішно визначаються |
-| **compatibility advisory** | Плагін використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) |
-| **legacy warning** | Плагін використовує `before_agent_start`, який є застарілим |
-| **hard error** | Конфігурація некоректна або не вдалося завантажити плагін |
+| Сигнал | Значення |
+| ------------------------- | ------------------------------------------------------------ |
+| **config valid** | Конфігурація успішно розбирається, а plugin коректно визначаються |
+| **compatibility advisory** | Plugin використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) |
+| **legacy warning** | Plugin використовує `before_agent_start`, який є застарілим |
+| **hard error** | Конфігурація недійсна або plugin не вдалося завантажити |
-Ні `hook-only`, ні `before_agent_start` сьогодні не зламають ваш плагін --
-`hook-only` є рекомендаційним сигналом, а `before_agent_start` лише викликає попередження. Ці
+Ні `hook-only`, ні `before_agent_start` сьогодні не зламають ваш plugin —
+`hook-only` є лише рекомендаційним сигналом, а `before_agent_start` спричиняє лише попередження. Ці
сигнали також з’являються в `openclaw status --all` і `openclaw plugins doctor`.
## Огляд архітектури
-Система плагінів OpenClaw має чотири шари:
+Система plugin в OpenClaw має чотири шари:
1. **Маніфест + виявлення**
- OpenClaw знаходить потенційні плагіни у налаштованих шляхах, коренях робочих просторів,
- глобальних коренях розширень і серед вбудованих розширень. На етапі виявлення спочатку читаються
- нативні маніфести `openclaw.plugin.json` та маніфести підтримуваних bundle.
+ OpenClaw знаходить потенційні plugin у налаштованих шляхах, коренях робочих просторів,
+ глобальних коренях розширень і вбудованих розширеннях. Виявлення спочатку читає нативні
+ маніфести `openclaw.plugin.json`, а також підтримувані маніфести пакетів.
2. **Увімкнення + валідація**
- Ядро визначає, чи виявлений плагін увімкнений, вимкнений, заблокований або
- вибраний для ексклюзивного слота, такого як пам’ять.
-3. **Завантаження середовища виконання**
- Нативні плагіни OpenClaw завантажуються в процесі через jiti та реєструють
- можливості в центральному реєстрі. Сумісні bundle нормалізуються в записи
+ Core вирішує, чи виявлений plugin увімкнено, вимкнено, заблоковано або
+ вибрано для ексклюзивного слота, такого як memory.
+3. **Завантаження під час виконання**
+ Нативні plugin OpenClaw завантажуються в межах процесу через jiti і реєструють
+ можливості в центральному реєстрі. Сумісні пакети нормалізуються в записи
реєстру без імпорту коду середовища виконання.
-4. **Споживання поверхонь**
- Решта OpenClaw читає реєстр, щоб надавати інструменти, канали, налаштування провайдерів,
- hooks, HTTP-маршрути, команди CLI та сервіси.
+4. **Використання поверхонь**
+ Решта OpenClaw читає реєстр, щоб надавати інструменти, канали, налаштування
+ постачальників, хуки, HTTP-маршрути, команди CLI та сервіси.
-Зокрема для CLI плагінів, виявлення кореневих команд розділене на дві фази:
+Зокрема для CLI plugin, виявлення кореневих команд поділено на дві фази:
- метадані на етапі розбору надходять із `registerCli(..., { descriptors: [...] })`
-- справжній модуль CLI плагіна може залишатися лінивим і реєструватися під час першого виклику
+- реальний модуль CLI plugin може залишатися ледачим і реєструватися під час першого виклику
-Це дає змогу зберігати код CLI, яким володіє плагін, усередині плагіна, водночас дозволяючи OpenClaw
-зарезервувати імена кореневих команд до розбору.
+Це дозволяє зберігати код CLI, що належить plugin, всередині plugin, і водночас дає OpenClaw
+змогу резервувати імена кореневих команд до початку розбору.
Важлива межа проєктування:
- виявлення + валідація конфігурації мають працювати на основі **метаданих маніфесту/схеми**
- без виконання коду плагіна
-- нативна поведінка середовища виконання походить зі шляху `register(api)` модуля плагіна
+ без виконання коду plugin
+- нативна поведінка під час виконання надходить із шляху `register(api)` модуля plugin
-Це розділення дає OpenClaw змогу перевіряти конфігурацію, пояснювати відсутні/вимкнені плагіни й
-будувати підказки для UI/схеми до того, як повне середовище виконання стане активним.
+Цей поділ дає OpenClaw змогу валідувати конфігурацію, пояснювати відсутні/вимкнені plugin і
+будувати підказки для UI/схеми до активації повного середовища виконання.
-### Плагіни каналів і спільний інструмент повідомлень
+### Channel Plugins і спільний інструмент повідомлень
-Плагінам каналів не потрібно реєструвати окремий інструмент send/edit/react для
-звичайних дій у чаті. OpenClaw зберігає в ядрі один спільний інструмент `message`,
-а плагіни каналів володіють специфічним для каналу виявленням та виконанням за ним.
+Channel Plugins не потрібно реєструвати окремий інструмент відправлення/редагування/реакцій для
+звичайних дій у чаті. OpenClaw зберігає один спільний інструмент `message` у core, а
+channel plugins володіють каналоспецифічним виявленням і виконанням за ним.
Поточна межа така:
-- ядро володіє спільним хостом інструмента `message`, прив’язкою prompt, обліком сесій/гілок
- і диспетчеризацією виконання
-- плагіни каналів володіють виявленням дій в обмеженій області, виявленням можливостей і будь-якими
- специфічними для каналу фрагментами схеми
-- плагіни каналів володіють граматикою розмов у сесії, специфічною для провайдера, наприклад
- тим, як ідентифікатори розмов кодують ідентифікатори гілок або успадковуються від батьківських розмов
-- плагіни каналів виконують фінальну дію через свій адаптер дій
+- core володіє хостом спільного інструмента `message`, зв’язуванням із prompt, веденням обліку
+ сесій/гілок і диспетчеризацією виконання
+- channel plugins володіють виявленням дій у межах області, виявленням можливостей і будь-якими
+ каналоспецифічними фрагментами схеми
+- channel plugins володіють граматикою розмов сесії, специфічною для постачальника, наприклад тим,
+ як ідентифікатори розмов кодують ідентифікатори гілок або успадковуються від батьківських розмов
+- channel plugins виконують фінальну дію через свій адаптер дій
-Для плагінів каналів поверхнею SDK є
+Для channel plugins поверхнею SDK є
`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик виявлення
-дозволяє плагіну повертати видимі дії, можливості та внески у схему разом,
-щоб ці частини не розходилися між собою.
+дозволяє plugin повертати свої видимі дії, можливості та внески у схему разом, щоб
+ці частини не розходилися між собою.
-Коли параметр інструмента повідомлень, специфічний для каналу, містить джерело медіа, наприклад
-локальний шлях або віддалений URL медіа, плагін також має повертати
-`mediaSourceParams` із `describeMessageTool(...)`. Ядро використовує цей явний
-список, щоб застосовувати нормалізацію шляхів sandbox і підказки доступу до вихідних медіа
-без жорсткого кодування імен параметрів, якими володіє плагін.
-Тут слід надавати перевагу мапам на рівні дій, а не одному пласкому списку на весь канал,
-щоб параметр медіа лише для профілю не нормалізувався для не пов’язаних дій, таких як
+Коли параметр channel-специфічного інструмента повідомлень містить джерело медіа, таке як
+локальний шлях або віддалений URL медіа, plugin також має повертати
+`mediaSourceParams` із `describeMessageTool(...)`. Core використовує цей явний список для
+застосування нормалізації шляхів у пісочниці та підказок щодо вихідного доступу до медіа
+без жорсткого кодування назв параметрів, що належать plugin.
+Тут варто віддавати перевагу картам у межах дій, а не одному плоскому списку на весь канал, щоб
+параметр медіа лише для профілю не нормалізувався в не пов’язаних діях, як-от
`send`.
-Ядро передає область середовища виконання в цей крок виявлення. Важливі поля включають:
+Core передає область середовища виконання в цей етап виявлення. Важливі поля включають:
- `accountId`
- `currentChannelId`
@@ -200,123 +200,125 @@ Hook `before_agent_start` і далі підтримується як шлях
- `agentId`
- довірений вхідний `requesterSenderId`
-Це важливо для плагінів, чутливих до контексту. Канал може приховувати або показувати
+Це важливо для context-sensitive plugin. Канал може приховувати або відкривати
дії з повідомленнями залежно від активного облікового запису, поточної кімнати/гілки/повідомлення або
-довіреної особи відправника запиту без жорсткого кодування специфічних для каналу гілок у
-ядрі інструмента `message`.
+довіреної особи відправника запиту без жорсткого кодування каналоспецифічних гілок у
+core-інструменті `message`.
-Саме тому зміни маршрутизації embedded runner усе ще залишаються роботою плагіна: runner
-відповідає за передавання поточної ідентичності чату/сесії в межу виявлення плагіна, щоб
-спільний інструмент `message` відкривав правильну поверхню, якою володіє канал,
+Саме тому зміни маршрутизації embedded-runner усе ще залишаються роботою plugin: runner
+відповідає за передавання поточної ідентичності чату/сесії в межу виявлення plugin,
+щоб спільний інструмент `message` відкривав правильну поверхню, що належить каналу,
для поточного ходу.
-Для допоміжних засобів виконання, якими володіє канал, вбудовані плагіни мають зберігати середовище виконання
-усередині власних модулів розширення. Ядро більше не володіє середовищами виконання дій із повідомленнями
-Discord, Slack, Telegram або WhatsApp у `src/agents/tools`.
+Для допоміжних засобів виконання, що належать каналу, вбудовані plugin мають зберігати runtime
+виконання всередині власних модулів розширення. Core більше не володіє runtime
+дій із повідомленнями для Discord, Slack, Telegram або WhatsApp у `src/agents/tools`.
Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, а вбудовані
-плагіни мають імпортувати власний локальний код середовища виконання безпосередньо зі своїх
-модулів, якими володіє розширення.
+plugin мають імпортувати власний локальний runtime-код безпосередньо зі своїх
+модулів, що належать розширенню.
-Така сама межа застосовується і до seams SDK із назвами провайдерів загалом: ядро не повинно
-імпортувати специфічні для каналів зручні barrels для Slack, Discord, Signal,
-WhatsApp або подібних розширень. Якщо ядру потрібна певна поведінка, воно має або
-використати власний barrel `api.ts` / `runtime-api.ts` вбудованого плагіна, або підвищити цю потребу
-до вузької узагальненої можливості у спільному SDK.
+Така сама межа загалом застосовується й до provider-іменованих поверхонь SDK: core не має
+імпортувати каналоспецифічні допоміжні barrel-модулі для Slack, Discord, Signal,
+WhatsApp або подібних розширень. Якщо core потрібна певна поведінка, слід або
+використати власний barrel `api.ts` / `runtime-api.ts` відповідного вбудованого plugin, або
+підняти цю потребу до вузької узагальненої можливості в спільному SDK.
-Зокрема для опитувань існують два шляхи виконання:
+Зокрема для опитувань існує два шляхи виконання:
-- `outbound.sendPoll` — це спільний базовий механізм для каналів, які відповідають загальній моделі опитувань
-- `actions.handleAction("poll")` — це бажаний шлях для специфічної для каналу семантики опитувань або додаткових параметрів опитування
+- `outbound.sendPoll` — це спільний базовий варіант для каналів, що відповідають загальній
+ моделі опитувань
+- `actions.handleAction("poll")` — бажаний шлях для каналоспецифічної семантики опитувань або
+ додаткових параметрів опитувань
-Тепер ядро відкладає спільний розбір опитувань до моменту, коли диспетчеризація опитування плагіна
-відхилить дію, тож обробники опитувань, якими володіє плагін, можуть приймати специфічні для каналу поля
-опитування без блокування загальним парсером опитувань на попередньому етапі.
+Тепер core відкладає спільний розбір опитувань до моменту, коли диспетчеризація опитувань plugin
+відхилить дію, тож обробники опитувань, що належать plugin, можуть приймати
+каналоспецифічні поля опитувань, не блокуючись спочатку узагальненим парсером опитувань.
-Повну послідовність запуску див. у [Конвеєр завантаження](#load-pipeline).
+Повну послідовність запуску див. в [Конвеєрі завантаження](#load-pipeline).
## Модель володіння можливостями
-OpenClaw розглядає нативний плагін як межу володіння для **компанії** або
-**функції**, а не як набір не пов’язаних між собою інтеграцій.
+OpenClaw розглядає нативний plugin як межу володіння для **компанії** або
+**можливості**, а не як набір непов’язаних інтеграцій.
-Це означає:
+Це означає таке:
-- плагін компанії зазвичай має володіти всіма поверхнями OpenClaw, що належать цій компанії
-- плагін функції зазвичай має володіти повною поверхнею функції, яку він додає
-- канали мають споживати спільні можливості ядра замість того, щоб повторно реалізовувати
- поведінку провайдера у довільний спосіб
+- plugin компанії зазвичай має володіти всіма поверхнями OpenClaw, що стосуються цієї компанії
+- plugin можливості зазвичай має володіти повною поверхнею можливості, яку він додає
+- канали мають споживати спільні можливості core замість того, щоб спеціальним чином
+ повторно реалізовувати поведінку постачальників
Приклади:
-- вбудований плагін `openai` володіє поведінкою провайдера моделей OpenAI та
- поведінкою OpenAI для мовлення + голосу в реальному часі + розуміння медіа + генерації зображень
-- вбудований плагін `elevenlabs` володіє поведінкою мовлення ElevenLabs
-- вбудований плагін `microsoft` володіє поведінкою мовлення Microsoft
-- вбудований плагін `google` володіє поведінкою провайдера моделей Google, а також поведінкою Google для
+- вбудований plugin `openai` володіє поведінкою постачальника моделей OpenAI, а також поведінкою OpenAI для
+ мовлення + голосу в реальному часі + розуміння медіа + генерації зображень
+- вбудований plugin `elevenlabs` володіє поведінкою ElevenLabs для мовлення
+- вбудований plugin `microsoft` володіє поведінкою Microsoft для мовлення
+- вбудований plugin `google` володіє поведінкою постачальника моделей Google, а також поведінкою Google для
розуміння медіа + генерації зображень + вебпошуку
-- вбудований плагін `firecrawl` володіє поведінкою Firecrawl для отримання вебданих
-- вбудовані плагіни `minimax`, `mistral`, `moonshot` і `zai` володіють своїми
- backend для розуміння медіа
-- вбудований плагін `qwen` володіє поведінкою текстового провайдера Qwen, а також
- поведінкою розуміння медіа та генерації відео
-- плагін `voice-call` є плагіном функції: він володіє транспортом викликів, інструментами,
- CLI, маршрутами та мостом Twilio media-stream, але споживає спільні можливості мовлення,
- а також транскрипції в реальному часі й голосу в реальному часі, замість того
- щоб імпортувати плагіни постачальників напряму
+- вбудований plugin `firecrawl` володіє поведінкою Firecrawl для отримання вебданих
+- вбудовані plugin `minimax`, `mistral`, `moonshot` і `zai` володіють своїми
+ бекендами розуміння медіа
+- вбудований plugin `qwen` володіє поведінкою текстового постачальника Qwen, а також
+ поведінкою для розуміння медіа та генерації відео
+- plugin `voice-call` є plugin можливості: він володіє транспортом викликів, інструментами,
+ CLI, маршрутами та мостом медіапотоку Twilio, але споживає спільні можливості мовлення,
+ транскрипції в реальному часі та голосу в реальному часі замість
+ прямого імпорту vendor plugin
-Очікуваний кінцевий стан:
+Бажаний кінцевий стан такий:
-- OpenAI живе в одному плагіні, навіть якщо він охоплює текстові моделі, мовлення, зображення та
+- OpenAI міститься в одному plugin, навіть якщо він охоплює текстові моделі, мовлення, зображення та
майбутнє відео
-- інший постачальник може зробити те саме для власної поверхні
-- каналам не важливо, який плагін постачальника володіє провайдером; вони споживають
- спільний контракт можливостей, який надає ядро
+- інший vendor може зробити те саме для власної області поверхонь
+- канали не повинні зважати, який vendor plugin володіє постачальником; вони споживають
+ спільний контракт можливості, який надає core
-Ось ключове розрізнення:
+Ось ключова відмінність:
- **plugin** = межа володіння
-- **capability** = контракт ядра, який кілька плагінів можуть реалізовувати або споживати
+- **capability** = контракт core, який кілька plugin можуть реалізовувати або споживати
-Тож якщо OpenClaw додає нову доменну область, наприклад відео, перше запитання не
-«який провайдер має жорстко кодувати обробку відео?» Перше запитання — «яким є
-контракт можливості ядра для відео?» Щойно цей контракт існує, плагіни постачальників
-можуть реєструватися для нього, а плагіни каналів/функцій можуть його споживати.
+Тому якщо OpenClaw додає новий домен, наприклад відео, перше запитання не таке:
+"який постачальник має жорстко закодувати обробку відео?" Перше запитання таке: "яким є
+контракт core для можливості відео?" Щойно цей контракт з’являється, vendor plugin
+можуть реєструватися для нього, а plugin каналів/можливостей можуть його споживати.
-Якщо можливість ще не існує, правильним кроком зазвичай є:
+Якщо можливість іще не існує, правильний крок зазвичай такий:
-1. визначити відсутню можливість у ядрі
-2. відкрити її через API/runtime плагіна у типізований спосіб
-3. підключити канали/функції до цієї можливості
-4. дозволити плагінам постачальників реєструвати реалізації
+1. визначити відсутню можливість у core
+2. відкрити її через API/runtime plugin у типізований спосіб
+3. підключити канали/можливості до цієї можливості
+4. дозволити vendor plugin реєструвати реалізації
-Це зберігає явне володіння й водночас уникає поведінки ядра, яка залежить від
-одного постачальника або одноразового шляху коду, специфічного для плагіна.
+Це зберігає явність володіння та водночас дає змогу уникнути поведінки core, яка залежить від
+одного vendor або одноразового plugin-специфічного шляху коду.
-### Шарування можливостей
+### Нашарування можливостей
-Використовуйте цю ментальну модель, коли вирішуєте, де має розміщуватися код:
+Використовуйте таку ментальну модель, коли вирішуєте, де має розміщуватися код:
-- **шар можливостей ядра**: спільна оркестрація, політика, fallback, правила
+- **шар можливостей core**: спільна оркестрація, політика, резервні сценарії, правила
злиття конфігурації, семантика доставки та типізовані контракти
-- **шар плагіна постачальника**: API, auth, каталоги моделей, мовлення
- synthesis, генерація зображень, майбутні backend відео, endpoint використання, специфічні для постачальника
-- **шар плагіна каналу/функції**: інтеграція Slack/Discord/voice-call/тощо,
- яка споживає можливості ядра й подає їх на поверхні
+- **шар vendor plugin**: vendor-специфічні API, автентифікація, каталоги моделей, синтез мовлення,
+ генерація зображень, майбутні відеобекенди, кінцеві точки використання
+- **шар plugin каналів/можливостей**: інтеграції Slack/Discord/voice-call тощо,
+ які споживають можливості core і представляють їх на певній поверхні
-Наприклад, TTS дотримується такої форми:
+Наприклад, TTS має таку форму:
-- ядро володіє політикою TTS під час відповіді, порядком fallback, prefs і доставкою каналом
-- `openai`, `elevenlabs` і `microsoft` володіють реалізаціями synthesis
-- `voice-call` споживає допоміжний засіб runtime для telephony TTS
+- core володіє політикою TTS під час відповіді, порядком резервних сценаріїв, налаштуваннями та доставкою в канали
+- `openai`, `elevenlabs` і `microsoft` володіють реалізаціями синтезу
+- `voice-call` споживає допоміжний runtime для TTS у телефонії
-Тій самій моделі слід надавати перевагу і для майбутніх можливостей.
+Той самий шаблон слід віддавати перевагу й для майбутніх можливостей.
-### Приклад плагіна компанії з кількома можливостями
+### Приклад plugin компанії з кількома можливостями
-Плагін компанії має виглядати цілісно ззовні. Якщо OpenClaw має спільні
-контракти для моделей, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа,
-генерації зображень, генерації відео, отримання вебданих і вебпошуку,
-постачальник може володіти всіма своїми поверхнями в одному місці:
+Plugin компанії має виглядати цілісно ззовні. Якщо OpenClaw має спільні
+контракти для моделей, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння
+медіа, генерації зображень, генерації відео, отримання вебданих і вебпошуку,
+vendor може володіти всіма своїми поверхнями в одному місці:
```ts
import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
@@ -372,240 +374,238 @@ export default plugin;
Важливі не точні назви допоміжних засобів. Важлива форма:
-- один плагін володіє поверхнею постачальника
-- ядро все одно володіє контрактами можливостей
-- канали та плагіни функцій споживають допоміжні засоби `api.runtime.*`, а не код постачальника
-- контрактні тести можуть перевіряти, що плагін зареєстрував ті можливості,
- якими він заявляє, що володіє
+- один plugin володіє поверхнею vendor
+- core усе ще володіє контрактами можливостей
+- канали та plugin можливостей споживають допоміжні засоби `api.runtime.*`, а не код vendor
+- контрактні тести можуть перевірити, що plugin зареєстрував ті можливості,
+ якими, за його твердженням, володіє
### Приклад можливості: розуміння відео
OpenClaw уже розглядає розуміння зображень/аудіо/відео як одну спільну
-можливість. Та сама модель володіння застосовується і тут:
+можливість. Тут застосовується та сама модель володіння:
-1. ядро визначає контракт розуміння медіа
-2. плагіни постачальників реєструють `describeImage`, `transcribeAudio` і
- `describeVideo`, де це застосовно
-3. канали та плагіни функцій споживають спільну поведінку ядра замість
- прямого підключення до коду постачальника
+1. core визначає контракт розуміння медіа
+2. vendor plugin реєструють `describeImage`, `transcribeAudio` і
+ `describeVideo`, де це доречно
+3. канали та plugin можливостей споживають спільну поведінку core замість
+ прямого підключення до коду vendor
-Це не дає вбудувати в ядро припущення одного провайдера щодо відео. Плагін володіє
-поверхнею постачальника; ядро володіє контрактом можливості та поведінкою fallback.
+Це дозволяє уникнути вбудовування в core відеоприпущень одного постачальника. Plugin володіє
+поверхнею vendor; core володіє контрактом можливості та поведінкою резервних сценаріїв.
-Генерація відео вже використовує ту саму послідовність: ядро володіє типізованим
-контрактом можливості та допоміжним засобом runtime, а плагіни постачальників реєструють
-реалізації `api.registerVideoGenerationProvider(...)` для нього.
+Генерація відео вже використовує ту саму послідовність: core володіє типізованим
+контрактом можливості та допоміжним runtime, а vendor plugin реєструють
+реалізації `api.registerVideoGenerationProvider(...)` для цього контракту.
-Потрібен конкретний контрольний список розгортання? Див.
-[Посібник з можливостей](/uk/plugins/architecture).
+Потрібен конкретний контрольний список упровадження? Див.
+[Capability Cookbook](/uk/plugins/architecture).
-## Контракти та забезпечення
+## Контракти та забезпечення дотримання
-Поверхня API плагіна навмисно типізована й централізована в
+Поверхня API plugin навмисно типізована й централізована в
`OpenClawPluginApi`. Цей контракт визначає підтримувані точки реєстрації та
-допоміжні засоби runtime, на які плагін може покладатися.
+допоміжні засоби runtime, на які plugin може покладатися.
Чому це важливо:
-- автори плагінів отримують один стабільний внутрішній стандарт
-- ядро може відхиляти дубльоване володіння, наприклад коли два плагіни реєструють один і той самий
- id провайдера
-- під час запуску можна показувати зрозумілу діагностику для некоректної реєстрації
-- контрактні тести можуть забезпечувати володіння вбудованих плагінів і запобігати тихому дрейфу
+- автори plugin отримують один стабільний внутрішній стандарт
+- core може відхиляти дубльоване володіння, наприклад коли два plugin реєструють один і той самий
+ ідентифікатор постачальника
+- під час запуску можна показувати придатні до дії діагностичні повідомлення для некоректних реєстрацій
+- контрактні тести можуть забезпечувати володіння вбудованих plugin і запобігати тихому дрейфу
-Є два шари забезпечення:
+Існує два шари забезпечення дотримання:
-1. **забезпечення реєстрації під час runtime**
- Реєстр плагінів перевіряє реєстрації під час завантаження плагінів. Приклади:
- дубльовані id провайдерів, дубльовані id провайдерів мовлення та некоректні
- реєстрації створюють діагностику плагінів замість невизначеної поведінки.
+1. **забезпечення дотримання під час runtime-реєстрації**
+ Реєстр plugin перевіряє реєстрації під час завантаження plugin. Приклади:
+ дубльовані ідентифікатори постачальників, дубльовані ідентифікатори постачальників мовлення та некоректні
+ реєстрації створюють діагностику plugin замість невизначеної поведінки.
2. **контрактні тести**
- Вбудовані плагіни фіксуються в контрактних реєстрах під час запуску тестів, щоб
- OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для
- провайдерів моделей, провайдерів мовлення, провайдерів вебпошуку та володіння
- реєстрацією вбудованих плагінів.
+ Вбудовані plugin фіксуються в контрактних реєстрах під час тестових запусків, щоб
+ OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для постачальників моделей,
+ постачальників мовлення, постачальників вебпошуку та володіння реєстрацією вбудованих plugin.
-Практичний ефект полягає в тому, що OpenClaw наперед знає, який плагін якою
-поверхнею володіє. Це дає ядру й каналам змогу безшовно компонуватися, тому що володіння
-оголошене, типізоване й придатне до тестування, а не неявне.
+Практичний ефект такий: OpenClaw заздалегідь знає, який plugin якою поверхнею
+володіє. Це дає змогу core і каналам безшовно компонуватися, тому що володіння
+задеклароване, типізоване й перевірюване, а не неявне.
### Що має входити до контракту
-Хороші контракти плагінів є:
+Добрі контракти plugin є:
- типізованими
- невеликими
- специфічними для можливості
-- такими, якими володіє ядро
-- придатними до повторного використання кількома плагінами
-- придатними до споживання каналами/функціями без знання постачальника
+- такими, що належать core
+- придатними до повторного використання кількома plugin
+- придатними до споживання каналами/можливостями без знання vendor
-Погані контракти плагінів — це:
+Погані контракти plugin є:
-- політика, специфічна для постачальника, прихована в ядрі
-- одноразові лазівки для плагінів, які обходять реєстр
-- код каналу, що напряму звертається до реалізації постачальника
-- ad hoc runtime-об’єкти, які не є частиною `OpenClawPluginApi` або
+- vendor-специфічною політикою, прихованою в core
+- одноразовими лазівками для plugin, які оминають реєстр
+- кодом каналу, що напряму звертається до реалізації vendor
+- ad hoc runtime-об’єктами, які не є частиною `OpenClawPluginApi` або
`api.runtime`
-Якщо є сумнів, піднімайте рівень абстракції: спочатку визначте можливість, а потім
-дозвольте плагінам підключатися до неї.
+Якщо є сумніви, підвищуйте рівень абстракції: спершу визначте можливість, а потім
+дозвольте plugin підключатися до неї.
## Модель виконання
-Нативні плагіни OpenClaw працюють **у процесі** разом із Gateway. Вони не
-ізольовані. Завантажений нативний плагін має ту саму межу довіри на рівні процесу, що
-й код ядра.
+Нативні plugin OpenClaw працюють **у межах процесу** разом із Gateway. Вони не
+ізольовані. Завантажений нативний plugin має ту саму межу довіри на рівні процесу, що
+й код core.
Наслідки:
-- нативний плагін може реєструвати інструменти, мережеві обробники, hooks і сервіси
-- помилка в нативному плагіні може спричинити збій або дестабілізувати gateway
-- зловмисний нативний плагін еквівалентний довільному виконанню коду всередині
+- нативний plugin може реєструвати інструменти, мережеві обробники, хуки та сервіси
+- помилка в нативному plugin може призвести до аварійного завершення або дестабілізації gateway
+- шкідливий нативний plugin еквівалентний довільному виконанню коду всередині
процесу OpenClaw
-Сумісні bundle за замовчуванням безпечніші, оскільки OpenClaw наразі розглядає їх
-як пакети метаданих/контенту. У поточних релізах це здебільшого означає
-вбудовані Skills.
+Сумісні пакети за замовчуванням безпечніші, оскільки OpenClaw наразі розглядає їх
+як пакети метаданих/вмісту. У поточних випусках це переважно означає вбудовані
+Skills.
-Використовуйте allowlist і явні шляхи встановлення/завантаження для невбудованих плагінів. Розглядайте
-плагіни робочого простору як код для часу розробки, а не як виробничі значення за замовчуванням.
+Для невбудованих plugin використовуйте allowlist і явні шляхи встановлення/завантаження. Розглядайте
+plugin робочого простору як код для розробки, а не як типові налаштування для production.
-Для назв пакетів вбудованого робочого простору закріплюйте id плагіна в npm-імені:
-`@openclaw/` за замовчуванням або зі схваленим типізованим суфіксом, таким як
-`-provider`, `-plugin`, `-speech`, `-sandbox` або `-media-understanding`, коли
-пакет навмисно відкриває вужчу роль плагіна.
+Для імен пакетів вбудованого робочого простору зберігайте прив’язку ідентифікатора plugin до npm-імені:
+`@openclaw/` за замовчуванням або затверджений типізований суфікс, як-от
+`-provider`, `-plugin`, `-speech`, `-sandbox` чи `-media-understanding`, коли
+пакет навмисно відкриває вужчу роль plugin.
Важлива примітка щодо довіри:
-- `plugins.allow` довіряє **id плагінів**, а не походженню джерела.
-- Плагін робочого простору з тим самим id, що й вбудований плагін, навмисно затіняє
- вбудовану копію, коли такий плагін робочого простору увімкнено/додано до allowlist.
+- `plugins.allow` довіряє **ідентифікаторам plugin**, а не походженню джерела.
+- Plugin робочого простору з тим самим ідентифікатором, що й вбудований plugin, навмисно затіняє
+ вбудовану копію, коли цей plugin робочого простору увімкнено/додано до allowlist.
- Це нормально й корисно для локальної розробки, тестування патчів і hotfix.
## Межа експорту
-OpenClaw експортує можливості, а не зручності реалізації.
+OpenClaw експортує можливості, а не зручні засоби реалізації.
-Зберігайте публічною реєстрацію можливостей. Скорочуйте експорт допоміжних засобів, що не є частиною контракту:
+Зберігайте реєстрацію можливостей публічною. Скорочуйте експорт допоміжних засобів, які не є частиною контракту:
-- підшляхи, специфічні для вбудованих плагінів
-- підшляхи plumbing runtime, які не призначені як публічний API
-- зручні допоміжні засоби, специфічні для постачальника
-- допоміжні засоби setup/onboarding, які є деталями реалізації
+- підшляхи допоміжних засобів, специфічні для вбудованих plugin
+- підшляхи plumbing runtime, які не призначені бути публічним API
+- vendor-специфічні зручні допоміжні засоби
+- допоміжні засоби налаштування/onboarding, які є деталями реалізації
-Деякі підшляхи допоміжних засобів вбудованих плагінів усе ще залишаються у згенерованій
-карті експорту SDK заради сумісності та підтримки вбудованих плагінів. Поточні приклади включають
+Деякі підшляхи допоміжних засобів вбудованих plugin усе ще залишаються в згенерованій карті експорту SDK
+заради сумісності та підтримки вбудованих plugin. Поточні приклади включають
`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
-`plugin-sdk/zalo-setup` і кілька seams `plugin-sdk/matrix*`. Розглядайте їх як
+`plugin-sdk/zalo-setup` і кілька швів `plugin-sdk/matrix*`. Розглядайте їх як
зарезервовані експорти деталей реалізації, а не як рекомендований шаблон SDK для
-нових сторонніх плагінів.
+нових сторонніх plugin.
## Конвеєр завантаження
Під час запуску OpenClaw приблизно виконує таке:
-1. виявляє корені потенційних плагінів
-2. читає нативні маніфести або маніфести сумісних bundle і метадані пакетів
-3. відхиляє небезпечні кандидати
-4. нормалізує конфігурацію плагінів (`plugins.enabled`, `allow`, `deny`, `entries`,
+1. виявляє корені потенційних plugin
+2. читає нативні або сумісні маніфести пакетів і метадані package
+3. відхиляє небезпечних кандидатів
+4. нормалізує конфігурацію plugin (`plugins.enabled`, `allow`, `deny`, `entries`,
`slots`, `load.paths`)
5. визначає стан увімкнення для кожного кандидата
6. завантажує увімкнені нативні модулі через jiti
-7. викликає hooks нативного `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації до реєстру плагінів
+7. викликає нативні хуки `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації в реєстр plugin
8. відкриває реєстр для команд/поверхонь runtime
-`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані плагіни використовують `register`; для нових плагінів віддавайте перевагу `register`.
+`activate` — це застарілий псевдонім для `register`: завантажувач визначає, що присутнє (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані plugin використовують `register`; для нових plugin віддавайте перевагу `register`.
Перевірки безпеки відбуваються **до** виконання runtime. Кандидати блокуються,
-коли entry виходить за межі кореня плагіна, шлях доступний на запис для всіх або
-володіння шляхом виглядає підозрілим для невбудованих плагінів.
+коли точка входу виходить за межі кореня plugin, шлях доступний для запису всім, або
+право власності на шлях виглядає підозрілим для невбудованих plugin.
### Поведінка manifest-first
Маніфест є джерелом істини для control plane. OpenClaw використовує його, щоб:
-- ідентифікувати плагін
-- виявляти оголошені канали/Skills/схему конфігурації або можливості bundle
-- перевіряти `plugins.entries..config`
-- доповнювати мітки/placeholder-и Control UI
+- ідентифікувати plugin
+- виявляти оголошені канали/Skills/схему конфігурації або можливості пакета
+- валідувати `plugins.entries..config`
+- доповнювати ярлики/placeholder-значення в Control UI
- показувати метадані встановлення/каталогу
-- зберігати дешеві дескриптори activation і setup без завантаження runtime плагіна
+- зберігати дешеві дескриптори активації та налаштування без завантаження runtime plugin
-Для нативних плагінів модуль runtime є частиною data plane. Він реєструє
-фактичну поведінку, таку як hooks, інструменти, команди або потоки провайдера.
+Для нативних plugin runtime-модуль є частиною data plane. Він реєструє
+фактичну поведінку, таку як хуки, інструменти, команди або потоки постачальника.
Необов’язкові блоки маніфесту `activation` і `setup` залишаються в control plane.
-Це дескриптори лише з метаданими для планування activation і виявлення setup;
-вони не замінюють реєстрацію runtime, `register(...)` або `setupEntry`.
-Перші реальні споживачі activation тепер використовують підказки маніфесту для команд, каналів і провайдерів,
-щоб звузити завантаження плагінів до ширшої матеріалізації реєстру:
+Це лише дескриптори метаданих для планування активації та виявлення налаштування;
+вони не замінюють runtime-реєстрацію, `register(...)` або `setupEntry`.
+Перші живі споживачі активації тепер використовують підказки маніфесту щодо команд, каналів і постачальників,
+щоб звузити завантаження plugin до ширшої матеріалізації реєстру:
-- завантаження CLI звужується до плагінів, які володіють запитаною основною командою
-- setup каналу/визначення плагіна звужується до плагінів, які володіють запитаним
- id каналу
-- явне setup провайдера/визначення runtime звужується до плагінів, які володіють
- запитаним id провайдера
+- завантаження CLI звужується до plugin, які володіють запитаною первинною командою
+- визначення plugin/налаштування каналу звужується до plugin, які володіють запитаним
+ ідентифікатором каналу
+- явне визначення налаштування/runtime постачальника звужується до plugin, які володіють
+ запитаним ідентифікатором постачальника
-Виявлення setup тепер надає перевагу id, якими володіють дескриптори, таким як `setup.providers` і
-`setup.cliBackends`, щоб звузити коло плагінів-кандидатів до того, як воно повернеться до
-`setup-api` для плагінів, яким і далі потрібні hooks runtime на етапі setup. Якщо більше
-ніж один виявлений плагін заявляє той самий нормалізований id провайдера setup або CLI backend,
-пошук setup відхиляє неоднозначного власника замість того, щоб покладатися на порядок
-виявлення.
+Виявлення налаштування тепер віддає перевагу ідентифікаторам, що належать дескрипторам, таким як `setup.providers` і
+`setup.cliBackends`, щоб звузити коло кандидатів plugin, перш ніж перейти до
+`setup-api` для plugin, яким усе ще потрібні runtime-хуки на етапі налаштування. Якщо більше ніж
+один виявлений plugin заявляє той самий нормалізований ідентифікатор постачальника налаштування або бекенда CLI,
+пошук налаштування відхиляє неоднозначного власника замість того, щоб покладатися на порядок виявлення.
### Що кешує завантажувач
-OpenClaw зберігає короткі внутрішньопроцесні кеші для:
+OpenClaw підтримує короткоживучі внутрішньопроцесні кеші для:
- результатів виявлення
- даних реєстру маніфестів
-- реєстрів завантажених плагінів
+- реєстрів завантажених plugin
-Ці кеші зменшують стрибкоподібне навантаження під час запуску та витрати на повторні команди. Їх безпечно
-розглядати як короткоживучі кеші продуктивності, а не як постійне збереження.
+Ці кеші зменшують стрибкоподібне навантаження під час запуску та накладні витрати повторних команд. Їх безпечно
+сприймати як короткоживучі кеші продуктивності, а не як постійне зберігання.
Примітка щодо продуктивності:
-- Установіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або
+- Встановіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або
`OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, щоб вимкнути ці кеші.
- Налаштовуйте вікна кешу за допомогою `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і
`OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`.
## Модель реєстру
-Завантажені плагіни не змінюють напряму довільні глобальні об’єкти ядра. Вони реєструються в
-центральному реєстрі плагінів.
+Завантажені plugin не змінюють напряму довільні глобальні об’єкти core. Вони реєструються в
+центральному реєстрі plugin.
Реєстр відстежує:
-- записи плагінів (ідентичність, джерело, походження, статус, діагностика)
+- записи plugin (ідентичність, джерело, походження, статус, діагностика)
- інструменти
-- застарілі hooks і типізовані hooks
+- застарілі хуки й типізовані хуки
- канали
-- провайдери
+- постачальників
- обробники Gateway RPC
- HTTP-маршрути
- реєстратори CLI
- фонові сервіси
-- команди, якими володіють плагіни
+- команди, що належать plugin
-Потім можливості ядра читають із цього реєстру замість того, щоб напряму взаємодіяти з модулями плагінів.
-Це зберігає односпрямованість завантаження:
+Потім можливості core читають із цього реєстру замість прямої взаємодії з модулями plugin.
+Це зберігає одностороннє завантаження:
-- модуль плагіна -> реєстрація в реєстрі
-- runtime ядра -> споживання реєстру
+- модуль plugin -> реєстрація в реєстрі
+- runtime core -> споживання з реєстру
-Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь ядра потрібна лише
-одна точка інтеграції: «прочитати реєстр», а не «робити спеціальний випадок для кожного модуля плагіна».
+Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь core потрібна
+лише одна точка інтеграції: "читати реєстр", а не "створювати окрему обробку для кожного модуля plugin".
-## Зворотні виклики прив’язки розмов
+## Колбеки прив’язки розмов
-Плагіни, які прив’язують розмову, можуть реагувати, коли дозвіл буде вирішено.
+Plugin, які прив’язують розмову, можуть реагувати, коли погодження буде завершено.
-Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після того, як запит на прив’язку буде схвалено або відхилено:
+Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати колбек після того, як запит на прив’язку буде схвалено або відхилено:
```ts
export default {
@@ -625,28 +625,28 @@ export default {
};
```
-Поля вмісту зворотного виклику:
+Поля в payload колбека:
- `status`: `"approved"` або `"denied"`
- `decision`: `"allow-once"`, `"allow-always"` або `"deny"`
- `binding`: визначена прив’язка для схвалених запитів
-- `request`: підсумок початкового запиту, підказка від’єднання, id відправника та
+- `request`: початковий зведений запит, підказка щодо від’єднання, ідентифікатор відправника та
метадані розмови
-Цей зворотний виклик призначений лише для сповіщення. Він не змінює того, кому дозволено прив’язувати
-розмову, і запускається після завершення обробки схвалення в ядрі.
+Цей колбек призначений лише для сповіщення. Він не змінює те, кому дозволено прив’язувати
+розмову, і виконується після завершення обробки погодження в core.
-## Hooks runtime провайдера
+## Хуки runtime постачальника
-Тепер плагіни провайдерів мають два шари:
+Provider Plugins тепер мають два шари:
-- метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-auth провайдера
- до завантаження runtime, `providerAuthAliases` для варіантів провайдера, що спільно використовують
- auth, `channelEnvVars` для дешевого пошуку env/setup каналу до
- завантаження runtime, а також `providerAuthChoices` для дешевих міток onboarding/auth-choice і
+- метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку автентифікації постачальника через env
+ до завантаження runtime, `providerAuthAliases` для варіантів постачальника, що використовують спільну
+ автентифікацію, `channelEnvVars` для дешевого пошуку channel env/setup до
+ завантаження runtime, а також `providerAuthChoices` для дешевих ярликів onboarding/вибору автентифікації та
метаданих прапорців CLI до завантаження runtime
-- hooks часу конфігурації: `catalog` / застарілий `discovery` плюс `applyConfigDefaults`
-- hooks runtime: `normalizeModelId`, `normalizeTransport`,
+- хуки на етапі конфігурації: `catalog` / застарілий `discovery` плюс `applyConfigDefaults`
+- runtime-хуки: `normalizeModelId`, `normalizeTransport`,
`normalizeConfig`,
`applyNativeStreamingUsageCompat`, `resolveConfigApiKey`,
`resolveSyntheticAuth`, `resolveExternalAuthProfiles`,
@@ -661,96 +661,97 @@ export default {
`classifyFailoverReason`, `isCacheTtlEligible`,
`buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`,
`isBinaryThinking`, `supportsXHighThinking`, `supportsAdaptiveThinking`,
+ `supportsMaxThinking`,
`resolveDefaultThinkingLevel`, `isModernModelRef`, `prepareRuntimeAuth`,
`resolveUsageAuth`, `fetchUsageSnapshot`, `createEmbeddingProvider`,
`buildReplayPolicy`,
`sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected`
-OpenClaw, як і раніше, володіє узагальненим циклом агента, failover, обробкою transcript і
-політикою інструментів. Ці hooks є поверхнею розширення для поведінки, специфічної для провайдера, без
-потреби в повністю власному transport inference.
+OpenClaw і надалі володіє узагальненим циклом агента, перемиканням на резервний варіант, обробкою транскрипту та
+політикою інструментів. Ці хуки є поверхнею розширення для provider-специфічної поведінки без
+необхідності мати повністю власний транспорт inference.
-Використовуйте `providerAuthEnvVars` у маніфесті, коли провайдер має облікові дані на основі env,
-які узагальнені шляхи auth/status/model-picker повинні бачити без завантаження runtime плагіна.
-Використовуйте `providerAuthAliases` у маніфесті, коли один id провайдера має повторно використовувати
-env vars, профілі auth, auth на основі конфігурації та вибір onboarding API-key іншого id провайдера.
-Використовуйте `providerAuthChoices` у маніфесті, коли поверхні CLI onboarding/auth-choice
-мають знати id вибору провайдера, мітки груп і просту прив’язку auth через один прапорець
-без завантаження runtime провайдера. Зберігайте `envVars` runtime провайдера для
-підказок, орієнтованих на операторів, як-от мітки onboarding або змінні setup
-client-id/client-secret для OAuth.
+Використовуйте маніфест `providerAuthEnvVars`, коли постачальник має облікові дані на основі env,
+які узагальнені шляхи auth/status/model-picker мають бачити без завантаження runtime plugin.
+Використовуйте маніфест `providerAuthAliases`, коли один ідентифікатор постачальника має повторно використовувати
+env vars, профілі автентифікації, автентифікацію з опорою на config та варіант onboarding API-ключа іншого ідентифікатора постачальника.
+Використовуйте маніфест `providerAuthChoices`, коли поверхні CLI для onboarding/вибору автентифікації
+мають знати ідентифікатор вибору постачальника, ярлики груп і просту прив’язку автентифікації одним прапорцем
+без завантаження runtime постачальника. Зберігайте runtime `envVars` постачальника для підказок, орієнтованих на операторів, таких як ярлики onboarding або
+змінні налаштування client-id/client-secret для OAuth.
-Використовуйте `channelEnvVars` у маніфесті, коли канал має auth або setup на основі env,
-які узагальнений fallback shell-env, перевірки config/status або підказки setup повинні бачити
+Використовуйте маніфест `channelEnvVars`, коли канал має автентифікацію або налаштування, керовані env, які
+узагальнені резервні сценарії shell-env, перевірки config/status або підказки налаштування мають бачити
без завантаження runtime каналу.
-### Порядок hooks і використання
+### Порядок хуків і використання
-Для плагінів моделей/провайдерів OpenClaw викликає hooks приблизно в такому порядку.
-Стовпець «Коли використовувати» — це швидкий посібник для прийняття рішень.
+Для plugin моделей/постачальників OpenClaw викликає хуки приблизно в такому порядку.
+Стовпець "When to use" — це короткий посібник для вибору.
-| # | Hook | Що він робить | Коли використовувати |
+| # | Хук | Що він робить | Коли використовувати |
| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або базовими значеннями `base URL` |
-| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації за замовчуванням, якими володіє провайдер, під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму auth, env або семантики сімейства моделей провайдера |
-| -- | _(пошук вбудованої моделі)_ | OpenClaw спочатку намагається пройти звичайним шляхом реєстру/каталогу | _(це не hook плагіна)_ |
-| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів до канонічного визначення моделі |
-| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера до узагальненого збирання моделі | Провайдер володіє очищенням transport для власних id провайдера в межах того самого сімейства transport |
-| 5 | `normalizeConfig` | Нормалізує `models.providers.` до визначення runtime/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із плагіном; вбудовані допоміжні засоби сімейства Google також страхують підтримувані записи конфігурації Google |
-| 6 | `applyNativeStreamingUsageCompat` | Застосовує переписування сумісності native streaming-usage до конфігурації провайдерів | Провайдеру потрібні виправлення метаданих native streaming usage, зумовлені endpoint |
-| 7 | `resolveConfigApiKey` | Визначає auth env-marker для конфігураційних провайдерів до завантаження auth runtime | Провайдер має власне визначення API-key env-marker; `amazon-bedrock` тут також має вбудований AWS env-marker resolver |
-| 8 | `resolveSyntheticAuth` | Відкриває локальний/self-hosted або auth на основі конфігурації без збереження відкритого тексту | Провайдер може працювати із synthetic/local marker облікових даних |
-| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі auth, якими володіє провайдер; типове значення `persistence` — `runtime-only` для облікових даних, якими володіє CLI/app | Провайдер повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh token |
-| 10 | `shouldDeferSyntheticProfileAuth` | Опускає збережені placeholder-и synthetic profile нижче за auth на основі env/config | Провайдер зберігає synthetic placeholder profile, які не повинні мати вищий пріоритет |
-| 11 | `resolveDynamicModel` | Синхронний fallback для model id, якими володіє провайдер і яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream model id |
-| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані до визначення невідомих id |
-| 13 | `normalizeResolvedModel` | Фінальне переписування до того, як embedded runner використає визначену модель | Провайдеру потрібні переписування transport, але він усе ще використовує transport ядра |
-| 14 | `contributeResolvedModelCompat` | Додає прапорці compat для моделей постачальника за іншим сумісним transport | Провайдер розпізнає власні моделі на proxy transport без перебрання на себе ролі провайдера |
-| 15 | `capabilities` | Метадані transcript/tooling, якими володіє провайдер і які використовує спільна логіка ядра | Провайдеру потрібні особливості transcript/сімейства провайдера |
-| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить embedded runner | Провайдеру потрібне очищення схем для сімейства transport |
-| 17 | `inspectToolSchemas` | Виводить діагностику схем, якими володіє провайдер, після нормалізації | Провайдер хоче попередження про ключові слова без навчання ядра правилам, специфічним для провайдера |
-| 18 | `resolveReasoningOutputMode` | Вибирає native або tagged контракт виводу reasoning | Провайдеру потрібен tagged reasoning/final output замість native полів |
-| 19 | `prepareExtraParams` | Нормалізація параметрів запиту до узагальнених обгорток параметрів потоку | Провайдеру потрібні параметри запиту за замовчуванням або очищення параметрів для конкретного провайдера |
-| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку власним transport | Провайдеру потрібен власний wire protocol, а не просто обгортка |
-| 21 | `wrapStreamFn` | Обгортка потоку після застосування узагальнених обгорток | Провайдеру потрібні обгортки сумісності заголовків/тіла/моделі запиту без власного transport |
-| 22 | `resolveTransportTurnState` | Додає native заголовки transport або метадані на рівні окремого ходу | Провайдер хоче, щоб узагальнені transport надсилали native ідентичність ходу, специфічну для провайдера |
-| 23 | `resolveWebSocketSessionPolicy` | Додає native заголовки WebSocket або політику охолодження сесії | Провайдер хоче, щоб узагальнені WS transport налаштовували заголовки сесії або політику fallback |
-| 24 | `formatApiKey` | Форматер профілю auth: збережений профіль стає рядком `apiKey` runtime | Провайдер зберігає додаткові метадані auth і потребує власної форми token для runtime |
-| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для власних endpoint оновлення або політики помилок оновлення | Провайдер не відповідає спільним засобам оновлення `pi-ai` |
-| 26 | `buildAuthDoctorHint` | Підказка виправлення, що додається, коли оновлення OAuth завершується помилкою | Провайдеру потрібні власні вказівки з виправлення auth після помилки оновлення |
-| 27 | `matchesContextOverflowError` | Matcher переповнення контекстного вікна, яким володіє провайдер | Провайдер має сирі помилки переповнення, які узагальнені евристики пропустять |
-| 28 | `classifyFailoverReason` | Класифікація причин failover, якою володіє провайдер | Провайдер може зіставляти сирі помилки API/transport із rate-limit/перевантаженням/тощо |
-| 29 | `isCacheTtlEligible` | Політика prompt-cache для провайдерів proxy/backhaul | Провайдеру потрібне керування TTL кешу, специфічне для proxy |
-| 30 | `buildMissingAuthMessage` | Замінник узагальненого повідомлення відновлення для відсутнього auth | Провайдеру потрібна власна підказка відновлення для відсутнього auth |
-| 31 | `suppressBuiltInModel` | Приховування застарілої upstream моделі плюс необов’язкова підказка помилки для користувача | Провайдеру потрібно приховати застарілі upstream рядки або замінити їх підказкою постачальника |
-| 32 | `augmentModelCatalog` | Synthetic/final рядки каталогу, додані після виявлення | Провайдеру потрібні synthetic рядки прямої сумісності в `models list` і засобах вибору |
-| 33 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для провайдерів binary-thinking | Провайдер підтримує лише двійкове thinking увімк./вимк. |
-| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Провайдер хоче `xhigh` лише для підмножини моделей |
-| 35 | `supportsAdaptiveThinking` | Підтримка thinking `adaptive` для вибраних моделей | Провайдер хоче показувати `adaptive` лише для моделей із керованим провайдером adaptive thinking |
-| 36 | `resolveDefaultThinkingLevel` | Типовий рівень `/think` для конкретного сімейства моделей | Провайдер володіє типовою політикою `/think` для сімейства моделей |
-| 37 | `isModernModelRef` | Matcher modern-model для фільтрів live profile і вибору smoke | Провайдер володіє зіставленням preferred-model для live/smoke |
-| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний token/key runtime безпосередньо перед inference | Провайдеру потрібен обмін token або короткоживучі облікові дані запиту |
-| 39 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` та пов’язаних поверхонь статусу | Провайдеру потрібен власний розбір token використання/квот або інші облікові дані usage |
-| 40 | `fetchUsageSnapshot` | Отримує та нормалізує специфічні для провайдера snapshots використання/квот після визначення auth | Провайдеру потрібен специфічний для нього endpoint usage або парсер payload |
-| 41 | `createEmbeddingProvider` | Будує адаптер embedding, яким володіє провайдер, для пам’яті/пошуку | Поведінка embedding для пам’яті належить плагіну провайдера |
-| 42 | `buildReplayPolicy` | Повертає політику replay, що керує обробкою transcript для провайдера | Провайдеру потрібна власна політика transcript (наприклад, видалення блоків thinking) |
-| 43 | `sanitizeReplayHistory` | Переписує історію replay після узагальненого очищення transcript | Провайдеру потрібні специфічні для нього переписування replay понад спільні допоміжні засоби Compaction |
-| 44 | `validateReplayTurns` | Фінальна перевірка або переформування ходів replay перед embedded runner | Transport провайдера потребує суворішої перевірки ходів після узагальненої санації |
-| 45 | `onModelSelected` | Запускає побічні ефекти після вибору моделі, якими володіє провайдер | Провайдеру потрібна телеметрія або стан, яким володіє провайдер, коли модель стає активною |
+| 1 | `catalog` | Публікує конфігурацію постачальника в `models.providers` під час генерації `models.json` | Постачальник володіє каталогом або базовими значеннями `base URL` |
+| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать постачальнику, під час матеріалізації конфігурації | Типові значення залежать від режиму автентифікації, env або семантики сімейства моделей постачальника |
+| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях реєстру/каталогу | _(не є хуком plugin)_ |
+| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Постачальник володіє очищенням псевдонімів перед визначенням канонічної моделі |
+| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства постачальника перед загальним складанням моделі | Постачальник володіє очищенням транспорту для користувацьких ідентифікаторів постачальників у тому самому сімействі транспорту |
+| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням runtime/постачальника | Постачальнику потрібне очищення конфігурації, яке має жити разом із plugin; допоміжні засоби вбудованого сімейства Google також страхують підтримувані записи конфігурації Google |
+| 6 | `applyNativeStreamingUsageCompat` | Застосовує переписування сумісності native streaming-usage до постачальників конфігурації | Постачальнику потрібні виправлення метаданих native streaming usage, зумовлені кінцевою точкою |
+| 7 | `resolveConfigApiKey` | Визначає автентифікацію env-marker для постачальників конфігурації до завантаження runtime-автентифікації | Постачальник має власне визначення API-ключа env-marker; `amazon-bedrock` також має тут вбудований розпізнавач AWS env-marker |
+| 8 | `resolveSyntheticAuth` | Виводить локальну/self-hosted або підкріплену config автентифікацію без збереження відкритого тексту | Постачальник може працювати із синтетичним/локальним маркером облікових даних |
+| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі автентифікації, що належать постачальнику; типове значення `persistence` — `runtime-only` для облікових даних, що належать CLI/app | Постачальник повторно використовує зовнішні облікові дані автентифікації без збереження скопійованих refresh-токенів |
+| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених синтетичних заповнювачів профілю порівняно з автентифікацією на основі env/config | Постачальник зберігає синтетичні профілі-заповнювачі, які не мають отримувати вищий пріоритет |
+| 11 | `resolveDynamicModel` | Синхронний резервний варіант для model id, що належать постачальнику і яких ще немає в локальному реєстрі | Постачальник приймає довільні upstream model id |
+| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Постачальнику потрібні мережеві метадані перед визначенням невідомих id |
+| 13 | `normalizeResolvedModel` | Фінальне переписування перед тим, як embedded runner використає визначену модель | Постачальнику потрібні переписування транспорту, але він усе ще використовує транспорт core |
+| 14 | `contributeResolvedModelCompat` | Додає прапорці compat для моделей vendor за іншим сумісним транспортом | Постачальник розпізнає власні моделі на проксі-транспорті, не перебираючи на себе самого постачальника |
+| 15 | `capabilities` | Метадані транскрипту/інструментів, що належать постачальнику і використовуються спільною логікою core | Постачальнику потрібні особливості транскрипту/сімейства постачальника |
+| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить embedded runner | Постачальнику потрібне очищення схем для сімейства транспорту |
+| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить постачальнику, після нормалізації | Постачальник хоче попередження щодо ключових слів без навчання core правилам, специфічним для постачальника |
+| 18 | `resolveReasoningOutputMode` | Вибирає native чи tagged контракт виводу reasoning | Постачальнику потрібен tagged reasoning/final output замість native полів |
+| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Постачальнику потрібні типові параметри запиту або очищення параметрів для конкретного постачальника |
+| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку власним транспортом | Постачальнику потрібен власний wire protocol, а не просто обгортка |
+| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Постачальнику потрібні обгортки сумісності заголовків/тіла запиту/моделі без власного транспорту |
+| 22 | `resolveTransportTurnState` | Прикріплює native заголовки або метадані транспорту для кожного ходу | Постачальник хоче, щоб загальні транспорти надсилали native ідентичність ходу постачальника |
+| 23 | `resolveWebSocketSessionPolicy` | Прикріплює native заголовки WebSocket або політику охолодження сесії | Постачальник хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або політику резервного варіанта |
+| 24 | `formatApiKey` | Форматувач профілю автентифікації: збережений профіль перетворюється на runtime-рядок `apiKey` | Постачальник зберігає додаткові метадані автентифікації і потребує власної форми runtime-токена |
+| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких кінцевих точок оновлення або політики помилки оновлення | Постачальник не відповідає спільним механізмам оновлення `pi-ai` |
+| 26 | `buildAuthDoctorHint` | Підказка з виправлення, що додається, коли оновлення OAuth завершується помилкою | Постачальнику потрібні власні рекомендації з виправлення автентифікації після помилки оновлення |
+| 27 | `matchesContextOverflowError` | Визначник переповнення вікна контексту, що належить постачальнику | Постачальник має сирі помилки переповнення, які загальні евристики не виявлять |
+| 28 | `classifyFailoverReason` | Класифікація причин переходу на резервний варіант, що належить постачальнику | Постачальник може зіставляти сирі помилки API/транспорту з rate-limit/перевантаженням тощо |
+| 29 | `isCacheTtlEligible` | Політика prompt-cache для проксі/backhaul-постачальників | Постачальнику потрібна специфічна для проксі перевірка TTL кешу |
+| 30 | `buildMissingAuthMessage` | Заміна для загального повідомлення відновлення за відсутності автентифікації | Постачальнику потрібна специфічна для нього підказка відновлення при відсутності автентифікації |
+| 31 | `suppressBuiltInModel` | Пригнічення застарілої upstream-моделі плюс необов’язкова підказка помилки для користувача | Постачальнику потрібно приховати застарілі upstream-рядки або замінити їх підказкою vendor |
+| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після виявлення | Постачальнику потрібні синтетичні рядки forward-compat у `models list` і засобах вибору |
+| 33 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для постачальників із двійковим thinking | Постачальник підтримує лише двійкове thinking увімк./вимк. |
+| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Постачальник хоче `xhigh` лише для підмножини моделей |
+| 35 | `supportsAdaptiveThinking` | Підтримка thinking `adaptive` для вибраних моделей | Постачальник хоче показувати `adaptive` лише для моделей із керованим постачальником adaptive thinking |
+| 36 | `supportsMaxThinking` | Підтримка reasoning `max` для вибраних моделей | Постачальник хоче показувати `max` лише для моделей із max thinking від постачальника |
+| 37 | `resolveDefaultThinkingLevel` | Типовий рівень `/think` для конкретного сімейства моделей | Постачальник володіє типовою політикою `/think` для сімейства моделей |
+| 38 | `isModernModelRef` | Визначник modern-model для фільтрів живих профілів і вибору smoke | Постачальник володіє зіставленням бажаних моделей для live/smoke |
+| 39 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний runtime-токен/ключ безпосередньо перед inference | Постачальнику потрібен обмін токена або короткоживучі облікові дані запиту |
+| 40 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` і пов’язаних поверхонь статусу | Постачальнику потрібен власний розбір токена usage/quota або інші облікові дані usage |
+| 41 | `fetchUsageSnapshot` | Отримує та нормалізує специфічні для постачальника знімки usage/quota після визначення автентифікації | Постачальнику потрібна специфічна для нього кінцева точка usage або парсер payload |
+| 42 | `createEmbeddingProvider` | Створює адаптер embedding, що належить постачальнику, для memory/search | Поведінка embedding для memory належить plugin постачальника |
+| 43 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою транскрипту для постачальника | Постачальнику потрібна власна політика транскрипту, наприклад видалення thinking-block |
+| 44 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Постачальнику потрібні специфічні для нього переписування replay понад спільні допоміжні засоби Compaction |
+| 45 | `validateReplayTurns` | Остаточна валідація або зміна форми ходів replay перед embedded runner | Транспорту постачальника потрібна суворіша валідація ходів після загальної санітизації |
+| 46 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать постачальнику | Постачальнику потрібна телеметрія або стан, що належить постачальнику, коли модель стає активною |
`normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють
-плагін провайдера, який збігся, а потім переходять до інших плагінів провайдерів, здатних до hooks,
-доки один із них справді не змінить id моделі або transport/config. Це зберігає
-працездатність alias/compat shim провайдерів без потреби для викликувача знати, який
-вбудований плагін володіє переписуванням. Якщо жоден hook провайдера не перепише підтримуваний
-запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google все одно
-застосує це очищення сумісності.
+відповідний plugin постачальника, а потім переходять до інших plugin постачальників,
+які підтримують хуки, доки один із них справді не змінить model id або transport/config.
+Це дає змогу shim-реалізаціям alias/compat для постачальників працювати без вимоги до викликача знати, який
+вбудований plugin володіє цим переписуванням. Якщо жоден хук постачальника не перепише підтримуваний
+запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google все одно застосує
+це очищення сумісності.
-Якщо провайдеру потрібен повністю власний wire protocol або власний виконавець запитів,
-це вже інший клас розширення. Ці hooks призначені для поведінки провайдера, яка
-все ще працює на звичайному циклі inference OpenClaw.
+Якщо постачальнику потрібен повністю власний wire protocol або власний виконавець запитів,
+це вже інший клас розширення. Ці хуки призначені для поведінки постачальника, яка
+все ще працює в межах звичайного циклу inference OpenClaw.
-### Приклад провайдера
+### Приклад постачальника
```ts
api.registerProvider({
@@ -808,114 +809,115 @@ api.registerProvider({
- Anthropic використовує `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`,
`resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`,
- `supportsAdaptiveThinking`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`
- і `wrapStreamFn`, тому що він володіє прямою сумісністю Claude 4.6,
- підказками сімейства провайдера, вказівками з відновлення auth, інтеграцією
- endpoint usage, допустимістю prompt-cache, типовими значеннями конфігурації з урахуванням auth, типовою
- політикою/adaptive thinking Claude та специфічним для Anthropic формуванням потоку для
- бета-заголовків, `/fast` / `serviceTier` і `context1m`.
-- Допоміжні засоби потоку Anthropic, специфічні для Claude, наразі залишаються у власному
- публічному seam `api.ts` / `contract-api.ts` вбудованого плагіна. Ця поверхня пакета
+ `supportsAdaptiveThinking`, `supportsMaxThinking`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`,
+ і `wrapStreamFn`, оскільки він володіє forward-compat для Claude 4.6,
+ підказками для сімейства постачальника, рекомендаціями з відновлення автентифікації, інтеграцією
+ кінцевої точки usage, придатністю prompt-cache, типовими значеннями config з урахуванням auth, типовою/адаптивною політикою thinking для Claude
+ та специфічним для Anthropic формуванням потоку для
+ beta-заголовків, `/fast` / `serviceTier` і `context1m`.
+- Специфічні для Claude допоміжні засоби потоку Anthropic поки що залишаються у власному
+ публічному шві `api.ts` / `contract-api.ts` вбудованого plugin. Ця поверхня package
експортує `wrapAnthropicProviderStream`, `resolveAnthropicBetas`,
- `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і нижчорівневі
+ `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і низькорівневі
конструктори обгорток Anthropic замість розширення узагальненого SDK навколо правил
- бета-заголовків одного провайдера.
+ beta-заголовків одного постачальника.
- OpenAI використовує `resolveDynamicModel`, `normalizeResolvedModel` і
`capabilities`, а також `buildMissingAuthMessage`, `suppressBuiltInModel`,
`augmentModelCatalog`, `supportsXHighThinking` і `isModernModelRef`,
- тому що він володіє прямою сумісністю GPT-5.4, прямою нормалізацією OpenAI
- `openai-completions` -> `openai-responses`, підказками auth з урахуванням Codex,
- приховуванням Spark, synthetic рядками списку OpenAI та політикою thinking /
+ оскільки він володіє forward-compat для GPT-5.4, прямою нормалізацією OpenAI
+ `openai-completions` -> `openai-responses`, підказками автентифікації з урахуванням Codex,
+ пригніченням Spark, синтетичними рядками списку OpenAI та політикою thinking /
live-model для GPT-5; сімейство потоків `openai-responses-defaults` володіє
- спільними native обгортками OpenAI Responses для заголовків attribution,
+ спільними native-обгортками OpenAI Responses для заголовків attribution,
`/fast`/`serviceTier`, деталізації тексту, native вебпошуку Codex,
- формування payload сумісності reasoning і керування контекстом Responses.
-- OpenRouter використовує `catalog`, а також `resolveDynamicModel` і
- `prepareDynamicModel`, тому що провайдер є pass-through і може відкривати нові
- id моделей до оновлення статичного каталогу OpenClaw; він також використовує
- `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб тримати
- специфічні для провайдера заголовки запитів, метадані маршрутизації, патчі reasoning і
- політику prompt-cache поза ядром. Його політика replay походить із
- сімейства `passthrough-gemini`, тоді як сімейство потоків `openrouter-thinking`
- володіє ін’єкцією proxy reasoning і пропусками для непідтримуваних моделей / `auto`.
+ формування payload для reasoning-compat і керування контекстом Responses.
+- OpenRouter використовує `catalog` разом із `resolveDynamicModel` і
+ `prepareDynamicModel`, оскільки постачальник є наскрізним і може відкривати нові
+ model id до того, як статичний каталог OpenClaw оновиться; він також використовує
+ `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб зберігати
+ специфічні для постачальника заголовки запитів, метадані маршрутизації, патчі reasoning і
+ політику prompt-cache поза core. Його політика replay походить із сімейства
+ `passthrough-gemini`, тоді як сімейство потоків `openrouter-thinking`
+ володіє ін’єкцією proxy reasoning і пропуском unsupported-model / `auto`.
- GitHub Copilot використовує `catalog`, `auth`, `resolveDynamicModel` і
- `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, тому що йому
- потрібні device login, якими володіє провайдер, поведінка fallback моделей, особливості
- transcript Claude, обмін token GitHub -> token Copilot і endpoint usage, яким володіє провайдер.
+ `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, оскільки йому
+ потрібні вхід через пристрій, що належать постачальнику, поведінка резервного варіанта моделі, особливості
+ транскрипту Claude, обмін GitHub token -> Copilot token і кінцева точка usage, що належить постачальнику.
- OpenAI Codex використовує `catalog`, `resolveDynamicModel`,
`normalizeResolvedModel`, `refreshOAuth` і `augmentModelCatalog`, а також
- `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, тому що він
- усе ще працює на transport OpenAI ядра, але володіє нормалізацією своїх
- transport/base URL, політикою fallback для оновлення OAuth, типовим вибором transport,
- synthetic рядками каталогу Codex та інтеграцією endpoint usage ChatGPT; він
+ `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки він
+ все ще працює на транспортах core OpenAI, але володіє нормалізацією свого
+ транспорту/base URL, політикою резервного варіанта оновлення OAuth, типовим вибором транспорту,
+ синтетичними рядками каталогу Codex та інтеграцією кінцевої точки usage ChatGPT; він
використовує те саме сімейство потоків `openai-responses-defaults`, що й прямий OpenAI.
- Google AI Studio і Gemini CLI OAuth використовують `resolveDynamicModel`,
`buildReplayPolicy`, `sanitizeReplayHistory`,
- `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, тому що
- сімейство replay `google-gemini` володіє fallback прямої сумісності Gemini 3.1,
- native перевіркою replay Gemini, санацією bootstrap replay, режимом
+ `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, оскільки
+ сімейство replay `google-gemini` володіє резервним варіантом forward-compat для Gemini 3.1,
+ native валідацією replay Gemini, санітизацією bootstrap replay, режимом
tagged reasoning-output і зіставленням modern-model, тоді як
- сімейство потоків `google-thinking` володіє нормалізацією payload thinking Gemini;
+ сімейство потоків `google-thinking` володіє нормалізацією payload thinking для Gemini;
Gemini CLI OAuth також використовує `formatApiKey`, `resolveUsageAuth` і
- `fetchUsageSnapshot` для форматування token, розбору token і підключення endpoint квот.
+ `fetchUsageSnapshot` для форматування токена, розбору токена та
+ підключення кінцевої точки quota.
- Anthropic Vertex використовує `buildReplayPolicy` через
сімейство replay `anthropic-by-model`, щоб очищення replay, специфічне для Claude, залишалося
- обмеженим id Claude, а не кожним transport `anthropic-messages`.
+ обмеженим ідентифікаторами Claude, а не кожним транспортом `anthropic-messages`.
- Amazon Bedrock використовує `buildReplayPolicy`, `matchesContextOverflowError`,
- `classifyFailoverReason` і `resolveDefaultThinkingLevel`, тому що він володіє
- класифікацією помилок throttle/not-ready/context-overflow, специфічною для Bedrock,
- для трафіку Anthropic-on-Bedrock; його політика replay все ще використовує той самий
- захист `anthropic-by-model`, лише для Claude.
+ `classifyFailoverReason` і `resolveDefaultThinkingLevel`, оскільки він володіє
+ специфічною для Bedrock класифікацією помилок throttle/not-ready/context-overflow
+ для трафіку Anthropic-on-Bedrock; його політика replay усе ще використовує той самий
+ guard `anthropic-by-model` лише для Claude.
- OpenRouter, Kilocode, Opencode і Opencode Go використовують `buildReplayPolicy`
- через сімейство replay `passthrough-gemini`, тому що вони проксіюють моделі Gemini
- через transport, сумісні з OpenAI, і потребують санації
- thought-signature Gemini без native перевірки replay Gemini або
- переписувань bootstrap.
+ через сімейство replay `passthrough-gemini`, оскільки вони проксіюють моделі Gemini
+ через OpenAI-сумісні транспорти й потребують санітизації
+ thought-signature Gemini без native валідації replay Gemini чи
+ переписування bootstrap.
- MiniMax використовує `buildReplayPolicy` через
- сімейство replay `hybrid-anthropic-openai`, тому що один провайдер володіє і
- семантикою повідомлень Anthropic, і семантикою, сумісною з OpenAI; він зберігає
- видалення блоків thinking лише для Claude на боці Anthropic, водночас перевизначаючи режим
+ сімейство replay `hybrid-anthropic-openai`, оскільки один постачальник володіє і
+ семантикою Anthropic-message, і OpenAI-compatible; це зберігає відкидання
+ thinking-block лише для Claude на боці Anthropic, водночас перевизначаючи режим
виводу reasoning назад на native, а сімейство потоків `minimax-fast-mode` володіє
переписуванням моделей fast-mode на спільному шляху потоку.
-- Moonshot використовує `catalog` і `wrapStreamFn`, тому що все ще використовує спільний
- transport OpenAI, але потребує нормалізації payload thinking, якою володіє провайдер; сімейство
- потоків `moonshot-thinking` зіставляє конфігурацію та стан `/think` зі своїм
- native payload binary thinking.
+- Moonshot використовує `catalog` разом із `wrapStreamFn`, оскільки він усе ще використовує спільний
+ транспорт OpenAI, але потребує нормалізації payload thinking, що належить постачальнику; сімейство потоків
+ `moonshot-thinking` відображає config разом зі станом `/think` на його
+ native binary thinking payload.
- Kilocode використовує `catalog`, `capabilities`, `wrapStreamFn` і
- `isCacheTtlEligible`, тому що йому потрібні заголовки запитів, якими володіє провайдер,
- нормалізація payload reasoning, підказки transcript Gemini та
- керування TTL кешу Anthropic; сімейство потоків `kilocode-thinking` зберігає ін’єкцію
- thinking Kilo на спільному шляху proxy потоку, пропускаючи `kilo/auto` та
- інші proxy id моделей, які не підтримують явні payload reasoning.
+ `isCacheTtlEligible`, оскільки йому потрібні заголовки запитів, що належать постачальнику,
+ нормалізація payload reasoning, підказки транскрипту Gemini і
+ перевірка cache-TTL Anthropic; сімейство потоків `kilocode-thinking` зберігає ін’єкцію
+ Kilo thinking на спільному proxy-шляху потоку, водночас пропускаючи `kilo/auto` та
+ інші proxy model id, які не підтримують явні payload reasoning.
- Z.AI використовує `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`,
`isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`,
- `resolveUsageAuth` і `fetchUsageSnapshot`, тому що він володіє fallback GLM-5,
- типовими значеннями `tool_stream`, UX binary thinking, зіставленням modern-model і
- як auth usage, так і отриманням квот; сімейство потоків `tool-stream-default-on`
- тримає обгортку `tool_stream`, увімкнену за замовчуванням, поза написаним вручну glue для окремих провайдерів.
+ `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки він володіє резервним варіантом GLM-5,
+ типовими значеннями `tool_stream`, UX двійкового thinking, зіставленням modern-model, а також
+ і автентифікацією usage, і отриманням quota; сімейство потоків `tool-stream-default-on` зберігає
+ обгортку `tool_stream` з типовим увімкненням поза рукописним glue-кодом для окремих постачальників.
- xAI використовує `normalizeResolvedModel`, `normalizeTransport`,
`contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`,
`resolveSyntheticAuth`, `resolveDynamicModel` і `isModernModelRef`,
- тому що він володіє нормалізацією native transport xAI Responses, переписуванням
- псевдонімів fast-mode Grok, типовим `tool_stream`, очищенням strict-tool / payload reasoning,
- повторним використанням fallback auth для інструментів, якими володіє плагін, прямим визначенням моделей Grok
- і compat-патчами, якими володіє провайдер, такими як профіль схем інструментів xAI,
- непідтримувані ключові слова схем, native `web_search` і декодування аргументів
- виклику інструментів із HTML-сутностей.
-- Mistral, OpenCode Zen і OpenCode Go використовують лише `capabilities`, щоб тримати
- особливості transcript/tooling поза ядром.
-- Вбудовані провайдери лише з каталогом, такі як `byteplus`, `cloudflare-ai-gateway`,
+ оскільки він володіє нормалізацією native транспорту xAI Responses, переписуванням
+ псевдонімів fast-mode для Grok, типовим `tool_stream`, очищенням strict-tool / reasoning-payload,
+ повторним використанням резервної автентифікації для інструментів, що належать plugin, визначенням
+ forward-compat моделі Grok і compat-патчами, що належать постачальнику, такими як профіль схеми інструментів xAI,
+ непідтримувані ключові слова схеми, native `web_search` і декодування аргументів
+ викликів інструментів з HTML-entity.
+- Mistral, OpenCode Zen і OpenCode Go використовують лише `capabilities`, щоб
+ тримати особливості транскрипту/інструментів поза core.
+- Постачальники лише з каталогом серед вбудованих, такі як `byteplus`, `cloudflare-ai-gateway`,
`huggingface`, `kimi-coding`, `nvidia`, `qianfan`,
`synthetic`, `together`, `venice`, `vercel-ai-gateway` і `volcengine`, використовують
лише `catalog`.
-- Qwen використовує `catalog` для свого текстового провайдера, а також спільні реєстрації
- розуміння медіа та генерації відео для своїх мультимодальних поверхонь.
-- MiniMax і Xiaomi використовують `catalog` разом із hooks usage, тому що їхня поведінка `/usage`
- належить плагіну, хоча inference усе ще працює через спільні transport.
+- Qwen використовує `catalog` для свого текстового постачальника, а також спільні реєстрації
+ розуміння медіа й генерації відео для своїх мультимодальних поверхонь.
+- MiniMax і Xiaomi використовують `catalog` разом із хуками usage, оскільки їхня поведінка `/usage`
+ належить plugin, навіть попри те, що inference усе ще виконується через спільні транспорти.
## Допоміжні засоби runtime
-Плагіни можуть отримувати доступ до вибраних допоміжних засобів ядра через `api.runtime`. Для TTS:
+Plugin можуть отримувати доступ до вибраних допоміжних засобів core через `api.runtime`. Для TTS:
```ts
const clip = await api.runtime.tts.textToSpeech({
@@ -936,14 +938,14 @@ const voices = await api.runtime.tts.listVoices({
Примітки:
-- `textToSpeech` повертає звичайний payload виводу TTS ядра для поверхонь файлів/голосових повідомлень.
-- Використовує конфігурацію ядра `messages.tts` і вибір провайдера.
-- Повертає буфер аудіо PCM + частоту дискретизації. Плагіни повинні виконати ресемплінг/кодування для провайдерів.
-- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для засобів вибору голосу або потоків setup, якими володіє постачальник.
-- Списки голосів можуть містити ширші метадані, такі як locale, gender і теги personality для засобів вибору, що враховують провайдера.
-- OpenAI і ElevenLabs сьогодні підтримують telephony. Microsoft — ні.
+- `textToSpeech` повертає звичайний payload виводу TTS core для поверхонь файлів/голосових нотаток.
+- Використовує конфігурацію core `messages.tts` і вибір постачальника.
+- Повертає буфер аудіо PCM + частоту дискретизації. Plugin мають виконати ресемплінг/кодування для постачальників.
+- `listVoices` є необов’язковим для кожного постачальника. Використовуйте його для voice picker, що належать vendor, або потоків налаштування.
+- Списки голосів можуть включати багатші метадані, такі як locale, gender і теги personality для picker, обізнаних із постачальником.
+- Сьогодні телефонію підтримують OpenAI і ElevenLabs. Microsoft — ні.
-Плагіни також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`.
+Plugin також можуть реєструвати постачальників мовлення через `api.registerSpeechProvider(...)`.
```ts
api.registerSpeechProvider({
@@ -963,15 +965,15 @@ api.registerSpeechProvider({
Примітки:
-- Зберігайте політику TTS, fallback і доставку відповідей у ядрі.
-- Використовуйте провайдерів мовлення для поведінки synthesis, якою володіє постачальник.
-- Застарілий ввід Microsoft `edge` нормалізується до id провайдера `microsoft`.
-- Бажана модель володіння орієнтована на компанію: один плагін постачальника може володіти
- текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами, коли OpenClaw додає ці
- контракти можливостей.
+- Зберігайте політику TTS, резервні сценарії та доставку відповідей у core.
+- Використовуйте постачальників мовлення для поведінки синтезу, що належить vendor.
+- Застарілий ввід Microsoft `edge` нормалізується до ідентифікатора постачальника `microsoft`.
+- Бажана модель володіння орієнтована на компанію: один vendor plugin може володіти
+ текстовими, мовленнєвими, графічними та майбутніми медіапостачальниками, коли OpenClaw додає
+ ці контракти можливостей.
-Для розуміння зображень/аудіо/відео плагіни реєструють одного типізованого
-провайдера розуміння медіа замість узагальненого набору key/value:
+Для розуміння зображень/аудіо/відео plugin реєструють одного типізованого
+постачальника розуміння медіа замість узагальненого набору ключ/значення:
```ts
api.registerMediaUnderstandingProvider({
@@ -985,16 +987,16 @@ api.registerMediaUnderstandingProvider({
Примітки:
-- Зберігайте orchestration, fallback, конфігурацію та прив’язку каналів у ядрі.
-- Зберігайте поведінку постачальника в плагіні провайдера.
+- Зберігайте оркестрацію, резервні сценарії, config і зв’язування каналів у core.
+- Зберігайте поведінку vendor у plugin постачальника.
- Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові
поля результату, нові необов’язкові можливості.
- Генерація відео вже дотримується того самого шаблону:
- - ядро володіє контрактом можливості та допоміжним засобом runtime
- - плагіни постачальників реєструють `api.registerVideoGenerationProvider(...)`
- - плагіни функцій/каналів споживають `api.runtime.videoGeneration.*`
+ - core володіє контрактом можливості та допоміжним runtime
+ - vendor plugin реєструють `api.registerVideoGenerationProvider(...)`
+ - plugin можливостей/каналів споживають `api.runtime.videoGeneration.*`
-Для допоміжних засобів runtime розуміння медіа плагіни можуть викликати:
+Для допоміжних засобів runtime розуміння медіа plugin можуть викликати:
```ts
const image = await api.runtime.mediaUnderstanding.describeImageFile({
@@ -1009,14 +1011,14 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({
});
```
-Для транскрипції аудіо плагіни можуть використовувати або runtime
-розуміння медіа, або старіший псевдонім STT:
+Для транскрипції аудіо plugin можуть використовувати або runtime розуміння медіа,
+або старіший псевдонім STT:
```ts
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
filePath: "/tmp/inbound-audio.ogg",
cfg: api.config,
- // Optional when MIME cannot be inferred reliably:
+ // Необов’язково, коли MIME не вдається надійно визначити:
mime: "audio/ogg",
});
```
@@ -1025,11 +1027,11 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
- `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для
розуміння зображень/аудіо/відео.
-- Використовує конфігурацію аудіо розуміння медіа ядра (`tools.media.audio`) і порядок fallback провайдерів.
-- Повертає `{ text: undefined }`, коли вивід транскрипції не створюється (наприклад, для пропущеного/непідтримуваного вводу).
-- `api.runtime.stt.transcribeAudioFile(...)` залишається як псевдонім сумісності.
+- Використовує конфігурацію аудіо розуміння медіа в core (`tools.media.audio`) і порядок резервних варіантів постачальників.
+- Повертає `{ text: undefined }`, коли вихід транскрипції не створюється (наприклад, для пропущеного/непідтримуваного вводу).
+- `api.runtime.stt.transcribeAudioFile(...)` залишається як псевдонім для сумісності.
-Плагіни також можуть запускати фонові запуски субагентів через `api.runtime.subagent`:
+Plugin також можуть запускати фонові виконання subagent через `api.runtime.subagent`:
```ts
const result = await api.runtime.subagent.run({
@@ -1044,13 +1046,13 @@ const result = await api.runtime.subagent.run({
Примітки:
- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії.
-- OpenClaw враховує ці поля перевизначення лише для довірених викликувачів.
-- Для fallback-запусків, якими володіє плагін, оператори повинні явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`.
-- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені плагіни конкретними канонічними цілями `provider/model`, або `"*"` для явного дозволу будь-якої цілі.
-- Недовірені запуски субагентів із плагіна все одно працюють, але запити на перевизначення відхиляються замість тихого fallback.
+- OpenClaw враховує ці поля перевизначення лише для довірених викликачів.
+- Для запусків резервних варіантів, що належать plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`.
+- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені plugin конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль.
+- Запуски subagent із недовірених plugin усе ще працюють, але запити на перевизначення відхиляються замість тихого переходу на резервний варіант.
-Для вебпошуку плагіни можуть споживати спільний допоміжний засіб runtime замість
-звернення до прив’язки інструментів агента:
+Для вебпошуку plugin можуть споживати спільний допоміжний runtime замість
+звернення до зв’язування інструмента агента:
```ts
const providers = api.runtime.webSearch.listProviders({
@@ -1066,14 +1068,14 @@ const result = await api.runtime.webSearch.search({
});
```
-Плагіни також можуть реєструвати провайдерів вебпошуку через
+Plugin також можуть реєструвати постачальників вебпошуку через
`api.registerWebSearchProvider(...)`.
Примітки:
-- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запитів у ядрі.
-- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для постачальника.
-- `api.runtime.webSearch.*` — це бажана спільна поверхня для плагінів функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента.
+- Зберігайте вибір постачальника, визначення облікових даних і спільну семантику запитів у core.
+- Використовуйте постачальників вебпошуку для vendor-специфічних транспортів пошуку.
+- `api.runtime.webSearch.*` — це бажана спільна поверхня для plugin можливостей/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента.
### `api.runtime.imageGeneration`
@@ -1088,12 +1090,12 @@ const providers = api.runtime.imageGeneration.listProviders({
});
```
-- `generate(...)`: генерує зображення з використанням налаштованого ланцюжка провайдерів генерації зображень.
-- `listProviders(...)`: перелічує доступних провайдерів генерації зображень і їхні можливості.
+- `generate(...)`: згенерувати зображення за допомогою налаштованого ланцюжка постачальників генерації зображень.
+- `listProviders(...)`: перелічити доступних постачальників генерації зображень і їхні можливості.
## HTTP-маршрути Gateway
-Плагіни можуть відкривати HTTP endpoint через `api.registerHttpRoute(...)`.
+Plugin можуть відкривати HTTP-ендпоїнти через `api.registerHttpRoute(...)`.
```ts
api.registerHttpRoute({
@@ -1111,31 +1113,31 @@ api.registerHttpRoute({
Поля маршруту:
- `path`: шлях маршруту під HTTP-сервером gateway.
-- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайний auth gateway, або `"plugin"` для auth/webhook verification, якими керує плагін.
+- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайну автентифікацію gateway, або `"plugin"` для автентифікації/перевірки Webhook, якою керує plugin.
- `match`: необов’язкове поле. `"exact"` (типово) або `"prefix"`.
-- `replaceExisting`: необов’язкове поле. Дозволяє тому самому плагіну замінити власну наявну реєстрацію маршруту.
+- `replaceExisting`: необов’язкове поле. Дозволяє тому самому plugin замінювати власну наявну реєстрацію маршруту.
- `handler`: повертайте `true`, коли маршрут обробив запит.
Примітки:
-- `api.registerHttpHandler(...)` видалено, і він спричинить помилку завантаження плагіна. Натомість використовуйте `api.registerHttpRoute(...)`.
-- Маршрути плагінів повинні явно оголошувати `auth`.
-- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна.
-- Перекривні маршрути з різними рівнями `auth` відхиляються. Залишайте ланцюжки fallthrough `exact`/`prefix` лише на одному рівні `auth`.
-- Маршрути `auth: "plugin"` **не** отримують автоматично операторські області runtime. Вони призначені для webhook/signature verification, якими керує плагін, а не для привілейованих допоміжних викликів Gateway.
+- `api.registerHttpHandler(...)` видалено, і він спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`.
+- Маршрути plugin мають явно оголошувати `auth`.
+- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один plugin не може замінити маршрут іншого plugin.
+- Перекривні маршрути з різними рівнями `auth` відхиляються. Зберігайте ланцюжки переходу `exact`/`prefix` лише на одному рівні auth.
+- Маршрути `auth: "plugin"` **не** отримують автоматично області runtime оператора. Вони призначені для Webhook і перевірки підписів, якими керує plugin, а не для привілейованих допоміжних викликів Gateway.
- Маршрути `auth: "gateway"` працюють усередині області runtime запиту Gateway, але ця область навмисно консервативна:
- - bearer auth із спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області runtime маршрутів плагіна на рівні `operator.write`, навіть якщо викликувач надсилає `x-openclaw-scopes`
- - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише коли заголовок явно присутній
- - якщо `x-openclaw-scopes` відсутній у таких запитах маршрутів плагіна з ідентичністю, область runtime повертається до `operator.write`
-- Практичне правило: не припускайте, що маршрут плагіна з auth gateway є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з ідентичністю та задокументуйте явний контракт заголовка `x-openclaw-scopes`.
+ - bearer-автентифікація зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області runtime маршрутів plugin зафіксованими на `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes`
+ - довірені HTTP-режими з ідентичністю викликача (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній
+ - якщо `x-openclaw-scopes` відсутній у таких запитах маршруту plugin з ідентичністю, область runtime повертається до `operator.write`
+- Практичне правило: не припускайте, що маршрут plugin з автентифікацією gateway є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим автентифікації з ідентичністю викликача й документуйте явний контракт заголовка `x-openclaw-scopes`.
## Шляхи імпорту Plugin SDK
-Під час написання плагінів використовуйте підшляхи SDK замість монолітного імпорту `openclaw/plugin-sdk`:
+Під час створення plugin використовуйте підшляхи SDK замість монолітного імпорту `openclaw/plugin-sdk`:
-- `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації плагінів.
-- `openclaw/plugin-sdk/core` для узагальненого спільного контракту, орієнтованого на плагіни.
-- `openclaw/plugin-sdk/config-schema` для експорту Zod-схеми кореневого `openclaw.json`
+- `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації plugin.
+- `openclaw/plugin-sdk/core` для узагальненого спільного контракту, орієнтованого на plugin.
+- `openclaw/plugin-sdk/config-schema` для експорту кореневої Zod-схеми `openclaw.json`
(`OpenClawSchema`).
- Стабільні примітиви каналів, такі як `openclaw/plugin-sdk/channel-setup`,
`openclaw/plugin-sdk/setup-runtime`,
@@ -1149,15 +1151,15 @@ api.registerHttpRoute({
`openclaw/plugin-sdk/channel-reply-pipeline`,
`openclaw/plugin-sdk/command-auth`,
`openclaw/plugin-sdk/secret-input` і
- `openclaw/plugin-sdk/webhook-ingress` для спільної прив’язки setup/auth/reply/webhook.
- `channel-inbound` — це спільний дім для debounce, зіставлення mention,
- допоміжних засобів політики вхідних mention, форматування envelope та
- допоміжних засобів контексту вхідного envelope.
- `channel-setup` — це вузький seam setup для необов’язкового встановлення.
- `setup-runtime` — це безпечна для runtime поверхня setup, що використовується `setupEntry` /
- відкладеним запуском, включно з безпечними для імпорту адаптерами patch setup.
- `setup-adapter-runtime` — це env-aware seam адаптера setup облікового запису.
- `setup-tools` — це малий seam допоміжних засобів для CLI/архівів/документації (`formatCliCommand`,
+ `openclaw/plugin-sdk/webhook-ingress` для спільного зв’язування
+ налаштування/автентифікації/відповідей/Webhook. `channel-inbound` — це спільний дім для debounce, зіставлення згадок,
+ допоміжних засобів політики вхідних згадок, форматування envelope і контекстних
+ допоміжних засобів для вхідних envelope.
+ `channel-setup` — це вузький шов налаштування необов’язкового встановлення.
+ `setup-runtime` — це безпечна для runtime поверхня налаштування, яка використовується `setupEntry` /
+ відкладеним запуском, включно з безпечними для імпорту адаптерами патчів налаштування.
+ `setup-adapter-runtime` — це env-обізнаний шов адаптера налаштування облікового запису.
+ `setup-tools` — це малий шов допоміжних засобів для CLI/архівів/документації (`formatCliCommand`,
`detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`,
`CONFIG_DIR`).
- Доменні підшляхи, такі як `openclaw/plugin-sdk/channel-config-helpers`,
@@ -1179,45 +1181,46 @@ api.registerHttpRoute({
`openclaw/plugin-sdk/text-runtime`,
`openclaw/plugin-sdk/runtime-store` і
`openclaw/plugin-sdk/directory-runtime` для спільних допоміжних засобів runtime/config.
- `telegram-command-config` — це вузький публічний seam для нормалізації/перевірки користувацьких
- команд Telegram і він залишається доступним, навіть якщо
- поверхня контракту вбудованого Telegram тимчасово недоступна.
- `text-runtime` — це спільний seam text/markdown/logging, включно з
- видаленням тексту, видимого assistant, допоміжними засобами рендерингу/розбиття markdown, допоміжними засобами редагування,
- допоміжними засобами тегів директив і безпечними утилітами тексту.
-- Специфічні для погодження channel seams мають віддавати перевагу одному контракту `approvalCapability` у плагіні. Потім ядро читає auth погодження, доставку, рендеринг,
- native-routing і поведінку lazy native-handler через цю одну можливість
- замість змішування поведінки погодження з не пов’язаними полями плагіна.
-- `openclaw/plugin-sdk/channel-runtime` застарів і залишається лише як
- shim сумісності для старіших плагінів. Новий код має імпортувати вужчі
- узагальнені примітиви, а код репозиторію не повинен додавати нові імпорти цього
+ `telegram-command-config` — це вузький публічний шов для нормалізації/валідації користувацьких
+ команд Telegram і він залишається доступним, навіть якщо поверхня контракту вбудованого
+ Telegram тимчасово недоступна.
+ `text-runtime` — це спільний шов для тексту/Markdown/логування, включно з
+ видаленням тексту, видимого помічнику, допоміжними засобами рендерингу/розбиття Markdown, допоміжними засобами редагування,
+ допоміжними засобами тегів директив і утилітами безпечного тексту.
+- Для каналоспецифічних швів погодження слід віддавати перевагу одному контракту `approvalCapability`
+ на plugin. Тоді core зчитує автентифікацію погодження, доставку, рендеринг,
+ native-маршрутизацію та ліниву поведінку native-обробника через цю одну можливість
+ замість змішування поведінки погодження з не пов’язаними полями plugin.
+- `openclaw/plugin-sdk/channel-runtime` є застарілим і залишається лише як
+ shim сумісності для старіших plugin. Новий код має імпортувати вужчі
+ узагальнені примітиви, а код у репозиторії не повинен додавати нові імпорти цього
shim.
-- Внутрішня будова вбудованих розширень залишається приватною. Зовнішні плагіни повинні використовувати лише підшляхи `openclaw/plugin-sdk/*`. Код ядра/тестів OpenClaw може використовувати
- публічні точки входу репозиторію в корені пакета плагіна, такі як `index.js`, `api.js`,
- `runtime-api.js`, `setup-entry.js`, і вузько спрямовані файли, такі як
- `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета плагіна з ядра або з
- іншого розширення.
+- Внутрішні компоненти вбудованих extension залишаються приватними. Зовнішні plugin мають використовувати лише підшляхи `openclaw/plugin-sdk/*`. Код core/test OpenClaw може використовувати
+ публічні точки входу репозиторію під коренем package plugin, такі як `index.js`, `api.js`,
+ `runtime-api.js`, `setup-entry.js`, а також вузькоспрямовані файли, такі як
+ `login-qr-api.js`. Ніколи не імпортуйте `src/*` package plugin із core або з
+ іншого extension.
- Поділ точок входу репозиторію:
`/api.js` — це barrel допоміжних засобів/типів,
`/runtime-api.js` — це barrel лише для runtime,
- `/index.js` — це точка входу вбудованого плагіна,
- а `/setup-entry.js` — це точка входу плагіна setup.
-- Поточні приклади вбудованих провайдерів:
+ `/index.js` — це точка входу вбудованого plugin,
+ а `/setup-entry.js` — це точка входу plugin для налаштування.
+- Поточні приклади вбудованих постачальників:
- Anthropic використовує `api.js` / `contract-api.js` для допоміжних засобів потоку Claude, таких
- як `wrapAnthropicProviderStream`, допоміжні засоби бета-заголовків і розбір `service_tier`.
- - OpenAI використовує `api.js` для конструкторів провайдерів, допоміжних засобів моделей за замовчуванням і
- конструкторів провайдерів реального часу.
- - OpenRouter використовує `api.js` для свого конструктора провайдера, а також допоміжних засобів onboarding/config,
- тоді як `register.runtime.js` усе ще може повторно експортувати узагальнені
+ як `wrapAnthropicProviderStream`, допоміжні засоби beta-заголовків і розбір `service_tier`.
+ - OpenAI використовує `api.js` для конструкторів постачальника, допоміжних засобів типової моделі та
+ конструкторів постачальника realtime.
+ - OpenRouter використовує `api.js` для свого конструктора постачальника, а також допоміжних засобів onboarding/config,
+ тоді як `register.runtime.js` усе ще може реекспортувати узагальнені
допоміжні засоби `plugin-sdk/provider-stream` для локального використання в репозиторії.
-- Публічні точки входу, завантажені через facade, надають перевагу активному знімку конфігурації runtime,
- коли він існує, а потім повертаються до визначеного файлу конфігурації на диску, коли
+- Публічні точки входу, завантажені через facade, віддають перевагу активному знімку конфігурації runtime,
+ якщо він існує, а потім повертаються до визначеного файлу конфігурації на диску, коли
OpenClaw ще не обслуговує знімок runtime.
- Узагальнені спільні примітиви залишаються бажаним публічним контрактом SDK. Невеликий
- зарезервований набір seams сумісності з допоміжними засобами вбудованих каналів із брендуванням
- усе ще існує. Розглядайте їх як seams для підтримки/сумісності вбудованих компонентів, а не як нові цілі імпорту для сторонніх розробників; нові міжканальні контракти й надалі мають з’являтися на
- узагальнених підшляхах `plugin-sdk/*` або в локальних barrels плагіна `api.js` /
- `runtime-api.js`.
+ зарезервований сумісний набір брендованих допоміжних швів вбудованих каналів усе ще
+ існує. Розглядайте їх як шви для підтримки вбудованих компонентів/сумісності, а не як нові цілі імпорту для сторонніх рішень; нові міжканальні контракти все одно мають з’являтися в
+ узагальнених підшляхах `plugin-sdk/*` або в локальних barrel `api.js` /
+ `runtime-api.js` plugin.
Примітка щодо сумісності:
@@ -1225,125 +1228,125 @@ api.registerHttpRoute({
- Спочатку віддавайте перевагу вузьким стабільним примітивам. Новіші підшляхи setup/pairing/reply/
feedback/contract/inbound/threading/command/secret-input/webhook/infra/
allowlist/status/message-tool є бажаним контрактом для нової роботи з
- вбудованими та зовнішніми плагінами.
+ вбудованими й зовнішніми plugin.
Розбір/зіставлення цілей має належати `openclaw/plugin-sdk/channel-targets`.
- Шлюзи дій повідомлень і допоміжні засоби message-id для реакцій мають належати
+ Шлюзи дій із повідомленнями та допоміжні засоби message-id для реакцій мають належати
`openclaw/plugin-sdk/channel-actions`.
-- Барrels допоміжних засобів, специфічні для вбудованих розширень, за замовчуванням не є стабільними. Якщо
- допоміжний засіб потрібен лише вбудованому розширенню, залишайте його за локальним
- seam `api.js` або `runtime-api.js` цього розширення замість того, щоб просувати його до
+- Barrel-модулі допоміжних засобів, специфічні для вбудованих extension, за замовчуванням не є стабільними. Якщо
+ допоміжний засіб потрібен лише вбудованому extension, зберігайте його за
+ локальним швом `api.js` або `runtime-api.js` цього extension замість того, щоб підвищувати його до
`openclaw/plugin-sdk/`.
-- Нові seams спільних допоміжних засобів мають бути узагальненими, а не брендованими під канал. Спільний розбір
- цілей має належати `openclaw/plugin-sdk/channel-targets`; внутрішня логіка, специфічна для каналу,
- залишається за локальним seam `api.js` або `runtime-api.js` плагіна-власника.
+- Нові шви спільних допоміжних засобів мають бути узагальненими, а не брендованими каналом. Спільний розбір
+ цілей має належати `openclaw/plugin-sdk/channel-targets`; специфічні для каналу
+ внутрішні компоненти мають залишатися за локальним швом `api.js` або `runtime-api.js`
+ plugin-власника.
- Підшляхи, специфічні для можливостей, такі як `image-generation`,
- `media-understanding` і `speech`, існують, тому що вбудовані/нативні плагіни
- використовують їх уже сьогодні. Їхня наявність сама по собі не означає, що кожен
- експортований допоміжний засіб є довгостроковим незмінним зовнішнім контрактом.
+ `media-understanding` і `speech`, існують, тому що вбудовані/нативні plugin використовують
+ їх уже сьогодні. Їхня наявність сама по собі не означає, що кожен експортований допоміжний засіб є
+ довгостроковим замороженим зовнішнім контрактом.
## Схеми інструмента повідомлень
-Плагіни мають володіти внесками у схему `describeMessageTool(...)`, специфічними для каналу.
-Зберігайте поля, специфічні для постачальника, у плагіні, а не в спільному ядрі.
+Plugin мають володіти каналоспецифічними внесками до схеми `describeMessageTool(...)`.
+Зберігайте provider-специфічні поля в plugin, а не в спільному core.
-Для спільних переносних фрагментів схеми повторно використовуйте узагальнені допоміжні засоби, експортовані через
+Для спільних переносимих фрагментів схеми повторно використовуйте узагальнені допоміжні засоби, експортовані через
`openclaw/plugin-sdk/channel-actions`:
- `createMessageToolButtonsSchema()` для payload у стилі сітки кнопок
-- `createMessageToolCardSchema()` для структурованих payload карток
+- `createMessageToolCardSchema()` для payload структурованих карток
-Якщо форма схеми має сенс лише для одного постачальника, визначайте її у власному
-джерелі цього плагіна, а не просувайте до спільного SDK.
+Якщо форма схеми має сенс лише для одного постачальника, визначайте її у
+власному вихідному коді цього plugin замість того, щоб підвищувати її до спільного SDK.
-## Визначення цілей каналу
+## Визначення цілі каналу
-Плагіни каналів мають володіти семантикою цілей, специфічною для каналу. Зберігайте спільний
-outbound host узагальненим і використовуйте поверхню адаптера повідомлень для правил постачальника:
+Channel Plugins мають володіти каналоспецифічною семантикою цілей. Зберігайте
+спільний вихідний host узагальненим і використовуйте поверхню адаптера обміну повідомленнями для правил постачальника:
- `messaging.inferTargetChatType({ to })` визначає, чи слід розглядати нормалізовану ціль
як `direct`, `group` або `channel` до пошуку в каталозі.
-- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи
- слід для вводу одразу перейти до визначення за схожістю на id замість пошуку в каталозі.
-- `messaging.targetResolver.resolveTarget(...)` є fallback плагіна, коли
- ядру потрібне фінальне визначення, яким володіє постачальник, після нормалізації або після
- промаху в каталозі.
-- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, специфічного для постачальника,
- щойно ціль буде визначено.
+- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи має
+ ввід одразу перейти до визначення за id-подібним значенням замість пошуку в каталозі.
+- `messaging.targetResolver.resolveTarget(...)` є резервним варіантом plugin, коли
+ core потребує остаточного визначення, що належить постачальнику, після нормалізації або
+ після промаху в каталозі.
+- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, специфічною для постачальника,
+ після того як ціль визначено.
Рекомендований поділ:
-- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають відбуватися до
+- Використовуйте `inferTargetChatType` для рішень щодо категорії, які мають відбуватися до
пошуку peers/groups.
-- Використовуйте `looksLikeId` для перевірок виду «розглядати це як явний/native id цілі».
-- Використовуйте `resolveTarget` для fallback нормалізації, специфічного для постачальника, а не для
+- Використовуйте `looksLikeId` для перевірок на кшталт "розглядати це як явний/native id цілі".
+- Використовуйте `resolveTarget` для резервної нормалізації, специфічної для постачальника, а не для
широкого пошуку в каталозі.
-- Зберігайте native id постачальника, такі як chat id, thread id, JID, handle та room
- id, усередині значень `target` або параметрів, специфічних для постачальника, а не в узагальнених полях SDK.
+- Зберігайте native id постачальника, такі як chat id, thread id, JID, handles і room
+ id, усередині значень `target` або provider-специфічних параметрів, а не в узагальнених полях SDK.
-## Каталоги на основі конфігурації
+## Каталоги на основі config
-Плагіни, які виводять записи каталогу з конфігурації, мають зберігати цю логіку в
-плагіні й повторно використовувати спільні допоміжні засоби з
+Plugin, які виводять записи каталогу з config, мають зберігати цю логіку в
+plugin і повторно використовувати спільні допоміжні засоби з
`openclaw/plugin-sdk/directory-runtime`.
-Використовуйте це, коли каналу потрібні peers/groups на основі конфігурації, наприклад:
+Використовуйте це, коли каналу потрібні peers/groups на основі config, наприклад:
-- DM peers на основі allowlist
-- налаштовані мапи каналів/груп
-- статичні fallback каталогу в межах облікового запису
+- peers для DM, керовані allowlist
+- налаштовані карти каналів/груп
+- статичні резервні варіанти каталогу в межах облікового запису
Спільні допоміжні засоби в `directory-runtime` обробляють лише узагальнені операції:
-- фільтрацію запиту
-- застосування ліміту
-- дедуплікацію/допоміжні засоби нормалізації
-- побудову `ChannelDirectoryEntry[]`
+- фільтрація запиту
+- застосування обмеження
+- допоміжні засоби дедуплікації/нормалізації
+- побудова `ChannelDirectoryEntry[]`
-Специфічні для каналу перевірка облікового запису й нормалізація id мають залишатися в
-реалізації плагіна.
+Каналоспецифічна перевірка облікового запису та нормалізація id мають залишатися в
+реалізації plugin.
-## Каталоги провайдерів
+## Каталоги постачальників
-Плагіни провайдерів можуть визначати каталоги моделей для inference за допомогою
+Provider Plugins можуть визначати каталоги моделей для inference за допомогою
`registerProvider({ catalog: { run(...) { ... } } })`.
`catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в
`models.providers`:
-- `{ provider }` для одного запису провайдера
-- `{ providers }` для кількох записів провайдера
+- `{ provider }` для одного запису постачальника
+- `{ providers }` для кількох записів постачальників
-Використовуйте `catalog`, коли плагін володіє model id, типовими значеннями base URL або
-метаданими моделей із auth-обмеженням, специфічними для провайдера.
+Використовуйте `catalog`, коли plugin володіє model id, типовими значеннями base URL або метаданими моделей, захищеними автентифікацією, що специфічні для постачальника.
-`catalog.order` керує тим, коли каталог плагіна зливається відносно
-вбудованих неявних провайдерів OpenClaw:
+`catalog.order` керує тим, коли каталог plugin зливається відносно
+вбудованих неявних постачальників OpenClaw:
-- `simple`: звичайні провайдери з API-key або на основі env
-- `profile`: провайдери, які з’являються, коли існують профілі auth
-- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів
-- `late`: останній прохід, після інших неявних провайдерів
+- `simple`: звичайні постачальники на основі API-ключа або env
+- `profile`: постачальники, які з’являються за наявності профілів автентифікації
+- `paired`: постачальники, які синтезують кілька пов’язаних записів постачальників
+- `late`: останній прохід, після інших неявних постачальників
-Пізніші провайдери перемагають у разі конфлікту ключів, тож плагіни можуть навмисно
-перевизначати вбудований запис провайдера з тим самим id провайдера.
+Пізніші постачальники перемагають у разі колізії ключів, тому plugin можуть навмисно
+перевизначати вбудований запис постачальника з тим самим ідентифікатором постачальника.
Сумісність:
- `discovery` усе ще працює як застарілий псевдонім
- якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog`
-## Інспекція каналу лише для читання
+## Перевірка каналу лише для читання
-Якщо ваш плагін реєструє канал, віддавайте перевагу реалізації
+Якщо ваш plugin реєструє канал, віддавайте перевагу реалізації
`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`.
Чому:
-- `resolveAccount(...)` — це шлях runtime. Він може припускати, що облікові дані
- повністю матеріалізовані, і може швидко завершуватися помилкою, коли потрібні secrets відсутні.
+- `resolveAccount(...)` — це runtime-шлях. Він може припускати, що облікові дані
+ повністю матеріалізовані, і швидко завершуватися помилкою, коли потрібні секрети відсутні.
- Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`,
- `openclaw channels status`, `openclaw channels resolve` і потоки doctor/config
- repair, не повинні потребувати матеріалізації облікових даних runtime лише для
+ `openclaw channels status`, `openclaw channels resolve`, а також потоки doctor/config
+ repair не повинні потребувати матеріалізації runtime-облікових даних лише для
опису конфігурації.
Рекомендована поведінка `inspectAccount(...)`:
@@ -1355,18 +1358,18 @@ outbound host узагальненим і використовуйте пове
- `botTokenSource`, `botTokenStatus`
- `appTokenSource`, `appTokenStatus`
- `signingSecretSource`, `signingSecretStatus`
-- Вам не потрібно повертати сирі значення token лише для повідомлення про доступність лише для читання.
- Достатньо повернути `tokenStatus: "available"` (і відповідне поле
- джерела) для команд у стилі status.
+- Не потрібно повертати сирі значення токенів лише для повідомлення про доступність
+ лише для читання. Повернення `tokenStatus: "available"` (і відповідного поля джерела)
+ достатньо для команд у стилі status.
- Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але
- недоступно в поточному шляху команди.
+ вони недоступні в поточному шляху команди.
-Це дає змогу командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди»
-замість збою або помилкового повідомлення, що обліковий запис не налаштовано.
+Це дає змогу командам лише для читання повідомляти "налаштовано, але недоступно в цьому шляху команди"
+замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштований.
-## Пакетні набори
+## Набори package
-Каталог плагіна може містити `package.json` з `openclaw.extensions`:
+Каталог plugin може містити `package.json` із `openclaw.extensions`:
```json
{
@@ -1378,66 +1381,66 @@ outbound host узагальненим і використовуйте пове
}
```
-Кожен запис стає плагіном. Якщо набір перелічує кілька розширень, id плагіна
+Кожен запис стає plugin. Якщо набір перелічує кілька extension, ідентифікатор plugin
стає `name/`.
-Якщо ваш плагін імпортує npm-залежності, установіть їх у цьому каталозі, щоб
+Якщо ваш plugin імпортує npm-залежності, встановіть їх у цьому каталозі, щоб
`node_modules` був доступний (`npm install` / `pnpm install`).
-Захист безпеки: кожен запис `openclaw.extensions` має залишатися всередині каталогу плагіна
-після визначення symlink. Записи, що виходять за межі каталогу пакета,
+Запобіжник безпеки: кожен запис `openclaw.extensions` має залишатися всередині каталогу plugin
+після визначення символічних посилань. Записи, які виходять за межі каталогу package,
відхиляються.
-Примітка щодо безпеки: `openclaw plugins install` установлює залежності плагіна за допомогою
-`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev-залежностей у runtime). Зберігайте дерева залежностей плагіна як
-«чисті JS/TS» і уникайте пакетів, що потребують збірок `postinstall`.
+Примітка щодо безпеки: `openclaw plugins install` установлює залежності plugin за допомогою
+`npm install --omit=dev --ignore-scripts` (без lifecycle-скриптів, без dev-залежностей під час runtime). Зберігайте дерево залежностей plugin
+"pure JS/TS" і уникайте package, які потребують збирання через `postinstall`.
-Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для setup.
-Коли OpenClaw потребує поверхонь setup для вимкненого плагіна каналу або
-коли плагін каналу увімкнено, але ще не налаштовано, він завантажує `setupEntry`
-замість повної точки входу плагіна. Це робить запуск і setup легшими,
-коли основна точка входу вашого плагіна також підключає інструменти, hooks або інший код
-лише для runtime.
+Необов’язково: `openclaw.setupEntry` може вказувати на полегшений модуль лише для налаштування.
+Коли OpenClaw потребує поверхонь налаштування для вимкненого channel plugin або
+коли channel plugin увімкнений, але ще не налаштований, він завантажує `setupEntry`
+замість повної точки входу plugin. Це робить запуск і налаштування легшими,
+коли основна точка входу plugin також підключає інструменти, хуки або інший код,
+потрібний лише під час runtime.
Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`
-може ввімкнути для плагіна каналу той самий шлях `setupEntry` під час
+може перевести channel plugin на той самий шлях `setupEntry` під час
передпрослуховувальної фази запуску gateway, навіть коли канал уже налаштовано.
Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати
-до того, як gateway почне слухати. На практиці це означає, що точка входу setup
-має реєструвати кожну можливість каналу, від якої залежить запуск, наприклад:
+до того, як gateway почне прослуховування. На практиці це означає, що точка входу налаштування
+має реєструвати кожну можливість, що належить каналу й від якої залежить запуск, наприклад:
-- саму реєстрацію каналу
-- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне слухати
-- будь-які методи gateway, інструменти або сервіси, які повинні існувати в тому самому вікні
+- власне реєстрацію каналу
+- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне прослуховування
+- будь-які методи Gateway, інструменти або сервіси, які мають існувати в це саме вікно
-Якщо ваша повна точка входу все ще володіє будь-якою потрібною можливістю запуску, не вмикайте
-цей прапорець. Залишайте плагін на типовій поведінці й дозвольте OpenClaw завантажити
+Якщо ваша повна точка входу все ще володіє будь-якою необхідною можливістю запуску, не вмикайте
+цей прапорець. Залиште plugin на типовій поведінці й дозвольте OpenClaw завантажити
повну точку входу під час запуску.
-Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для setup, з якими ядро
+Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для налаштування, з якими core
може консультуватися до завантаження повного runtime каналу. Поточна поверхня
-просування setup така:
+підвищення налаштування така:
- `singleAccountKeysToMove`
- `namedAccountPromotionKeys`
- `resolveSingleAccountPromotionTarget(...)`
-Ядро використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію каналу з одним обліковим записом
-у `channels..accounts.*` без завантаження повної точки входу плагіна.
-Matrix — поточний вбудований приклад: він переносить лише ключі auth/bootstrap у
-іменований просунутий обліковий запис, коли іменовані облікові записи вже існують, і може
+Core використовує цю поверхню, коли йому потрібно підвищити застарілу конфігурацію каналу з одним обліковим записом
+до `channels..accounts.*`, не завантажуючи повну точку входу plugin.
+Matrix є поточним вбудованим прикладом: він переносить лише auth/bootstrap-ключі до
+іменованого підвищеного облікового запису, коли іменовані облікові записи вже існують, і може
зберігати налаштований неканонічний ключ default-account замість того, щоб завжди створювати
`accounts.default`.
-Ці адаптери patch setup зберігають ліниве виявлення поверхні контракту вбудованих компонентів. Час
-імпорту залишається легким; поверхня просування завантажується лише під час першого використання
-замість повторного входу до запуску вбудованого каналу під час імпорту модуля.
+Ці адаптери патчів налаштування зберігають ліниве виявлення поверхні контракту вбудованих компонентів.
+Час імпорту залишається малим; поверхня підвищення завантажується лише під час першого використання
+замість повторного входу в запуск вбудованого каналу під час імпорту модуля.
-Коли ці поверхні запуску містять методи Gateway RPC, тримайте їх на
-специфічному для плагіна префіксі. Простори імен адміністрування ядра (`config.*`,
+Коли ці поверхні запуску включають методи Gateway RPC, зберігайте їх на
+plugin-специфічному префіксі. Простори імен адміністратора core (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються
-як `operator.admin`, навіть якщо плагін запитує вужчу область.
+як `operator.admin`, навіть якщо plugin запитує вужчу область.
Приклад:
@@ -1454,10 +1457,10 @@ Matrix — поточний вбудований приклад: він пере
}
```
-### Метадані каталогу каналу
+### Метадані каталогу каналів
-Плагіни каналів можуть оголошувати метадані setup/discovery через `openclaw.channel`, а
-підказки встановлення через `openclaw.install`. Це дає змогу зберігати дані каталогу ядра вільними від даних.
+Channel Plugins можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` та
+підказки встановлення через `openclaw.install`. Це дає змогу тримати дані каталогу core порожніми.
Приклад:
@@ -1472,7 +1475,7 @@ Matrix — поточний вбудований приклад: він пере
"selectionLabel": "Nextcloud Talk (self-hosted)",
"docsPath": "/channels/nextcloud-talk",
"docsLabel": "nextcloud-talk",
- "blurb": "Самостійно розміщений чат через webhook-ботів Nextcloud Talk.",
+ "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
"order": 65,
"aliases": ["nc-talk", "nc"]
},
@@ -1487,18 +1490,18 @@ Matrix — поточний вбудований приклад: він пере
Корисні поля `openclaw.channel`, окрім мінімального прикладу:
-- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/status
+- `detailLabel`: вторинний ярлик для багатших поверхонь каталогу/status
- `docsLabel`: перевизначає текст посилання для посилання на документацію
-- `preferOver`: id плагінів/каналів нижчого пріоритету, які цей запис каталогу має переважати
-- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування копією для поверхні вибору
-- `markdownCapable`: позначає канал як такий, що підтримує markdown, для рішень щодо outbound-форматування
-- `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, коли встановлено `false`
-- `exposure.setup`: приховує канал із інтерактивних засобів вибору setup/configure, коли встановлено `false`
-- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації
+- `preferOver`: ідентифікатори plugin/каналів із нижчим пріоритетом, які цей запис каталогу має випереджати
+- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору
+- `markdownCapable`: позначає канал як здатний до Markdown для рішень форматування вихідних повідомлень
+- `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false`
+- `exposure.setup`: приховує канал з інтерактивних picker налаштування/конфігурації, якщо встановлено `false`
+- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документацією
- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; віддавайте перевагу `exposure`
-- `quickstartAllowFrom`: включає канал у стандартний потік швидкого старту `allowFrom`
+- `quickstartAllowFrom`: підключає канал до стандартного потоку quickstart `allowFrom`
- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис
-- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення announce target
+- `preferSessionLookupForAnnounceTarget`: віддає перевагу пошуку сесії під час визначення announce target
OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт
реєстру MPM). Помістіть JSON-файл в одне з таких місць:
@@ -1508,18 +1511,18 @@ OpenClaw також може зливати **зовнішні каталоги
- `~/.openclaw/plugins/catalog.json`
Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) на
-один або кілька JSON-файлів (з розділенням комами/крапками з комою/`PATH`). Кожен файл має
+один чи кілька JSON-файлів (із розділенням комою/крапкою з комою/`PATH`). Кожен файл має
містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`.
-## Плагіни контекстного рушія
+## Plugin рушія контексту
-Плагіни контекстного рушія володіють оркестрацією контексту сесії для ingest, assembly
-та Compaction. Реєструйте їх зі свого плагіна через
-`api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через
+Plugin рушія контексту володіють оркестрацією контексту сесії для ingest, assembly
+та Compaction. Реєструйте їх зі свого plugin через
+`api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій за допомогою
`plugins.slots.contextEngine`.
-Використовуйте це, коли вашому плагіну потрібно замінити або розширити типовий
-конвеєр контексту, а не просто додати пошук у пам’яті або hooks.
+Використовуйте це, коли вашому plugin потрібно замінити або розширити типовий
+конвеєр контексту, а не просто додати пошук у memory чи хуки.
```ts
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";
@@ -1585,45 +1588,45 @@ export default function (api) {
## Додавання нової можливості
-Коли плагіну потрібна поведінка, яка не вписується в поточний API, не обходьте
-систему плагінів через приватне внутрішнє звернення. Додайте відсутню можливість.
+Коли plugin потребує поведінки, яка не вписується в поточний API, не обходьте
+систему plugin приватним зверненням углиб. Додайте відсутню можливість.
Рекомендована послідовність:
-1. визначте контракт ядра
- Вирішіть, якою спільною поведінкою має володіти ядро: політика, fallback, злиття конфігурації,
- життєвий цикл, семантика для каналів і форма допоміжного засобу runtime.
-2. додайте типізовані поверхні реєстрації/runtime плагіна
+1. визначте контракт core
+ Вирішіть, якою спільною поведінкою має володіти core: політикою, резервним варіантом, злиттям config,
+ життєвим циклом, семантикою для каналів і формою допоміжних засобів runtime.
+2. додайте типізовані поверхні реєстрації/runtime plugin
Розширте `OpenClawPluginApi` і/або `api.runtime` найменшою корисною
типізованою поверхнею можливості.
-3. підключіть ядро + споживачів каналів/функцій
- Канали й плагіни функцій мають споживати нову можливість через ядро,
- а не імпортувати реалізацію постачальника напряму.
-4. зареєструйте реалізації постачальників
- Потім плагіни постачальників реєструють свої backend для цієї можливості.
-5. додайте покриття контракту
+3. підключіть споживачів core + каналів/можливостей
+ Канали та plugin можливостей мають споживати нову можливість через core,
+ а не імпортувати реалізацію vendor напряму.
+4. зареєструйте реалізації vendor
+ Потім vendor plugin реєструють свої бекенди для цієї можливості.
+5. додайте контрактне покриття
Додайте тести, щоб володіння та форма реєстрації з часом залишалися явними.
-Саме так OpenClaw залишається послідовним, не стаючи жорстко прив’язаним до
-світогляду одного провайдера. Див. [Посібник з можливостей](/uk/plugins/architecture)
-для конкретного контрольного списку файлів і розгорнутого прикладу.
+Саме так OpenClaw зберігає чітку позицію, не стаючи жорстко прив’язаним до
+світогляду одного постачальника. Див. [Capability Cookbook](/uk/plugins/architecture)
+для конкретного контрольного списку файлів і готового прикладу.
### Контрольний список можливості
Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих
поверхонь разом:
-- типів контракту ядра в `src//types.ts`
-- допоміжного засобу runner/runtime ядра в `src//runtime.ts`
-- поверхні реєстрації API плагіна в `src/plugins/types.ts`
-- прив’язки реєстру плагінів у `src/plugins/registry.ts`
-- відкриття runtime плагіна в `src/plugins/runtime/*`, коли плагіни функцій/каналів
- повинні його споживати
-- допоміжних засобів capture/test у `src/test-utils/plugin-registration.ts`
-- перевірок володіння/контракту в `src/plugins/contracts/registry.ts`
-- документації для операторів/плагінів у `docs/`
+- типи контракту core у `src//types.ts`
+- runner/допоміжний runtime core у `src//runtime.ts`
+- поверхня реєстрації API plugin у `src/plugins/types.ts`
+- підключення реєстру plugin у `src/plugins/registry.ts`
+- відкриття runtime plugin у `src/plugins/runtime/*`, коли plugin можливостей/каналів
+ мають це споживати
+- допоміжні засоби capture/test у `src/test-utils/plugin-registration.ts`
+- перевірки володіння/контракту в `src/plugins/contracts/registry.ts`
+- документація для операторів/plugin у `docs/`
-Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість
+Якщо одна з цих поверхонь відсутня, це зазвичай ознака того, що можливість
ще не повністю інтегрована.
### Шаблон можливості
@@ -1662,7 +1665,7 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);
Це зберігає правило простим:
-- ядро володіє контрактом можливості + orchestration
-- плагіни постачальників володіють реалізаціями постачальників
-- плагіни функцій/каналів споживають допоміжні засоби runtime
-- контрактні тести зберігають володіння явним
+- core володіє контрактом можливості + оркестрацією
+- vendor plugin володіють реалізаціями vendor
+- plugin можливостей/каналів споживають допоміжні засоби runtime
+- контрактні тести зберігають явність володіння
diff --git a/docs/uk/plugins/sdk-provider-plugins.md b/docs/uk/plugins/sdk-provider-plugins.md
index 9c82556b1..d63e8eafe 100644
--- a/docs/uk/plugins/sdk-provider-plugins.md
+++ b/docs/uk/plugins/sdk-provider-plugins.md
@@ -1,40 +1,40 @@
---
read_when:
- Ви створюєте новий плагін постачальника моделей
- - Ви хочете додати до OpenClaw OpenAI-сумісний проксі або власну LLM
+ - Ви хочете додати OpenAI-сумісний проксі або власну LLM до OpenClaw
- Вам потрібно зрозуміти автентифікацію постачальника, каталоги та runtime-хуки
sidebarTitle: Provider Plugins
summary: Покроковий посібник зі створення плагіна постачальника моделей для OpenClaw
title: Створення плагінів постачальників
x-i18n:
- generated_at: "2026-04-21T05:21:17Z"
+ generated_at: "2026-04-21T06:04:47Z"
model: gpt-5.4
provider: openai
- source_hash: ac15d705e805dfb74a2a13538bcddf9a2fc78a4529657f2e1c1aab676cb3984d
+ source_hash: 459761118c7394c1643c170edfec97c87e1c6323b436183b53ad7a2fed783b04
source_path: plugins/sdk-provider-plugins.md
workflow: 15
---
# Створення плагінів постачальників
-Цей посібник допоможе вам створити плагін постачальника, який додає постачальника
-моделей (LLM) до OpenClaw. Наприкінці у вас буде постачальник із каталогом моделей,
+Цей посібник проводить через створення плагіна постачальника, який додає постачальника моделей
+(LLM) до OpenClaw. Наприкінці у вас буде постачальник із каталогом моделей,
автентифікацією через API-ключ і динамічним визначенням моделей.
Якщо ви раніше не створювали жодного плагіна OpenClaw, спочатку прочитайте
- [Початок роботи](/uk/plugins/building-plugins), щоб ознайомитися з базовою
- структурою пакета та налаштуванням маніфесту.
+ [Початок роботи](/uk/plugins/building-plugins) про базову структуру
+ пакета та налаштування маніфесту.
- Плагіни постачальників додають моделі до стандартного циклу інференсу OpenClaw. Якщо модель
- має працювати через нативний агентний демон, який керує потоками, Compaction або подіями
+ Плагіни постачальників додають моделі до звичайного циклу інференсу OpenClaw. Якщо модель
+ має працювати через нативний демон агента, який керує потоками, Compaction або подіями
інструментів, поєднайте постачальника з [agent harness](/uk/plugins/sdk-agent-harness),
замість того щоб виносити деталі протоколу демона в core.
-## Покрокова інструкція
+## Покроковий розбір
@@ -97,12 +97,12 @@ x-i18n:
Маніфест оголошує `providerAuthEnvVars`, щоб OpenClaw міг виявляти
- облікові дані без завантаження runtime вашого плагіна. Додайте `providerAuthAliases`,
+ облікові дані без завантаження runtime вашого плагіна. Додавайте `providerAuthAliases`,
коли варіант постачальника має повторно використовувати автентифікацію іншого id постачальника. `modelSupport`
- необов’язковий і дозволяє OpenClaw автоматично завантажувати ваш плагін постачальника зі скорочених
+ є необов’язковим і дозволяє OpenClaw автоматично завантажувати ваш плагін постачальника зі скорочених
id моделей, таких як `acme-large`, ще до появи runtime-хуків. Якщо ви публікуєте
- постачальника в ClawHub, поля `openclaw.compat` і `openclaw.build`
- у `package.json` є обов’язковими.
+ постачальника в ClawHub, ці поля `openclaw.compat` і `openclaw.build`
+ є обов’язковими в `package.json`.
@@ -182,8 +182,8 @@ x-i18n:
`openclaw onboard --acme-ai-api-key ` і вибрати
`acme-ai/acme-large` як свою модель.
- Якщо постачальник вище за течією використовує інші керівні токени, ніж OpenClaw, додайте
- невелике двоспрямоване текстове перетворення замість заміни шляху потоку:
+ Якщо вхідний постачальник використовує інші керувальні токени, ніж OpenClaw, додайте
+ невелике двонапрямне текстове перетворення замість заміни шляху потоку:
```typescript
api.registerTextTransforms({
@@ -200,13 +200,13 @@ x-i18n:
});
```
- `input` переписує фінальний системний промпт і текстовий вміст повідомлення перед
- передаванням. `output` переписує текстові дельти асистента та фінальний текст до того, як
- OpenClaw розбере власні керівні маркери або виконає доставку через канал.
+ `input` переписує фінальний системний промпт і вміст текстового повідомлення перед
+ транспортуванням. `output` переписує текстові дельти асистента і фінальний текст до того,
+ як OpenClaw розбере власні керувальні маркери або доставку через канал.
- Для вбудованих постачальників, які реєструють лише одного текстового постачальника з
- автентифікацією через API-ключ плюс один runtime на основі каталогу, краще використовувати вужчий
- хелпер `defineSingleProviderPluginEntry(...)`:
+ Для вбудованих постачальників, які реєструють лише одного текстового постачальника з API-key
+ автентифікацією плюс один runtime на основі каталогу, надавайте перевагу
+ вужчому хелперу `defineSingleProviderPluginEntry(...)`:
```typescript
import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry";
@@ -241,24 +241,25 @@ x-i18n:
});
```
- Якщо ваш потік автентифікації також має оновлювати `models.providers.*`, aliases і
- модель агента за замовчуванням під час onboarding, використовуйте preset-хелпери з
+ Якщо ваш потік автентифікації також має оновлювати `models.providers.*`, псевдоніми
+ та модель агента за замовчуванням під час onboarding, використовуйте хелпери пресетів з
`openclaw/plugin-sdk/provider-onboard`. Найвужчі хелпери —
`createDefaultModelPresetAppliers(...)`,
`createDefaultModelsPresetAppliers(...)` і
`createModelCatalogPresetAppliers(...)`.
- Коли нативна кінцева точка постачальника підтримує блоки використання в потоці на
- звичайному транспорті `openai-completions`, віддавайте перевагу спільним хелперам каталогу з
- `openclaw/plugin-sdk/provider-catalog-shared` замість жорсткого кодування перевірок id постачальника.
+ Коли нативний endpoint постачальника підтримує потокові блоки usage на
+ звичайному транспорті `openai-completions`, надавайте перевагу спільним хелперам каталогу з
+ `openclaw/plugin-sdk/provider-catalog-shared` замість жорсткого кодування перевірок за id постачальника.
`supportsNativeStreamingUsageCompat(...)` і
- `applyProviderNativeStreamingUsageCompat(...)` визначають підтримку за мапою можливостей кінцевої точки, тож нативні
- кінцеві точки в стилі Moonshot/DashScope також можуть підключатися, навіть якщо плагін використовує власний id постачальника.
+ `applyProviderNativeStreamingUsageCompat(...)` визначають підтримку за картою можливостей endpoint, тож
+ нативні endpoint-и на кшталт Moonshot/DashScope усе одно підключаються, навіть якщо плагін використовує
+ власний id постачальника.
- Якщо ваш постачальник приймає довільні id моделей (як проксі або маршрутизатор),
+ Якщо ваш постачальник приймає довільні id моделей (наприклад, проксі або маршрутизатор),
додайте `resolveDynamicModel`:
```typescript
@@ -281,16 +282,16 @@ x-i18n:
```
Якщо для визначення потрібен мережевий виклик, використовуйте `prepareDynamicModel` для асинхронного
- прогріву — після його завершення `resolveDynamicModel` запускається знову.
+ попереднього прогріву — після його завершення `resolveDynamicModel` буде виконано знову.
- Більшості постачальників достатньо лише `catalog` + `resolveDynamicModel`. Додавайте хуки
- поступово, коли це буде потрібно вашому постачальнику.
+ Більшості постачальників потрібні лише `catalog` + `resolveDynamicModel`. Додавайте хуки
+ поступово, коли цього вимагатиме ваш постачальник.
- Спільні builder-хелпери тепер охоплюють найпоширеніші сімейства replay/tool-compat,
- тож плагінам зазвичай не потрібно вручну підключати кожен хук окремо:
+ Спільні builder-хелпери тепер покривають найпоширеніші сімейства replay/tool-compat,
+ тому плагінам зазвичай не потрібно вручну підключати кожен хук окремо:
```typescript
import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared";
@@ -310,15 +311,15 @@ x-i18n:
});
```
- Доступні на сьогодні сімейства replay:
+ Доступні сьогодні сімейства replay:
| Сімейство | Що воно підключає |
| --- | --- |
- | `openai-compatible` | Спільна політика replay у стилі OpenAI для OpenAI-сумісних транспортів, включно з очищенням tool-call-id, виправленням порядку assistant-first і загальною валідацією Gemini-turn там, де це потрібно транспорту |
- | `anthropic-by-model` | Політика replay з урахуванням Claude, яка вибирається за `modelId`, тож транспорти Anthropic-message отримують Claude-специфічне очищення thinking-block лише тоді, коли визначена модель справді має id Claude |
- | `google-gemini` | Нативна політика replay для Gemini плюс очищення bootstrap replay і режим tagged reasoning-output |
- | `passthrough-gemini` | Очищення thought-signature для моделей Gemini, що працюють через OpenAI-сумісні проксі-транспорти; не вмикає нативну валідацію replay Gemini або bootstrap-перезаписи |
- | `hybrid-anthropic-openai` | Гібридна політика для постачальників, які поєднують поверхні моделей Anthropic-message і OpenAI-compatible в одному плагіні; необов’язкове відкидання thinking-block лише для Claude залишається обмеженим стороною Anthropic |
+ | `openai-compatible` | Спільну політику replay у стилі OpenAI для OpenAI-сумісних транспортів, включно з очищенням tool-call-id, виправленнями порядку assistant-first і загальною валідацією Gemini-turn там, де цього потребує транспорт |
+ | `anthropic-by-model` | Політику replay з урахуванням Claude, яка вибирається за `modelId`, тож транспорти Anthropic-message отримують специфічне для Claude очищення thinking-block лише тоді, коли визначена модель справді має id Claude |
+ | `google-gemini` | Нативну політику replay Gemini плюс очищення bootstrap replay і режим tagged reasoning-output |
+ | `passthrough-gemini` | Очищення Gemini thought-signature для моделей Gemini, що працюють через OpenAI-сумісні проксі-транспорти; не вмикає нативну валідацію replay Gemini або переписування bootstrap |
+ | `hybrid-anthropic-openai` | Гібридну політику для постачальників, які поєднують поверхні моделей Anthropic-message та OpenAI-compatible в одному плагіні; необов’язкове видалення thinking-block лише для Claude залишається обмеженим стороною Anthropic |
Реальні вбудовані приклади:
@@ -328,17 +329,17 @@ x-i18n:
- `minimax`: `hybrid-anthropic-openai`
- `moonshot`, `ollama`, `xai` і `zai`: `openai-compatible`
- Доступні на сьогодні сімейства потоків:
+ Доступні сьогодні сімейства потоків:
| Сімейство | Що воно підключає |
| --- | --- |
- | `google-thinking` | Нормалізація payload thinking Gemini на спільному шляху потоку |
- | `kilocode-thinking` | Обгортка reasoning Kilo на спільному шляху потоку проксі, де `kilo/auto` і непідтримувані id reasoning проксі пропускають ін’єкцію thinking |
- | `moonshot-thinking` | Відображення payload native-thinking Moonshot у двійковому форматі з config + рівня `/think` |
- | `minimax-fast-mode` | Перезапис моделі fast-mode MiniMax на спільному шляху потоку |
- | `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: заголовки attribution, `/fast`/`serviceTier`, деталізація тексту, нативний вебпошук Codex, формування payload для сумісності reasoning і керування контекстом Responses |
- | `openrouter-thinking` | Обгортка reasoning OpenRouter для маршрутів проксі, з централізованою обробкою пропусків для непідтримуваних моделей/`auto` |
- | `tool-stream-default-on` | Обгортка `tool_stream`, увімкнена за замовчуванням, для постачальників на кшталт Z.AI, які хочуть потокову передачу інструментів, якщо її не вимкнено явно |
+ | `google-thinking` | Нормалізацію payload thinking Gemini у спільному шляху потоку |
+ | `kilocode-thinking` | Обгортку Kilo reasoning у спільному шляху проксі-потоку, де `kilo/auto` і непідтримувані id reasoning проксі пропускають ін’єкцію thinking |
+ | `moonshot-thinking` | Відображення бінарного payload native-thinking Moonshot із config + рівня `/think` |
+ | `minimax-fast-mode` | Переписування моделі MiniMax fast-mode у спільному шляху потоку |
+ | `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: заголовки attribution, `/fast`/`serviceTier`, текстова verbosity, нативний вебпошук Codex, формування payload для reasoning-compat і керування контекстом Responses |
+ | `openrouter-thinking` | Обгортку OpenRouter reasoning для маршрутів проксі, з централізованою обробкою пропусків для непідтримуваних моделей/`auto` |
+ | `tool-stream-default-on` | Обгортку `tool_stream`, увімкнену за замовчуванням, для постачальників на кшталт Z.AI, яким потрібен потоковий режим інструментів, якщо його явно не вимкнено |
Реальні вбудовані приклади:
@@ -351,23 +352,23 @@ x-i18n:
- `zai`: `tool-stream-default-on`
`openclaw/plugin-sdk/provider-model-shared` також експортує enum сімейств
- replay, а також спільні хелпери, з яких ці сімейства побудовані. Поширені публічні
+ replay, а також спільні хелпери, з яких ці сімейства побудовані. Типові публічні
експорти включають:
- `ProviderReplayFamily`
- `buildProviderReplayFamilyHooks(...)`
- - спільні builder-хелпери replay, такі як `buildOpenAICompatibleReplayPolicy(...)`,
+ - спільні builder-и replay, такі як `buildOpenAICompatibleReplayPolicy(...)`,
`buildAnthropicReplayPolicyForModel(...)`,
`buildGoogleGeminiReplayPolicy(...)` і
`buildHybridAnthropicOrOpenAIReplayPolicy(...)`
- хелпери replay Gemini, такі як `sanitizeGoogleGeminiReplayHistory(...)`
і `resolveTaggedReasoningOutputMode()`
- - хелпери для кінцевих точок/моделей, такі як `resolveProviderEndpoint(...)`,
+ - хелпери endpoint/model, такі як `resolveProviderEndpoint(...)`,
`normalizeProviderId(...)`, `normalizeGooglePreviewModelId(...)` і
`normalizeNativeXaiModelId(...)`
- `openclaw/plugin-sdk/provider-stream` надає і builder сімейств, і
- публічні хелпери-обгортки, які ці сімейства повторно використовують. Поширені публічні експорти
+ `openclaw/plugin-sdk/provider-stream` надає як builder сімейств, так і
+ публічні хелпери-обгортки, які ці сімейства повторно використовують. Типові публічні експорти
включають:
- `ProviderStreamFamily`
@@ -386,45 +387,45 @@ x-i18n:
приклад: `@openclaw/anthropic-provider` експортує
`wrapAnthropicProviderStream`, `resolveAnthropicBetas`,
`resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і
- низькорівневі builder-обгортки Anthropic зі свого публічного шва `api.ts` /
+ низькорівневі builder-и обгорток Anthropic через свій публічний seam `api.ts` /
`contract-api.ts`. Ці хелпери залишаються специфічними для Anthropic, тому
- що вони також кодують обробку бета-версій Claude OAuth і gating `context1m`.
+ що вони також кодують обробку Claude OAuth beta і gating `context1m`.
- Інші вбудовані постачальники також зберігають специфічні для транспорту обгортки локально, коли
- таку поведінку неможливо чисто поділити між сімействами. Поточний приклад: вбудований
- плагін xAI зберігає нативне формування Responses xAI у власному
- `wrapStreamFn`, включно з перезаписами псевдонімів `/fast`, `tool_stream`
+ Інші вбудовані постачальники також тримають локальними обгортки, специфічні для транспорту, коли
+ цю поведінку не можна чисто поділити між сімействами. Поточний приклад: вбудований
+ плагін xAI тримає формування нативних xAI Responses у власному
+ `wrapStreamFn`, включно з переписуванням псевдонімів `/fast`, `tool_stream`
за замовчуванням, очищенням непідтримуваних strict-tool і видаленням
- payload reasoning, специфічного для xAI.
+ payload reasoning, специфічним для xAI.
`openclaw/plugin-sdk/provider-tools` наразі надає одне спільне
- сімейство схем інструментів плюс спільні хелпери схем/сумісності:
+ сімейство схем інструментів плюс спільні хелпери schema/compat:
- - `ProviderToolCompatFamily` документує поточний спільний перелік сімейств.
- - `buildProviderToolCompatFamilyHooks("gemini")` підключає
- очищення схеми Gemini + діагностику для постачальників, яким потрібні безпечні для Gemini схеми інструментів.
+ - `ProviderToolCompatFamily` документує поточний набір спільних сімейств.
+ - `buildProviderToolCompatFamilyHooks("gemini")` підключає очищення схеми Gemini
+ + діагностику для постачальників, яким потрібні безпечні для Gemini схеми інструментів.
- `normalizeGeminiToolSchemas(...)` і `inspectGeminiToolSchemas(...)`
- — це базові публічні хелпери схем Gemini.
- - `resolveXaiModelCompatPatch()` повертає вбудований патч сумісності xAI:
- `toolSchemaProfile: "xai"`, непідтримувані ключові слова схем, нативну
- підтримку `web_search` і декодування HTML-сутностей у аргументах виклику інструментів.
- - `applyXaiModelCompat(model)` застосовує той самий патч сумісності xAI до
- визначеної моделі, перш ніж вона потрапить до runner.
+ є базовими публічними хелперами схем Gemini.
+ - `resolveXaiModelCompatPatch()` повертає вбудований compat patch xAI:
+ `toolSchemaProfile: "xai"`, непідтримувані ключові слова схеми, нативну
+ підтримку `web_search` і декодування аргументів виклику інструментів із HTML-entity.
+ - `applyXaiModelCompat(model)` застосовує той самий compat patch xAI до
+ визначеної моделі до того, як вона потрапить до runner.
Реальний вбудований приклад: плагін xAI використовує `normalizeResolvedModel` плюс
- `contributeResolvedModelCompat`, щоб ці метадані сумісності залишалися у володінні
- постачальника, а не були жорстко закодовані в core.
+ `contributeResolvedModelCompat`, щоб ці метадані compat належали
+ постачальнику, а не жорстко кодували правила xAI в core.
- Той самий шаблон package-root також лежить в основі інших вбудованих постачальників:
+ Такий самий шаблон package-root також використовується в інших вбудованих постачальниках:
- `@openclaw/openai-provider`: `api.ts` експортує builder-и постачальників,
хелпери моделей за замовчуванням і builder-и realtime-постачальників
- `@openclaw/openrouter-provider`: `api.ts` експортує builder
- постачальника, а також хелпери onboarding/config
+ постачальника разом із хелперами onboarding/config
-
- Для постачальників, яким потрібен обмін токенами перед кожним викликом інференсу:
+
+ Для постачальників, яким потрібен обмін токенів перед кожним викликом інференсу:
```typescript
prepareRuntimeAuth: async (ctx) => {
@@ -456,8 +457,8 @@ x-i18n:
```
- Для постачальників, яким потрібні нативні заголовки або метадані запиту/сесії на
- загальних HTTP- або WebSocket-транспортах:
+ Для постачальників, яким потрібні нативні заголовки запиту/сесії або метадані в
+ узагальнених HTTP- чи WebSocket-транспортах:
```typescript
resolveTransportTurnState: (ctx) => ({
@@ -477,7 +478,7 @@ x-i18n:
}),
```
-
+
Для постачальників, які надають дані про використання/білінг:
```typescript
@@ -493,83 +494,84 @@ x-i18n:
- OpenClaw викликає хуки в такому порядку. Більшість постачальників використовують лише 2-3:
+ OpenClaw викликає хуки в такому порядку. Більшість постачальників використовують лише 2–3:
- | # | Hook | Коли використовувати |
+ | # | Хук | Коли використовувати |
| --- | --- | --- |
- | 1 | `catalog` | Каталог моделей або значення `baseUrl` за замовчуванням |
+ | 1 | `catalog` | Каталог моделей або базові значення `baseUrl` |
| 2 | `applyConfigDefaults` | Глобальні значення за замовчуванням, що належать постачальнику, під час materialization config |
- | 3 | `normalizeModelId` | Очищення псевдонімів legacy/preview model-id перед пошуком |
- | 4 | `normalizeTransport` | Очищення `api` / `baseUrl` сімейства постачальника перед загальним збиранням моделі |
+ | 3 | `normalizeModelId` | Очищення застарілих/preview псевдонімів model-id перед пошуком |
+ | 4 | `normalizeTransport` | Очищення `api` / `baseUrl` сімейства постачальника перед збиранням узагальненої моделі |
| 5 | `normalizeConfig` | Нормалізація config `models.providers.` |
- | 6 | `applyNativeStreamingUsageCompat` | Перезаписи сумісності native streaming-usage для постачальників config |
+ | 6 | `applyNativeStreamingUsageCompat` | Переписування native streaming-usage compat для постачальників config |
| 7 | `resolveConfigApiKey` | Визначення автентифікації env-marker, що належить постачальнику |
- | 8 | `resolveSyntheticAuth` | Синтетична автентифікація для локальних/self-hosted або config-backed випадків |
- | 9 | `shouldDeferSyntheticProfileAuth` | Опускати синтетичні placeholder-и збережених профілів нижче за env/config auth |
+ | 8 | `resolveSyntheticAuth` | Синтетична автентифікація для local/self-hosted або на основі config |
+ | 9 | `shouldDeferSyntheticProfileAuth` | Опускання синтетичних placeholder-ів збереженого профілю нижче за env/config auth |
| 10 | `resolveDynamicModel` | Приймати довільні id моделей upstream |
| 11 | `prepareDynamicModel` | Асинхронне отримання метаданих перед визначенням |
- | 12 | `normalizeResolvedModel` | Перезаписи транспорту перед runner |
+ | 12 | `normalizeResolvedModel` | Переписування транспорту перед runner |
Примітки щодо runtime fallback:
- - `normalizeConfig` спочатку перевіряє відповідний постачальник, а потім інші
+ - `normalizeConfig` спочатку перевіряє відповідного постачальника, а потім інші
плагіни постачальників із підтримкою хуків, доки один із них справді не змінить config.
Якщо жоден хук постачальника не переписує підтримуваний запис config сімейства Google,
- усе одно застосовується вбудований нормалізатор config Google.
+ усе одно застосовується вбудований normalizer config Google.
- `resolveConfigApiKey` використовує хук постачальника, якщо він доступний. Вбудований
шлях `amazon-bedrock` також має тут вбудований resolver AWS env-marker,
- хоча сама runtime-автентифікація Bedrock і далі використовує стандартний
+ хоча сама runtime-автентифікація Bedrock усе ще використовує стандартний
ланцюжок AWS SDK.
- | 13 | `contributeResolvedModelCompat` | Прапори сумісності для моделей постачальників за іншим сумісним транспортом |
- | 14 | `capabilities` | Legacy-мішок статичних можливостей; лише для сумісності |
+ | 13 | `contributeResolvedModelCompat` | Прапори compat для моделей постачальників за іншим сумісним транспортом |
+ | 14 | `capabilities` | Застарілий статичний набір capability; лише для сумісності |
| 15 | `normalizeToolSchemas` | Очищення схеми інструментів, що належить постачальнику, перед реєстрацією |
| 16 | `inspectToolSchemas` | Діагностика схеми інструментів, що належить постачальнику |
- | 17 | `resolveReasoningOutputMode` | Контракт виходу reasoning: tagged чи native |
+ | 17 | `resolveReasoningOutputMode` | Контракт tagged vs native reasoning-output |
| 18 | `prepareExtraParams` | Параметри запиту за замовчуванням |
| 19 | `createStreamFn` | Повністю власний транспорт StreamFn |
- | 20 | `wrapStreamFn` | Власні обгортки заголовків/тіла на стандартному шляху потоку |
- | 21 | `resolveTransportTurnState` | Нативні заголовки/метадані для кожного ходу |
- | 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сесії WS / час охолодження |
- | 23 | `formatApiKey` | Власна форма runtime-токена |
+ | 20 | `wrapStreamFn` | Власні обгортки заголовків/тіла в звичайному шляху потоку |
+ | 21 | `resolveTransportTurnState` | Нативні заголовки/метадані для кожного turn |
+ | 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сесії WS / cool-down |
+ | 23 | `formatApiKey` | Власний формат runtime-токена |
| 24 | `refreshOAuth` | Власне оновлення OAuth |
- | 25 | `buildAuthDoctorHint` | Підказка для відновлення автентифікації |
- | 26 | `matchesContextOverflowError` | Визначення переповнення, що належить постачальнику |
+ | 25 | `buildAuthDoctorHint` | Порада з відновлення автентифікації |
+ | 26 | `matchesContextOverflowError` | Визначення overflow, що належить постачальнику |
| 27 | `classifyFailoverReason` | Класифікація rate-limit/overload, що належить постачальнику |
- | 28 | `isCacheTtlEligible` | Керування TTL кешу промптів |
+ | 28 | `isCacheTtlEligible` | Контроль TTL кешу промптів |
| 29 | `buildMissingAuthMessage` | Власна підказка про відсутню автентифікацію |
| 30 | `suppressBuiltInModel` | Приховати застарілі рядки upstream |
- | 31 | `augmentModelCatalog` | Синтетичні рядки для forward-compat |
- | 32 | `isBinaryThinking` | Увімкнення/вимкнення двійкового thinking |
+ | 31 | `augmentModelCatalog` | Синтетичні рядки для прямої forward-compat |
+ | 32 | `isBinaryThinking` | Бінарний режим thinking увімк./вимк. |
| 33 | `supportsXHighThinking` | Підтримка reasoning `xhigh` |
| 34 | `supportsAdaptiveThinking` | Підтримка adaptive thinking |
- | 35 | `resolveDefaultThinkingLevel` | Політика `/think` за замовчуванням |
- | 36 | `isModernModelRef` | Відповідність моделей для live/smoke |
- | 37 | `prepareRuntimeAuth` | Обмін токенами перед інференсом |
- | 38 | `resolveUsageAuth` | Власний розбір облікових даних використання |
- | 39 | `fetchUsageSnapshot` | Власна кінцева точка використання |
- | 40 | `createEmbeddingProvider` | Адаптер embedding, що належить постачальнику, для пам’яті/пошуку |
- | 41 | `buildReplayPolicy` | Власна політика replay/Compaction транскрипту |
- | 42 | `sanitizeReplayHistory` | Специфічні для постачальника перезаписи replay після загального очищення |
- | 43 | `validateReplayTurns` | Сувора валідація ходів replay перед вбудованим runner |
- | 44 | `onModelSelected` | Зворотний виклик після вибору моделі (наприклад, телеметрія) |
+ | 35 | `supportsMaxThinking` | Підтримка reasoning `max` |
+ | 36 | `resolveDefaultThinkingLevel` | Політика `/think` за замовчуванням |
+ | 37 | `isModernModelRef` | Відповідність моделей live/smoke |
+ | 38 | `prepareRuntimeAuth` | Обмін токенів перед інференсом |
+ | 39 | `resolveUsageAuth` | Власний парсинг облікових даних usage |
+ | 40 | `fetchUsageSnapshot` | Власний endpoint usage |
+ | 41 | `createEmbeddingProvider` | Адаптер embedding, що належить постачальнику, для пам’яті/пошуку |
+ | 42 | `buildReplayPolicy` | Власна політика replay/Compaction транскрипту |
+ | 43 | `sanitizeReplayHistory` | Переписування replay, специфічні для постачальника, після узагальненого очищення |
+ | 44 | `validateReplayTurns` | Строга валідація replay-turn перед вбудованим runner |
+ | 45 | `onModelSelected` | Колбек після вибору моделі (наприклад, telemetry) |
Примітка щодо налаштування промптів:
- - `resolveSystemPromptContribution` дозволяє постачальнику інжектувати
- cache-aware інструкції для системного промпту для сімейства моделей. Віддавайте перевагу йому замість
- `before_prompt_build`, коли поведінка належить одному сімейству постачальника/моделі
- і має зберігати стабільний/динамічний поділ кешу.
+ - `resolveSystemPromptContribution` дозволяє постачальнику додавати cache-aware
+ настанови для системного промпту для сімейства моделей. Надавайте йому перевагу перед
+ `before_prompt_build`, коли поведінка належить одному постачальнику/сімейству моделей
+ і має зберігати стабільний/динамічний розподіл кешу.
- Докладні описи та приклади з реального світу див. у
- [Внутрішні компоненти: runtime-хуки постачальника](/uk/plugins/architecture#provider-runtime-hooks).
+ Докладні описи та приклади з реального світу дивіться в
+ [Інтернали: Runtime-хуки постачальника](/uk/plugins/architecture#provider-runtime-hooks).
- Плагін постачальника може реєструвати мовлення, транскрипцію в реальному часі, голос у реальному
- часі, розуміння медіа, генерацію зображень, генерацію відео, web fetch
+ Плагін постачальника може реєструвати speech, realtime transcription, realtime
+ voice, media understanding, image generation, video generation, web fetch
і web search поряд із текстовим інференсом:
```typescript
@@ -679,19 +681,19 @@ x-i18n:
```
OpenClaw класифікує це як плагін **hybrid-capability**. Це
- рекомендований шаблон для корпоративних плагінів (один плагін на одного постачальника). Див.
- [Внутрішні компоненти: володіння можливостями](/uk/plugins/architecture#capability-ownership-model).
+ рекомендований шаблон для корпоративних плагінів (один плагін на постачальника). Див.
+ [Інтернали: Володіння можливостями](/uk/plugins/architecture#capability-ownership-model).
- Для генерації відео віддавайте перевагу показаній вище структурі можливостей з урахуванням режимів:
+ Для генерації відео надавайте перевагу показаній вище структурі можливостей з урахуванням режимів:
`generate`, `imageToVideo` і `videoToVideo`. Плоскі агреговані поля, такі
як `maxInputImages`, `maxInputVideos` і `maxDurationSeconds`, не
- достатні, щоб чисто оголосити підтримку режимів перетворення або вимкнених режимів.
+ достатні, щоб коректно оголосити підтримку режимів перетворення або вимкнених режимів.
Постачальники генерації музики мають дотримуватися того самого шаблону:
`generate` для генерації лише за промптом і `edit` для генерації
- на основі референсного зображення. Плоскі агреговані поля, такі як `maxInputImages`,
+ на основі зображення-референсу. Плоскі агреговані поля, такі як `maxInputImages`,
`supportsLyrics` і `supportsFormat`, не достатні, щоб оголосити
- підтримку редагування; очікуваний контракт — це явні блоки `generate` / `edit`.
+ підтримку редагування; очікуваним контрактом є явні блоки `generate` / `edit`.
@@ -732,43 +734,43 @@ x-i18n:
## Публікація в ClawHub
-Плагіни постачальників публікуються так само, як і будь-які інші зовнішні кодові плагіни:
+Плагіни постачальників публікуються так само, як і будь-який інший зовнішній кодовий плагін:
```bash
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
```
-Не використовуйте тут застарілий псевдонім публікації лише для Skills; пакети плагінів мають використовувати
+Не використовуйте тут застарілий псевдонім публікації лише для Skills; пакети плагінів повинні використовувати
`clawhub package publish`.
## Структура файлів
```
/acme-ai/
-├── package.json # Метадані openclaw.providers
-├── openclaw.plugin.json # Маніфест із метаданими автентифікації постачальника
+├── package.json # metadata openclaw.providers
+├── openclaw.plugin.json # Маніфест із metadata автентифікації постачальника
├── index.ts # definePluginEntry + registerProvider
└── src/
├── provider.test.ts # Тести
- └── usage.ts # Кінцева точка використання (необов’язково)
+ └── usage.ts # Endpoint usage (необов’язково)
```
-## Довідник щодо порядку каталогу
+## Довідка щодо порядку каталогу
-`catalog.order` визначає, коли ваш каталог зливається відносно вбудованих
+`catalog.order` керує тим, коли ваш каталог об’єднується відносно вбудованих
постачальників:
-| Порядок | Коли | Випадок використання |
-| --------- | ------------- | ----------------------------------------------- |
-| `simple` | Перший прохід | Звичайні постачальники з API-ключем |
-| `profile` | Після simple | Постачальники, обмежені профілями автентифікації |
-| `paired` | Після profile | Синтез кількох пов’язаних записів |
-| `late` | Останній прохід | Перевизначення наявних постачальників (перемагає при конфлікті) |
+| Порядок | Коли | Випадок використання |
+| --------- | ------------- | ---------------------------------------------- |
+| `simple` | Перший прохід | Звичайні постачальники з API-key |
+| `profile` | Після simple | Постачальники, що залежать від профілів auth |
+| `paired` | Після profile | Синтез кількох пов’язаних записів |
+| `late` | Останній прохід | Перевизначення наявних постачальників (перемагає при конфлікті) |
## Наступні кроки
- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — якщо ваш плагін також надає канал
-- [SDK Runtime](/uk/plugins/sdk-runtime) — хелпери `api.runtime` (TTS, пошук, subagent)
-- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник з імпортів subpath
-- [Внутрішні компоненти плагінів](/uk/plugins/architecture#provider-runtime-hooks) — деталі хуків і вбудовані приклади
+- [SDK Runtime](/uk/plugins/sdk-runtime) — хелпери `api.runtime` (TTS, search, subagent)
+- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів subpath
+- [Інтернали плагінів](/uk/plugins/architecture#provider-runtime-hooks) — подробиці про хуки та вбудовані приклади
diff --git a/docs/uk/providers/mistral.md b/docs/uk/providers/mistral.md
index 2996a7337..25aae542a 100644
--- a/docs/uk/providers/mistral.md
+++ b/docs/uk/providers/mistral.md
@@ -1,22 +1,22 @@
---
read_when:
- Ви хочете використовувати моделі Mistral в OpenClaw
- - Вам потрібні онбординг ключа API Mistral і посилання на моделі
+ - Вам потрібні онбординг для ключа API Mistral і посилання на моделі
summary: Використовуйте моделі Mistral і транскрипцію Voxtral з OpenClaw
title: Mistral
x-i18n:
- generated_at: "2026-04-12T10:33:33Z"
+ generated_at: "2026-04-21T06:04:44Z"
model: gpt-5.4
provider: openai
- source_hash: 0474f55587909ce9bbdd47b881262edbeb1b07eb3ed52de1090a8ec4d260c97b
+ source_hash: e87d04e3d45c04280c90821b1addd87dd612191249836747fba27cde48b9890f
source_path: providers/mistral.md
workflow: 15
---
# Mistral
-OpenClaw підтримує Mistral як для маршрутизації текстових/зображувальних моделей (`mistral/...`), так і для транскрипції аудіо через Voxtral у media understanding.
-Mistral також можна використовувати для ембедингів пам’яті (`memorySearch.provider = "mistral"`).
+OpenClaw підтримує Mistral як для маршрутизації текстових/графічних моделей (`mistral/...`), так і для аудіотранскрипції через Voxtral у media understanding.
+Mistral також можна використовувати для вбудовувань пам’яті (`memorySearch.provider = "mistral"`).
- Провайдер: `mistral`
- Автентифікація: `MISTRAL_API_KEY`
@@ -26,14 +26,14 @@ Mistral також можна використовувати для ембеди
- Створіть ключ API в [Mistral Console](https://console.mistral.ai/).
+ Створіть ключ API у [Mistral Console](https://console.mistral.ai/).
```bash
openclaw onboard --auth-choice mistral-api-key
```
- Або передайте ключ безпосередньо:
+ Або передайте ключ напряму:
```bash
openclaw onboard --mistral-api-key "$MISTRAL_API_KEY"
@@ -48,7 +48,7 @@ Mistral також можна використовувати для ембеди
}
```
-
+
```bash
openclaw models list --provider mistral
```
@@ -61,17 +61,17 @@ Mistral також можна використовувати для ембеди
| Посилання на модель | Вхідні дані | Контекст | Макс. вивід | Примітки |
| --------------------------------- | ----------- | -------- | ----------- | ---------------------------------------------------------------- |
-| `mistral/mistral-large-latest` | text, image | 262,144 | 16,384 | Модель за замовчуванням |
-| `mistral/mistral-medium-2508` | text, image | 262,144 | 8,192 | Mistral Medium 3.1 |
-| `mistral/mistral-small-latest` | text, image | 128,000 | 16,384 | Mistral Small 4; регульоване міркування через API `reasoning_effort` |
-| `mistral/pixtral-large-latest` | text, image | 128,000 | 32,768 | Pixtral |
-| `mistral/codestral-latest` | text | 256,000 | 4,096 | Програмування |
-| `mistral/devstral-medium-latest` | text | 262,144 | 32,768 | Devstral 2 |
-| `mistral/magistral-small` | text | 128,000 | 40,000 | З увімкненим міркуванням |
+| `mistral/mistral-large-latest` | текст, зображення | 262,144 | 16,384 | Модель за замовчуванням |
+| `mistral/mistral-medium-2508` | текст, зображення | 262,144 | 8,192 | Mistral Medium 3.1 |
+| `mistral/mistral-small-latest` | текст, зображення | 128,000 | 16,384 | Mistral Small 4; регульоване мислення через API `reasoning_effort` |
+| `mistral/pixtral-large-latest` | текст, зображення | 128,000 | 32,768 | Pixtral |
+| `mistral/codestral-latest` | текст | 256,000 | 4,096 | Програмування |
+| `mistral/devstral-medium-latest` | текст | 262,144 | 32,768 | Devstral 2 |
+| `mistral/magistral-small` | текст | 128,000 | 40,000 | Із підтримкою міркування |
-## Транскрипція аудіо (Voxtral)
+## Аудіотранскрипція (Voxtral)
-Використовуйте Voxtral для транскрипції аудіо через конвеєр media understanding.
+Використовуйте Voxtral для аудіотранскрипції через конвеєр media understanding.
```json5
{
@@ -93,24 +93,24 @@ Mistral також можна використовувати для ембеди
## Розширена конфігурація
-
- `mistral/mistral-small-latest` відповідає Mistral Small 4 і підтримує [регульоване міркування](https://docs.mistral.ai/capabilities/reasoning/adjustable) в API Chat Completions через `reasoning_effort` (`none` мінімізує додаткове міркування у виводі; `high` показує повні сліди міркування перед фінальною відповіддю).
+
+ `mistral/mistral-small-latest` відповідає Mistral Small 4 і підтримує [регульоване мислення](https://docs.mistral.ai/capabilities/reasoning/adjustable) в API Chat Completions через `reasoning_effort` (`none` зводить додаткові міркування у виводі до мінімуму; `high` показує повні сліди міркувань перед фінальною відповіддю).
- OpenClaw зіставляє рівень **thinking** сесії з API Mistral:
+ OpenClaw зіставляє рівень **мислення** сесії з API Mistral:
- | Рівень thinking в OpenClaw | Mistral `reasoning_effort` |
- | --------------------------------------------- | -------------------------- |
- | **off** / **minimal** | `none` |
- | **low** / **medium** / **high** / **xhigh** / **adaptive** | `high` |
+ | Рівень мислення OpenClaw | Mistral `reasoning_effort` |
+ | ------------------------------------------------ | -------------------------- |
+ | **off** / **minimal** | `none` |
+ | **low** / **medium** / **high** / **xhigh** / **adaptive** / **max** | `high` |
- Інші моделі у вбудованому каталозі Mistral не використовують цей параметр. Продовжуйте використовувати моделі `magistral-*`, якщо вам потрібна нативна поведінка Mistral, орієнтована насамперед на міркування.
+ Інші моделі з вбудованого каталогу Mistral не використовують цей параметр. Продовжуйте використовувати моделі `magistral-*`, якщо вам потрібна рідна для Mistral поведінка, орієнтована насамперед на міркування.
-
- Mistral може надавати ембединги пам’яті через `/v1/embeddings` (модель за замовчуванням: `mistral-embed`).
+
+ Mistral може надавати вбудовування пам’яті через `/v1/embeddings` (модель за замовчуванням: `mistral-embed`).
```json5
{
@@ -123,7 +123,7 @@ Mistral також можна використовувати для ембеди
- Автентифікація Mistral використовує `MISTRAL_API_KEY`.
- Базовий URL провайдера за замовчуванням: `https://api.mistral.ai/v1`.
- - Модель онбордингу за замовчуванням — `mistral/mistral-large-latest`.
+ - Моделлю за замовчуванням для онбордингу є `mistral/mistral-large-latest`.
- Z.AI використовує Bearer-автентифікацію з вашим ключем API.
@@ -135,6 +135,6 @@ Mistral також можна використовувати для ембеди
Вибір провайдерів, посилань на моделі та поведінки резервного перемикання.
- Налаштування транскрипції аудіо та вибір провайдера.
+ Налаштування аудіотранскрипції та вибір провайдера.
diff --git a/docs/uk/tools/thinking.md b/docs/uk/tools/thinking.md
index 46f345f61..aa0af693c 100644
--- a/docs/uk/tools/thinking.md
+++ b/docs/uk/tools/thinking.md
@@ -1,124 +1,127 @@
---
read_when:
- - Налаштування синтаксичного аналізу або значень за замовчуванням для директив мислення, швидкого режиму чи докладності
+ - Налаштування аналізу директив мислення, швидкого режиму або докладного режиму чи їхніх значень за замовчуванням
summary: Синтаксис директив для /think, /fast, /verbose, /trace і видимості міркувань
title: Рівні мислення
x-i18n:
- generated_at: "2026-04-21T05:21:16Z"
+ generated_at: "2026-04-21T06:04:47Z"
model: gpt-5.4
provider: openai
- source_hash: 7fbcb2feb14331e000ae0bcb908f060dba0ce900d6628a42e87e98502b13f6e9
+ source_hash: edee9420e1cc3eccfa18d87061c4a4d6873e70cb51fff85305fafbcd6a5d6a7d
source_path: tools/thinking.md
workflow: 15
---
-# Рівні мислення (/think директиви)
+# Рівні мислення (директиви `/think`)
## Що це робить
- Вбудована директива в будь-якому вхідному тілі: `/t `, `/think:` або `/thinking `.
-- Рівні (аліаси): `off | minimal | low | medium | high | xhigh | adaptive`
+- Рівні (псевдоніми): `off | minimal | low | medium | high | xhigh | adaptive | max`
- minimal → «think»
- low → «think hard»
- medium → «think harder»
- high → «ultrathink» (максимальний бюджет)
- - xhigh → «ultrathink+» (зусилля GPT-5.2 + моделей Codex і Anthropic Claude Opus 4.7)
- - adaptive → adaptive thinking, кероване провайдером (підтримується для Claude 4.6 на Anthropic/Bedrock і Anthropic Claude Opus 4.7)
+ - xhigh → «ultrathink+» (зусилля GPT-5.2 + Codex models і Anthropic Claude Opus 4.7)
+ - adaptive → кероване провайдером адаптивне мислення (підтримується для Claude 4.6 на Anthropic/Bedrock і Anthropic Claude Opus 4.7)
+ - max → максимальне міркування провайдера (наразі Anthropic Claude Opus 4.7)
- `x-high`, `x_high`, `extra-high`, `extra high` і `extra_high` зіставляються з `xhigh`.
- - `highest`, `max` зіставляються з `high`.
+ - `highest` зіставляється з `high`.
- Примітки щодо провайдерів:
- - `adaptive` рекламується лише в нативних меню команд і засобах вибору для провайдерів/моделей, які заявляють підтримку adaptive thinking. Воно, як і раніше, приймається як введена директива для сумісності з наявними конфігураціями та аліасами.
+ - `adaptive` показується лише в нативних меню команд і засобах вибору для провайдерів/моделей, які декларують підтримку adaptive thinking. Воно, як і раніше, приймається як введена директива для сумісності з наявними конфігураціями та псевдонімами.
+ - `max` показується лише в нативних меню команд і засобах вибору для провайдерів/моделей, які декларують підтримку max thinking. Наявні збережені параметри `max` повторно зіставляються з найбільшим підтримуваним рівнем для вибраної моделі, якщо модель не підтримує `max`.
- Моделі Anthropic Claude 4.6 за замовчуванням використовують `adaptive`, якщо явний рівень мислення не задано.
- - Anthropic Claude Opus 4.7 не використовує adaptive thinking за замовчуванням. Типове значення effort в його API залишається на боці провайдера, якщо ви явно не задасте рівень мислення.
- - Anthropic Claude Opus 4.7 зіставляє `/think xhigh` з adaptive thinking плюс `output_config.effort: "xhigh"`, тому що `/think` — це директива мислення, а `xhigh` — це параметр effort для Opus 4.7.
- - Моделі OpenAI GPT зіставляють `/think` через підтримку effort у Responses API, специфічну для моделі. `/think off` надсилає `reasoning.effort: "none"` лише коли цільова модель це підтримує; інакше OpenClaw пропускає payload із вимкненим reasoning, а не надсилає непідтримуване значення.
- - MiniMax (`minimax/*`) на Anthropic-сумісному потоковому шляху за замовчуванням використовує `thinking: { type: "disabled" }`, якщо ви явно не задали thinking у параметрах моделі або параметрах запиту. Це запобігає витоку delta `reasoning_content` із ненативного для Anthropic потокового формату MiniMax.
- - Z.AI (`zai/*`) підтримує лише бінарне мислення (`on`/`off`). Будь-який рівень, відмінний від `off`, трактується як `on` (зіставляється з `low`).
+ - Anthropic Claude Opus 4.7 не використовує adaptive thinking за замовчуванням. Його стандартне значення зусилля API залишається під керуванням провайдера, якщо ви явно не задасте рівень мислення.
+ - Anthropic Claude Opus 4.7 зіставляє `/think xhigh` з adaptive thinking плюс `output_config.effort: "xhigh"`, оскільки `/think` — це директива мислення, а `xhigh` — це налаштування зусилля Opus 4.7.
+ - Anthropic Claude Opus 4.7 також підтримує `/think max`; воно зіставляється з тим самим шляхом максимального зусилля під керуванням провайдера.
+ - Моделі OpenAI GPT зіставляють `/think` через підтримку effort API Responses, специфічну для моделі. `/think off` надсилає `reasoning.effort: "none"` лише тоді, коли цільова модель це підтримує; інакше OpenClaw пропускає payload вимкненого міркування замість надсилання непідтримуваного значення.
+ - MiniMax (`minimax/*`) на сумісному з Anthropic шляху потокової передачі за замовчуванням використовує `thinking: { type: "disabled" }`, якщо ви явно не задасте thinking у params моделі або params запиту. Це запобігає витоку дельт `reasoning_content` із ненативного Anthropic-формату потоку MiniMax.
+ - Z.AI (`zai/*`) підтримує лише двійкове мислення (`on`/`off`). Будь-який рівень, відмінний від `off`, трактується як `on` (зіставляється з `low`).
- Moonshot (`moonshot/*`) зіставляє `/think off` з `thinking: { type: "disabled" }`, а будь-який рівень, відмінний від `off`, — з `thinking: { type: "enabled" }`. Коли thinking увімкнено, Moonshot приймає лише `tool_choice` `auto|none`; OpenClaw нормалізує несумісні значення до `auto`.
## Порядок визначення
1. Вбудована директива в повідомленні (застосовується лише до цього повідомлення).
2. Перевизначення сесії (задається надсиланням повідомлення, що містить лише директиву).
-3. Типове значення для агента (`agents.list[].thinkingDefault` у конфігурації).
-4. Глобальне типове значення (`agents.defaults.thinkingDefault` у конфігурації).
-5. Резервний варіант: `adaptive` для моделей Anthropic Claude 4.6, `off` для Anthropic Claude Opus 4.7, якщо не налаштовано явно, `low` для інших моделей із підтримкою reasoning, інакше `off`.
+3. Значення за замовчуванням для агента (`agents.list[].thinkingDefault` у конфігурації).
+4. Глобальне значення за замовчуванням (`agents.defaults.thinkingDefault` у конфігурації).
+5. Резервне значення: `adaptive` для моделей Anthropic Claude 4.6, `off` для Anthropic Claude Opus 4.7, якщо це явно не налаштовано, `low` для інших моделей із підтримкою міркування, інакше `off`.
-## Установлення типового значення для сесії
+## Установлення значення за замовчуванням для сесії
- Надішліть повідомлення, яке **містить лише** директиву (допускаються пробіли), наприклад `/think:medium` або `/t high`.
-- Це закріплюється за поточною сесією (типово для кожного відправника окремо); скидається через `/think:off` або після скидання через неактивність сесії.
-- Надсилається відповідь-підтвердження (`Thinking level set to high.` / `Thinking disabled.`). Якщо рівень невалідний (наприклад, `/thinking big`), команда відхиляється з підказкою, а стан сесії залишається без змін.
+- Воно закріплюється для поточної сесії (за замовчуванням для кожного відправника окремо); скидається через `/think:off` або скидання через неактивність сесії.
+- Надсилається відповідь-підтвердження (`Thinking level set to high.` / `Thinking disabled.`). Якщо рівень недійсний (наприклад, `/thinking big`), команду буде відхилено з підказкою, а стан сесії залишиться без змін.
- Надішліть `/think` (або `/think:`) без аргументу, щоб побачити поточний рівень мислення.
## Застосування за агентом
-- **Вбудований Pi**: визначений рівень передається в runtime внутрішнього агента Pi.
+- **Вбудований Pi**: визначений рівень передається до внутрішньопроцесного середовища виконання агента Pi.
-## Швидкий режим (/fast)
+## Швидкий режим (`/fast`)
- Рівні: `on|off`.
-- Повідомлення лише з директивою перемикає перевизначення швидкого режиму для сесії та відповідає `Fast mode enabled.` / `Fast mode disabled.`.
+- Повідомлення лише з директивою перемикає перевизначення швидкого режиму для сесії та повертає `Fast mode enabled.` / `Fast mode disabled.`.
- Надішліть `/fast` (або `/fast status`) без режиму, щоб побачити поточний ефективний стан швидкого режиму.
- OpenClaw визначає швидкий режим у такому порядку:
1. Вбудована/окрема директива `/fast on|off`
2. Перевизначення сесії
- 3. Типове значення для агента (`agents.list[].fastModeDefault`)
+ 3. Значення за замовчуванням для агента (`agents.list[].fastModeDefault`)
4. Конфігурація для моделі: `agents.defaults.models["/"].params.fastMode`
- 5. Резервний варіант: `off`
-- Для `openai/*` швидкий режим зіставляється з пріоритетною обробкою OpenAI через надсилання `service_tier=priority` у підтримуваних запитах Responses.
-- Для `openai-codex/*` швидкий режим надсилає той самий прапорець `service_tier=priority` у Codex Responses. OpenClaw підтримує один спільний перемикач `/fast` для обох шляхів автентифікації.
-- Для прямих публічних запитів `anthropic/*`, включно з трафіком, автентифікованим через OAuth і надісланим до `api.anthropic.com`, швидкий режим зіставляється з рівнями сервісу Anthropic: `/fast on` задає `service_tier=auto`, `/fast off` задає `service_tier=standard_only`.
+ 5. Резервне значення: `off`
+- Для `openai/*` швидкий режим зіставляється з пріоритетною обробкою OpenAI шляхом надсилання `service_tier=priority` у підтримуваних запитах Responses.
+- Для `openai-codex/*` швидкий режим надсилає той самий прапорець `service_tier=priority` у Codex Responses. OpenClaw зберігає один спільний перемикач `/fast` для обох шляхів автентифікації.
+- Для прямих публічних запитів `anthropic/*`, включно з трафіком з OAuth-автентифікацією, надісланим до `api.anthropic.com`, швидкий режим зіставляється з рівнями сервісу Anthropic: `/fast on` задає `service_tier=auto`, `/fast off` задає `service_tier=standard_only`.
- Для `minimax/*` на Anthropic-сумісному шляху `/fast on` (або `params.fastMode: true`) переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`.
-- Явні параметри моделі Anthropic `serviceTier` / `service_tier` мають пріоритет над типовим значенням швидкого режиму, якщо задано обидва. OpenClaw усе одно пропускає вставлення рівня сервісу Anthropic для проксі base URL, які не належать Anthropic.
+- Явні параметри моделі Anthropic `serviceTier` / `service_tier` перевизначають стандартне значення швидкого режиму, якщо задано обидва. OpenClaw, як і раніше, пропускає вставлення рівня сервісу Anthropic для проксі URL-адрес, що не належать Anthropic.
-## Директиви докладності (/verbose або /v)
+## Докладні директиви (`/verbose` або `/v`)
- Рівні: `on` (мінімальний) | `full` | `off` (типово).
-- Повідомлення лише з директивою перемикає докладність для сесії та відповідає `Verbose logging enabled.` / `Verbose logging disabled.`; невалідні рівні повертають підказку без зміни стану.
-- `/verbose off` зберігає явне перевизначення сесії; очистіть його через інтерфейс Sessions, вибравши `inherit`.
-- Вбудована директива впливає лише на це повідомлення; в інших випадках застосовуються типові значення сесії/глобальні.
+- Повідомлення лише з директивою перемикає докладність сесії та повертає `Verbose logging enabled.` / `Verbose logging disabled.`; недійсні рівні повертають підказку без зміни стану.
+- `/verbose off` зберігає явне перевизначення сесії; очистьте його через інтерфейс Sessions, вибравши `inherit`.
+- Вбудована директива впливає лише на це повідомлення; в інших випадках застосовуються значення за замовчуванням для сесії/глобальні.
- Надішліть `/verbose` (або `/verbose:`) без аргументу, щоб побачити поточний рівень докладності.
-- Коли докладність увімкнена, агенти, які надсилають структуровані результати інструментів (Pi, інші JSON-агенти), повертають кожен виклик інструмента як окреме повідомлення лише з метаданими з префіксом ` : `, коли доступно (path/command). Ці короткі зведення інструментів надсилаються щойно кожен інструмент запускається (окремими бульбашками), а не як потокові delta.
-- Короткі зведення про збої інструментів залишаються видимими у звичайному режимі, але суфікси з необробленими деталями помилок приховуються, якщо тільки докладність не `on` або `full`.
-- Коли докладність `full`, вихідні дані інструментів також пересилаються після завершення (окремою бульбашкою, обрізані до безпечної довжини). Якщо ви перемкнете `/verbose on|full|off` під час активного виконання, наступні бульбашки інструментів врахують нове налаштування.
+- Коли verbose увімкнено, агенти, які надсилають структуровані результати інструментів (Pi, інші JSON-агенти), повертають кожен виклик інструмента як окреме повідомлення лише з метаданими з префіксом ` : `, коли доступно (шлях/команда). Ці підсумки інструментів надсилаються щойно кожен інструмент запускається (окремими бульбашками), а не як потокові дельти.
+- Підсумки збоїв інструментів залишаються видимими у звичайному режимі, але суфікси з необробленими подробицями помилок приховуються, якщо verbose не має значення `on` або `full`.
+- Коли verbose має значення `full`, виходи інструментів також пересилаються після завершення (окремою бульбашкою, обрізаною до безпечної довжини). Якщо ви перемкнете `/verbose on|full|off`, поки виконання ще триває, наступні бульбашки інструментів врахують нове налаштування.
-## Директиви trace Plugin (/trace)
+## Директиви трасування Plugin (`/trace`)
- Рівні: `on` | `off` (типово).
-- Повідомлення лише з директивою перемикає виведення trace Plugin для сесії та відповідає `Plugin trace enabled.` / `Plugin trace disabled.`.
-- Вбудована директива впливає лише на це повідомлення; в інших випадках застосовуються типові значення сесії/глобальні.
-- Надішліть `/trace` (або `/trace:`) без аргументу, щоб побачити поточний рівень trace.
-- `/trace` вужчий за `/verbose`: він показує лише trace/debug-рядки, що належать Plugin, як-от зведення налагодження Active Memory.
-- Рядки trace можуть з’являтися в `/status` і як додаткове діагностичне повідомлення після звичайної відповіді асистента.
+- Повідомлення лише з директивою перемикає виведення трасування plugin для сесії та повертає `Plugin trace enabled.` / `Plugin trace disabled.`.
+- Вбудована директива впливає лише на це повідомлення; в інших випадках застосовуються значення за замовчуванням для сесії/глобальні.
+- Надішліть `/trace` (або `/trace:`) без аргументу, щоб побачити поточний рівень трасування.
+- `/trace` вужчий за `/verbose`: він показує лише рядки трасування/налагодження, що належать plugin, наприклад підсумки налагодження Active Memory.
+- Рядки трасування можуть з’являтися в `/status` і як діагностичне повідомлення після звичайної відповіді помічника.
-## Видимість reasoning (/reasoning)
+## Видимість міркувань (`/reasoning`)
- Рівні: `on|off|stream`.
- Повідомлення лише з директивою перемикає, чи показуються блоки мислення у відповідях.
-- Коли увімкнено, reasoning надсилається як **окреме повідомлення** з префіксом `Reasoning:`.
-- `stream` (лише Telegram): потоково виводить reasoning у чернеткову бульбашку Telegram під час генерації відповіді, а потім надсилає фінальну відповідь без reasoning.
-- Аліас: `/reason`.
-- Надішліть `/reasoning` (або `/reasoning:`) без аргументу, щоб побачити поточний рівень reasoning.
-- Порядок визначення: вбудована директива, потім перевизначення сесії, потім типове значення для агента (`agents.list[].reasoningDefault`), потім резервний варіант (`off`).
+- Коли ввімкнено, міркування надсилається як **окреме повідомлення** з префіксом `Reasoning:`.
+- `stream` (лише Telegram): транслює міркування в чернетку-бульбашку Telegram під час генерації відповіді, а потім надсилає фінальну відповідь без міркувань.
+- Псевдонім: `/reason`.
+- Надішліть `/reasoning` (або `/reasoning:`) без аргументу, щоб побачити поточний рівень видимості міркувань.
+- Порядок визначення: вбудована директива, потім перевизначення сесії, потім значення за замовчуванням для агента (`agents.list[].reasoningDefault`), потім резервне значення (`off`).
## Пов’язане
-- Документація про elevated mode розміщена в [Elevated mode](/uk/tools/elevated).
+- Документація для elevated mode міститься в [Elevated mode](/uk/tools/elevated).
## Heartbeat
-- Тіло запиту Heartbeat — це налаштований prompt heartbeat (типово: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Вбудовані директиви в повідомленні heartbeat застосовуються як завжди (але уникайте зміни типових значень сесії з heartbeat).
-- Доставка Heartbeat за замовчуванням надсилає лише фінальний payload. Щоб також надсилати окреме повідомлення `Reasoning:` (коли доступне), задайте `agents.defaults.heartbeat.includeReasoning: true` або для агента `agents.list[].heartbeat.includeReasoning: true`.
+- Тіло probe Heartbeat — це налаштований запит heartbeat (типово: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Вбудовані директиви в heartbeat-повідомленні застосовуються як зазвичай (але уникайте зміни значень сесії за замовчуванням із heartbeat).
+- Доставка Heartbeat типово використовує лише фінальний payload. Щоб також надсилати окреме повідомлення `Reasoning:` (коли воно доступне), задайте `agents.defaults.heartbeat.includeReasoning: true` або для конкретного агента `agents.list[].heartbeat.includeReasoning: true`.
-## Інтерфейс вебчату
+## Вебінтерфейс чату
-- Селектор мислення у вебчаті відображає збережений рівень сесії зі сховища/конфігурації вхідної сесії під час завантаження сторінки.
-- Вибір іншого рівня негайно записує перевизначення сесії через `sessions.patch`; він не чекає наступного надсилання і не є одноразовим перевизначенням `thinkingOnce`.
-- Перший варіант завжди `Default ()`, де визначене типове значення береться з активної моделі сесії: `adaptive` для Claude 4.6 на Anthropic, `off` для Anthropic Claude Opus 4.7, якщо не налаштовано, `low` для інших моделей із підтримкою reasoning, інакше `off`.
-- Засіб вибору залишається залежним від провайдера:
+- Перемикач мислення у вебчаті відображає збережений рівень сесії зі сховища/конфігурації вхідної сесії під час завантаження сторінки.
+- Вибір іншого рівня відразу записує перевизначення сесії через `sessions.patch`; він не чекає наступного надсилання і не є одноразовим перевизначенням `thinkingOnce`.
+- Перший варіант завжди має вигляд `Default ()`, де визначене значення за замовчуванням походить від активної моделі сесії: `adaptive` для Claude 4.6 на Anthropic, `off` для Anthropic Claude Opus 4.7, якщо не налаштовано інакше, `low` для інших моделей із підтримкою міркування, і `off` в інших випадках.
+- Засіб вибору залишається обізнаним про провайдера:
- більшість провайдерів показують `off | minimal | low | medium | high`
- Anthropic/Bedrock Claude 4.6 показує `off | minimal | low | medium | high | adaptive`
- - Anthropic Claude Opus 4.7 показує `off | minimal | low | medium | high | xhigh | adaptive`
- - Z.AI показує бінарне `off | on`
-- `/think:` як і раніше працює й оновлює той самий збережений рівень сесії, тому директиви чату й засіб вибору залишаються синхронізованими.
+ - Anthropic Claude Opus 4.7 показує `off | minimal | low | medium | high | xhigh | adaptive | max`
+ - Z.AI показує двійкове `off | on`
+- `/think:` як і раніше працює та оновлює той самий збережений рівень сесії, тому директиви чату й засіб вибору залишаються синхронізованими.