chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
62e3a7bb08
commit
a05f5ea7a4
@ -2,28 +2,28 @@
|
||||
read_when:
|
||||
- Ви хочете підключити бота Feishu/Lark
|
||||
- Ви налаштовуєте канал Feishu
|
||||
summary: Огляд бота Feishu, функції та налаштування
|
||||
summary: Огляд, функції та налаштування бота Feishu
|
||||
title: Feishu
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T01:17:06Z"
|
||||
generated_at: "2026-04-25T07:01:55Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f68a03c457fb2be7654f298fbad759705983d9e673b7b7b950609694894bdcbc
|
||||
source_hash: 01e6373cc5744973e9f18016c5d5bd6a036a03eb269cba3b5fd7f4108cad2ecb
|
||||
source_path: channels/feishu.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Feishu / Lark
|
||||
|
||||
Feishu/Lark — це універсальна платформа для співпраці, де команди спілкуються в чаті, діляться документами, керують календарями та разом виконують роботу.
|
||||
Feishu/Lark — це універсальна платформа для співпраці, де команди спілкуються в чаті, обмінюються документами, керують календарями та спільно виконують роботу.
|
||||
|
||||
**Статус:** готово до використання у продакшені для особистих повідомлень боту та групових чатів. WebSocket — режим за замовчуванням; режим Webhook є необов’язковим.
|
||||
**Статус:** готово до використання у продакшені для особистих повідомлень боту та групових чатів. Режим WebSocket є стандартним; режим Webhook — необов’язковий.
|
||||
|
||||
---
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
> **Потрібен OpenClaw 2026.4.24 або новіший.** Виконайте `openclaw --version`, щоб перевірити. Оновіть за допомогою `openclaw update`.
|
||||
> **Потрібен OpenClaw 2026.4.24 або новіший.** Щоб перевірити, виконайте `openclaw --version`. Оновіть за допомогою `openclaw update`.
|
||||
|
||||
<Steps>
|
||||
<Step title="Запустіть майстер налаштування каналу">
|
||||
@ -46,14 +46,14 @@ Feishu/Lark — це універсальна платформа для спів
|
||||
|
||||
### Особисті повідомлення
|
||||
|
||||
Налаштуйте `dmPolicy`, щоб визначити, хто може надсилати боту особисті повідомлення:
|
||||
Налаштуйте `dmPolicy`, щоб керувати тим, хто може надсилати боту особисті повідомлення:
|
||||
|
||||
- `"pairing"` — невідомі користувачі отримують код сполучення; схвалення через CLI
|
||||
- `"allowlist"` — спілкуватися можуть лише користувачі, перелічені в `allowFrom` (за замовчуванням: лише власник бота)
|
||||
- `"pairing"` — невідомі користувачі отримують код сполучення; підтвердження через CLI
|
||||
- `"allowlist"` — спілкуватися можуть лише користувачі, перелічені в `allowFrom` (типово: лише власник бота)
|
||||
- `"open"` — дозволити всіх користувачів
|
||||
- `"disabled"` — вимкнути всі особисті повідомлення
|
||||
|
||||
**Схвалити запит на сполучення:**
|
||||
**Підтвердження запиту на сполучення:**
|
||||
|
||||
```bash
|
||||
openclaw pairing list feishu
|
||||
@ -62,19 +62,19 @@ openclaw pairing approve feishu <CODE>
|
||||
|
||||
### Групові чати
|
||||
|
||||
**Політика груп** (`channels.feishu.groupPolicy`):
|
||||
**Політика для груп** (`channels.feishu.groupPolicy`):
|
||||
|
||||
| Value | Поведінка |
|
||||
| ------------- | ------------------------------------------- |
|
||||
| `"open"` | Відповідати на всі повідомлення в групах |
|
||||
| `"allowlist"` | Відповідати лише групам у `groupAllowFrom` |
|
||||
| `"disabled"` | Вимкнути всі повідомлення в групах |
|
||||
| Значення | Поведінка |
|
||||
| ------------- | ------------------------------------------ |
|
||||
| `"open"` | Відповідати на всі повідомлення в групах |
|
||||
| `"allowlist"` | Відповідати лише в групах із `groupAllowFrom` |
|
||||
| `"disabled"` | Вимкнути всі групові повідомлення |
|
||||
|
||||
За замовчуванням: `allowlist`
|
||||
Типове значення: `allowlist`
|
||||
|
||||
**Вимога згадки** (`channels.feishu.requireMention`):
|
||||
|
||||
- `true` — вимагати @згадку (за замовчуванням)
|
||||
- `true` — вимагати @згадку (типово)
|
||||
- `false` — відповідати без @згадки
|
||||
- Перевизначення для окремої групи: `channels.feishu.groups.<chat_id>.requireMention`
|
||||
|
||||
@ -94,7 +94,7 @@ openclaw pairing approve feishu <CODE>
|
||||
}
|
||||
```
|
||||
|
||||
### Дозволити всі групи, але все одно вимагати @згадку
|
||||
### Дозволити всі групи, але все ще вимагати @згадку
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -107,14 +107,14 @@ openclaw pairing approve feishu <CODE>
|
||||
}
|
||||
```
|
||||
|
||||
### Дозволити лише певні групи
|
||||
### Дозволити лише конкретні групи
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
feishu: {
|
||||
groupPolicy: "allowlist",
|
||||
// ID груп мають вигляд: oc_xxx
|
||||
// Ідентифікатори груп мають вигляд: oc_xxx
|
||||
groupAllowFrom: ["oc_xxx", "oc_yyy"],
|
||||
},
|
||||
},
|
||||
@ -148,19 +148,19 @@ openclaw pairing approve feishu <CODE>
|
||||
|
||||
### ID групи (`chat_id`, формат: `oc_xxx`)
|
||||
|
||||
Відкрийте групу у Feishu/Lark, натисніть значок меню у верхньому правому куті та перейдіть до **Settings**. ID групи (`chat_id`) указано на сторінці налаштувань.
|
||||
Відкрийте групу у Feishu/Lark, натисніть значок меню у верхньому правому куті та перейдіть у **Settings**. ID групи (`chat_id`) вказано на сторінці налаштувань.
|
||||
|
||||
|
||||
|
||||
|
||||
### ID користувача (`open_id`, формат: `ou_xxx`)
|
||||
|
||||
Запустіть Gateway, надішліть боту особисте повідомлення, а потім перевірте логи:
|
||||
Запустіть Gateway, надішліть боту особисте повідомлення, а потім перевірте журнали:
|
||||
|
||||
```bash
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
Знайдіть `open_id` у виводі логів. Ви також можете перевірити запити на сполучення, що очікують схвалення:
|
||||
Шукайте `open_id` у виводі журналу. Також можна перевірити запити на сполучення, які очікують підтвердження:
|
||||
|
||||
```bash
|
||||
openclaw pairing list feishu
|
||||
@ -170,33 +170,33 @@ openclaw pairing list feishu
|
||||
|
||||
## Поширені команди
|
||||
|
||||
| Command | Опис |
|
||||
| --------- | ----------------------------- |
|
||||
| `/status` | Показати статус бота |
|
||||
| `/reset` | Скинути поточну сесію |
|
||||
| `/model` | Показати або змінити AI-модель |
|
||||
| Команда | Опис |
|
||||
| --------- | --------------------------------- |
|
||||
| `/status` | Показати статус бота |
|
||||
| `/reset` | Скинути поточну сесію |
|
||||
| `/model` | Показати або перемкнути AI-модель |
|
||||
|
||||
> Feishu/Lark не підтримує нативні меню slash-команд, тому надсилайте їх як звичайні текстові повідомлення.
|
||||
> Feishu/Lark не підтримує вбудовані меню slash-команд, тому надсилайте ці команди як звичайні текстові повідомлення.
|
||||
|
||||
---
|
||||
|
||||
## Усунення неполадок
|
||||
## Усунення несправностей
|
||||
|
||||
### Бот не відповідає в групових чатах
|
||||
|
||||
1. Переконайтеся, що бота додано до групи
|
||||
2. Переконайтеся, що ви @згадуєте бота (це потрібно за замовчуванням)
|
||||
2. Переконайтеся, що ви згадуєте бота через @ (типово це обов’язково)
|
||||
3. Перевірте, що `groupPolicy` не має значення `"disabled"`
|
||||
4. Перевірте логи: `openclaw logs --follow`
|
||||
4. Перевірте журнали: `openclaw logs --follow`
|
||||
|
||||
### Бот не отримує повідомлення
|
||||
|
||||
1. Переконайтеся, що бот опублікований і схвалений у Feishu Open Platform / Lark Developer
|
||||
2. Переконайтеся, що підписка на події включає `im.message.receive_v1`
|
||||
1. Переконайтеся, що бота опубліковано й схвалено у Feishu Open Platform / Lark Developer
|
||||
2. Переконайтеся, що підписка на події містить `im.message.receive_v1`
|
||||
3. Переконайтеся, що вибрано **persistent connection** (WebSocket)
|
||||
4. Переконайтеся, що надано всі потрібні дозволи
|
||||
5. Переконайтеся, що Gateway запущено: `openclaw gateway status`
|
||||
6. Перевірте логи: `openclaw logs --follow`
|
||||
6. Перевірте журнали: `openclaw logs --follow`
|
||||
|
||||
### App Secret скомпрометовано
|
||||
|
||||
@ -237,19 +237,19 @@ openclaw pairing list feishu
|
||||
|
||||
### Обмеження повідомлень
|
||||
|
||||
- `textChunkLimit` — розмір фрагмента вихідного тексту (за замовчуванням: `2000` символів)
|
||||
- `mediaMaxMb` — ліміт завантаження/вивантаження медіа (за замовчуванням: `30` МБ)
|
||||
- `textChunkLimit` — розмір фрагмента вихідного тексту (типово: `2000` символів)
|
||||
- `mediaMaxMb` — обмеження на завантаження/вивантаження медіа (типово: `30` МБ)
|
||||
|
||||
### Потокове передавання
|
||||
### Streaming
|
||||
|
||||
Feishu/Lark підтримує потокові відповіді через інтерактивні картки. Коли це ввімкнено, бот оновлює картку в реальному часі під час генерації тексту.
|
||||
Feishu/Lark підтримує потокові відповіді через інтерактивні картки. Якщо цю функцію ввімкнено, бот оновлює картку в реальному часі під час генерації тексту.
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
feishu: {
|
||||
streaming: true, // увімкнути виведення потокових карток (за замовчуванням: true)
|
||||
blockStreaming: true, // увімкнути потокове передавання на рівні блоків (за замовчуванням: true)
|
||||
streaming: true, // увімкнути потоковий вивід у картках (типово: true)
|
||||
blockStreaming: true, // увімкнути потокову передачу на рівні блоків (типово: true)
|
||||
},
|
||||
},
|
||||
}
|
||||
@ -261,8 +261,8 @@ Feishu/Lark підтримує потокові відповіді через і
|
||||
|
||||
Зменште кількість викликів API Feishu/Lark за допомогою двох необов’язкових прапорців:
|
||||
|
||||
- `typingIndicator` (за замовчуванням `true`): установіть `false`, щоб пропустити виклики реакції набору тексту
|
||||
- `resolveSenderNames` (за замовчуванням `true`): установіть `false`, щоб пропустити пошук профілів відправників
|
||||
- `typingIndicator` (типово `true`): установіть `false`, щоб пропустити виклики реакцій друку
|
||||
- `resolveSenderNames` (типово `true`): установіть `false`, щоб пропустити пошук профілів відправників
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -277,9 +277,9 @@ Feishu/Lark підтримує потокові відповіді через і
|
||||
|
||||
### Сесії ACP
|
||||
|
||||
Feishu/Lark підтримує ACP для особистих повідомлень і повідомлень у гілках груп. ACP у Feishu/Lark керується текстовими командами — нативних меню slash-команд немає, тому використовуйте повідомлення `/acp ...` безпосередньо в розмові.
|
||||
Feishu/Lark підтримує ACP для особистих повідомлень і повідомлень у гілках груп. ACP у Feishu/Lark керується текстовими командами — вбудованих меню slash-команд немає, тому використовуйте повідомлення `/acp ...` безпосередньо в розмові.
|
||||
|
||||
#### Постійна прив’язка ACP
|
||||
#### Постійне прив’язування ACP
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -331,7 +331,7 @@ Feishu/Lark підтримує ACP для особистих повідомле
|
||||
/acp spawn codex --thread here
|
||||
```
|
||||
|
||||
`--thread here` працює для особистих повідомлень і повідомлень у гілках Feishu/Lark. Подальші повідомлення в прив’язаній розмові маршрутизуються безпосередньо до цієї сесії ACP.
|
||||
`--thread here` працює для особистих повідомлень і повідомлень у гілках Feishu/Lark. Подальші повідомлення в прив’язаній розмові будуть маршрутизуватися безпосередньо до цієї сесії ACP.
|
||||
|
||||
### Маршрутизація між кількома агентами
|
||||
|
||||
@ -368,10 +368,10 @@ Feishu/Lark підтримує ACP для особистих повідомле
|
||||
Поля маршрутизації:
|
||||
|
||||
- `match.channel`: `"feishu"`
|
||||
- `match.peer.kind`: `"direct"` (особисте повідомлення) або `"group"` (груповий чат)
|
||||
- `match.peer.kind`: `"direct"` (особисті повідомлення) або `"group"` (груповий чат)
|
||||
- `match.peer.id`: Open ID користувача (`ou_xxx`) або ID групи (`oc_xxx`)
|
||||
|
||||
Поради щодо пошуку дивіться в розділі [Отримання ID групи/користувача](#get-groupuser-ids).
|
||||
Поради щодо пошуку див. у [Отримання ID групи/користувача](#get-groupuser-ids).
|
||||
|
||||
---
|
||||
|
||||
@ -379,33 +379,33 @@ Feishu/Lark підтримує ACP для особистих повідомле
|
||||
|
||||
Повна конфігурація: [Конфігурація Gateway](/uk/gateway/configuration)
|
||||
|
||||
| Setting | Опис | За замовчуванням |
|
||||
| ------------------------------------------------- | ------------------------------------------- | ---------------- |
|
||||
| `channels.feishu.enabled` | Увімкнути/вимкнути канал | `true` |
|
||||
| `channels.feishu.domain` | Домен API (`feishu` або `lark`) | `feishu` |
|
||||
| `channels.feishu.connectionMode` | Транспорт подій (`websocket` або `webhook`) | `websocket` |
|
||||
| `channels.feishu.defaultAccount` | Обліковий запис за замовчуванням для вихідної маршрутизації | `default` |
|
||||
| `channels.feishu.verificationToken` | Потрібно для режиму webhook | — |
|
||||
| `channels.feishu.encryptKey` | Потрібно для режиму webhook | — |
|
||||
| `channels.feishu.webhookPath` | Шлях маршруту Webhook | `/feishu/events` |
|
||||
| `channels.feishu.webhookHost` | Хост прив’язки Webhook | `127.0.0.1` |
|
||||
| `channels.feishu.webhookPort` | Порт прив’язки Webhook | `3000` |
|
||||
| `channels.feishu.accounts.<id>.appId` | App ID | — |
|
||||
| `channels.feishu.accounts.<id>.appSecret` | App Secret | — |
|
||||
| `channels.feishu.accounts.<id>.domain` | Перевизначення домену для окремого облікового запису | `feishu` |
|
||||
| `channels.feishu.dmPolicy` | Політика особистих повідомлень | `allowlist` |
|
||||
| `channels.feishu.allowFrom` | Список дозволених для особистих повідомлень (список `open_id`) | [BotOwnerId] |
|
||||
| `channels.feishu.groupPolicy` | Політика груп | `allowlist` |
|
||||
| `channels.feishu.groupAllowFrom` | Список дозволених груп | — |
|
||||
| `channels.feishu.requireMention` | Вимагати @згадку в групах | `true` |
|
||||
| `channels.feishu.groups.<chat_id>.requireMention` | Перевизначення @згадки для окремої групи | inherited |
|
||||
| `channels.feishu.groups.<chat_id>.enabled` | Увімкнути/вимкнути окрему групу | `true` |
|
||||
| `channels.feishu.textChunkLimit` | Розмір фрагмента повідомлення | `2000` |
|
||||
| `channels.feishu.mediaMaxMb` | Ліміт розміру медіа | `30` |
|
||||
| `channels.feishu.streaming` | Виведення потокових карток | `true` |
|
||||
| `channels.feishu.blockStreaming` | Потокове передавання на рівні блоків | `true` |
|
||||
| `channels.feishu.typingIndicator` | Надсилати реакції набору тексту | `true` |
|
||||
| `channels.feishu.resolveSenderNames` | Визначати відображувані імена відправників | `true` |
|
||||
| Параметр | Опис | Типове значення |
|
||||
| ------------------------------------------------ | -------------------------------------------- | ---------------- |
|
||||
| `channels.feishu.enabled` | Увімкнути/вимкнути канал | `true` |
|
||||
| `channels.feishu.domain` | Домен API (`feishu` або `lark`) | `feishu` |
|
||||
| `channels.feishu.connectionMode` | Транспорт подій (`websocket` або `webhook`) | `websocket` |
|
||||
| `channels.feishu.defaultAccount` | Типовий обліковий запис для вихідної маршрутизації | `default` |
|
||||
| `channels.feishu.verificationToken` | Потрібний для режиму Webhook | — |
|
||||
| `channels.feishu.encryptKey` | Потрібний для режиму Webhook | — |
|
||||
| `channels.feishu.webhookPath` | Шлях маршруту Webhook | `/feishu/events` |
|
||||
| `channels.feishu.webhookHost` | Хост прив’язки Webhook | `127.0.0.1` |
|
||||
| `channels.feishu.webhookPort` | Порт прив’язки Webhook | `3000` |
|
||||
| `channels.feishu.accounts.<id>.appId` | App ID | — |
|
||||
| `channels.feishu.accounts.<id>.appSecret` | App Secret | — |
|
||||
| `channels.feishu.accounts.<id>.domain` | Перевизначення домену для облікового запису | `feishu` |
|
||||
| `channels.feishu.dmPolicy` | Політика особистих повідомлень | `allowlist` |
|
||||
| `channels.feishu.allowFrom` | Список дозволених для особистих повідомлень (`open_id`) | [BotOwnerId] |
|
||||
| `channels.feishu.groupPolicy` | Політика для груп | `allowlist` |
|
||||
| `channels.feishu.groupAllowFrom` | Список дозволених груп | — |
|
||||
| `channels.feishu.requireMention` | Вимагати @згадку в групах | `true` |
|
||||
| `channels.feishu.groups.<chat_id>.requireMention` | Перевизначення @згадки для окремої групи | inherited |
|
||||
| `channels.feishu.groups.<chat_id>.enabled` | Увімкнути/вимкнути конкретну групу | `true` |
|
||||
| `channels.feishu.textChunkLimit` | Розмір фрагмента повідомлення | `2000` |
|
||||
| `channels.feishu.mediaMaxMb` | Обмеження розміру медіа | `30` |
|
||||
| `channels.feishu.streaming` | Потоковий вивід у картках | `true` |
|
||||
| `channels.feishu.blockStreaming` | Потокова передача на рівні блоків | `true` |
|
||||
| `channels.feishu.typingIndicator` | Надсилати реакції друку | `true` |
|
||||
| `channels.feishu.resolveSenderNames` | Визначати відображувані імена відправників | `true` |
|
||||
|
||||
---
|
||||
|
||||
@ -428,21 +428,23 @@ Feishu/Lark підтримує ACP для особистих повідомле
|
||||
- ✅ Файли
|
||||
- ✅ Аудіо
|
||||
- ✅ Відео/медіа
|
||||
- ✅ Інтерактивні картки (включно з потоковими оновленнями)
|
||||
- ⚠️ Форматований текст (форматування у стилі post; не підтримує всі можливості створення вмісту Feishu/Lark)
|
||||
- ✅ Інтерактивні картки (зокрема з потоковими оновленнями)
|
||||
- ⚠️ Форматований текст (форматування у стилі post; не підтримує всі можливості авторингу Feishu/Lark)
|
||||
|
||||
### Гілки та відповіді
|
||||
|
||||
- ✅ Вбудовані відповіді
|
||||
- ✅ Відповіді у гілках
|
||||
- ✅ Відповіді з медіа залишаються прив’язаними до гілки під час відповіді на повідомлення в гілці
|
||||
- ✅ Відповіді в гілках
|
||||
- ✅ Відповіді з медіа зберігають прив’язку до гілки під час відповіді на повідомлення в гілці
|
||||
|
||||
Для `groupSessionScope: "group_topic"` і `"group_topic_sender"` власні тематичні групи Feishu/Lark використовують подію `thread_id` (`omt_*`) як канонічний ключ сесії теми. Звичайні відповіді в групі, які OpenClaw перетворює на гілки, і далі використовують ID кореневого повідомлення відповіді (`om_*`), щоб перший хід і наступний хід залишалися в межах однієї сесії.
|
||||
|
||||
---
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд каналів](/uk/channels) — усі підтримувані канали
|
||||
- [Сполучення](/uk/channels/pairing) — автентифікація особистих повідомлень і процес сполучення
|
||||
- [Групи](/uk/channels/groups) — поведінка групових чатів і обмеження через згадки
|
||||
- [Сполучення](/uk/channels/pairing) — автентифікація в особистих повідомленнях і процес сполучення
|
||||
- [Групи](/uk/channels/groups) — поведінка групового чату та вимога згадки
|
||||
- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень
|
||||
- [Безпека](/uk/gateway/security) — модель доступу та посилення захисту
|
||||
- [Безпека](/uk/gateway/security) — модель доступу та зміцнення захисту
|
||||
|
||||
@ -1,37 +1,35 @@
|
||||
---
|
||||
read_when:
|
||||
- Підключення Codex, Claude Code або іншого клієнта MCP до каналів на основі OpenClaw
|
||||
- Підключення Codex, Claude Code або іншого клієнта MCP до каналів на базі OpenClaw
|
||||
- Запуск `openclaw mcp serve`
|
||||
- Керування збереженими в OpenClaw визначеннями серверів MCP
|
||||
summary: Відкривайте доступ до розмов каналів OpenClaw через MCP і керуйте збереженими визначеннями серверів MCP
|
||||
summary: Відкрийте доступ до розмов каналів OpenClaw через MCP і керуйте збереженими визначеннями серверів MCP
|
||||
title: MCP
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T03:15:24Z"
|
||||
generated_at: "2026-04-25T07:01:56Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b9df42ebc547f07698f84888d8cd6125340d0f0e02974a965670844589e1fbf8
|
||||
source_hash: 43505ab290d01a2c3f7dd9ff39b8a074360ba4365b628da71459c6f9a9659dc5
|
||||
source_path: cli/mcp.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
`openclaw mcp` має два завдання:
|
||||
`openclaw mcp` має дві задачі:
|
||||
|
||||
- запускати OpenClaw як MCP-сервер за допомогою `openclaw mcp serve`
|
||||
- керувати визначеннями вихідних MCP-серверів, що належать OpenClaw, за допомогою `list`, `show`,
|
||||
- запускати OpenClaw як сервер MCP за допомогою `openclaw mcp serve`
|
||||
- керувати визначеннями вихідних серверів MCP, якими володіє OpenClaw, за допомогою `list`, `show`,
|
||||
`set` і `unset`
|
||||
|
||||
Іншими словами:
|
||||
|
||||
- `serve` — це OpenClaw, що діє як MCP-сервер
|
||||
- `list` / `show` / `set` / `unset` — це OpenClaw, що діє як клієнтський
|
||||
реєстр для інших MCP-серверів, які його середовища виконання можуть
|
||||
використовувати пізніше
|
||||
- `serve` — це OpenClaw, що працює як сервер MCP
|
||||
- `list` / `show` / `set` / `unset` — це OpenClaw, що працює як реєстр на боці клієнта MCP
|
||||
для інших серверів MCP, які його середовища виконання можуть використати пізніше
|
||||
|
||||
Використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має самостійно
|
||||
розміщувати сесію середовища кодування та маршрутизувати це середовище
|
||||
виконання через ACP.
|
||||
Використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має сам розміщувати
|
||||
сеанс coding harness і маршрутизувати це середовище виконання через ACP.
|
||||
|
||||
## OpenClaw як MCP-сервер
|
||||
## OpenClaw як сервер MCP
|
||||
|
||||
Це шлях `openclaw mcp serve`.
|
||||
|
||||
@ -39,19 +37,19 @@ x-i18n:
|
||||
|
||||
Використовуйте `openclaw mcp serve`, коли:
|
||||
|
||||
- Codex, Claude Code або інший клієнт MCP має безпосередньо взаємодіяти
|
||||
з розмовами каналів на основі OpenClaw
|
||||
- у вас уже є локальний або віддалений Gateway OpenClaw із маршрутизованими сесіями
|
||||
- вам потрібен один MCP-сервер, який працює через канальні бекенди OpenClaw,
|
||||
- Codex, Claude Code або інший клієнт MCP має напряму взаємодіяти з
|
||||
розмовами каналів на базі OpenClaw
|
||||
- у вас уже є локальний або віддалений Gateway OpenClaw із маршрутизованими сеансами
|
||||
- вам потрібен один сервер MCP, який працює через серверні частини каналів OpenClaw,
|
||||
замість запуску окремих мостів для кожного каналу
|
||||
|
||||
Натомість використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має сам
|
||||
розміщувати середовище виконання кодування та зберігати сесію агента всередині OpenClaw.
|
||||
Натомість використовуйте [`openclaw acp`](/uk/cli/acp), коли OpenClaw має сам розміщувати
|
||||
середовище виконання coding і тримати сеанс агента всередині OpenClaw.
|
||||
|
||||
## Як це працює
|
||||
|
||||
`openclaw mcp serve` запускає stdio MCP-сервер. Клієнт MCP володіє цим
|
||||
процесом. Поки клієнт тримає stdio-сесію відкритою, міст підключається до
|
||||
`openclaw mcp serve` запускає сервер MCP через stdio. Клієнт MCP володіє цим
|
||||
процесом. Поки клієнт тримає сеанс stdio відкритим, міст підключається до
|
||||
локального або віддаленого Gateway OpenClaw через WebSocket і відкриває
|
||||
маршрутизовані розмови каналів через MCP.
|
||||
|
||||
@ -59,55 +57,55 @@ x-i18n:
|
||||
|
||||
1. клієнт MCP запускає `openclaw mcp serve`
|
||||
2. міст підключається до Gateway
|
||||
3. маршрутизовані сесії стають MCP-розмовами та інструментами стенограми/історії
|
||||
3. маршрутизовані сеанси стають розмовами MCP та інструментами transcript/history
|
||||
4. живі події ставляться в чергу в пам’яті, поки міст підключений
|
||||
5. якщо ввімкнено режим каналу Claude, та сама сесія також може отримувати
|
||||
специфічні для Claude push-сповіщення
|
||||
5. якщо увімкнено режим каналу Claude, той самий сеанс також може отримувати
|
||||
push-сповіщення, специфічні для Claude
|
||||
|
||||
Важлива поведінка:
|
||||
|
||||
- стан живої черги починається, коли міст підключається
|
||||
- старіша історія стенограми читається через `messages_read`
|
||||
- push-сповіщення Claude існують лише поки жива MCP-сесія
|
||||
- коли клієнт відключається, міст завершує роботу, і жива черга зникає
|
||||
- stdio MCP-сервери, запущені OpenClaw (вбудовані або налаштовані користувачем), зупиняються
|
||||
- старіша історія transcript читається через `messages_read`
|
||||
- push-сповіщення Claude існують лише поки активний сеанс MCP
|
||||
- коли клієнт від’єднується, міст завершує роботу, і жива черга зникає
|
||||
- сервери stdio MCP, запущені OpenClaw (вбудовані або налаштовані користувачем), завершуються
|
||||
як дерево процесів під час вимкнення, тому дочірні підпроцеси, запущені
|
||||
сервером, не зберігаються після завершення батьківського stdio-клієнта
|
||||
- видалення або скидання сесії звільняє MCP-клієнти цієї сесії через
|
||||
спільний шлях очищення середовища виконання, тому не залишається жодних
|
||||
завислих stdio-з’єднань, пов’язаних із видаленою сесією
|
||||
сервером, не виживають після завершення батьківського клієнта stdio
|
||||
- видалення або скидання сеансу звільняє клієнтів MCP цього сеансу через
|
||||
спільний шлях очищення середовища виконання, тож не залишається завислих
|
||||
stdio-з’єднань, прив’язаних до вилученого сеансу
|
||||
|
||||
## Вибір режиму клієнта
|
||||
|
||||
Використовуйте той самий міст двома різними способами:
|
||||
Той самий міст можна використовувати двома різними способами:
|
||||
|
||||
- Загальні клієнти MCP: лише стандартні інструменти MCP. Використовуйте `conversations_list`,
|
||||
- Звичайні клієнти MCP: лише стандартні інструменти MCP. Використовуйте `conversations_list`,
|
||||
`messages_read`, `events_poll`, `events_wait`, `messages_send` та
|
||||
інструменти схвалення.
|
||||
інструменти погодження.
|
||||
- Claude Code: стандартні інструменти MCP плюс адаптер каналу, специфічний для Claude.
|
||||
Увімкніть `--claude-channel-mode on` або залиште типове значення `auto`.
|
||||
Увімкніть `--claude-channel-mode on` або залиште значення за замовчуванням `auto`.
|
||||
|
||||
Наразі `auto` поводиться так само, як `on`. Виявлення можливостей клієнта
|
||||
ще не реалізовано.
|
||||
ще немає.
|
||||
|
||||
## Що відкриває `serve`
|
||||
|
||||
Міст використовує наявні метадані маршруту сесії Gateway, щоб відкривати
|
||||
розмови, прив’язані до каналу. Розмова з’являється, коли OpenClaw уже має
|
||||
стан сесії з відомим маршрутом, таким як:
|
||||
Міст використовує наявні метадані маршруту сеансу Gateway, щоб відкривати
|
||||
розмови, прив’язані до каналів. Розмова з’являється, коли OpenClaw уже має стан
|
||||
сеансу з відомим маршрутом, таким як:
|
||||
|
||||
- `channel`
|
||||
- метадані одержувача або призначення
|
||||
- метадані отримувача або призначення
|
||||
- необов’язковий `accountId`
|
||||
- необов’язковий `threadId`
|
||||
|
||||
Це дає клієнтам MCP одну точку, щоб:
|
||||
Це дає клієнтам MCP єдине місце, де можна:
|
||||
|
||||
- перелічувати нещодавні маршрутизовані розмови
|
||||
- читати нещодавню історію стенограми
|
||||
- очікувати нові вхідні події
|
||||
- переглядати список нещодавніх маршрутизованих розмов
|
||||
- читати недавню історію transcript
|
||||
- чекати нові вхідні події
|
||||
- надсилати відповідь назад тим самим маршрутом
|
||||
- бачити запити на схвалення, які надходять, поки міст підключений
|
||||
- бачити запити на погодження, які надходять, поки міст підключений
|
||||
|
||||
## Використання
|
||||
|
||||
@ -118,17 +116,17 @@ openclaw mcp serve
|
||||
# Віддалений Gateway
|
||||
openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
|
||||
|
||||
# Віддалений Gateway з автентифікацією паролем
|
||||
# Віддалений Gateway з автентифікацією за паролем
|
||||
openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password
|
||||
|
||||
# Увімкнути докладні журнали моста
|
||||
# Увімкнути докладні журнали мосту
|
||||
openclaw mcp serve --verbose
|
||||
|
||||
# Вимкнути push-сповіщення, специфічні для Claude
|
||||
openclaw mcp serve --claude-channel-mode off
|
||||
```
|
||||
|
||||
## Інструменти моста
|
||||
## Інструменти мосту
|
||||
|
||||
Поточний міст відкриває такі інструменти MCP:
|
||||
|
||||
@ -144,8 +142,8 @@ openclaw mcp serve --claude-channel-mode off
|
||||
|
||||
### `conversations_list`
|
||||
|
||||
Перелічує нещодавні розмови, прив’язані до сесії, які вже мають метадані
|
||||
маршруту в стані сесії Gateway.
|
||||
Показує список нещодавніх розмов, прив’язаних до сеансів, які вже мають
|
||||
метадані маршруту в стані сеансу Gateway.
|
||||
|
||||
Корисні фільтри:
|
||||
|
||||
@ -161,43 +159,44 @@ openclaw mcp serve --claude-channel-mode off
|
||||
|
||||
### `messages_read`
|
||||
|
||||
Читає нещодавні повідомлення стенограми для однієї розмови, прив’язаної до сесії.
|
||||
Читає недавні повідомлення transcript для однієї розмови, прив’язаної до сеансу.
|
||||
|
||||
### `attachments_fetch`
|
||||
|
||||
Витягує нетекстові блоки вмісту повідомлення з одного повідомлення стенограми. Це
|
||||
подання метаданих поверх вмісту стенограми, а не окреме довговічне сховище blob-вкладень.
|
||||
Витягує нетекстові блоки вмісту повідомлення з одного повідомлення transcript. Це
|
||||
подання метаданих поверх вмісту transcript, а не окреме стійке сховище
|
||||
вкладень blob.
|
||||
|
||||
### `events_poll`
|
||||
|
||||
Читає поставлені в чергу живі події, починаючи з числового курсора.
|
||||
Читає поставлені в чергу живі події від числового курсора.
|
||||
|
||||
### `events_wait`
|
||||
|
||||
Виконує long-polling, доки не надійде наступна відповідна поставлена в чергу подія
|
||||
або не спливе час очікування.
|
||||
Виконує long-polling, доки не надійде наступна відповідна поставлена в чергу
|
||||
подія або не спливе час очікування.
|
||||
|
||||
Використовуйте це, коли загальному клієнту MCP потрібна доставка, близька до
|
||||
реального часу, без push-протоколу, специфічного для Claude.
|
||||
Використовуйте це, коли звичайному клієнту MCP потрібна доставка, близька до
|
||||
реального часу, без протоколу push, специфічного для Claude.
|
||||
|
||||
### `messages_send`
|
||||
|
||||
Надсилає текст назад тим самим маршрутом, уже записаним у сесії.
|
||||
Надсилає текст назад тим самим маршрутом, уже збереженим у сеансі.
|
||||
|
||||
Поточна поведінка:
|
||||
|
||||
- потребує наявного маршруту розмови
|
||||
- використовує канал сесії, одержувача, id облікового запису та id треду
|
||||
- використовує канал сеансу, отримувача, id облікового запису та id треду
|
||||
- надсилає лише текст
|
||||
|
||||
### `permissions_list_open`
|
||||
|
||||
Перелічує очікувальні запити на схвалення exec/Plugin, які міст спостерігав
|
||||
після підключення до Gateway.
|
||||
Показує список очікуваних запитів на погодження exec/plugin, які міст спостерігав
|
||||
від моменту підключення до Gateway.
|
||||
|
||||
### `permissions_respond`
|
||||
|
||||
Вирішує один очікувальний запит на схвалення exec/Plugin за допомогою:
|
||||
Вирішує один очікуваний запит на погодження exec/plugin за допомогою:
|
||||
|
||||
- `allow-once`
|
||||
- `allow-always`
|
||||
@ -205,7 +204,7 @@ openclaw mcp serve --claude-channel-mode off
|
||||
|
||||
## Модель подій
|
||||
|
||||
Міст зберігає чергу подій у пам’яті, поки він підключений.
|
||||
Міст тримає в пам’яті чергу подій, поки він підключений.
|
||||
|
||||
Поточні типи подій:
|
||||
|
||||
@ -218,22 +217,22 @@ openclaw mcp serve --claude-channel-mode off
|
||||
|
||||
Важливі обмеження:
|
||||
|
||||
- черга є лише живою; вона починається, коли запускається міст MCP
|
||||
- черга лише жива; вона починається, коли запускається міст MCP
|
||||
- `events_poll` і `events_wait` самі по собі не відтворюють старішу історію Gateway
|
||||
- довговічне відставання слід читати через `messages_read`
|
||||
- стійкий backlog слід читати через `messages_read`
|
||||
|
||||
## Сповіщення каналу Claude
|
||||
|
||||
Міст також може відкривати сповіщення каналу, специфічні для Claude. Це
|
||||
еквівалент OpenClaw для адаптера каналу Claude Code: стандартні інструменти MCP
|
||||
залишаються доступними, але живі вхідні повідомлення також можуть надходити як
|
||||
специфічні для Claude MCP-сповіщення.
|
||||
специфічні для Claude сповіщення MCP.
|
||||
|
||||
Прапорці:
|
||||
|
||||
- `--claude-channel-mode off`: лише стандартні інструменти MCP
|
||||
- `--claude-channel-mode on`: увімкнути сповіщення каналу Claude
|
||||
- `--claude-channel-mode auto`: поточне типове значення; така сама поведінка моста, як у `on`
|
||||
- `--claude-channel-mode auto`: поточне значення за замовчуванням; така сама поведінка мосту, як у `on`
|
||||
|
||||
Коли режим каналу Claude увімкнено, сервер оголошує експериментальні
|
||||
можливості Claude і може надсилати:
|
||||
@ -241,22 +240,22 @@ openclaw mcp serve --claude-channel-mode off
|
||||
- `notifications/claude/channel`
|
||||
- `notifications/claude/channel/permission`
|
||||
|
||||
Поточна поведінка моста:
|
||||
Поточна поведінка мосту:
|
||||
|
||||
- вхідні повідомлення стенограми `user` пересилаються як
|
||||
- вхідні повідомлення transcript типу `user` пересилаються як
|
||||
`notifications/claude/channel`
|
||||
- запити на дозволи Claude, отримані через MCP, відстежуються в пам’яті
|
||||
- якщо пов’язана розмова пізніше надсилає `yes abcde` або `no abcde`, міст
|
||||
- запити на погодження Claude, отримані через MCP, відстежуються в пам’яті
|
||||
- якщо пізніше пов’язана розмова надішле `yes abcde` або `no abcde`, міст
|
||||
перетворює це на `notifications/claude/channel/permission`
|
||||
- ці сповіщення доступні лише в живій сесії; якщо клієнт MCP відключається,
|
||||
ціль для push більше не існує
|
||||
- ці сповіщення доступні лише в межах живого сеансу; якщо клієнт MCP
|
||||
від’єднається, цілі для push більше не буде
|
||||
|
||||
Це навмисно специфічно для клієнта. Загальні клієнти MCP мають покладатися на
|
||||
стандартні інструменти опитування.
|
||||
Це навмисно орієнтовано на конкретного клієнта. Звичайні клієнти MCP повинні
|
||||
покладатися на стандартні інструменти опитування.
|
||||
|
||||
## Конфігурація клієнта MCP
|
||||
|
||||
Приклад конфігурації stdio-клієнта:
|
||||
Приклад конфігурації клієнта stdio:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -276,8 +275,8 @@ openclaw mcp serve --claude-channel-mode off
|
||||
}
|
||||
```
|
||||
|
||||
Для більшості загальних клієнтів MCP починайте зі стандартної поверхні
|
||||
інструментів і ігноруйте режим Claude. Увімкніть режим Claude лише для
|
||||
Для більшості звичайних клієнтів MCP починайте зі стандартної поверхні
|
||||
інструментів та ігноруйте режим Claude. Увімкніть режим Claude лише для
|
||||
клієнтів, які справді розуміють методи сповіщень, специфічні для Claude.
|
||||
|
||||
## Параметри
|
||||
@ -295,27 +294,26 @@ openclaw mcp serve --claude-channel-mode off
|
||||
За можливості віддавайте перевагу `--token-file` або `--password-file` замість
|
||||
вбудованих секретів.
|
||||
|
||||
## Безпека та межа довіри
|
||||
## Межа безпеки й довіри
|
||||
|
||||
Міст не вигадує маршрутизацію. Він лише відкриває розмови, які Gateway уже
|
||||
вміє маршрутизувати.
|
||||
|
||||
Це означає:
|
||||
|
||||
- списки дозволених відправників, спарювання та довіра на рівні каналу як і раніше
|
||||
належать базовій конфігурації каналу OpenClaw
|
||||
- allowlist відправників, pairing і довіра на рівні каналу все ще належать
|
||||
до базової конфігурації каналу OpenClaw
|
||||
- `messages_send` може відповідати лише через наявний збережений маршрут
|
||||
- стан схвалення є лише живим/у пам’яті для поточної сесії моста
|
||||
- автентифікація моста має використовувати ті самі засоби контролю токена або пароля Gateway,
|
||||
- стан погодження є лише живим/в пам’яті для поточного сеансу мосту
|
||||
- автентифікація мосту має використовувати ті самі елементи контролю токена або пароля Gateway,
|
||||
яким ви б довіряли для будь-якого іншого віддаленого клієнта Gateway
|
||||
|
||||
Якщо розмова відсутня в `conversations_list`, типовою причиною є не
|
||||
конфігурація MCP. Це відсутні або неповні метадані маршруту в базовій
|
||||
сесії Gateway.
|
||||
конфігурація MCP. Це відсутні або неповні метадані маршруту в базовому сеансі Gateway.
|
||||
|
||||
## Тестування
|
||||
|
||||
OpenClaw постачає детермінований Docker smoke-тест для цього моста:
|
||||
OpenClaw постачається з детермінованим Docker smoke-тестом для цього мосту:
|
||||
|
||||
```bash
|
||||
pnpm test:docker:mcp-channels
|
||||
@ -323,72 +321,75 @@ pnpm test:docker:mcp-channels
|
||||
|
||||
Цей smoke-тест:
|
||||
|
||||
- запускає контейнер Gateway із підготовленими даними
|
||||
- запускає другий контейнер, який запускає `openclaw mcp serve`
|
||||
- перевіряє виявлення розмов, читання стенограм, читання метаданих вкладень,
|
||||
- запускає контейнер Gateway із попередньо підготовленими даними
|
||||
- запускає другий контейнер, який викликає `openclaw mcp serve`
|
||||
- перевіряє виявлення розмов, читання transcript, читання метаданих вкладень,
|
||||
поведінку черги живих подій і маршрутизацію вихідних надсилань
|
||||
- перевіряє сповіщення в стилі Claude для каналу та дозволів через реальний
|
||||
stdio MCP-міст
|
||||
- перевіряє сповіщення каналів і погоджень у стилі Claude через реальний
|
||||
міст stdio MCP
|
||||
|
||||
Це найшвидший спосіб довести, що міст працює, без підключення реального
|
||||
облікового запису Telegram, Discord або iMessage до тестового запуску.
|
||||
|
||||
Для ширшого контексту тестування див. [Testing](/uk/help/testing).
|
||||
Для ширшого контексту тестування дивіться [Testing](/uk/help/testing).
|
||||
|
||||
## Усунення несправностей
|
||||
## Усунення проблем
|
||||
|
||||
### Не повертаються розмови
|
||||
### Не повертаються жодні розмови
|
||||
|
||||
Зазвичай це означає, що сесія Gateway ще не придатна для маршрутизації.
|
||||
Підтвердьте, що базова сесія має збережені метадані маршруту каналу/провайдера,
|
||||
одержувача та необов’язкового облікового запису/треду.
|
||||
Зазвичай це означає, що сеанс Gateway ще не придатний для маршрутизації.
|
||||
Підтвердьте, що базовий сеанс має збережені channel/provider, отримувача та
|
||||
необов’язкові метадані маршруту account/thread.
|
||||
|
||||
### `events_poll` або `events_wait` пропускає старіші повідомлення
|
||||
|
||||
Це очікувано. Жива черга починається, коли міст підключається. Читайте старішу
|
||||
історію стенограми через `messages_read`.
|
||||
історію transcript через `messages_read`.
|
||||
|
||||
### Сповіщення Claude не з’являються
|
||||
|
||||
Перевірте все з наведеного:
|
||||
Перевірте все з цього списку:
|
||||
|
||||
- клієнт тримав stdio MCP-сесію відкритою
|
||||
- клієнт тримав сеанс stdio MCP відкритим
|
||||
- `--claude-channel-mode` має значення `on` або `auto`
|
||||
- клієнт справді розуміє методи сповіщень, специфічні для Claude
|
||||
- вхідне повідомлення сталося після підключення моста
|
||||
- вхідне повідомлення сталося після підключення мосту
|
||||
|
||||
### Відсутні схвалення
|
||||
### Відсутні погодження
|
||||
|
||||
`permissions_list_open` показує лише запити на схвалення, спостережені під час
|
||||
підключення моста. Це не API довговічної історії схвалень.
|
||||
`permissions_list_open` показує лише запити на погодження, спостережені, поки
|
||||
міст був підключений. Це не API стійкої історії погоджень.
|
||||
|
||||
## OpenClaw як реєстр MCP-клієнта
|
||||
## OpenClaw як реєстр клієнтів MCP
|
||||
|
||||
Це шлях `openclaw mcp list`, `show`, `set` і `unset`.
|
||||
|
||||
Ці команди не відкривають OpenClaw через MCP. Вони керують визначеннями
|
||||
MCP-серверів, що належать OpenClaw, у `mcp.servers` в конфігурації OpenClaw.
|
||||
Ці команди не відкривають OpenClaw через MCP. Вони керують визначеннями серверів MCP,
|
||||
якими володіє OpenClaw, у `mcp.servers` у конфігурації OpenClaw.
|
||||
|
||||
Ці збережені визначення призначені для середовищ виконання, які OpenClaw
|
||||
запускає або налаштовує пізніше, таких як вбудований Pi та інші адаптери
|
||||
середовища виконання. OpenClaw централізовано зберігає визначення, щоб цим
|
||||
середовищам виконання не доводилося тримати власні дублікати списків MCP-серверів.
|
||||
запускає або налаштовує пізніше, наприклад вбудований Pi та інші адаптери
|
||||
середовища виконання. OpenClaw зберігає визначення централізовано, щоб цим
|
||||
середовищам не потрібно було підтримувати власні дубльовані списки серверів MCP.
|
||||
|
||||
Важлива поведінка:
|
||||
|
||||
- ці команди лише читають або записують конфігурацію OpenClaw
|
||||
- вони не підключаються до цільового MCP-сервера
|
||||
- вони не підключаються до цільового сервера MCP
|
||||
- вони не перевіряють, чи команда, URL або віддалений транспорт
|
||||
доступні прямо зараз
|
||||
- адаптери середовища виконання вирішують, які форми транспорту вони фактично підтримують
|
||||
під час виконання
|
||||
- вбудований Pi відкриває налаштовані MCP-інструменти у звичайних профілях
|
||||
- адаптери середовища виконання самі вирішують, які форми транспорту вони
|
||||
фактично підтримують під час виконання
|
||||
- вбудований Pi відкриває налаштовані інструменти MCP у звичайних профілях
|
||||
інструментів `coding` і `messaging`; `minimal` усе ще приховує їх, а
|
||||
`tools.deny: ["bundle-mcp"]` явно вимикає їх
|
||||
- вбудовані середовища виконання MCP, прив’язані до сеансу, прибираються після
|
||||
`mcp.sessionIdleTtlMs` мілісекунд простою (типово 10 хвилин; встановіть `0`,
|
||||
щоб вимкнути), а одноразові вбудовані запуски очищають їх наприкінці виконання
|
||||
|
||||
## Збережені визначення MCP-серверів
|
||||
## Збережені визначення серверів MCP
|
||||
|
||||
OpenClaw також зберігає в конфігурації полегшений реєстр MCP-серверів для
|
||||
OpenClaw також зберігає в конфігурації легковажний реєстр серверів MCP для
|
||||
поверхонь, яким потрібні визначення MCP, керовані OpenClaw.
|
||||
|
||||
Команди:
|
||||
@ -400,10 +401,10 @@ OpenClaw також зберігає в конфігурації полегше
|
||||
|
||||
Примітки:
|
||||
|
||||
- `list` сортує назви серверів.
|
||||
- `show` без назви виводить повний налаштований об’єкт MCP-серверів.
|
||||
- `set` очікує одне значення об’єкта JSON у командному рядку.
|
||||
- `unset` завершується з помилкою, якщо іменований сервер не існує.
|
||||
- `list` сортує імена серверів.
|
||||
- `show` без імені виводить повний налаштований об’єкт сервера MCP.
|
||||
- `set` очікує одне значення JSON-об’єкта в командному рядку.
|
||||
- `unset` завершується помилкою, якщо сервера з вказаним іменем не існує.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -433,32 +434,32 @@ openclaw mcp unset context7
|
||||
}
|
||||
```
|
||||
|
||||
### Транспорт stdio
|
||||
### Транспорт Stdio
|
||||
|
||||
Запускає локальний дочірній процес і взаємодіє через stdin/stdout.
|
||||
Запускає локальний дочірній процес і спілкується через stdin/stdout.
|
||||
|
||||
| Field | Description |
|
||||
| -------------------------- | --------------------------------- |
|
||||
| Поле | Опис |
|
||||
| -------------------------- | ----------------------------------- |
|
||||
| `command` | Виконуваний файл для запуску (обов’язково) |
|
||||
| `args` | Масив аргументів командного рядка |
|
||||
| `env` | Додаткові змінні середовища |
|
||||
| `cwd` / `workingDirectory` | Робочий каталог для процесу |
|
||||
| `args` | Масив аргументів командного рядка |
|
||||
| `env` | Додаткові змінні середовища |
|
||||
| `cwd` / `workingDirectory` | Робочий каталог для процесу |
|
||||
|
||||
#### Фільтр безпеки env для stdio
|
||||
#### Фільтр безпеки env для Stdio
|
||||
|
||||
OpenClaw відхиляє ключі env запуску інтерпретатора, які можуть змінити спосіб запуску stdio MCP-сервера до першого RPC, навіть якщо вони присутні в блоці `env` сервера. Заблоковані ключі включають `NODE_OPTIONS`, `PYTHONSTARTUP`, `PYTHONPATH`, `PERL5OPT`, `RUBYOPT`, `SHELLOPTS`, `PS4` та подібні змінні керування середовищем виконання. Запуск відхиляє їх із помилкою конфігурації, щоб вони не могли впровадити неявну преамбулу, підмінити інтерпретатор або ввімкнути налагоджувач для stdio-процесу. Звичайні облікові дані, проксі та змінні середовища, специфічні для сервера (`GITHUB_TOKEN`, `HTTP_PROXY`, користувацькі `*_API_KEY` тощо), не зачіпаються.
|
||||
OpenClaw відхиляє ключі env запуску інтерпретатора, які можуть змінити спосіб запуску сервера stdio MCP до першого RPC, навіть якщо вони присутні в блоці `env` сервера. Заблоковані ключі включають `NODE_OPTIONS`, `PYTHONSTARTUP`, `PYTHONPATH`, `PERL5OPT`, `RUBYOPT`, `SHELLOPTS`, `PS4` та подібні змінні керування середовищем виконання. Запуск відхиляє їх з помилкою конфігурації, щоб вони не могли впровадити неявний пролог, підмінити інтерпретатор або ввімкнути налагоджувач для процесу stdio. Звичайні змінні середовища для облікових даних, proxy та специфічні для сервера (`GITHUB_TOKEN`, `HTTP_PROXY`, власні `*_API_KEY` тощо) не зачіпаються.
|
||||
|
||||
Якщо вашому MCP-серверу справді потрібна одна із заблокованих змінних, задайте її в процесі хоста Gateway, а не в `env` stdio-сервера.
|
||||
Якщо вашому серверу MCP справді потрібна одна із заблокованих змінних, задайте її в процесі хоста Gateway, а не в `env` сервера stdio.
|
||||
|
||||
### Транспорт SSE / HTTP
|
||||
|
||||
Підключається до віддаленого MCP-сервера через HTTP Server-Sent Events.
|
||||
Підключається до віддаленого сервера MCP через HTTP Server-Sent Events.
|
||||
|
||||
| Field | Description |
|
||||
| Поле | Опис |
|
||||
| --------------------- | ---------------------------------------------------------------- |
|
||||
| `url` | URL HTTP або HTTPS віддаленого сервера (обов’язково) |
|
||||
| `headers` | Необов’язкова карта ключ-значення HTTP-заголовків (наприклад, токени автентифікації) |
|
||||
| `connectionTimeoutMs` | Тайм-аут підключення для окремого сервера в мс (необов’язково) |
|
||||
| `headers` | Необов’язкова карта HTTP-заголовків ключ-значення (наприклад, токени автентифікації) |
|
||||
| `connectionTimeoutMs` | Тайм-аут підключення для сервера в мс (необов’язково) |
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -477,19 +478,19 @@ OpenClaw відхиляє ключі env запуску інтерпретато
|
||||
}
|
||||
```
|
||||
|
||||
Чутливі значення в `url` (userinfo) і `headers` маскуються в журналах і
|
||||
Чутливі значення в `url` (userinfo) і `headers` маскуються в журналах та
|
||||
виводі стану.
|
||||
|
||||
### Транспорт Streamable HTTP
|
||||
|
||||
`streamable-http` — це додатковий варіант транспорту поряд із `sse` і `stdio`. Він використовує HTTP-streaming для двостороннього зв’язку з віддаленими MCP-серверами.
|
||||
`streamable-http` — це додатковий варіант транспорту поряд із `sse` і `stdio`. Він використовує потоковий HTTP для двостороннього зв’язку з віддаленими серверами MCP.
|
||||
|
||||
| Field | Description |
|
||||
| --------------------- | -------------------------------------------------------------------------------------- |
|
||||
| `url` | URL HTTP або HTTPS віддаленого сервера (обов’язково) |
|
||||
| Поле | Опис |
|
||||
| --------------------- | ------------------------------------------------------------------------------------ |
|
||||
| `url` | URL HTTP або HTTPS віддаленого сервера (обов’язково) |
|
||||
| `transport` | Встановіть `"streamable-http"`, щоб вибрати цей транспорт; якщо не вказано, OpenClaw використовує `sse` |
|
||||
| `headers` | Необов’язкова карта ключ-значення HTTP-заголовків (наприклад, токени автентифікації) |
|
||||
| `connectionTimeoutMs` | Тайм-аут підключення для окремого сервера в мс (необов’язково) |
|
||||
| `headers` | Необов’язкова карта HTTP-заголовків ключ-значення (наприклад, токени автентифікації) |
|
||||
| `connectionTimeoutMs` | Тайм-аут підключення для сервера в мс (необов’язково) |
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -511,23 +512,23 @@ OpenClaw відхиляє ключі env запуску інтерпретато
|
||||
```
|
||||
|
||||
Ці команди керують лише збереженою конфігурацією. Вони не запускають міст
|
||||
каналу, не відкривають живу сесію MCP-клієнта і не доводять, що цільовий
|
||||
каналу, не відкривають живий сеанс клієнта MCP і не доводять, що цільовий
|
||||
сервер доступний.
|
||||
|
||||
## Поточні обмеження
|
||||
|
||||
Ця сторінка документує міст у тому вигляді, у якому він постачається сьогодні.
|
||||
Ця сторінка документує міст у тому вигляді, в якому він постачається сьогодні.
|
||||
|
||||
Поточні обмеження:
|
||||
|
||||
- виявлення розмов залежить від наявних метаданих маршруту сесії Gateway
|
||||
- виявлення розмов залежить від наявних метаданих маршруту сеансу Gateway
|
||||
- немає загального push-протоколу, окрім адаптера, специфічного для Claude
|
||||
- інструментів редагування повідомлень або реакцій поки немає
|
||||
- поки немає інструментів редагування повідомлень або react
|
||||
- транспорт HTTP/SSE/streamable-http підключається до одного віддаленого сервера; мультиплексованого upstream поки немає
|
||||
- `permissions_list_open` включає лише схвалення, спостережені, поки міст
|
||||
- `permissions_list_open` включає лише погодження, спостережені, поки міст був
|
||||
підключений
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Довідник CLI](/uk/cli)
|
||||
- [Plugins](/uk/cli/plugins)
|
||||
- [Довідка CLI](/uk/cli)
|
||||
- [Плагіни](/uk/cli/plugins)
|
||||
|
||||
@ -1,26 +1,26 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете змінити типові моделі або переглянути стан автентифікації провайдера
|
||||
- Ви хочете змінити моделі за замовчуванням або переглянути статус автентифікації провайдера
|
||||
- Ви хочете просканувати доступні моделі/провайдерів і налагодити профілі автентифікації
|
||||
summary: Довідка CLI для `openclaw models` (status/list/set/scan, псевдоніми, резервні варіанти, автентифікація)
|
||||
title: Моделі
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T03:15:35Z"
|
||||
generated_at: "2026-04-25T07:01:56Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 08e04342ef240bf7a1f60c4d4e2667d17c9a97e985c1b170db8538c890dc8119
|
||||
source_hash: 2755657b334b8722da06e31fa1d69a5dced3d74e5aeadd38d625039f15911d69
|
||||
source_path: cli/models.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# `openclaw models`
|
||||
|
||||
Виявлення моделей, сканування та конфігурація (типова модель, резервні варіанти, профілі автентифікації).
|
||||
Виявлення моделей, сканування та конфігурація (модель за замовчуванням, резервні варіанти, профілі автентифікації).
|
||||
|
||||
Пов’язане:
|
||||
|
||||
- Провайдери + моделі: [Моделі](/uk/providers/models)
|
||||
- Концепції вибору моделі + слеш-команда `/models`: [Концепція моделей](/uk/concepts/models)
|
||||
- Концепції вибору моделей + слеш-команда `/models`: [Концепція моделей](/uk/concepts/models)
|
||||
- Налаштування автентифікації провайдера: [Початок роботи](/uk/start/getting-started)
|
||||
|
||||
## Поширені команди
|
||||
@ -32,42 +32,46 @@ openclaw models set <model-or-alias>
|
||||
openclaw models scan
|
||||
```
|
||||
|
||||
`openclaw models status` показує визначені типові/резервні варіанти, а також огляд автентифікації.
|
||||
Коли доступні знімки використання провайдера, розділ стану OAuth/API key містить
|
||||
`openclaw models status` показує визначені модель за замовчуванням/резервні варіанти, а також огляд автентифікації.
|
||||
Коли доступні знімки використання провайдера, розділ статусу OAuth/API-ключів містить
|
||||
вікна використання провайдера та знімки квот.
|
||||
Поточні провайдери з вікнами використання: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
|
||||
Codex, MiniMax, Xiaomi і z.ai. Дані автентифікації використання надходять із хуків,
|
||||
специфічних для провайдера, коли вони доступні; інакше OpenClaw повертається до зіставлення облікових даних
|
||||
OAuth/API key з профілів автентифікації, середовища або конфігурації.
|
||||
У виводі `--json` `auth.providers` — це огляд провайдерів з урахуванням env/config/store,
|
||||
тоді як `auth.oauth` — це лише стан профілів сховища автентифікації.
|
||||
Codex, MiniMax, Xiaomi і z.ai. Автентифікація використання надходить із хуків,
|
||||
специфічних для провайдера, коли вони доступні; інакше OpenClaw використовує резервний варіант і підбирає OAuth/API-key
|
||||
облікові дані з профілів автентифікації, змінних середовища або конфігурації.
|
||||
У виводі `--json` `auth.providers` — це огляд провайдера з урахуванням env/config/store,
|
||||
тоді як `auth.oauth` — це лише стан профілів у сховищі автентифікації.
|
||||
Додайте `--probe`, щоб виконати живі перевірки автентифікації для кожного налаштованого профілю провайдера.
|
||||
Перевірки є реальними запитами (можуть споживати токени та спричиняти обмеження швидкості).
|
||||
Використовуйте `--agent <id>`, щоб перевірити стан моделі/автентифікації налаштованого агента. Якщо параметр не вказано,
|
||||
Перевірки є реальними запитами (можуть витрачати токени та спричиняти обмеження швидкості).
|
||||
Використовуйте `--agent <id>`, щоб перевірити стан моделі/автентифікації налаштованого агента. Якщо цей параметр не вказано,
|
||||
команда використовує `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`, якщо вони задані, інакше —
|
||||
налаштованого типового агента.
|
||||
Рядки перевірки можуть походити з профілів автентифікації, облікових даних середовища або `models.json`.
|
||||
налаштованого агента за замовчуванням.
|
||||
Рядки перевірок можуть надходити з профілів автентифікації, облікових даних середовища або `models.json`.
|
||||
|
||||
Примітки:
|
||||
|
||||
- `models set <model-or-alias>` приймає `provider/model` або псевдонім.
|
||||
- `models list` є лише для читання: вона читає конфігурацію, профілі автентифікації, наявний стан каталогу
|
||||
- `models list` є лише для читання: команда читає конфігурацію, профілі автентифікації, наявний стан каталогу
|
||||
та рядки каталогу, що належать провайдеру, але не перезаписує
|
||||
`models.json`.
|
||||
- `models list --all` включає вбудовані статичні рядки каталогу, що належать провайдеру, навіть
|
||||
якщо ви ще не пройшли автентифікацію в цього провайдера. Такі рядки все одно показуються
|
||||
якщо ви ще не автентифікувалися в цього провайдера. Такі рядки все одно показуються
|
||||
як недоступні, доки не буде налаштовано відповідну автентифікацію.
|
||||
- `models list` зберігає власні метадані моделі та обмеження середовища виконання окремо. У табличному
|
||||
виводі `Ctx` показує `contextTokens/contextWindow`, коли ефективне обмеження середовища виконання
|
||||
відрізняється від власного вікна контексту; рядки JSON містять `contextTokens`,
|
||||
якщо провайдер надає це обмеження.
|
||||
- `models list --provider <id>` фільтрує за ідентифікатором провайдера, наприклад `moonshot` або
|
||||
`openai-codex`. Він не приймає відображувані мітки з інтерактивних засобів вибору провайдера,
|
||||
`openai-codex`. Команда не приймає відображувані мітки з інтерактивних засобів вибору провайдера,
|
||||
такі як `Moonshot AI`.
|
||||
- Посилання на моделі розбираються розділенням за **першим** `/`. Якщо ідентифікатор моделі містить `/` (у стилі OpenRouter), додайте префікс провайдера (приклад: `openrouter/moonshotai/kimi-k2`).
|
||||
- Якщо ви пропускаєте провайдера, OpenClaw спочатку визначає введене значення як псевдонім, потім —
|
||||
як унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише після цього
|
||||
повертається до налаштованого типового провайдера з попередженням про застарілість.
|
||||
Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw
|
||||
повертається до першого налаштованого провайдера/моделі замість показу
|
||||
застарілого типового значення від видаленого провайдера.
|
||||
- `models status` може показувати `marker(<value>)` у виводі автентифікації для не секретних заповнювачів (наприклад `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) замість маскування їх як секретів.
|
||||
- Посилання на моделі розбираються шляхом поділу за **першим** `/`. Якщо ідентифікатор моделі містить `/` (у стилі OpenRouter), додайте префікс провайдера (приклад: `openrouter/moonshotai/kimi-k2`).
|
||||
- Якщо ви не вказали провайдера, OpenClaw спочатку визначає введення як псевдонім, потім —
|
||||
як унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише потім
|
||||
використовує резервний варіант — налаштованого провайдера за замовчуванням — із попередженням про застарілість.
|
||||
Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw
|
||||
використовує резервний варіант — перший налаштований провайдер/модель — замість показу
|
||||
застарілого значення за замовчуванням для видаленого провайдера.
|
||||
- `models status` може показувати `marker(<value>)` у виводі автентифікації для незасекречених заповнювачів (наприклад `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) замість маскування їх як секретів.
|
||||
|
||||
### `models status`
|
||||
|
||||
@ -84,7 +88,7 @@ OAuth/API key з профілів автентифікації, середови
|
||||
- `--probe-max-tokens <n>`
|
||||
- `--agent <id>` (ідентифікатор налаштованого агента; перевизначає `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
|
||||
|
||||
Категорії стану перевірки:
|
||||
Групи статусів перевірки:
|
||||
|
||||
- `ok`
|
||||
- `auth`
|
||||
@ -95,15 +99,15 @@ OAuth/API key з профілів автентифікації, середови
|
||||
- `unknown`
|
||||
- `no_model`
|
||||
|
||||
Випадки деталей/кодів причин перевірки, на які варто очікувати:
|
||||
Варіанти detail/reason-code перевірки, яких варто очікувати:
|
||||
|
||||
- `excluded_by_auth_order`: збережений профіль існує, але явний
|
||||
`auth.order.<provider>` його пропустив, тому перевірка повідомляє про виключення замість
|
||||
спроби його використати.
|
||||
- `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
|
||||
профіль присутній, але не підходить/не може бути визначений.
|
||||
- `no_model`: автентифікація провайдера існує, але OpenClaw не зміг визначити
|
||||
кандидата моделі для перевірки для цього провайдера.
|
||||
профіль присутній, але не є придатним/не може бути визначений.
|
||||
- `no_model`: автентифікація провайдера існує, але OpenClaw не зміг визначити придатний для перевірки
|
||||
кандидат моделі для цього провайдера.
|
||||
|
||||
## Псевдоніми + резервні варіанти
|
||||
|
||||
@ -123,9 +127,9 @@ openclaw models auth paste-token
|
||||
|
||||
`models auth add` — це інтерактивний помічник автентифікації. Він може запускати потік автентифікації провайдера
|
||||
(OAuth/API key) або провести вас через ручне вставлення токена, залежно від
|
||||
вибраного провайдера.
|
||||
обраного провайдера.
|
||||
|
||||
`models auth login` запускає потік автентифікації Plugin провайдера (OAuth/API key). Використовуйте
|
||||
`models auth login` запускає потік автентифікації плагіна провайдера (OAuth/API key). Використовуйте
|
||||
`openclaw plugins list`, щоб побачити, які провайдери встановлено.
|
||||
|
||||
Приклади:
|
||||
@ -136,21 +140,21 @@ openclaw models auth login --provider openai-codex --set-default
|
||||
|
||||
Примітки:
|
||||
|
||||
- `setup-token` і `paste-token` залишаються універсальними командами токенів для провайдерів,
|
||||
які надають методи автентифікації токеном.
|
||||
- `setup-token` вимагає інтерактивного TTY і запускає метод автентифікації токеном провайдера
|
||||
- `setup-token` і `paste-token` залишаються універсальними командами для роботи з токенами для провайдерів,
|
||||
які надають методи токен-автентифікації.
|
||||
- `setup-token` вимагає інтерактивного TTY і запускає метод токен-автентифікації провайдера
|
||||
(типово — метод `setup-token` цього провайдера, якщо він його надає).
|
||||
- `paste-token` приймає рядок токена, згенерований в іншому місці або автоматизацією.
|
||||
- `paste-token` вимагає `--provider`, запитує значення токена та записує
|
||||
його до типового ідентифікатора профілю `<provider>:manual`, якщо ви не передасте
|
||||
- `paste-token` приймає рядок токена, згенерований деінде або засобами автоматизації.
|
||||
- `paste-token` вимагає `--provider`, запитує значення токена й записує
|
||||
його до ідентифікатора профілю за замовчуванням `<provider>:manual`, якщо ви не передали
|
||||
`--profile-id`.
|
||||
- `paste-token --expires-in <duration>` зберігає абсолютний строк дії токена на основі
|
||||
відносної тривалості, наприклад `365d` або `12h`.
|
||||
- Примітка Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож OpenClaw вважає повторне використання Claude CLI та використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику.
|
||||
- `setup-token` / `paste-token` для Anthropic залишаються доступними як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI та `claude -p`, коли це доступно.
|
||||
- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI та використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику.
|
||||
- `setup-token` / `paste-token` Anthropic залишаються доступними як підтримуваний шлях роботи з токенами в OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI та `claude -p`, коли це можливо.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Довідка CLI](/uk/cli)
|
||||
- [Вибір моделі](/uk/concepts/model-providers)
|
||||
- [Перемикання моделей при відмові](/uk/concepts/model-failover)
|
||||
- [Відмовостійке перемикання моделей](/uk/concepts/model-failover)
|
||||
|
||||
@ -1,78 +1,79 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібен довідник із налаштування моделей для кожного provider окремо
|
||||
- Вам потрібні приклади конфігурацій або команд початкового налаштування CLI для provider-ів моделей
|
||||
summary: Огляд provider-ів моделей із прикладами конфігурацій і потоками CLI
|
||||
title: Provider-и моделей
|
||||
- Вам потрібен довідник із налаштування моделей для кожного постачальника окремо
|
||||
- Вам потрібні приклади конфігурацій або команди онбордингу CLI для постачальників моделей
|
||||
summary: Огляд постачальника моделі з прикладами конфігурацій + потоками CLI
|
||||
title: Постачальники моделей
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T05:55:45Z"
|
||||
generated_at: "2026-04-25T07:01:56Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: bdab460823e3138377a7e2b183b31caa64bb2eef4c9e77ebd8db0aacc97493bb
|
||||
source_hash: fe2871809711608b3e1d996084b834978b15f21dfeea1ac767dce4c1299be0aa
|
||||
source_path: concepts/model-providers.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Довідник для **provider-ів LLM/моделей** (а не каналів чату, як-от WhatsApp/Telegram). Правила вибору моделей див. у [Моделі](/uk/concepts/models).
|
||||
Довідник для **постачальників LLM/моделей** (а не чат-каналів на кшталт WhatsApp/Telegram). Правила вибору моделей див. у [Models](/uk/concepts/models).
|
||||
|
||||
## Швидкі правила
|
||||
|
||||
- Посилання на моделі використовують формат `provider/model` (приклад: `opencode/claude-opus-4-6`).
|
||||
- `agents.defaults.models` працює як allowlist, якщо його задано.
|
||||
- Helper-и CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
|
||||
- `agents.defaults.models` працює як список дозволених значень, якщо його задано.
|
||||
- Допоміжні команди CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
|
||||
- `models.providers.*.models[].contextWindow` — це нативні метадані моделі; `contextTokens` — це фактичне обмеження під час виконання.
|
||||
- Правила fallback, cooldown probes і збереження session-override: [Перемикання моделей при збоях](/uk/concepts/model-failover).
|
||||
- Маршрути родини OpenAI залежать від префікса: `openai/<model>` використовує прямий provider API key OpenAI у PI, `openai-codex/<model>` використовує Codex OAuth у PI, а `openai/<model>` плюс `agents.defaults.embeddedHarness.runtime: "codex"` використовує нативний harness app-server Codex. Див. [OpenAI](/uk/providers/openai) і [Codex harness](/uk/plugins/codex-harness). Якщо поділ між provider і runtime заплутує, спершу прочитайте [Середовища виконання агентів](/uk/concepts/agent-runtimes).
|
||||
- Автоувімкнення Plugin дотримується тієї самої межі: `openai-codex/<model>` належить Plugin OpenAI, тоді як Plugin Codex вмикається через `embeddedHarness.runtime: "codex"` або застарілі посилання `codex/<model>`.
|
||||
- Середовища CLI використовують той самий поділ: вибирайте канонічні посилання на моделі, як-от `anthropic/claude-*`, `google/gemini-*` або `openai/gpt-*`, а потім задавайте `agents.defaults.embeddedHarness.runtime` як `claude-cli`, `google-gemini-cli` або `codex-cli`, якщо хочете локальний backend CLI. Застарілі посилання `claude-cli/*`, `google-gemini-cli/*` і `codex-cli/*` мігрують назад до канонічних посилань provider, а runtime записується окремо.
|
||||
- GPT-5.5 зараз доступна через маршрути subscription/OAuth: `openai-codex/gpt-5.5` у PI або `openai/gpt-5.5` із harness app-server Codex. Прямий маршрут API key для `openai/gpt-5.5` підтримується, щойно OpenAI увімкне GPT-5.5 у публічному API; до того часу для конфігурацій `OPENAI_API_KEY` використовуйте моделі з доступним API, наприклад `openai/gpt-5.4`.
|
||||
- Правила резервного перемикання, перевірки після cooldown і збереження перевизначень сесії див.: [Model failover](/uk/concepts/model-failover).
|
||||
- Маршрути сімейства OpenAI залежать від префікса: `openai/<model>` використовує прямого постачальника API-ключа OpenAI у PI, `openai-codex/<model>` використовує OAuth Codex у PI, а `openai/<model>` разом із `agents.defaults.embeddedHarness.runtime: "codex"` використовує нативний app-server harness Codex. Див. [OpenAI](/uk/providers/openai) і [Codex harness](/uk/plugins/codex-harness). Якщо розділення між постачальником і runtime викликає плутанину, спочатку прочитайте [Agent runtimes](/uk/concepts/agent-runtimes).
|
||||
- Автоматичне ввімкнення Plugin дотримується тієї самої межі: `openai-codex/<model>` належить Plugin OpenAI, тоді як Plugin Codex вмикається через `embeddedHarness.runtime: "codex"` або застарілі посилання `codex/<model>`.
|
||||
- Runtime CLI використовують те саме розділення: вибирайте канонічні посилання на моделі, як-от `anthropic/claude-*`, `google/gemini-*` або `openai/gpt-*`, а потім задавайте `agents.defaults.embeddedHarness.runtime` як `claude-cli`, `google-gemini-cli` або `codex-cli`, якщо вам потрібен локальний бекенд CLI. Застарілі посилання `claude-cli/*`, `google-gemini-cli/*` і `codex-cli/*` мігрують назад до канонічних посилань постачальників, а runtime записується окремо.
|
||||
- GPT-5.5 доступна через `openai-codex/gpt-5.5` у PI, нативний app-server harness Codex і публічний API OpenAI, якщо вбудований каталог PI надає `openai/gpt-5.5` для вашої інсталяції.
|
||||
|
||||
## Поведінка provider-ів, що належить Plugin
|
||||
## Поведінка постачальників, якою керують Plugin
|
||||
|
||||
Більшість provider-специфічної логіки знаходиться в provider Plugin (`registerProvider(...)`), тоді як OpenClaw зберігає загальний цикл inference. Plugin-и відповідають за onboarding, каталоги моделей, зіставлення auth env-var, нормалізацію transport/config, очищення схем інструментів, класифікацію failover, оновлення OAuth, звітування про використання, профілі thinking/reasoning тощо.
|
||||
Більшість специфічної для постачальників логіки живе в Plugin постачальників (`registerProvider(...)`), тоді як OpenClaw зберігає загальний цикл inference. Plugin відповідають за онбординг, каталоги моделей, зіставлення env var для автентифікації, нормалізацію транспорту/конфігурації, очищення схем інструментів, класифікацію failover, оновлення OAuth, звітність про використання, профілі thinking/reasoning тощо.
|
||||
|
||||
Повний список хуків provider-SDK і прикладів bundled Plugin наведено в [Provider plugins](/uk/plugins/sdk-provider-plugins). Provider, якому потрібен повністю власний виконавець запитів, — це окрема, глибша поверхня розширення.
|
||||
Повний список хуків SDK постачальників і прикладів вбудованих Plugin наведено в [Provider plugins](/uk/plugins/sdk-provider-plugins). Постачальник, якому потрібен повністю кастомний виконавець запитів, використовує окрему, глибшу поверхню розширення.
|
||||
|
||||
<Note>
|
||||
`capabilities` runtime provider-а — це спільні метадані runner-а (родина provider-а, особливості transcript/tooling, підказки щодо transport/cache). Це не те саме, що [публічна модель capability](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє Plugin (text inference, speech тощо).
|
||||
`capabilities` runtime постачальника — це спільні метадані виконавця (сімейство постачальника, особливості transcript/tooling, підказки для transport/cache). Це не те саме, що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє Plugin (текстовий inference, мовлення тощо).
|
||||
</Note>
|
||||
|
||||
## Ротація API key
|
||||
## Ротація API-ключів
|
||||
|
||||
- Підтримується загальна ротація provider-ів для вибраних provider-ів.
|
||||
- Підтримується загальна ротація ключів постачальників для вибраних постачальників.
|
||||
- Налаштуйте кілька ключів через:
|
||||
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (один live override, найвищий пріоритет)
|
||||
- `OPENCLAW_LIVE_<PROVIDER>_KEY` (одне live-перевизначення, найвищий пріоритет)
|
||||
- `<PROVIDER>_API_KEYS` (список через кому або крапку з комою)
|
||||
- `<PROVIDER>_API_KEY` (основний ключ)
|
||||
- `<PROVIDER>_API_KEY_*` (нумерований список, наприклад `<PROVIDER>_API_KEY_1`)
|
||||
- Для provider-ів Google також використовується `GOOGLE_API_KEY` як fallback.
|
||||
- Для постачальників Google `GOOGLE_API_KEY` також включається як запасний варіант.
|
||||
- Порядок вибору ключів зберігає пріоритет і прибирає дублікати значень.
|
||||
- Запити повторюються з наступним ключем лише у відповідях rate-limit (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміти використання).
|
||||
- Збої, не пов’язані з rate-limit, одразу завершуються помилкою; ротація ключів не виконується.
|
||||
- Коли всі можливі ключі зазнають невдачі, повертається фінальна помилка з останньої спроби.
|
||||
- Запити повторюються з наступним ключем лише у відповідь на rate-limit помилки (наприклад, `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання).
|
||||
- Помилки, не пов’язані з rate-limit, одразу завершуються невдачею; ротація ключів не виконується.
|
||||
- Коли всі можливі ключі завершуються невдачею, повертається остання помилка з останньої спроби.
|
||||
|
||||
## Вбудовані provider-и (каталог pi-ai)
|
||||
## Вбудовані постачальники (каталог pi-ai)
|
||||
|
||||
OpenClaw постачається з каталогом pi‑ai. Для цих provider-ів **не потрібна** конфігурація `models.providers`; достатньо задати auth і вибрати модель.
|
||||
OpenClaw постачається з каталогом pi‑ai. Для цих постачальників **не потрібна**
|
||||
конфігурація `models.providers`; просто задайте автентифікацію й виберіть модель.
|
||||
|
||||
### OpenAI
|
||||
|
||||
- Provider: `openai`
|
||||
- Auth: `OPENAI_API_KEY`
|
||||
- Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (один override)
|
||||
- Приклади моделей: `openai/gpt-5.4`, `openai/gpt-5.4-mini`
|
||||
- Пряма підтримка GPT-5.5 через API тут буде готова в майбутньому, щойно OpenAI відкриє GPT-5.5 у API
|
||||
- Перевіряйте доступність прямого API через `openclaw models list --provider openai` перед використанням `openai/gpt-5.5` без runtime app-server Codex
|
||||
- Постачальник: `openai`
|
||||
- Автентифікація: `OPENAI_API_KEY`
|
||||
- Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення)
|
||||
- Приклади моделей: `openai/gpt-5.5`, `openai/gpt-5.4`, `openai/gpt-5.4-mini`
|
||||
- Підтримка прямого API для GPT-5.5 залежить від версії вбудованого каталогу PI у вашій інсталяції; перед використанням `openai/gpt-5.5` без runtime app-server Codex перевірте через `openclaw models list --provider openai`
|
||||
- CLI: `openclaw onboard --auth-choice openai-api-key`
|
||||
- Стандартний transport — `auto` (спочатку WebSocket, fallback на SSE)
|
||||
- Перевизначення для конкретної моделі через `agents.defaults.models["openai/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- Прогрівання OpenAI Responses WebSocket за замовчуванням увімкнене через `params.openaiWsWarmup` (`true`/`false`)
|
||||
- Типовий transport — `auto` (спочатку WebSocket, потім SSE)
|
||||
- Перевизначення для окремої моделі через `agents.defaults.models["openai/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- Warm-up OpenAI Responses WebSocket типово ввімкнено через `params.openaiWsWarmup` (`true`/`false`)
|
||||
- Пріоритетну обробку OpenAI можна ввімкнути через `agents.defaults.models["openai/<model>"].params.serviceTier`
|
||||
- `/fast` і `params.fastMode` зіставляють прямі запити Responses `openai/*` з `service_tier=priority` на `api.openai.com`
|
||||
- Використовуйте `params.serviceTier`, якщо вам потрібен явний tier замість спільного перемикача `/fast`
|
||||
- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не до загальних OpenAI-сумісних proxy
|
||||
- Нативні маршрути OpenAI також зберігають `store` Responses, підказки prompt-cache і формування payload для сумісності reasoning OpenAI; proxy-маршрути цього не роблять
|
||||
- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, тому що live-запити OpenAI API його відхиляють, а поточний каталог Codex його не надає
|
||||
- `/fast` і `params.fastMode` зіставляють прямі запити Responses `openai/*` із `service_tier=priority` на `api.openai.com`
|
||||
- Використовуйте `params.serviceTier`, якщо вам потрібен явний рівень замість спільного перемикача `/fast`
|
||||
- Приховані заголовки атрибуції OpenClaw (`originator`, `version`,
|
||||
`User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не до загальних OpenAI-сумісних проксі
|
||||
- Нативні маршрути OpenAI також зберігають `store` Responses, підказки кешу prompt і формування payload для сумісності reasoning OpenAI; проксі-маршрути — ні
|
||||
- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, оскільки live-запити до API OpenAI його відхиляють, а поточний каталог Codex його не показує
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -82,14 +83,14 @@ OpenClaw постачається з каталогом pi‑ai. Для цих p
|
||||
|
||||
### Anthropic
|
||||
|
||||
- Provider: `anthropic`
|
||||
- Auth: `ANTHROPIC_API_KEY`
|
||||
- Необов’язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (один override)
|
||||
- Постачальник: `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`, зокрема трафік з автентифікацією API key і 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`, коли це можливо.
|
||||
- Прямі публічні запити 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
|
||||
{
|
||||
@ -99,22 +100,24 @@ OpenClaw постачається з каталогом pi‑ai. Для цих p
|
||||
|
||||
### OpenAI Codex OAuth
|
||||
|
||||
- Provider: `openai-codex`
|
||||
- Auth: OAuth (ChatGPT)
|
||||
- Постачальник: `openai-codex`
|
||||
- Автентифікація: OAuth (ChatGPT)
|
||||
- Посилання на модель PI: `openai-codex/gpt-5.5`
|
||||
- Посилання для нативного harness app-server Codex: `openai/gpt-5.5` із `agents.defaults.embeddedHarness.runtime: "codex"`
|
||||
- Документація для нативного harness app-server Codex: [Codex harness](/uk/plugins/codex-harness)
|
||||
- Посилання нативного app-server harness Codex: `openai/gpt-5.5` з `agents.defaults.embeddedHarness.runtime: "codex"`
|
||||
- Документація нативного app-server harness Codex: [Codex harness](/uk/plugins/codex-harness)
|
||||
- Застарілі посилання на моделі: `codex/gpt-*`
|
||||
- Межа Plugin: `openai-codex/*` завантажує Plugin OpenAI; нативний Plugin app-server Codex вибирається лише через runtime Codex harness або застарілі посилання `codex/*`.
|
||||
- Межа Plugin: `openai-codex/*` завантажує Plugin OpenAI; нативний Plugin app-server Codex вибирається лише runtime Codex harness або застарілими посиланнями `codex/*`.
|
||||
- CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex`
|
||||
- Стандартний transport — `auto` (спочатку WebSocket, fallback на SSE)
|
||||
- Перевизначення для конкретної моделі PI через `agents.defaults.models["openai-codex/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- Типовий transport — `auto` (спочатку WebSocket, потім SSE)
|
||||
- Перевизначення для окремої моделі PI через `agents.defaults.models["openai-codex/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- `params.serviceTier` також передається в нативних запитах Codex Responses (`chatgpt.com/backend-api`)
|
||||
- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) додаються лише до нативного трафіку Codex на `chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних proxy
|
||||
- Використовує той самий спільний перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority`
|
||||
- `openai-codex/gpt-5.5` зберігає нативні `contextWindow = 1000000` і стандартні runtime `contextTokens = 272000`; перевизначайте обмеження runtime через `models.providers.openai-codex.models[].contextTokens`
|
||||
- Примітка щодо політики: OpenAI Codex OAuth офіційно підтримується для зовнішніх інструментів/workflow, таких як OpenClaw.
|
||||
- Поточний доступ до GPT-5.5 використовує цей маршрут OAuth/subscription, доки OpenAI не ввімкне GPT-5.5 у публічному API.
|
||||
- Приховані заголовки атрибуції OpenClaw (`originator`, `version`,
|
||||
`User-Agent`) додаються лише до нативного трафіку Codex на
|
||||
`chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних проксі
|
||||
- Використовує той самий перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority`
|
||||
- `openai-codex/gpt-5.5` використовує нативні значення каталогу Codex `contextWindow = 400000` і типове runtime `contextTokens = 272000`; перевизначте runtime-ліміт через `models.providers.openai-codex.models[].contextTokens`
|
||||
- Примітка щодо політики: OpenAI Codex OAuth явно підтримується для зовнішніх інструментів/процесів на кшталт OpenClaw.
|
||||
- Використовуйте `openai-codex/gpt-5.5`, якщо вам потрібен маршрут Codex OAuth/підписки; використовуйте `openai/gpt-5.5`, якщо ваше налаштування API-ключа і локальний каталог показують маршрут публічного API.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -134,17 +137,17 @@ OpenClaw постачається з каталогом pi‑ai. Для цих p
|
||||
}
|
||||
```
|
||||
|
||||
### Інші розміщені варіанти в стилі subscription
|
||||
### Інші хостовані варіанти в стилі підписки
|
||||
|
||||
- [Qwen Cloud](/uk/providers/qwen): поверхня provider-а Qwen Cloud плюс зіставлення endpoint-ів Alibaba DashScope і Coding Plan
|
||||
- [MiniMax](/uk/providers/minimax): доступ до MiniMax Coding Plan через OAuth або API key
|
||||
- [GLM models](/uk/providers/glm): endpoint-и Z.AI Coding Plan або загального API
|
||||
- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud, а також зіставлення кінцевих точок Alibaba DashScope і Coding Plan
|
||||
- [MiniMax](/uk/providers/minimax): OAuth MiniMax Coding Plan або доступ за API-ключем
|
||||
- [GLM models](/uk/providers/glm): кінцеві точки Z.AI Coding Plan або загального API
|
||||
|
||||
### OpenCode
|
||||
|
||||
- Auth: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`)
|
||||
- Provider runtime Zen: `opencode`
|
||||
- Provider runtime Go: `opencode-go`
|
||||
- Автентифікація: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`)
|
||||
- Постачальник runtime Zen: `opencode`
|
||||
- Постачальник runtime Go: `opencode-go`
|
||||
- Приклади моделей: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.6`
|
||||
- CLI: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`
|
||||
|
||||
@ -154,68 +157,70 @@ OpenClaw постачається з каталогом pi‑ai. Для цих p
|
||||
}
|
||||
```
|
||||
|
||||
### Google Gemini (API key)
|
||||
### Google Gemini (API-ключ)
|
||||
|
||||
- Provider: `google`
|
||||
- Auth: `GEMINI_API_KEY`
|
||||
- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (один override)
|
||||
- Постачальник: `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`
|
||||
- CLI: `openclaw onboard --auth-choice gemini-api-key`
|
||||
- Thinking: `/think adaptive` використовує динамічне thinking Google. Gemini 3/3.1 не мають фіксованого `thinkingLevel`; Gemini 2.5 надсилає `thinkingBudget: -1`.
|
||||
- Прямі запуски Gemini також приймають `agents.defaults.models["google/<model>"].params.cachedContent` (або застаріле `cached_content`) для передавання нативного дескриптора provider-а `cachedContents/...`; cache hit-и Gemini відображаються як OpenClaw `cacheRead`
|
||||
- Thinking: `/think adaptive` використовує динамічний thinking Google. Gemini 3/3.1 не надсилають фіксований
|
||||
`thinkingLevel`; Gemini 2.5 надсилає `thinkingBudget: -1`.
|
||||
- Прямі запуски Gemini також приймають `agents.defaults.models["google/<model>"].params.cachedContent`
|
||||
(або застарілий `cached_content`) для передавання нативного дескриптора постачальника
|
||||
`cachedContents/...`; збіги кешу Gemini відображаються як OpenClaw `cacheRead`
|
||||
|
||||
### Google Vertex і Gemini CLI
|
||||
|
||||
- Provider-и: `google-vertex`, `google-gemini-cli`
|
||||
- Auth: Vertex використовує gcloud ADC; Gemini CLI використовує власний потік OAuth
|
||||
- Застереження: Gemini CLI OAuth в OpenClaw — неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Перегляньте умови Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити.
|
||||
- Gemini CLI OAuth постачається як частина bundled Plugin `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`
|
||||
- Примітка: вам **не потрібно** вставляти client id або secret у `openclaw.json`. Потік входу CLI зберігає токени в auth profiles на host Gateway.
|
||||
- Якщо після входу запити не працюють, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на host Gateway.
|
||||
- JSON-відповіді Gemini CLI розбираються з `response`; дані про використання беруться з fallback на `stats`, де `stats.cached` нормалізується до OpenClaw `cacheRead`.
|
||||
- Увімкнення: `openclaw plugins enable google`
|
||||
- Вхід: `openclaw models auth login --provider google-gemini-cli --set-default`
|
||||
- Типова модель: `google-gemini-cli/gemini-3-flash-preview`
|
||||
- Примітка: вам **не потрібно** вставляти client id або secret у `openclaw.json`. Потік входу CLI зберігає токени в профілях автентифікації на хості Gateway.
|
||||
- Якщо після входу запити завершуються помилкою, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості Gateway.
|
||||
- JSON-відповіді Gemini CLI розбираються з `response`; використання за замовчуванням береться з `stats`, а `stats.cached` нормалізується до OpenClaw `cacheRead`.
|
||||
|
||||
### Z.AI (GLM)
|
||||
|
||||
- Provider: `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` примусово вибирають конкретну поверхню
|
||||
- Псевдоніми: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*`
|
||||
- `zai-api-key` автоматично визначає відповідну кінцеву точку Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово вибирають конкретну поверхню
|
||||
|
||||
### Vercel AI Gateway
|
||||
|
||||
- Provider: `vercel-ai-gateway`
|
||||
- Auth: `AI_GATEWAY_API_KEY`
|
||||
- Постачальник: `vercel-ai-gateway`
|
||||
- Автентифікація: `AI_GATEWAY_API_KEY`
|
||||
- Приклади моделей: `vercel-ai-gateway/anthropic/claude-opus-4.6`,
|
||||
`vercel-ai-gateway/moonshotai/kimi-k2.6`
|
||||
- CLI: `openclaw onboard --auth-choice ai-gateway-api-key`
|
||||
|
||||
### Kilo Gateway
|
||||
|
||||
- Provider: `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/`
|
||||
- Статичний fallback-каталог постачається з `kilocode/kilo/auto`; live
|
||||
виявлення через `https://api.kilo.ai/api/gateway/models` може додатково
|
||||
розширити каталог runtime.
|
||||
- Точна маршрутизація upstream за `kilocode/kilo/auto` належить Kilo Gateway,
|
||||
- Базовий URL: `https://api.kilo.ai/api/gateway/`
|
||||
- Статичний запасний каталог постачається з `kilocode/kilo/auto`; live-виявлення через
|
||||
`https://api.kilo.ai/api/gateway/models` може додатково розширити runtime-каталог.
|
||||
- Точна маршрутизація вгору за потоком для `kilocode/kilo/auto` належить Kilo Gateway,
|
||||
а не жорстко закодована в OpenClaw.
|
||||
|
||||
Деталі налаштування див. у [/providers/kilocode](/uk/providers/kilocode).
|
||||
Докладні відомості про налаштування див. у [/providers/kilocode](/uk/providers/kilocode).
|
||||
|
||||
### Інші bundled provider Plugin
|
||||
### Інші вбудовані Plugin постачальників
|
||||
|
||||
| Provider | Id | Auth env | Приклад моделі |
|
||||
| Постачальник | Id | Auth env | Приклад моделі |
|
||||
| ----------------------- | -------------------------------- | ------------------------------------------------------------ | ---------------------------------------------- |
|
||||
| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |
|
||||
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` |
|
||||
@ -241,30 +246,31 @@ OpenClaw постачається з каталогом pi‑ai. Для цих p
|
||||
| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` |
|
||||
| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` |
|
||||
|
||||
Особливості, які варто знати:
|
||||
Варто знати такі особливості:
|
||||
|
||||
- **OpenRouter** застосовує свої заголовки атрибуції застосунку й маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Посилання DeepSeek, Moonshot і ZAI придатні для cache-TTL у prompt caching під керуванням OpenRouter, але не отримують маркери кешу Anthropic. Як proxy-стиль OpenAI-сумісного шляху, він пропускає формування, доступне лише для нативного OpenAI (`serviceTier`, `store` у Responses, підказки prompt-cache, сумісність reasoning OpenAI). Посилання на базі Gemini зберігають лише санітизацію thought-signature для proxy-Gemini.
|
||||
- **Kilo Gateway** для посилань на базі Gemini дотримується того самого шляху санітизації proxy-Gemini; `kilocode/kilo/auto` та інші посилання, що не підтримують proxy reasoning, пропускають ін’єкцію proxy reasoning.
|
||||
- **MiniMax** onboarding через API key записує явні текстові визначення chat-моделей M2.7; розуміння зображень залишається в media provider `MiniMax-VL-01`, що належить Plugin.
|
||||
- **xAI** використовує шлях xAI Responses. `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast`. `tool_stream` увімкнено за замовчуванням; вимкніть через `agents.defaults.models["xai/<model>"].params.tool_stream=false`.
|
||||
- **Cerebras** моделі GLM використовують `zai-glm-4.7` / `zai-glm-4.6`; OpenAI-сумісний Base URL — `https://api.cerebras.ai/v1`.
|
||||
- **OpenRouter** застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Посилання DeepSeek, Moonshot і ZAI підтримують TTL кешу для керованого OpenRouter кешування prompt, але не отримують маркери кешу Anthropic. Як проксі-шлях у стилі OpenAI-compatible, він пропускає формування, притаманне лише нативному OpenAI (`serviceTier`, `store` Responses, підказки кешу prompt, сумісність reasoning OpenAI). Посилання на базі Gemini зберігають лише санітизацію сигнатури думок proxy-Gemini.
|
||||
- **Kilo Gateway** для посилань на базі Gemini дотримується того самого шляху санітизації proxy-Gemini; `kilocode/kilo/auto` та інші посилання, де reasoning через proxy не підтримується, пропускають ін’єкцію reasoning через proxy.
|
||||
- **MiniMax** онбординг через API-ключ записує явні текстові визначення моделей чату M2.7; розпізнавання зображень залишається на медіа-постачальнику `MiniMax-VL-01`, яким керує Plugin.
|
||||
- **xAI** використовує шлях xAI Responses. `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast`. `tool_stream` типово ввімкнено; вимкніть через `agents.defaults.models["xai/<model>"].params.tool_stream=false`.
|
||||
- **Cerebras** моделі GLM використовують `zai-glm-4.7` / `zai-glm-4.6`; базовий URL у форматі OpenAI-compatible: `https://api.cerebras.ai/v1`.
|
||||
|
||||
## Provider-и через `models.providers` (custom/Base URL)
|
||||
## Постачальники через `models.providers` (custom/base URL)
|
||||
|
||||
Використовуйте `models.providers` (або `models.json`), щоб додавати **custom** provider-и або OpenAI/Anthropic‑сумісні proxy.
|
||||
Використовуйте `models.providers` (або `models.json`) для додавання **власних** постачальників або
|
||||
OpenAI/Anthropic‑compatible проксі.
|
||||
|
||||
Багато з bundled provider Plugin нижче вже публікують стандартний каталог.
|
||||
Багато вбудованих нижче Plugin постачальників уже публікують типовий каталог.
|
||||
Використовуйте явні записи `models.providers.<id>` лише тоді, коли хочете перевизначити
|
||||
стандартний base URL, headers або список моделей.
|
||||
типовий base URL, заголовки або список моделей.
|
||||
|
||||
### Moonshot AI (Kimi)
|
||||
|
||||
Moonshot постачається як bundled provider Plugin. Використовуйте вбудований provider
|
||||
за замовчуванням і додавайте явний запис `models.providers.moonshot` лише тоді, коли
|
||||
Moonshot постачається як вбудований Plugin постачальника. Типово використовуйте
|
||||
вбудованого постачальника, а явний запис `models.providers.moonshot` додавайте лише тоді, коли
|
||||
потрібно перевизначити base URL або метадані моделі:
|
||||
|
||||
- Provider: `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`
|
||||
|
||||
@ -301,10 +307,10 @@ Id моделей Kimi K2:
|
||||
|
||||
### Kimi Coding
|
||||
|
||||
Kimi Coding використовує Anthropic-сумісний endpoint Moonshot AI:
|
||||
Kimi Coding використовує Anthropic-compatible кінцеву точку Moonshot AI:
|
||||
|
||||
- Provider: `kimi`
|
||||
- Auth: `KIMI_API_KEY`
|
||||
- Постачальник: `kimi`
|
||||
- Автентифікація: `KIMI_API_KEY`
|
||||
- Приклад моделі: `kimi/kimi-code`
|
||||
|
||||
```json5
|
||||
@ -316,14 +322,14 @@ Kimi Coding використовує Anthropic-сумісний endpoint Moonsho
|
||||
}
|
||||
```
|
||||
|
||||
Застарілий `kimi/k2p5` і далі приймається як сумісний id моделі.
|
||||
Застарілий `kimi/k2p5` і далі приймається як id моделі для сумісності.
|
||||
|
||||
### Volcano Engine (Doubao)
|
||||
|
||||
Volcano Engine (火山引擎) надає доступ до Doubao та інших моделей у Китаї.
|
||||
|
||||
- Provider: `volcengine` (для кодування: `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`
|
||||
|
||||
@ -335,9 +341,13 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши
|
||||
}
|
||||
```
|
||||
|
||||
Початкове налаштування за замовчуванням використовує поверхню кодування, але загальний каталог `volcengine/*` реєструється одночасно.
|
||||
Онбординг типово використовує coding-поверхню, але загальний каталог `volcengine/*`
|
||||
реєструється одночасно.
|
||||
|
||||
У вибирачах моделей onboarding/configure для варіанта auth Volcengine пріоритет надається рядкам `volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажені, OpenClaw повертається до нефільтрованого каталогу замість показу порожнього вибирача в межах provider-а.
|
||||
У засобах вибору моделей onboarding/configure для варіанта автентифікації Volcengine пріоритет надається і рядкам
|
||||
`volcengine/*`, і `volcengine-plan/*`. Якщо ці моделі ще не завантажені,
|
||||
OpenClaw повертається до нефільтрованого каталогу, замість того щоб показувати порожній
|
||||
picker з областю постачальника.
|
||||
|
||||
Доступні моделі:
|
||||
|
||||
@ -347,7 +357,7 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши
|
||||
- `volcengine/glm-4-7-251222` (GLM 4.7)
|
||||
- `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K)
|
||||
|
||||
Моделі кодування (`volcengine-plan`):
|
||||
Coding-моделі (`volcengine-plan`):
|
||||
|
||||
- `volcengine-plan/ark-code-latest`
|
||||
- `volcengine-plan/doubao-seed-code`
|
||||
@ -355,12 +365,12 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши
|
||||
- `volcengine-plan/kimi-k2-thinking`
|
||||
- `volcengine-plan/glm-4.7`
|
||||
|
||||
### BytePlus (міжнародний)
|
||||
### BytePlus (International)
|
||||
|
||||
BytePlus ARK надає доступ до тих самих моделей, що й Volcano Engine, для міжнародних користувачів.
|
||||
BytePlus ARK надає міжнародним користувачам доступ до тих самих моделей, що й Volcano Engine.
|
||||
|
||||
- Provider: `byteplus` (для кодування: `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`
|
||||
|
||||
@ -372,9 +382,13 @@ BytePlus ARK надає доступ до тих самих моделей, що
|
||||
}
|
||||
```
|
||||
|
||||
Початкове налаштування за замовчуванням використовує поверхню кодування, але загальний каталог `byteplus/*` реєструється одночасно.
|
||||
Онбординг типово використовує coding-поверхню, але загальний каталог `byteplus/*`
|
||||
реєструється одночасно.
|
||||
|
||||
У вибирачах моделей onboarding/configure для варіанта auth BytePlus пріоритет надається рядкам `byteplus/*` і `byteplus-plan/*`. Якщо ці моделі ще не завантажені, OpenClaw повертається до нефільтрованого каталогу замість показу порожнього вибирача в межах provider-а.
|
||||
У засобах вибору моделей onboarding/configure для варіанта автентифікації BytePlus пріоритет надається і рядкам
|
||||
`byteplus/*`, і `byteplus-plan/*`. Якщо ці моделі ще не завантажені,
|
||||
OpenClaw повертається до нефільтрованого каталогу, замість того щоб показувати порожній
|
||||
picker з областю постачальника.
|
||||
|
||||
Доступні моделі:
|
||||
|
||||
@ -382,7 +396,7 @@ BytePlus ARK надає доступ до тих самих моделей, що
|
||||
- `byteplus/kimi-k2-5-260127` (Kimi K2.5)
|
||||
- `byteplus/glm-4-7-251222` (GLM 4.7)
|
||||
|
||||
Моделі кодування (`byteplus-plan`):
|
||||
Coding-моделі (`byteplus-plan`):
|
||||
|
||||
- `byteplus-plan/ark-code-latest`
|
||||
- `byteplus-plan/doubao-seed-code`
|
||||
@ -392,10 +406,10 @@ BytePlus ARK надає доступ до тих самих моделей, що
|
||||
|
||||
### Synthetic
|
||||
|
||||
Synthetic надає Anthropic-сумісні моделі через provider `synthetic`:
|
||||
Synthetic надає Anthropic-compatible моделі через постачальника `synthetic`:
|
||||
|
||||
- Provider: `synthetic`
|
||||
- Auth: `SYNTHETIC_API_KEY`
|
||||
- Постачальник: `synthetic`
|
||||
- Автентифікація: `SYNTHETIC_API_KEY`
|
||||
- Приклад моделі: `synthetic/hf:MiniMaxAI/MiniMax-M2.5`
|
||||
- CLI: `openclaw onboard --auth-choice synthetic-api-key`
|
||||
|
||||
@ -420,35 +434,37 @@ Synthetic надає Anthropic-сумісні моделі через provider `
|
||||
|
||||
### MiniMax
|
||||
|
||||
MiniMax налаштовується через `models.providers`, оскільки використовує custom endpoint-и:
|
||||
MiniMax налаштовується через `models.providers`, оскільки використовує власні кінцеві точки:
|
||||
|
||||
- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth`
|
||||
- MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth`
|
||||
- MiniMax API key (Global): `--auth-choice minimax-global-api`
|
||||
- MiniMax API key (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-сумісному streaming-шляху MiniMax OpenClaw за замовчуванням вимикає thinking, якщо ви явно його не задасте, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`.
|
||||
На Anthropic-compatible шляху потокової передачі MiniMax OpenClaw типово вимикає thinking,
|
||||
якщо ви не задали його явно, а `/fast on` переписує
|
||||
`MiniMax-M2.7` на `MiniMax-M2.7-highspeed`.
|
||||
|
||||
Поділ capability, що належить Plugin:
|
||||
Розділення можливостей, яким керує Plugin:
|
||||
|
||||
- Стандартні text/chat залишаються на `minimax/MiniMax-M2.7`
|
||||
- Типові значення text/chat залишаються на `minimax/MiniMax-M2.7`
|
||||
- Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01`
|
||||
- Розуміння зображень — це `MiniMax-VL-01`, що належить Plugin, для обох шляхів auth MiniMax
|
||||
- Вебпошук залишається на id provider-а `minimax`
|
||||
- Розпізнавання зображень — це `MiniMax-VL-01`, яким на обох шляхах автентифікації MiniMax керує Plugin
|
||||
- Вебпошук залишається на id постачальника `minimax`
|
||||
|
||||
### LM Studio
|
||||
|
||||
LM Studio постачається як bundled provider Plugin, який використовує нативний API:
|
||||
LM Studio постачається як вбудований Plugin постачальника, який використовує нативний API:
|
||||
|
||||
- Provider: `lmstudio`
|
||||
- Auth: `LM_API_TOKEN`
|
||||
- Стандартний base URL для inference: `http://localhost:1234/v1`
|
||||
- Постачальник: `lmstudio`
|
||||
- Автентифікація: `LM_API_TOKEN`
|
||||
- Типовий базовий URL inference: `http://localhost:1234/v1`
|
||||
|
||||
Потім задайте модель (замініть на один з id, які повертає `http://localhost:1234/api/v1/models`):
|
||||
Потім задайте модель (замініть на один з id, повернених `http://localhost:1234/api/v1/models`):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -458,20 +474,21 @@ LM Studio постачається як bundled provider Plugin, який вик
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw використовує нативні `LM Studio` `/api/v1/models` і `/api/v1/models/load` для виявлення й auto-load, а `/v1/chat/completions` — для inference за замовчуванням.
|
||||
Деталі налаштування й усунення несправностей див. у [/providers/lmstudio](/uk/providers/lmstudio).
|
||||
OpenClaw використовує нативні `LM Studio` `/api/v1/models` і `/api/v1/models/load`
|
||||
для виявлення та авто-завантаження, а `/v1/chat/completions` — для inference за замовчуванням.
|
||||
Відомості про налаштування й усунення несправностей див. у [/providers/lmstudio](/uk/providers/lmstudio).
|
||||
|
||||
### Ollama
|
||||
|
||||
Ollama постачається як bundled provider Plugin і використовує нативний API Ollama:
|
||||
Ollama постачається як вбудований Plugin постачальника й використовує нативний API Ollama:
|
||||
|
||||
- Provider: `ollama`
|
||||
- Auth: не потрібна (локальний сервер)
|
||||
- Постачальник: `ollama`
|
||||
- Автентифікація: не потрібна (локальний сервер)
|
||||
- Приклад моделі: `ollama/llama3.3`
|
||||
- Встановлення: [https://ollama.com/download](https://ollama.com/download)
|
||||
|
||||
```bash
|
||||
# Встановіть Ollama, потім завантажте модель:
|
||||
# Install Ollama, then pull a model:
|
||||
ollama pull llama3.3
|
||||
```
|
||||
|
||||
@ -483,27 +500,26 @@ ollama pull llama3.3
|
||||
}
|
||||
```
|
||||
|
||||
Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте це через
|
||||
`OLLAMA_API_KEY`, а bundled provider Plugin додає Ollama безпосередньо до
|
||||
`openclaw onboard` і вибирача моделей. Див. [/providers/ollama](/uk/providers/ollama)
|
||||
для onboarding, cloud/local mode і custom-конфігурації.
|
||||
Ollama локально виявляється за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте його через
|
||||
`OLLAMA_API_KEY`, а вбудований Plugin постачальника додає Ollama безпосередньо до
|
||||
`openclaw onboard` і picker моделей. Відомості про онбординг, хмарний/локальний режим і власну конфігурацію див. у [/providers/ollama](/uk/providers/ollama).
|
||||
|
||||
### vLLM
|
||||
|
||||
vLLM постачається як bundled provider Plugin для локальних/self-hosted OpenAI-сумісних
|
||||
vLLM постачається як вбудований Plugin постачальника для локальних/self-hosted OpenAI-compatible
|
||||
серверів:
|
||||
|
||||
- Provider: `vllm`
|
||||
- Auth: необов’язкова (залежить від вашого сервера)
|
||||
- Стандартний base URL: `http://127.0.0.1:8000/v1`
|
||||
- Постачальник: `vllm`
|
||||
- Автентифікація: необов’язкова (залежить від вашого сервера)
|
||||
- Типовий базовий URL: `http://127.0.0.1:8000/v1`
|
||||
|
||||
Щоб увімкнути auto-discovery локально (підійде будь-яке значення, якщо ваш сервер не вимагає auth):
|
||||
Щоб увімкнути авто-виявлення локально (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації):
|
||||
|
||||
```bash
|
||||
export VLLM_API_KEY="vllm-local"
|
||||
```
|
||||
|
||||
Потім задайте модель (замініть на один з id, які повертає `/v1/models`):
|
||||
Потім задайте модель (замініть на один з id, повернених `/v1/models`):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -513,25 +529,25 @@ export VLLM_API_KEY="vllm-local"
|
||||
}
|
||||
```
|
||||
|
||||
Деталі див. у [/providers/vllm](/uk/providers/vllm).
|
||||
Відомості див. у [/providers/vllm](/uk/providers/vllm).
|
||||
|
||||
### SGLang
|
||||
|
||||
SGLang постачається як bundled provider Plugin для швидких self-hosted
|
||||
OpenAI-сумісних серверів:
|
||||
SGLang постачається як вбудований Plugin постачальника для швидких self-hosted
|
||||
OpenAI-compatible серверів:
|
||||
|
||||
- Provider: `sglang`
|
||||
- Auth: необов’язкова (залежить від вашого сервера)
|
||||
- Стандартний base URL: `http://127.0.0.1:30000/v1`
|
||||
- Постачальник: `sglang`
|
||||
- Автентифікація: необов’язкова (залежить від вашого сервера)
|
||||
- Типовий базовий URL: `http://127.0.0.1:30000/v1`
|
||||
|
||||
Щоб увімкнути auto-discovery локально (підійде будь-яке значення, якщо ваш сервер не
|
||||
вимагає auth):
|
||||
Щоб увімкнути авто-виявлення локально (підійде будь-яке значення, якщо ваш сервер не
|
||||
вимагає автентифікації):
|
||||
|
||||
```bash
|
||||
export SGLANG_API_KEY="sglang-local"
|
||||
```
|
||||
|
||||
Потім задайте модель (замініть на один з id, які повертає `/v1/models`):
|
||||
Потім задайте модель (замініть на один з id, повернених `/v1/models`):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -541,11 +557,11 @@ export SGLANG_API_KEY="sglang-local"
|
||||
}
|
||||
```
|
||||
|
||||
Деталі див. у [/providers/sglang](/uk/providers/sglang).
|
||||
Відомості див. у [/providers/sglang](/uk/providers/sglang).
|
||||
|
||||
### Локальні proxy (LM Studio, vLLM, LiteLLM тощо)
|
||||
### Локальні проксі (LM Studio, vLLM, LiteLLM тощо)
|
||||
|
||||
Приклад (OpenAI‑сумісний):
|
||||
Приклад (OpenAI‑compatible):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -580,21 +596,24 @@ export SGLANG_API_KEY="sglang-local"
|
||||
|
||||
Примітки:
|
||||
|
||||
- Для custom provider-ів `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` необов’язкові.
|
||||
Якщо їх не вказано, OpenClaw використовує такі значення за замовчуванням:
|
||||
- Для custom постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` не є обов’язковими.
|
||||
Якщо їх пропущено, OpenClaw типово використовує:
|
||||
- `reasoning: false`
|
||||
- `input: ["text"]`
|
||||
- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
|
||||
- `contextWindow: 200000`
|
||||
- `maxTokens: 8192`
|
||||
- Рекомендовано: задавайте явні значення, що відповідають обмеженням вашого proxy/моделі.
|
||||
- Для `api: "openai-completions"` на не нативних endpoint-ах (будь-який непорожній `baseUrl`, чий host не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникати помилок provider 400 для непідтримуваних ролей `developer`.
|
||||
- Маршрути OpenAI-сумісного proxy-стилю також пропускають формування запитів, доступне лише для нативного OpenAI: без `service_tier`, без `store` у Responses, без `store` у Completions, без підказок prompt-cache, без формування payload для сумісності reasoning OpenAI і без прихованих заголовків атрибуції OpenClaw.
|
||||
- Для OpenAI-сумісних Completions proxy, яким потрібні vendor-специфічні поля,
|
||||
- Рекомендовано: задавайте явні значення, що відповідають обмеженням вашого проксі/моделі.
|
||||
- Для `api: "openai-completions"` на ненативних кінцевих точках (будь-який непорожній `baseUrl`, чий хост не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникнути помилок постачальника 400 для ролей `developer`, які не підтримуються.
|
||||
- Маршрути OpenAI-compatible у стилі проксі також пропускають формування запитів, притаманне лише нативному OpenAI:
|
||||
без `service_tier`, без `store` Responses, без `store` Completions, без
|
||||
підказок кешу prompt, без формування payload для сумісності reasoning OpenAI і без прихованих
|
||||
заголовків атрибуції OpenClaw.
|
||||
- Для проксі Completions у форматі OpenAI-compatible, яким потрібні поля, специфічні для постачальника,
|
||||
задайте `agents.defaults.models["provider/model"].params.extra_body` (або
|
||||
`extraBody`), щоб об’єднати додатковий JSON у вихідне тіло запиту.
|
||||
- Якщо `baseUrl` порожній або не вказаний, OpenClaw зберігає стандартну поведінку OpenAI (яка вказує на `api.openai.com`).
|
||||
- Для безпеки явне `compat.supportsDeveloperRole: true` однаково перевизначається на не нативних endpoint-ах `openai-completions`.
|
||||
- Якщо `baseUrl` порожній/не заданий, OpenClaw зберігає типову поведінку OpenAI (яка вказує на `api.openai.com`).
|
||||
- Для безпеки явний `compat.supportsDeveloperRole: true` усе одно перевизначається на ненативних кінцевих точках `openai-completions`.
|
||||
|
||||
## Приклади CLI
|
||||
|
||||
@ -604,11 +623,11 @@ openclaw models set opencode/claude-opus-4-6
|
||||
openclaw models list
|
||||
```
|
||||
|
||||
Див. також: [Конфігурація](/uk/gateway/configuration) для повних прикладів конфігурації.
|
||||
Див. також: [Configuration](/uk/gateway/configuration) для повних прикладів конфігурації.
|
||||
|
||||
## Пов’язане
|
||||
## Пов’язані матеріали
|
||||
|
||||
- [Моделі](/uk/concepts/models) — конфігурація моделей і псевдоніми
|
||||
- [Model failover](/uk/concepts/model-failover) — ланцюжки fallback і поведінка повторних спроб
|
||||
- [Довідник із конфігурації](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей
|
||||
- [Provider-и](/uk/providers) — окремі інструкції з налаштування для кожного provider-а
|
||||
- [Models](/uk/concepts/models) — конфігурація моделей і псевдоніми
|
||||
- [Model failover](/uk/concepts/model-failover) — ланцюжки резервного перемикання й поведінка повторних спроб
|
||||
- [Configuration reference](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделі
|
||||
- [Providers](/uk/providers) — посібники з налаштування для кожного постачальника
|
||||
|
||||
@ -1,45 +1,45 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібен надійний резервний варіант, коли API-провайдери зазнають збою
|
||||
- Ви використовуєте Codex CLI або інші локальні AI CLI й хочете використовувати їх повторно
|
||||
- Ви хочете зрозуміти міст MCP local loopback для доступу CLI-бекенда до інструментів
|
||||
summary: 'Бекенди CLI: резервний локальний AI CLI з необов’язковим мостом інструментів MCP'
|
||||
- Вам потрібен надійний резервний варіант, коли API-провайдери не працюють
|
||||
- Ви використовуєте Codex CLI або інші локальні AI CLI і хочете повторно використовувати їх
|
||||
- Ви хочете зрозуміти міст local loopback MCP для доступу до інструментів бекенду CLI
|
||||
summary: 'Бекенди CLI: локальний резервний AI CLI з необов’язковим мостом інструментів MCP'
|
||||
title: Бекенди CLI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T18:10:13Z"
|
||||
generated_at: "2026-04-25T07:01:57Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 81d5f41ebaf16d4171379cf446b4c70b167519cd1f647c0701cccda19f0b3419
|
||||
source_hash: 09e184bb99a6c354738c3d770460bc2f282a31c41d2cbce4c1e021ae828ba27c
|
||||
source_path: gateway/cli-backends.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
OpenClaw може запускати **локальні AI CLI** як **текстовий резервний варіант**, коли API-провайдери недоступні,
|
||||
обмежені за rate limit або тимчасово працюють некоректно. Це навмисно консервативний підхід:
|
||||
OpenClaw може запускати **локальні AI CLI** як **резервний варіант лише для тексту**, коли API-провайдери недоступні,
|
||||
обмежені за частотою запитів або тимчасово працюють некоректно. Це навмисно консервативний підхід:
|
||||
|
||||
- **Інструменти OpenClaw не інжектуються безпосередньо**, але бекенди з `bundleMcp: true`
|
||||
можуть отримувати інструменти gateway через міст MCP local loopback.
|
||||
- **Потокове передавання JSONL** для CLI, які це підтримують.
|
||||
- **Інструменти OpenClaw не впроваджуються безпосередньо**, але бекенди з `bundleMcp: true`
|
||||
можуть отримувати інструменти gateway через міст loopback MCP.
|
||||
- **Потокова передача JSONL** для CLI, які її підтримують.
|
||||
- **Сесії підтримуються** (тому наступні ходи залишаються узгодженими).
|
||||
- **Зображення можна передавати далі**, якщо CLI приймає шляхи до зображень.
|
||||
|
||||
Це задумано як **страхувальна сітка**, а не як основний шлях. Використовуйте це, коли
|
||||
вам потрібні текстові відповіді в стилі «завжди працює» без залежності від зовнішніх API.
|
||||
вам потрібні текстові відповіді в режимі «працює завжди» без залежності від зовнішніх API.
|
||||
|
||||
Якщо вам потрібне повноцінне середовище harness із керуванням сесіями ACP, фоновими завданнями,
|
||||
прив’язкою до thread/conversation і постійними зовнішніми сесіями кодування, використовуйте
|
||||
[ACP Agents](/uk/tools/acp-agents). CLI-бекенди — це не ACP.
|
||||
прив’язкою до потоку/розмови та постійними зовнішніми сесіями кодування, використовуйте
|
||||
[ACP Agents](/uk/tools/acp-agents). Бекенди CLI — це не ACP.
|
||||
|
||||
## Швидкий старт для початківців
|
||||
|
||||
Ви можете використовувати Codex CLI **без жодної конфігурації** (вбудований Plugin OpenAI
|
||||
Ви можете використовувати Codex CLI **без жодної конфігурації** (вбудований плагін OpenAI
|
||||
реєструє бекенд за замовчуванням):
|
||||
|
||||
```bash
|
||||
openclaw agent --message "hi" --model codex-cli/gpt-5.5
|
||||
```
|
||||
|
||||
Якщо ваш gateway працює під launchd/systemd і PATH мінімальний, додайте лише
|
||||
Якщо ваш gateway працює через launchd/systemd і `PATH` мінімальний, додайте лише
|
||||
шлях до команди:
|
||||
|
||||
```json5
|
||||
@ -56,16 +56,16 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5
|
||||
}
|
||||
```
|
||||
|
||||
Ось і все. Жодних ключів, жодної додаткової конфігурації автентифікації не потрібно, окрім самої CLI.
|
||||
Ось і все. Жодних ключів, жодної додаткової конфігурації автентифікації, окрім самої CLI.
|
||||
|
||||
Якщо ви використовуєте вбудований CLI-бекенд як **основний провайдер повідомлень** на
|
||||
хості gateway, OpenClaw тепер автоматично завантажує відповідний вбудований Plugin, коли ваша конфігурація
|
||||
явно посилається на цей бекенд у model ref або в
|
||||
Якщо ви використовуєте вбудований бекенд CLI як **основного провайдера повідомлень** на
|
||||
хості gateway, OpenClaw тепер автоматично завантажує відповідний вбудований плагін, коли ваша конфігурація
|
||||
явно посилається на цей бекенд у посиланні на модель або в
|
||||
`agents.defaults.cliBackends`.
|
||||
|
||||
## Використання як резервного варіанту
|
||||
|
||||
Додайте CLI-бекенд до списку резервних, щоб він запускався лише тоді, коли основні моделі недоступні:
|
||||
Додайте бекенд CLI до списку резервних варіантів, щоб він запускався лише тоді, коли основні моделі не працюють:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -86,20 +86,20 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5
|
||||
|
||||
Примітки:
|
||||
|
||||
- Якщо ви використовуєте `agents.defaults.models` (allowlist), ви також маєте включити туди моделі CLI-бекенда.
|
||||
- Якщо основний провайдер недоступний (автентифікація, rate limits, тайм-аути), OpenClaw
|
||||
спробує CLI-бекенд наступним.
|
||||
- Якщо ви використовуєте `agents.defaults.models` (список дозволених), ви також маєте включити туди моделі вашого бекенду CLI.
|
||||
- Якщо основний провайдер не працює (автентифікація, ліміти частоти, тайм-аути), OpenClaw
|
||||
спробує далі бекенд CLI.
|
||||
|
||||
## Огляд конфігурації
|
||||
|
||||
Усі CLI-бекенди розміщуються в:
|
||||
Усі бекенди CLI знаходяться тут:
|
||||
|
||||
```
|
||||
agents.defaults.cliBackends
|
||||
```
|
||||
|
||||
Кожен запис має ключ у вигляді **provider id** (наприклад, `codex-cli`, `my-cli`).
|
||||
Provider id стає лівою частиною вашого model ref:
|
||||
Кожен запис має ключ **ідентифікатора провайдера** (наприклад, `codex-cli`, `my-cli`).
|
||||
Ідентифікатор провайдера стає лівою частиною посилання на модель:
|
||||
|
||||
```
|
||||
<provider>/<model>
|
||||
@ -145,41 +145,41 @@ Provider id стає лівою частиною вашого model ref:
|
||||
|
||||
## Як це працює
|
||||
|
||||
1. **Вибирає бекенд** на основі префікса provider (`codex-cli/...`).
|
||||
2. **Будує system prompt** з використанням того самого prompt OpenClaw і контексту workspace.
|
||||
3. **Запускає CLI** з id сесії (якщо підтримується), щоб історія залишалася узгодженою.
|
||||
Вбудований бекенд `claude-cli` підтримує процес Claude stdio живим для кожної
|
||||
сесії OpenClaw і надсилає наступні ходи через stdin stream-json.
|
||||
1. **Вибирає бекенд** на основі префікса провайдера (`codex-cli/...`).
|
||||
2. **Формує системний prompt** з використанням того самого prompt OpenClaw і контексту робочого простору.
|
||||
3. **Виконує CLI** з ідентифікатором сесії (якщо підтримується), щоб історія залишалася узгодженою.
|
||||
Вбудований бекенд `claude-cli` підтримує процес Claude stdio активним для кожної
|
||||
сесії OpenClaw і надсилає наступні ходи через stream-json stdin.
|
||||
4. **Розбирає вивід** (JSON або звичайний текст) і повертає фінальний текст.
|
||||
5. **Зберігає id сесій** для кожного бекенда, щоб наступні ходи повторно використовували ту саму CLI-сесію.
|
||||
5. **Зберігає ідентифікатори сесій** для кожного бекенду, щоб наступні ходи повторно використовували ту саму сесію CLI.
|
||||
|
||||
<Note>
|
||||
Вбудований бекенд Anthropic `claude-cli` знову підтримується. Співробітники Anthropic
|
||||
повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає
|
||||
використання `claude -p` санкціонованим для цієї інтеграції, якщо Anthropic не опублікує
|
||||
Вбудований Anthropic-бекенд `claude-cli` знову підтримується. Співробітники Anthropic
|
||||
повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw розглядає
|
||||
використання `claude -p` як санкціоноване для цієї інтеграції, якщо Anthropic не опублікує
|
||||
нову політику.
|
||||
</Note>
|
||||
|
||||
Вбудований бекенд OpenAI `codex-cli` передає system prompt OpenClaw через
|
||||
override конфігурації `model_instructions_file` у Codex (`-c
|
||||
model_instructions_file="..."`). Codex не надає прапорець у стилі Claude
|
||||
`--append-system-prompt`, тому OpenClaw записує зібраний prompt у тимчасовий
|
||||
файл для кожної нової сесії Codex CLI.
|
||||
Вбудований OpenAI-бекенд `codex-cli` передає системний prompt OpenClaw через
|
||||
перевизначення конфігурації Codex `model_instructions_file` (`-c
|
||||
model_instructions_file="..."`). Codex не надає прапора у стилі Claude
|
||||
`--append-system-prompt`, тому OpenClaw записує зібраний prompt у
|
||||
тимчасовий файл для кожної нової сесії Codex CLI.
|
||||
|
||||
Вбудований бекенд Anthropic `claude-cli` отримує знімок Skills OpenClaw
|
||||
двома способами: компактний каталог Skills OpenClaw у доданому system prompt і
|
||||
тимчасовий Plugin Claude Code, переданий через `--plugin-dir`. Plugin містить
|
||||
лише дозволені Skills для цього агента/сесії, тому власний resolver Skills у Claude Code
|
||||
бачить той самий відфільтрований набір, який OpenClaw інакше рекламував би в prompt.
|
||||
Перевизначення env/API key для Skills і далі застосовуються OpenClaw до середовища дочірнього процесу під час виконання.
|
||||
Вбудований Anthropic-бекенд `claude-cli` отримує знімок Skills OpenClaw
|
||||
двома способами: компактний каталог Skills OpenClaw у доданому системному prompt і
|
||||
тимчасовий плагін Claude Code, переданий через `--plugin-dir`. Плагін містить
|
||||
лише ті Skills, які підходять для цього агента/сесії, тому вбудований механізм розв’язання Skills Claude Code
|
||||
бачить той самий відфільтрований набір, який OpenClaw інакше рекламував би у prompt.
|
||||
Перевизначення середовища/API-ключів для Skills усе ще застосовуються OpenClaw до середовища дочірнього процесу для цього запуску.
|
||||
|
||||
Claude CLI також має власний неінтерактивний режим дозволів. OpenClaw зіставляє його
|
||||
з наявною policy виконання замість додавання специфічної для Claude конфігурації: коли
|
||||
ефективно запитана policy виконання — YOLO (`tools.exec.security: "full"` і
|
||||
з наявною політикою exec замість додавання окремої конфігурації для Claude: коли
|
||||
ефективно запитана політика exec — YOLO (`tools.exec.security: "full"` і
|
||||
`tools.exec.ask: "off"`), OpenClaw додає `--permission-mode bypassPermissions`.
|
||||
Налаштування `agents.list[].tools.exec` для окремого агента мають пріоритет над глобальним `tools.exec` для
|
||||
цього агента. Щоб примусово встановити інший режим Claude, задайте явні сирі аргументи бекенда,
|
||||
наприклад `--permission-mode default` або `--permission-mode acceptEdits`, у
|
||||
цього агента. Щоб примусово використати інший режим Claude, задайте явні сирі аргументи бекенду,
|
||||
такі як `--permission-mode default` або `--permission-mode acceptEdits`, у
|
||||
`agents.defaults.cliBackends.claude-cli.args` і відповідних `resumeArgs`.
|
||||
|
||||
Перш ніж OpenClaw зможе використовувати вбудований бекенд `claude-cli`, сам Claude Code
|
||||
@ -192,40 +192,42 @@ openclaw models auth login --provider anthropic --method cli --set-default
|
||||
```
|
||||
|
||||
Використовуйте `agents.defaults.cliBackends.claude-cli.command` лише тоді, коли бінарний файл `claude`
|
||||
ще не доступний у `PATH`.
|
||||
вже недоступний у `PATH`.
|
||||
|
||||
## Сесії
|
||||
|
||||
- Якщо CLI підтримує сесії, задайте `sessionArg` (наприклад, `--session-id`) або
|
||||
`sessionArgs` (placeholder `{sessionId}`), коли ID потрібно вставити
|
||||
в кілька прапорців.
|
||||
- Якщо CLI використовує **підкоманду resume** з іншими прапорцями, задайте
|
||||
`sessionArgs` (плейсхолдер `{sessionId}`), коли ID потрібно вставити
|
||||
в кілька прапорів.
|
||||
- Якщо CLI використовує **підкоманду resume** з іншими прапорами, задайте
|
||||
`resumeArgs` (замінює `args` під час відновлення) і за потреби `resumeOutput`
|
||||
(для відновлень не у форматі JSON).
|
||||
- `sessionMode`:
|
||||
- `always`: завжди надсилати id сесії (новий UUID, якщо нічого не збережено).
|
||||
- `existing`: надсилати id сесії лише якщо його було збережено раніше.
|
||||
- `none`: ніколи не надсилати id сесії.
|
||||
- `always`: завжди надсилати ідентифікатор сесії (новий UUID, якщо нічого не збережено).
|
||||
- `existing`: надсилати ідентифікатор сесії лише тоді, коли його було збережено раніше.
|
||||
- `none`: ніколи не надсилати ідентифікатор сесії.
|
||||
- `claude-cli` за замовчуванням використовує `liveSession: "claude-stdio"`, `output: "jsonl"`
|
||||
і `input: "stdin"`, щоб наступні ходи повторно використовували живий процес Claude, поки
|
||||
він активний. Теплий stdio тепер є варіантом за замовчуванням, зокрема для користувацьких конфігурацій,
|
||||
у яких не вказані поля транспорту. Якщо Gateway перезапускається або неактивний процес завершується,
|
||||
OpenClaw відновлюється із збереженого id сесії Claude. Збережені id сесій
|
||||
перевіряються на наявність доступного для читання transcript проєкту перед
|
||||
і `input: "stdin"`, щоб наступні ходи повторно використовували активний процес Claude,
|
||||
поки він активний. Теплий stdio тепер є типовим режимом, зокрема для користувацьких конфігурацій,
|
||||
у яких поля транспорту не задані. Якщо Gateway перезапускається або неактивний процес
|
||||
завершується, OpenClaw відновлюється зі збереженого ідентифікатора сесії Claude. Збережені ідентифікатори сесій
|
||||
перевіряються на наявність доступного для читання наявного транскрипту проєкту перед
|
||||
відновленням, тому фантомні прив’язки очищаються з `reason=transcript-missing`,
|
||||
а не тихо запускають нову сесію Claude CLI під `--resume`.
|
||||
- Збережені CLI-сесії — це безперервність, якою володіє provider. Неявне щоденне
|
||||
скидання сесії не розриває їх; це роблять `/reset` і явні policy `session.reset`.
|
||||
а не тихо запускають нову сесію Claude CLI через `--resume`.
|
||||
- Збережені сесії CLI — це безперервність, що належить провайдеру. Неявне щоденне
|
||||
скидання їх не обриває; `/reset` і явні політики `session.reset` — обривають.
|
||||
|
||||
Примітки щодо серіалізації:
|
||||
|
||||
- `serialize: true` зберігає впорядкованість запусків в одній lane.
|
||||
- Більшість CLI серіалізуються в одній lane provider.
|
||||
- OpenClaw скидає повторне використання збереженої CLI-сесії, коли змінюється вибрана ідентичність автентифікації,
|
||||
зокрема змінений id auth profile, статичний API key, статичний токен або ідентичність OAuth-облікового запису, якщо CLI її розкриває. Ротація токенів доступу й оновлення OAuth не
|
||||
розриває збережену CLI-сесію. Якщо CLI не розкриває стабільний id OAuth-облікового запису, OpenClaw дозволяє цій CLI самостійно застосовувати дозволи на resume.
|
||||
- `serialize: true` зберігає впорядкованість запусків у тій самій lane.
|
||||
- Більшість CLI серіалізують на одній lane провайдера.
|
||||
- OpenClaw відмовляється від повторного використання збереженої сесії CLI, коли змінюється вибрана автентифікаційна ідентичність,
|
||||
зокрема якщо змінюється ID профілю автентифікації, статичний API-ключ, статичний токен
|
||||
або ідентичність OAuth-акаунта, якщо CLI її надає. Ротація OAuth access і refresh токенів
|
||||
не обриває збережену сесію CLI. Якщо CLI не надає стабільний ID OAuth-акаунта,
|
||||
OpenClaw дозволяє цій CLI самій забезпечувати дозволи на відновлення.
|
||||
|
||||
## Зображення (передавання далі)
|
||||
## Зображення (передача наскрізь)
|
||||
|
||||
Якщо ваша CLI приймає шляхи до зображень, задайте `imageArg`:
|
||||
|
||||
@ -234,28 +236,29 @@ imageArg: "--image",
|
||||
imageMode: "repeat"
|
||||
```
|
||||
|
||||
OpenClaw записуватиме base64-зображення у тимчасові файли. Якщо задано `imageArg`, ці
|
||||
шляхи передаються як аргументи CLI. Якщо `imageArg` відсутній, OpenClaw додає
|
||||
шляхи до файлів у prompt (ін’єкція шляхів), чого достатньо для CLI, які автоматично
|
||||
OpenClaw записуватиме base64-зображення в тимчасові файли. Якщо задано `imageArg`, ці
|
||||
шляхи передаються як аргументи CLI. Якщо `imageArg` не задано, OpenClaw додає
|
||||
шляхи до файлів у prompt (ін’єкція шляху), чого достатньо для CLI, які автоматично
|
||||
завантажують локальні файли зі звичайних шляхів.
|
||||
|
||||
## Входи / виходи
|
||||
|
||||
- `output: "json"` (за замовчуванням) намагається розібрати JSON і витягти текст + id сесії.
|
||||
- Для JSON-виводу Gemini CLI OpenClaw читає текст відповіді з `response`, а
|
||||
використання — з `stats`, коли `usage` відсутній або порожній.
|
||||
- `output: "jsonl"` розбирає потоки JSONL (наприклад, Codex CLI `--json`) і витягує фінальне повідомлення агента плюс ідентифікатори сесії, якщо вони присутні.
|
||||
- `output: "json"` (типово) намагається розібрати JSON і витягти текст + ідентифікатор сесії.
|
||||
- Для JSON-виводу Gemini CLI OpenClaw зчитує текст відповіді з `response`, а
|
||||
використання — зі `stats`, коли `usage` відсутній або порожній.
|
||||
- `output: "jsonl"` розбирає потоки JSONL (наприклад Codex CLI `--json`) і витягує фінальне повідомлення агента разом з ідентифікаторами сесії,
|
||||
якщо вони присутні.
|
||||
- `output: "text"` розглядає stdout як фінальну відповідь.
|
||||
|
||||
Режими введення:
|
||||
|
||||
- `input: "arg"` (за замовчуванням) передає prompt як останній аргумент CLI.
|
||||
- `input: "arg"` (типово) передає prompt як останній аргумент CLI.
|
||||
- `input: "stdin"` надсилає prompt через stdin.
|
||||
- Якщо prompt дуже довгий і задано `maxPromptArgChars`, використовується stdin.
|
||||
|
||||
## Значення за замовчуванням (керуються Plugin)
|
||||
## Значення за замовчуванням (належать плагіну)
|
||||
|
||||
Вбудований Plugin OpenAI також реєструє значення за замовчуванням для `codex-cli`:
|
||||
Вбудований плагін OpenAI також реєструє значення за замовчуванням для `codex-cli`:
|
||||
|
||||
- `command: "codex"`
|
||||
- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
|
||||
@ -266,7 +269,7 @@ OpenClaw записуватиме base64-зображення у тимчасо
|
||||
- `imageArg: "--image"`
|
||||
- `sessionMode: "existing"`
|
||||
|
||||
Вбудований Plugin Google також реєструє значення за замовчуванням для `google-gemini-cli`:
|
||||
Вбудований плагін Google також реєструє значення за замовчуванням для `google-gemini-cli`:
|
||||
|
||||
- `command: "gemini"`
|
||||
- `args: ["--output-format", "json", "--prompt", "{prompt}"]`
|
||||
@ -281,28 +284,28 @@ OpenClaw записуватиме base64-зображення у тимчасо
|
||||
`gemini` у `PATH` (`brew install gemini-cli` або
|
||||
`npm install -g @google/gemini-cli`).
|
||||
|
||||
Примітки щодо JSON Gemini CLI:
|
||||
Примітки щодо Gemini CLI JSON:
|
||||
|
||||
- Текст відповіді читається з поля JSON `response`.
|
||||
- Використання бере резервне значення з `stats`, коли `usage` відсутній або порожній.
|
||||
- `stats.cached` нормалізується в `cacheRead` OpenClaw.
|
||||
- Якщо `stats.input` відсутній, OpenClaw виводить кількість вхідних токенів із
|
||||
- Текст відповіді зчитується з поля JSON `response`.
|
||||
- Використання береться зі `stats`, якщо `usage` відсутній або порожній.
|
||||
- `stats.cached` нормалізується до OpenClaw `cacheRead`.
|
||||
- Якщо `stats.input` відсутній, OpenClaw виводить вхідні токени з
|
||||
`stats.input_tokens - stats.cached`.
|
||||
|
||||
Перевизначайте лише за потреби (типовий випадок: абсолютний шлях `command`).
|
||||
Перевизначайте лише за потреби (поширений випадок: абсолютний шлях `command`).
|
||||
|
||||
## Значення за замовчуванням, керовані Plugin
|
||||
## Значення за замовчуванням, що належать плагіну
|
||||
|
||||
Значення за замовчуванням для CLI-бекендів тепер є частиною поверхні Plugin:
|
||||
Значення за замовчуванням для бекендів CLI тепер є частиною поверхні плагіна:
|
||||
|
||||
- Plugins реєструють їх через `api.registerCliBackend(...)`.
|
||||
- `id` бекенда стає префіксом provider у model refs.
|
||||
- Конфігурація користувача в `agents.defaults.cliBackends.<id>` усе ще перевизначає значення Plugin за замовчуванням.
|
||||
- Очищення конфігурації, специфічне для бекенда, залишається під контролем Plugin через необов’язковий
|
||||
hook `normalizeConfig`.
|
||||
- Плагіни реєструють їх через `api.registerCliBackend(...)`.
|
||||
- `id` бекенду стає префіксом провайдера в посиланнях на моделі.
|
||||
- Користувацька конфігурація в `agents.defaults.cliBackends.<id>` як і раніше перевизначає значення плагіна за замовчуванням.
|
||||
- Очищення конфігурації, специфічне для бекенду, залишається у власності плагіна через необов’язковий
|
||||
хук `normalizeConfig`.
|
||||
|
||||
Plugins, яким потрібні невеликі шими сумісності для prompt/повідомлень, можуть оголошувати
|
||||
двонапрямні текстові перетворення без заміни provider або CLI-бекенда:
|
||||
Плагіни, яким потрібні невеликі шими сумісності prompt/повідомлень, можуть оголосити
|
||||
двонапрямні текстові перетворення без заміни провайдера або бекенду CLI:
|
||||
|
||||
```typescript
|
||||
api.registerTextTransforms({
|
||||
@ -319,59 +322,65 @@ api.registerTextTransforms({
|
||||
});
|
||||
```
|
||||
|
||||
`input` переписує system prompt і prompt користувача, передані до CLI. `output`
|
||||
`input` переписує системний prompt і користувацький prompt, передані до CLI. `output`
|
||||
переписує потокові дельти помічника й розібраний фінальний текст до того, як OpenClaw обробить
|
||||
власні control markers і доставку каналом.
|
||||
власні керувальні маркери та доставку в channel.
|
||||
|
||||
Для CLI, які виводять JSONL, сумісний зі stream-json Claude Code, задайте
|
||||
`jsonlDialect: "claude-stream-json"` у конфігурації цього бекенда.
|
||||
Для CLI, які видають JSONL, сумісний із Claude Code stream-json, задайте
|
||||
`jsonlDialect: "claude-stream-json"` у конфігурації цього бекенду.
|
||||
|
||||
## Оверлеї MCP для bundle
|
||||
## Bundle MCP overlays
|
||||
|
||||
CLI-бекенди **не** отримують виклики інструментів OpenClaw безпосередньо, але бекенд може
|
||||
ввімкнути генерацію оверлею конфігурації MCP за допомогою `bundleMcp: true`.
|
||||
Бекенди CLI **не** отримують виклики інструментів OpenClaw безпосередньо, але бекенд може
|
||||
увімкнути згенерований оверлей конфігурації MCP через `bundleMcp: true`.
|
||||
|
||||
Поточна вбудована поведінка:
|
||||
|
||||
- `claude-cli`: згенерований суворий файл конфігурації MCP
|
||||
- `codex-cli`: inline override конфігурації для `mcp_servers`; згенерований
|
||||
loopback-сервер OpenClaw позначається режимом схвалення інструментів для окремого сервера в Codex,
|
||||
щоб виклики MCP не зависали через локальні запити на схвалення
|
||||
- `claude-cli`: згенерований строгий файл конфігурації MCP
|
||||
- `codex-cli`: вбудовані перевизначення конфігурації для `mcp_servers`; згенерований
|
||||
loopback-сервер OpenClaw позначається режимом погодження інструментів на рівні сервера Codex,
|
||||
щоб виклики MCP не зависали на локальних запитах підтвердження
|
||||
- `google-gemini-cli`: згенерований файл системних налаштувань Gemini
|
||||
|
||||
Коли bundle MCP увімкнено, OpenClaw:
|
||||
|
||||
- запускає loopback HTTP MCP-сервер, який надає інструменти gateway процесу CLI
|
||||
- автентифікує міст за допомогою токена для кожної сесії (`OPENCLAW_MCP_TOKEN`)
|
||||
- обмежує доступ до інструментів поточною сесією, обліковим записом і контекстом каналу
|
||||
- завантажує увімкнені сервери bundle-MCP для поточного workspace
|
||||
- об’єднує їх із будь-якою наявною формою конфігурації/налаштувань MCP бекенда
|
||||
- переписує конфігурацію запуску, використовуючи режим інтеграції, що належить бекенду, із відповідного extension
|
||||
- автентифікує міст токеном на рівні сесії (`OPENCLAW_MCP_TOKEN`)
|
||||
- обмежує доступ до інструментів поточною сесією, акаунтом і контекстом channel
|
||||
- завантажує увімкнені bundle-MCP сервери для поточного робочого простору
|
||||
- об’єднує їх із будь-якою наявною формою конфігурації/налаштувань MCP бекенду
|
||||
- переписує конфігурацію запуску з використанням режиму інтеграції, що належить бекенду з відповідного extension
|
||||
|
||||
Якщо жоден MCP-сервер не увімкнено, OpenClaw все одно інжектує сувору конфігурацію, коли
|
||||
бекенд використовує bundle MCP, щоб фонові запуски залишалися ізольованими.
|
||||
Якщо жоден MCP-сервер не увімкнено, OpenClaw все одно впроваджує строгу конфігурацію, коли
|
||||
бекенд увімкнув bundle MCP, щоб фонові запуски залишалися ізольованими.
|
||||
|
||||
Вбудовані MCP-рантайми з областю дії сесії кешуються для повторного використання в межах сесії, а потім
|
||||
очищаються після `mcp.sessionIdleTtlMs` мілісекунд простою (типово 10
|
||||
хвилин; встановіть `0`, щоб вимкнути). Одноразові вбудовані запуски, як-от перевірки auth,
|
||||
генерація slug і очищення запитів recall Active Memory, виконують очищення наприкінці запуску, щоб дочірні
|
||||
stdio-процеси й потоки Streamable HTTP/SSE не жили довше за сам запуск.
|
||||
|
||||
## Обмеження
|
||||
|
||||
- **Без прямих викликів інструментів OpenClaw.** OpenClaw не інжектує виклики інструментів у
|
||||
протокол CLI-бекенда. Бекенди бачать інструменти gateway лише тоді, коли використовують
|
||||
- **Без прямих викликів інструментів OpenClaw.** OpenClaw не впроваджує виклики інструментів у
|
||||
протокол бекенду CLI. Бекенди бачать інструменти gateway лише тоді, коли вони увімкнули
|
||||
`bundleMcp: true`.
|
||||
- **Streaming залежить від бекенда.** Деякі бекенди передають JSONL потоком; інші буферизують
|
||||
- **Потокова передача залежить від бекенду.** Деякі бекенди передають JSONL потоком; інші буферизують
|
||||
до завершення.
|
||||
- **Структуровані виходи** залежать від JSON-формату CLI.
|
||||
- **Сесії Codex CLI** відновлюються через текстовий вивід (без JSONL), що менш
|
||||
структуровано, ніж початковий запуск `--json`. Сесії OpenClaw і далі працюють
|
||||
структуровано, ніж початковий запуск `--json`. Сесії OpenClaw при цьому все одно працюють
|
||||
нормально.
|
||||
|
||||
## Усунення несправностей
|
||||
## Усунення проблем
|
||||
|
||||
- **CLI не знайдено**: задайте `command` як повний шлях.
|
||||
- **Неправильна назва моделі**: використовуйте `modelAliases`, щоб зіставити `provider/model` → модель CLI.
|
||||
- **Немає безперервності сесії**: переконайтеся, що задано `sessionArg` і що `sessionMode` не є
|
||||
- **Немає безперервності сесії**: переконайтеся, що задано `sessionArg`, а `sessionMode` не дорівнює
|
||||
`none` (Codex CLI наразі не може відновлюватися з JSON-виводом).
|
||||
- **Зображення ігноруються**: задайте `imageArg` (і переконайтеся, що CLI підтримує шляхи до файлів).
|
||||
- **Зображення ігноруються**: задайте `imageArg` (і перевірте, що CLI підтримує шляхи до файлів).
|
||||
|
||||
## Пов’язане
|
||||
## Пов’язані матеріали
|
||||
|
||||
- [Gateway runbook](/uk/gateway)
|
||||
- [Local models](/uk/gateway/local-models)
|
||||
- [Runbook Gateway](/uk/gateway)
|
||||
- [Локальні моделі](/uk/gateway/local-models)
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- Налаштування політики, списків дозволеного або експериментальних можливостей для `tools.*`
|
||||
- Реєстрація користувацьких провайдерів або перевизначення базових URL-адрес
|
||||
- Налаштування політики, списків дозволених елементів або експериментальних функцій `tools.*`
|
||||
- Реєстрація власних провайдерів або перевизначення base URL
|
||||
- Налаштування самостійно розміщених кінцевих точок, сумісних з OpenAI
|
||||
summary: Конфігурація інструментів (політика, експериментальні перемикачі, інструменти на основі провайдерів) і налаштування користувацького провайдера/base-URL
|
||||
title: Конфігурація — інструменти та користувацькі провайдери
|
||||
summary: Конфігурація інструментів (політика, експериментальні перемикачі, інструменти з підтримкою провайдера) і налаштування власного провайдера/base-URL
|
||||
title: Конфігурація — інструменти та власні провайдери
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T00:30:50Z"
|
||||
generated_at: "2026-04-25T07:01:57Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a3a9ab07a5536196f3ba6c64111eb97206c3b4ff12e497564fe09684193e5c8a
|
||||
source_hash: d63b080550a6c95d714d3bb42c2b079368040aa09378d88c2e498ccd5ec113c1
|
||||
source_path: gateway/config-tools.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Ключі конфігурації `tools.*` і налаштування користувацького провайдера / base-URL. Для агентів,
|
||||
Ключі конфігурації `tools.*` і налаштування власного провайдера / base URL. Для агентів,
|
||||
каналів та інших ключів конфігурації верхнього рівня див.
|
||||
[Довідник із конфігурації](/uk/gateway/configuration-reference).
|
||||
|
||||
@ -22,7 +22,7 @@ x-i18n:
|
||||
|
||||
### Профілі інструментів
|
||||
|
||||
`tools.profile` задає базовий список дозволеного перед `tools.allow`/`tools.deny`:
|
||||
`tools.profile` задає базовий список дозволених елементів перед `tools.allow`/`tools.deny`:
|
||||
|
||||
Локальне онбординг-налаштування за замовчуванням встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явно вказані профілі зберігаються).
|
||||
|
||||
@ -35,24 +35,24 @@ x-i18n:
|
||||
|
||||
### Групи інструментів
|
||||
|
||||
| Група | Інструменти |
|
||||
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
|
||||
| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як псевдонім для `exec`) |
|
||||
| `group:fs` | `read`, `write`, `edit`, `apply_patch` |
|
||||
| Група | Інструменти |
|
||||
| ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
|
||||
| `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` | Усі вбудовані інструменти (не включає плагіни провайдерів) |
|
||||
| `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` | Усі вбудовані інструменти (за винятком плагінів провайдерів) |
|
||||
|
||||
### `tools.allow` / `tools.deny`
|
||||
|
||||
Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Без урахування регістру, підтримує шаблони `*`. Застосовується навіть коли пісочницю Docker вимкнено.
|
||||
Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Без урахування регістру, підтримує шаблони `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -78,7 +78,7 @@ x-i18n:
|
||||
|
||||
### `tools.elevated`
|
||||
|
||||
Керує розширеним доступом `exec` поза пісочницею:
|
||||
Керує розширеним доступом `exec` поза sandbox:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -96,7 +96,7 @@ x-i18n:
|
||||
|
||||
- Перевизначення на рівні агента (`agents.list[].tools.elevated`) може лише додатково обмежувати.
|
||||
- `/elevated on|off|ask|full` зберігає стан для кожної сесії; вбудовані директиви застосовуються до одного повідомлення.
|
||||
- Розширений `exec` обходить пісочницю та використовує налаштований шлях виходу (`gateway` за замовчуванням або `node`, коли ціль `exec` — `node`).
|
||||
- Розширений `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` за замовчуванням або `node`, якщо ціль `exec` — `node`).
|
||||
|
||||
### `tools.exec`
|
||||
|
||||
@ -120,8 +120,8 @@ x-i18n:
|
||||
|
||||
### `tools.loopDetection`
|
||||
|
||||
Перевірки безпеки на цикли інструментів **вимкнені за замовчуванням**. Установіть `enabled: true`, щоб увімкнути виявлення.
|
||||
Параметри можна задати глобально в `tools.loopDetection` і перевизначити для окремого агента в `agents.list[].tools.loopDetection`.
|
||||
Перевірки безпеки циклів інструментів **вимкнені за замовчуванням**. Установіть `enabled: true`, щоб увімкнути виявлення.
|
||||
Параметри можна визначити глобально в `tools.loopDetection` і перевизначити для окремого агента в `agents.list[].tools.loopDetection`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -166,7 +166,7 @@ x-i18n:
|
||||
},
|
||||
fetch: {
|
||||
enabled: true,
|
||||
provider: "firecrawl", // необов’язково; пропустіть для автовизначення
|
||||
provider: "firecrawl", // необов’язково; не вказуйте для автовизначення
|
||||
maxChars: 50000,
|
||||
maxCharsCap: 50000,
|
||||
maxResponseBytes: 2000000,
|
||||
@ -191,7 +191,7 @@ x-i18n:
|
||||
media: {
|
||||
concurrency: 2,
|
||||
asyncCompletion: {
|
||||
directSend: false, // опціонально: надсилати завершені асинхронні музичні/відео результати безпосередньо в канал
|
||||
directSend: false, // опціонально: надсилати завершену асинхронну музику/відео безпосередньо в канал
|
||||
},
|
||||
audio: {
|
||||
enabled: true,
|
||||
@ -217,7 +217,7 @@ x-i18n:
|
||||
|
||||
<Accordion title="Поля запису моделі медіа">
|
||||
|
||||
**Запис провайдера** (`type: "provider"` або пропущено):
|
||||
**Запис провайдера** (`type: "provider"` або не вказано):
|
||||
|
||||
- `provider`: ідентифікатор API-провайдера (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо)
|
||||
- `model`: перевизначення ідентифікатора моделі
|
||||
@ -226,21 +226,21 @@ x-i18n:
|
||||
**CLI-запис** (`type: "cli"`):
|
||||
|
||||
- `command`: виконуваний файл для запуску
|
||||
- `args`: шаблонізовані аргументи (підтримує `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо)
|
||||
- `args`: параметризовані аргументи (підтримуються `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо)
|
||||
|
||||
**Спільні поля:**
|
||||
**Загальні поля:**
|
||||
|
||||
- `capabilities`: необов’язковий список (`image`, `audio`, `video`). Значення за замовчуванням: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio.
|
||||
- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису.
|
||||
- У разі помилки використовується наступний запис.
|
||||
- У разі помилки виконується перехід до наступного запису.
|
||||
|
||||
Автентифікація провайдера виконується у стандартному порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`.
|
||||
Автентифікація провайдера відбувається у стандартному порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`.
|
||||
|
||||
**Поля асинхронного завершення:**
|
||||
|
||||
- `asyncCompletion.directSend`: коли `true`, завершені асинхронні завдання `music_generate`
|
||||
і `video_generate` спочатку намагаються доставити результат безпосередньо в канал. За замовчуванням: `false`
|
||||
(застарілий шлях пробудження сесії запитувача/доставки моделлю).
|
||||
- `asyncCompletion.directSend`: якщо `true`, завершені асинхронні завдання `music_generate`
|
||||
і `video_generate` спочатку намагаються доставлятися безпосередньо в канал. Значення за замовчуванням: `false`
|
||||
(застарілий шлях пробудження сесії запитувача/доставки через модель).
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -259,9 +259,9 @@ x-i18n:
|
||||
|
||||
### `tools.sessions`
|
||||
|
||||
Керує тим, які сесії можуть бути ціллю для інструментів сесій (`sessions_list`, `sessions_history`, `sessions_send`).
|
||||
Керує тим, на які сесії можуть бути націлені інструменти сесій (`sessions_list`, `sessions_history`, `sessions_send`).
|
||||
|
||||
За замовчуванням: `tree` (поточна сесія + сесії, породжені нею, наприклад субагенти).
|
||||
Значення за замовчуванням: `tree` (поточна сесія + сесії, породжені нею, наприклад субагенти).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -279,8 +279,8 @@ x-i18n:
|
||||
- `self`: лише ключ поточної сесії.
|
||||
- `tree`: поточна сесія + сесії, породжені поточною сесією (субагенти).
|
||||
- `agent`: будь-яка сесія, що належить поточному ідентифікатору агента (може включати інших користувачів, якщо ви запускаєте сесії для кожного відправника під тим самим ідентифікатором агента).
|
||||
- `all`: будь-яка сесія. Націлювання між агентами все одно вимагає `tools.agentToAgent`.
|
||||
- Обмеження пісочниці: коли поточна сесія працює в пісочниці і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`.
|
||||
- `all`: будь-яка сесія. Націлення між агентами все одно потребує `tools.agentToAgent`.
|
||||
- Обмеження sandbox: якщо поточна сесія працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`.
|
||||
|
||||
### `tools.sessions_spawn`
|
||||
|
||||
@ -291,10 +291,10 @@ x-i18n:
|
||||
tools: {
|
||||
sessions_spawn: {
|
||||
attachments: {
|
||||
enabled: false, // опціонально: установіть true, щоб дозволити вбудовані файлові вкладення
|
||||
maxTotalBytes: 5242880, // загалом 5 МБ для всіх файлів
|
||||
enabled: false, // опціонально: встановіть true, щоб дозволити вбудовані файлові вкладення
|
||||
maxTotalBytes: 5242880, // 5 MB сумарно для всіх файлів
|
||||
maxFiles: 50,
|
||||
maxFileBytes: 1048576, // 1 МБ на файл
|
||||
maxFileBytes: 1048576, // 1 MB на файл
|
||||
retainOnSessionKeep: false, // зберігати вкладення, коли cleanup="keep"
|
||||
},
|
||||
},
|
||||
@ -306,16 +306,16 @@ x-i18n:
|
||||
|
||||
- Вкладення підтримуються лише для `runtime: "subagent"`. Середовище ACP їх відхиляє.
|
||||
- Файли матеріалізуються в робочому просторі дочірньої сесії в `.openclaw/attachments/<uuid>/` разом із `.manifest.json`.
|
||||
- Вміст вкладень автоматично редагується під час збереження транскрипту.
|
||||
- Входи base64 перевіряються суворою перевіркою алфавіту/доповнення та захистом розміру до декодування.
|
||||
- Вміст вкладень автоматично редагується в збереженні транскриптів.
|
||||
- Входи Base64 перевіряються суворою перевіркою алфавіту/доповнення та захистом розміру до декодування.
|
||||
- Права доступу до файлів: `0700` для каталогів і `0600` для файлів.
|
||||
- Очищення виконується згідно з політикою `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`.
|
||||
- Очищення виконується відповідно до політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`.
|
||||
|
||||
<a id="toolsexperimental"></a>
|
||||
|
||||
### `tools.experimental`
|
||||
|
||||
Прапорці експериментальних вбудованих інструментів. За замовчуванням вимкнено, якщо не застосовується правило автоувімкнення strict-agentic GPT-5.
|
||||
Експериментальні прапорці вбудованих інструментів. За замовчуванням вимкнено, якщо не застосовується правило автоувімкнення strict-agentic GPT-5.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -330,8 +330,8 @@ x-i18n:
|
||||
Примітки:
|
||||
|
||||
- `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи.
|
||||
- За замовчуванням: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цією областю, або `false`, щоб залишити його вимкненим навіть для запусків strict-agentic GPT-5.
|
||||
- Коли інструмент увімкнено, системний промпт також додає вказівки з використання, щоб модель застосовувала його лише для суттєвої роботи та підтримувала не більше одного кроку `in_progress`.
|
||||
- Значення за замовчуванням: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цією областю, або `false`, щоб залишити його вимкненим навіть для запусків strict-agentic GPT-5.
|
||||
- Коли інструмент увімкнено, системний промпт також додає вказівки щодо використання, щоб модель застосовувала його лише для суттєвої роботи й підтримувала не більш ніж один крок у стані `in_progress`.
|
||||
|
||||
### `agents.defaults.subagents`
|
||||
|
||||
@ -352,15 +352,15 @@ x-i18n:
|
||||
```
|
||||
|
||||
- `model`: модель за замовчуванням для породжених субагентів. Якщо не вказано, субагенти успадковують модель викликача.
|
||||
- `allowAgents`: список дозволених ідентифікаторів цільових агентів за замовчуванням для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; за замовчуванням: лише той самий агент).
|
||||
- `runTimeoutSeconds`: тайм-аут за замовчуванням (у секундах) для `sessions_spawn`, коли виклик інструмента не містить `runTimeoutSeconds`. `0` означає відсутність тайм-ауту.
|
||||
- Політика інструментів для кожного субагента: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
|
||||
- `allowAgents`: список дозволених цільових ідентифікаторів агентів за замовчуванням для `sessions_spawn`, якщо агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; за замовчуванням: лише той самий агент).
|
||||
- `runTimeoutSeconds`: тайм-аут за замовчуванням (у секундах) для `sessions_spawn`, коли виклик інструмента не містить `runTimeoutSeconds`. `0` означає без тайм-ауту.
|
||||
- Політика інструментів для субагентів: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`.
|
||||
|
||||
---
|
||||
|
||||
## Користувацькі провайдери та base URL
|
||||
## Власні провайдери та base URL
|
||||
|
||||
OpenClaw використовує вбудований каталог моделей. Додавайте користувацьких провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents/<agentId>/agent/models.json`.
|
||||
OpenClaw використовує вбудований каталог моделей. Додавайте власних провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents/<agentId>/agent/models.json`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -389,49 +389,49 @@ OpenClaw використовує вбудований каталог модел
|
||||
}
|
||||
```
|
||||
|
||||
- Використовуйте `authHeader: true` + `headers` для нестандартних потреб автентифікації.
|
||||
- Використовуйте `authHeader: true` + `headers` для власних потреб автентифікації.
|
||||
- Перевизначайте кореневий каталог конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий псевдонім змінної середовища).
|
||||
- Пріоритет злиття для однакових ідентифікаторів провайдерів:
|
||||
- Пріоритет злиття для провайдерів із однаковими ідентифікаторами:
|
||||
- Непорожні значення `baseUrl` з агентського `models.json` мають пріоритет.
|
||||
- Непорожні значення `apiKey` з агента мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті конфігурації/профілю автентифікації.
|
||||
- Значення `apiKey` для провайдерів, керованих SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для посилань на змінні середовища, `secretref-managed` для посилань file/exec) замість збереження розкритих секретів.
|
||||
- Значення заголовків провайдера, керованих SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для посилань на змінні середовища, `secretref-managed` для посилань file/exec).
|
||||
- Порожні або відсутні `apiKey`/`baseUrl` в агенті беруться з `models.providers` у конфігурації.
|
||||
- Для однакових моделей `contextWindow`/`maxTokens` використовують вище значення між явною конфігурацією та неявними значеннями каталогу.
|
||||
- Для однакових моделей `contextTokens` зберігає явне обмеження середовища виконання, якщо воно задане; використовуйте це, щоб обмежити ефективний контекст без зміни власних метаданих моделі.
|
||||
- Значення `apiKey` для провайдера, яким керує SecretRef, оновлюються з вихідних маркерів (`ENV_VAR_NAME` для посилань на змінні середовища, `secretref-managed` для посилань на файл/exec) замість збереження розкритих секретів.
|
||||
- Значення заголовків провайдера, якими керує SecretRef, оновлюються з вихідних маркерів (`secretref-env:ENV_VAR_NAME` для посилань на змінні середовища, `secretref-managed` для посилань на файл/exec).
|
||||
- Порожні або відсутні агентські `apiKey`/`baseUrl` беруться з `models.providers` у конфігурації.
|
||||
- Для однакових моделей `contextWindow`/`maxTokens` використовують більше значення між явною конфігурацією та неявними значеннями каталогу.
|
||||
- Для однакових моделей `contextTokens` зберігає явне обмеження середовища виконання, якщо воно задане; використовуйте це, щоб обмежити ефективний контекст без зміни рідних метаданих моделі.
|
||||
- Використовуйте `models.mode: "replace"`, якщо хочете, щоб конфігурація повністю переписала `models.json`.
|
||||
- Збереження маркерів є авторитетним щодо джерела: маркери записуються з активного знімка вихідної конфігурації (до розкриття), а не з розкритих значень секретів середовища виконання.
|
||||
- Збереження маркерів визначається джерелом: маркери записуються з активного знімка конфігурації джерела (до розкриття), а не з розкритих секретних значень середовища виконання.
|
||||
|
||||
### Докладно про поля провайдера
|
||||
|
||||
- `models.mode`: поведінка каталогу провайдерів (`merge` або `replace`).
|
||||
- `models.providers`: мапа користувацьких провайдерів, ключована ідентифікатором провайдера.
|
||||
- Безпечне редагування: використовуйте `openclaw config set models.providers.<id> '<json>' --strict-json --merge` або `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` для додаткових оновлень. `config set` відмовляється від руйнівних замін, якщо не передати `--replace`.
|
||||
- `models.mode`: поведінка каталогу провайдера (`merge` або `replace`).
|
||||
- `models.providers`: мапа власних провайдерів, ключована за ідентифікатором провайдера.
|
||||
- Безпечне редагування: використовуйте `openclaw config set models.providers.<id> '<json>' --strict-json --merge` або `openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge` для додаткових оновлень. `config set` відхиляє руйнівні заміни, якщо не передано `--replace`.
|
||||
- `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо).
|
||||
- `models.providers.*.apiKey`: облікові дані провайдера (бажано SecretRef/підстановка змінних середовища).
|
||||
- `models.providers.*.apiKey`: облікові дані провайдера (бажано через підстановку SecretRef/env).
|
||||
- `models.providers.*.auth`: стратегія автентифікації (`api-key`, `token`, `oauth`, `aws-sdk`).
|
||||
- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` додавати `options.num_ctx` у запити (за замовчуванням: `true`).
|
||||
- `models.providers.*.authHeader`: примусово передавати облікові дані в заголовку `Authorization`, коли це потрібно.
|
||||
- `models.providers.*.baseUrl`: базова URL-адреса висхідного API.
|
||||
- `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації через проксі/орендаря.
|
||||
- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів до провайдера моделі.
|
||||
- `request.headers`: додаткові заголовки (об’єднуються зі значеннями провайдера за замовчуванням). Значення підтримують SecretRef.
|
||||
- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вставляє `options.num_ctx` у запити (за замовчуванням: `true`).
|
||||
- `models.providers.*.authHeader`: примусово передає облікові дані в заголовку `Authorization`, коли це потрібно.
|
||||
- `models.providers.*.baseUrl`: базовий URL API вище за течією.
|
||||
- `models.providers.*.headers`: додаткові статичні заголовки для проксі/маршрутизації орендарів.
|
||||
- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів провайдера моделей.
|
||||
- `request.headers`: додаткові заголовки (зливаються зі значеннями провайдера за замовчуванням). Значення підтримують SecretRef.
|
||||
- `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value`, необов’язковим `prefix`).
|
||||
- `request.proxy`: перевизначення HTTP-проксі. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими підтримують необов’язковий підоб’єкт `tls`.
|
||||
- `request.tls`: перевизначення TLS для прямих з’єднань. Поля: `ca`, `cert`, `key`, `passphrase` (усі підтримують SecretRef), `serverName`, `insecureSkipVerify`.
|
||||
- `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS розв’язується у приватні, CGNAT або подібні діапазони, через захист HTTP fetch провайдера (явне ввімкнення оператором для довірених самостійно розміщених OpenAI-сумісних кінцевих точок). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-запобіжник fetch. За замовчуванням `false`.
|
||||
- `request.allowPrivateNetwork`: якщо `true`, дозволяє HTTPS до `baseUrl`, коли DNS резолвиться в приватні, CGNAT або подібні діапазони, через захист HTTP fetch провайдера (явне рішення оператора для довірених самостійно розміщених OpenAI-сумісних кінцевих точок). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-захист fetch. За замовчуванням `false`.
|
||||
- `models.providers.*.models`: явні записи каталогу моделей провайдера.
|
||||
- `models.providers.*.models.*.contextWindow`: метадані власного вікна контексту моделі.
|
||||
- `models.providers.*.models.*.contextTokens`: необов’язкове обмеження контексту середовища виконання. Використовуйте це, коли хочете менший ефективний бюджет контексту, ніж власний `contextWindow` моделі.
|
||||
- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім не-власним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це значення в `false` під час виконання. Порожній/відсутній `baseUrl` зберігає стандартну поведінку OpenAI.
|
||||
- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-сумісних chat-кінцевих точок, що приймають лише рядки. Коли `true`, OpenClaw сплющує масиви `messages[].content`, які містять лише текст, у звичайні рядки перед надсиланням запиту.
|
||||
- `plugins.entries.amazon-bedrock.config.discovery`: корінь налаштувань авто-виявлення Bedrock.
|
||||
- `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне виявлення.
|
||||
- `models.providers.*.models.*.contextWindow`: метадані рідного вікна контексту моделі.
|
||||
- `models.providers.*.models.*.contextTokens`: необов’язкове обмеження контексту середовища виконання. Використовуйте це, якщо хочете менший ефективний бюджет контексту, ніж рідний `contextWindow` моделі; `openclaw models list` показує обидва значення, коли вони відрізняються.
|
||||
- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім нерідним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це значення в `false` під час виконання. Порожній/відсутній `baseUrl` зберігає стандартну поведінку OpenAI.
|
||||
- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-сумісних чат-ендпоінтів, що підтримують лише рядки. Якщо `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`: необов’язковий фільтр ідентифікатора провайдера для цільового виявлення.
|
||||
- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: інтервал опитування для оновлення виявлення.
|
||||
- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервне вікно контексту для виявлених моделей.
|
||||
- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервна максимальна кількість токенів виводу для виявлених моделей.
|
||||
- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервне максимальне число вихідних токенів для виявлених моделей.
|
||||
|
||||
### Приклади провайдерів
|
||||
|
||||
@ -486,7 +486,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`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -507,7 +507,7 @@ OpenClaw використовує вбудований каталог модел
|
||||
|
||||
- Загальна кінцева точка: `https://api.z.ai/api/paas/v4`
|
||||
- Кінцева точка для кодування (за замовчуванням): `https://api.z.ai/api/coding/paas/v4`
|
||||
- Для загальної кінцевої точки визначте користувацького провайдера з перевизначенням base URL.
|
||||
- Для загальної кінцевої точки визначте власного провайдера з перевизначенням base URL.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -546,9 +546,9 @@ OpenClaw використовує вбудований каталог модел
|
||||
}
|
||||
```
|
||||
|
||||
Для кінцевої точки в Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`.
|
||||
Для китайської кінцевої точки: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`.
|
||||
|
||||
Власні кінцеві точки Moonshot оголошують сумісність потокового використання на спільному
|
||||
Рідні кінцеві точки Moonshot оголошують сумісність використання потокової передачі на спільному
|
||||
транспорті `openai-completions`, і OpenClaw визначає це за можливостями кінцевої точки,
|
||||
а не лише за ідентифікатором вбудованого провайдера.
|
||||
|
||||
@ -607,7 +607,7 @@ OpenClaw використовує вбудований каталог модел
|
||||
}
|
||||
```
|
||||
|
||||
Base URL має не містити `/v1` (клієнт Anthropic додає його сам). Скорочений варіант: `openclaw onboard --auth-choice synthetic-api-key`.
|
||||
Base URL має не містити `/v1` (клієнт Anthropic додає його). Скорочений варіант: `openclaw onboard --auth-choice synthetic-api-key`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -652,15 +652,15 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й
|
||||
`openclaw onboard --auth-choice minimax-cn-api`.
|
||||
Каталог моделей за замовчуванням містить лише M2.7.
|
||||
На Anthropic-сумісному шляху потокової передачі OpenClaw вимикає thinking
|
||||
за замовчуванням, якщо ви явно не задасте `thinking` самостійно. `/fast on` або
|
||||
для MiniMax за замовчуванням, якщо ви явно не задасте `thinking` самостійно. `/fast on` або
|
||||
`params.fastMode: true` переписує `MiniMax-M2.7` на
|
||||
`MiniMax-M2.7-highspeed`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Локальні моделі">
|
||||
<Accordion title="Локальні моделі (LM Studio)">
|
||||
|
||||
Див. [Локальні моделі](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на достатньо потужному обладнанні; залишайте розміщені моделі об’єднаними для резервного використання.
|
||||
Див. [Локальні моделі](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на достатньо потужному обладнанні; залишайте об’єднаними розміщені моделі як резервний варіант.
|
||||
|
||||
</Accordion>
|
||||
|
||||
|
||||
@ -1,61 +1,99 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібні точні семантики полів конфігурації або значення за замовчуванням
|
||||
- Ви перевіряєте блоки конфігурації каналів, моделей, Gateway або інструментів
|
||||
summary: Довідка з конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем
|
||||
title: Довідка з конфігурації
|
||||
- Вам потрібні точні семантики або значення за замовчуванням конфігурації на рівні полів
|
||||
- Ви перевіряєте блоки конфігурації каналу, моделі, Gateway або інструмента
|
||||
summary: Довідник конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем
|
||||
title: Довідник конфігурації
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T05:55:51Z"
|
||||
generated_at: "2026-04-25T07:01:56Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6fc32c7387a8ece01020342186b52202d954a44c6db3fa827a5ed4302e995af7
|
||||
source_hash: a0f69861c754e0f6d3e41ac357fa56612b90da69249c6f24ec9f6ade21acc1d3
|
||||
source_path: gateway/configuration-reference.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Основна довідка з конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration).
|
||||
Основний довідник конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Конфігурація](/uk/gateway/configuration).
|
||||
|
||||
Охоплює основні поверхні конфігурації OpenClaw і містить посилання назовні, коли підсистема має власну глибшу довідку. Каталоги команд, що належать каналам і Plugin, а також глибокі параметри пам’яті/QMD розміщено на окремих сторінках, а не тут.
|
||||
Охоплює основні поверхні конфігурації OpenClaw і надає посилання назовні, коли підсистема має власний глибший довідник. Каталоги команд, що належать каналам і Plugin, а також детальні параметри пам’яті/QMD розміщені на окремих сторінках, а не тут.
|
||||
|
||||
Джерело істини в коді:
|
||||
|
||||
- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, із вбудованими метаданими Plugin/каналів, об’єднаними за наявності
|
||||
- `config.schema.lookup` повертає один вузол схеми для певного шляху для інструментів детального перегляду
|
||||
- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють baseline hash документації конфігурації щодо поточної поверхні схеми
|
||||
- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, із об’єднаними метаданими bundled/plugin/channel, коли вони доступні
|
||||
- `config.schema.lookup` повертає один вузол схеми для вказаного шляху для інструментів детального перегляду
|
||||
- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш документації конфігурації відносно поточної поверхні схеми
|
||||
|
||||
Окремі глибокі довідники:
|
||||
Окремі поглиблені довідники:
|
||||
|
||||
- [Memory configuration reference](/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 команд
|
||||
- сторінки каналів/Plugin-власників для поверхонь команд, специфічних для каналу
|
||||
- [Довідник конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming`
|
||||
- [Slash-команди](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд
|
||||
- сторінки відповідного каналу/Plugin для поверхонь команд, специфічних для каналу
|
||||
|
||||
Формат конфігурації — **JSON5** (дозволено коментарі та завершаючі коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не задано.
|
||||
Формат конфігурації — **JSON5** (дозволені коментарі та кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено.
|
||||
|
||||
---
|
||||
|
||||
## Канали
|
||||
|
||||
Ключі конфігурації для окремих каналів перенесено на окрему сторінку — див.
|
||||
[Configuration — channels](/uk/gateway/config-channels) для `channels.*`,
|
||||
включно зі Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та іншими
|
||||
bundled каналами (автентифікація, контроль доступу, кілька облікових записів, обмеження за згадками).
|
||||
Ключі конфігурації для кожного каналу перенесено на окрему сторінку — див.
|
||||
[Конфігурація — канали](/uk/gateway/config-channels) для `channels.*`,
|
||||
зокрема Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та інших
|
||||
bundled каналів (автентифікація, контроль доступу, кілька облікових записів, керування згадками).
|
||||
|
||||
## Типові значення агента, мультиагентність, сесії та повідомлення
|
||||
## Значення агента за замовчуванням, multi-agent, сесії та повідомлення
|
||||
|
||||
Перенесено на окрему сторінку — див.
|
||||
[Configuration — agents](/uk/gateway/config-agents) для:
|
||||
[Конфігурація — агенти](/uk/gateway/config-agents) для:
|
||||
|
||||
- `agents.defaults.*` (робочий простір, модель, thinking, heartbeat, пам’ять, медіа, Skills, sandbox)
|
||||
- `multiAgent.*` (маршрутизація та прив’язки мультиагентності)
|
||||
- `session.*` (життєвий цикл сесії, compaction, prунінг)
|
||||
- `agents.defaults.*` (робочий простір, модель, thinking, Heartbeat, пам’ять, медіа, Skills, sandbox)
|
||||
- `multiAgent.*` (маршрутизація та прив’язки multi-agent)
|
||||
- `session.*` (життєвий цикл сесії, Compaction, очищення)
|
||||
- `messages.*` (доставка повідомлень, TTS, рендеринг markdown)
|
||||
- `talk.*` (режим Talk)
|
||||
- `talk.silenceTimeoutMs`: якщо не задано, Talk зберігає типове для платформи вікно паузи перед надсиланням транскрипту (`700 ms на macOS та Android, 900 ms на iOS`)
|
||||
- `talk.silenceTimeoutMs`: якщо не задано, Talk зберігає стандартне для платформи вікно паузи перед надсиланням транскрипту (`700 ms на macOS та Android, 900 ms на iOS`)
|
||||
|
||||
## Інструменти та власні провайдери
|
||||
## Інструменти та користувацькі провайдери
|
||||
|
||||
Політика інструментів, експериментальні перемикачі, конфігурація інструментів із підтримкою провайдерів і налаштування власних провайдерів / base-URL перенесені на окрему сторінку — див.
|
||||
[Configuration — tools and custom providers](/uk/gateway/config-tools).
|
||||
Політика інструментів, експериментальні перемикачі, конфігурація інструментів на базі провайдерів і налаштування користувацьких провайдерів / базових URL перенесено на окрему сторінку — див.
|
||||
[Конфігурація — інструменти та користувацькі провайдери](/uk/gateway/config-tools).
|
||||
|
||||
## MCP
|
||||
|
||||
Визначення MCP-серверів, якими керує OpenClaw, знаходяться в `mcp.servers` і
|
||||
використовуються вбудованим Pi та іншими адаптерами часу виконання. Команди `openclaw mcp list`,
|
||||
`show`, `set` і `unset` керують цим блоком без підключення до
|
||||
цільового сервера під час редагування конфігурації.
|
||||
|
||||
```json5
|
||||
{
|
||||
mcp: {
|
||||
// Необов’язково. За замовчуванням: 600000 ms (10 хвилин). Установіть 0, щоб вимкнути видалення при простої.
|
||||
sessionIdleTtlMs: 600000,
|
||||
servers: {
|
||||
docs: {
|
||||
command: "npx",
|
||||
args: ["-y", "@modelcontextprotocol/server-fetch"],
|
||||
},
|
||||
remote: {
|
||||
url: "https://example.com/mcp",
|
||||
transport: "streamable-http", // streamable-http | sse
|
||||
headers: {
|
||||
Authorization: "Bearer ${MCP_REMOTE_TOKEN}",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
- `mcp.servers`: іменовані визначення stdio або віддалених MCP-серверів для середовищ виконання, які
|
||||
надають налаштовані інструменти MCP.
|
||||
- `mcp.sessionIdleTtlMs`: TTL простою для bundled MCP runtime з областю дії сесії.
|
||||
Одноразові вбудовані запуски запитують очищення наприкінці запуску; цей TTL є запасним механізмом для
|
||||
довготривалих сесій і майбутніх викликів.
|
||||
|
||||
Див. [MCP](/uk/cli/mcp#openclaw-as-an-mcp-client-registry) і
|
||||
[CLI backends](/uk/gateway/cli-backends#bundle-mcp-overlays) для поведінки під час виконання.
|
||||
|
||||
## Skills
|
||||
|
||||
@ -82,14 +120,14 @@ bundled каналами (автентифікація, контроль дос
|
||||
}
|
||||
```
|
||||
|
||||
- `allowBundled`: необов’язковий allowlist лише для bundled Skills (керовані/робочі Skills не зачіпаються).
|
||||
- `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет).
|
||||
- `install.preferBrew`: якщо true, віддавати перевагу інсталяторам Homebrew, коли `brew`
|
||||
доступний, перед переходом до інших типів інсталяторів.
|
||||
- `install.nodeManager`: пріоритет менеджера Node для специфікацій `metadata.openclaw.install`
|
||||
- `allowBundled`: необов’язковий список дозволу лише для bundled skills (керовані/workspace skills не зачіпаються).
|
||||
- `load.extraDirs`: додаткові спільні корені skills (найнижчий пріоритет).
|
||||
- `install.preferBrew`: якщо `true`, надавати перевагу інсталяторам Homebrew, коли `brew`
|
||||
доступний, перш ніж переходити до інших типів інсталяторів.
|
||||
- `install.nodeManager`: бажаний менеджер вузлів для специфікацій `metadata.openclaw.install`
|
||||
(`npm` | `pnpm` | `yarn` | `bun`).
|
||||
- `entries.<skillKey>.enabled: false` вимикає Skill, навіть якщо він bundled/installed.
|
||||
- `entries.<skillKey>.apiKey`: спрощене поле для Skills, які оголошують основну env-змінну (рядок відкритого тексту або об’єкт SecretRef).
|
||||
- `entries.<skillKey>.enabled: false` вимикає skill, навіть якщо він bundled/інстальований.
|
||||
- `entries.<skillKey>.apiKey`: зручне поле для skills, які оголошують основну змінну середовища (простий текстовий рядок або об’єкт SecretRef).
|
||||
|
||||
---
|
||||
|
||||
@ -117,43 +155,43 @@ bundled каналами (автентифікація, контроль дос
|
||||
}
|
||||
```
|
||||
|
||||
- Завантажуються з `~/.openclaw/extensions`, `<workspace>/.openclaw/extensions` і `plugins.load.paths`.
|
||||
- Виявлення приймає нативні Plugin OpenClaw, а також сумісні bundles Codex і Claude, включно з bundles Claude зі стандартним макетом без manifest.
|
||||
- **Зміни конфігурації потребують перезапуску gateway.**
|
||||
- `allow`: необов’язковий allowlist (завантажуються лише перелічені Plugin). `deny` має пріоритет.
|
||||
- `plugins.entries.<id>.apiKey`: спрощене поле API-ключа на рівні Plugin (коли підтримується Plugin).
|
||||
- `plugins.entries.<id>.env`: мапа env-змінних у межах Plugin.
|
||||
- `plugins.entries.<id>.hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` і ігнорує поля, що змінюють prompt, із застарілого `before_agent_start`, зберігаючи застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hooks Plugin і підтримуваних директорій hooks, наданих bundle.
|
||||
- `plugins.entries.<id>.hooks.allowConversationAccess`: коли `true`, довірені неbundled Plugin можуть читати сирий вміст розмови з типізованих hooks, таких як `llm_input`, `llm_output` і `agent_end`.
|
||||
- `plugins.entries.<id>.subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремого запуску фонових subagent.
|
||||
- `plugins.entries.<id>.subagent.allowedModels`: необов’язковий allowlist канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"`, лише якщо свідомо хочете дозволити будь-яку модель.
|
||||
- `plugins.entries.<id>.config`: об’єкт конфігурації, визначений Plugin (валідується схемою нативного Plugin OpenClaw, якщо доступна).
|
||||
- Налаштування облікового запису/runtime для Plugin-каналів розміщуються в `channels.<id>` і мають описуватися метаданими `channelConfigs` у manifest Plugin-власника, а не центральним реєстром параметрів OpenClaw.
|
||||
- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера Firecrawl web-fetch.
|
||||
- `apiKey`: API-ключ Firecrawl (приймає SecretRef). Використовує резервне значення з `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілого `tools.web.fetch.firecrawl.apiKey` або env-змінної `FIRECRAWL_API_KEY`.
|
||||
- `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`).
|
||||
- `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`).
|
||||
- `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні).
|
||||
- `timeoutSeconds`: тайм-аут scrape-запиту в секундах (типово: `60`).
|
||||
- Завантажуються з `~/.openclaw/extensions`, `<workspace>/.openclaw/extensions`, а також `plugins.load.paths`.
|
||||
- Виявлення підтримує нативні Plugins OpenClaw, а також сумісні пакети Codex і Claude, включно з пакетами Claude стандартного макета без маніфесту.
|
||||
- **Зміни конфігурації потребують перезапуску Gateway.**
|
||||
- `allow`: необов’язковий список дозволу (завантажуються лише перелічені Plugins). `deny` має пріоритет.
|
||||
- `plugins.entries.<id>.apiKey`: зручне поле API-ключа на рівні Plugin (коли підтримується Plugin).
|
||||
- `plugins.entries.<id>.env`: карта змінних середовища в межах Plugin.
|
||||
- `plugins.entries.<id>.hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` та ігнорує поля зміни prompt із застарілого `before_agent_start`, зберігаючи при цьому застарілі `modelOverride` і `providerOverride`. Застосовується до нативних хуків Plugin і підтримуваних каталогів хуків, наданих пакетами.
|
||||
- `plugins.entries.<id>.hooks.allowConversationAccess`: коли `true`, довірені небандловані Plugins можуть читати сирий вміст розмови з типізованих хуків, таких як `llm_input`, `llm_output` і `agent_end`.
|
||||
- `plugins.entries.<id>.subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для кожного запуску фонових підзапусків subagent.
|
||||
- `plugins.entries.<id>.subagent.allowedModels`: необов’язковий список дозволу канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли ви свідомо хочете дозволити будь-яку модель.
|
||||
- `plugins.entries.<id>.config`: об’єкт конфігурації, визначений Plugin (перевіряється схемою нативного Plugin OpenClaw, якщо доступна).
|
||||
- Налаштування облікових записів/runtime для плагінів каналів містяться в `channels.<id>` і мають описуватися метаданими `channelConfigs` у маніфесті відповідного Plugin, а не центральним реєстром опцій OpenClaw.
|
||||
- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl.
|
||||
- `apiKey`: API-ключ Firecrawl (підтримує SecretRef). Використовує як резервне джерело `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілий `tools.web.fetch.firecrawl.apiKey` або змінну середовища `FIRECRAWL_API_KEY`.
|
||||
- `baseUrl`: базовий URL API Firecrawl (за замовчуванням: `https://api.firecrawl.dev`).
|
||||
- `onlyMainContent`: витягувати лише основний вміст сторінок (за замовчуванням: `true`).
|
||||
- `maxAgeMs`: максимальний вік кешу в мілісекундах (за замовчуванням: `172800000` / 2 дні).
|
||||
- `timeoutSeconds`: тайм-аут запиту на скрапінг у секундах (за замовчуванням: `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 * * *"`).
|
||||
- `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 configuration reference](/uk/reference/memory-config):
|
||||
- Повна конфігурація пам’яті міститься в [Довіднику конфігурації пам’яті](/uk/reference/memory-config):
|
||||
- `agents.defaults.memorySearch.*`
|
||||
- `memory.backend`
|
||||
- `memory.citations`
|
||||
- `memory.qmd.*`
|
||||
- `plugins.entries.memory-core.config.dreaming`
|
||||
- Увімкнені Plugin-бандли Claude також можуть додавати вбудовані типові значення Pi з `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі конфігурації OpenClaw.
|
||||
- `plugins.slots.memory`: вибрати id активного Plugin пам’яті або `"none"`, щоб вимкнути Plugin пам’яті.
|
||||
- `plugins.slots.contextEngine`: вибрати id активного Plugin engine контексту; типово `"legacy"`, якщо ви не встановили й не вибрали інший engine.
|
||||
- `plugins.installs`: керовані CLI метадані встановлення, які використовує `openclaw plugins update`.
|
||||
- Містить `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`.
|
||||
- Сприймайте `plugins.installs.*` як керований стан; віддавайте перевагу командам CLI замість ручного редагування.
|
||||
- Увімкнені Plugins Claude bundle також можуть надавати вбудовані значення Pi за замовчуванням із `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі конфігурації OpenClaw.
|
||||
- `plugins.slots.memory`: вибір id активного плагіна пам’яті або `"none"` для вимкнення плагінів пам’яті.
|
||||
- `plugins.slots.contextEngine`: вибір id активного плагіна рушія контексту; за замовчуванням `"legacy"`, якщо ви не встановите й не виберете інший рушій.
|
||||
- `plugins.installs`: метадані інсталяції, керовані CLI, які використовуються `openclaw plugins update`.
|
||||
- Містять `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`.
|
||||
- Розглядайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI над ручними редагуваннями.
|
||||
|
||||
Див. [Plugins](/uk/tools/plugin).
|
||||
|
||||
@ -168,8 +206,8 @@ bundled каналами (автентифікація, контроль дос
|
||||
evaluateEnabled: true,
|
||||
defaultProfile: "user",
|
||||
ssrfPolicy: {
|
||||
// dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
|
||||
// allowPrivateNetwork: true, // legacy alias
|
||||
// dangerouslyAllowPrivateNetwork: true, // вмикайте лише для довіреного доступу до приватної мережі
|
||||
// allowPrivateNetwork: true, // застарілий псевдонім
|
||||
// hostnameAllowlist: ["*.example.com", "example.com"],
|
||||
// allowedHostnames: ["localhost"],
|
||||
},
|
||||
@ -209,31 +247,31 @@ bundled каналами (автентифікація, контроль дос
|
||||
- `tabCleanup` звільняє відстежувані вкладки основного агента після простою або коли
|
||||
сесія перевищує свій ліміт. Установіть `idleMinutes: 0` або `maxTabsPerSession: 0`, щоб
|
||||
вимкнути ці окремі режими очищення.
|
||||
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація браузера за замовчуванням лишається суворою.
|
||||
- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true`, лише якщо ви свідомо довіряєте навігації браузера в приватній мережі.
|
||||
- У суворому режимі віддалені кінцеві точки профілів CDP (`profiles.*.cdpUrl`) підпадають під ті самі обмеження приватної мережі під час перевірок доступності/виявлення.
|
||||
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація браузера за замовчуванням залишається суворо обмеженою.
|
||||
- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації браузера в приватній мережі.
|
||||
- У суворому режимі кінцеві точки віддалених профілів CDP (`profiles.*.cdpUrl`) підлягають такому самому блокуванню приватної мережі під час перевірок доступності/виявлення.
|
||||
- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім.
|
||||
- У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків.
|
||||
- Віддалені профілі є лише attach-only (start/stop/reset недоступні).
|
||||
- Віддалені профілі працюють лише в режимі attach-only (запуск/зупинка/скидання вимкнені).
|
||||
- `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`, щоб націлитися на конкретний
|
||||
профіль браузера на базі Chromium, такий як Brave або Edge.
|
||||
- Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP:
|
||||
дії на основі snapshot/ref замість націлювання на CSS-selector, hooks завантаження одного файлу,
|
||||
відсутність перевизначення тайм-ауту діалогів, відсутність `wait --load networkidle`, а також
|
||||
`responsebody`, експорту PDF, перехоплення завантажень чи пакетних дій.
|
||||
Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S),
|
||||
коли ваш провайдер надає вам прямий URL WebSocket DevTools.
|
||||
- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися на
|
||||
вибраному хості або через підключений browser node.
|
||||
- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний
|
||||
профіль браузера на базі Chromium, наприклад Brave або Edge.
|
||||
- Профілі `existing-session` зберігають поточні обмеження маршрутизації Chrome MCP:
|
||||
дії на основі snapshot/ref замість націлювання за CSS-селекторами, хуки завантаження
|
||||
одного файла, без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без
|
||||
`responsebody`, експорту PDF, перехоплення завантажень або пакетних дій.
|
||||
- Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно
|
||||
задавайте `cdpUrl` лише для віддаленого CDP.
|
||||
- Локальні керовані профілі можуть встановлювати `executablePath`, щоб перевизначити глобальний
|
||||
- Локальні керовані профілі можуть задавати `executablePath`, щоб перевизначити глобальний
|
||||
`browser.executablePath` для цього профілю. Використовуйте це, щоб запускати один профіль у
|
||||
Chrome, а інший — у Brave.
|
||||
- Порядок автодетекції: браузер за замовчуванням, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
- `browser.executablePath` приймає `~` для домашньої директорії вашої ОС.
|
||||
- Сервіс керування: лише loopback (порт похідний від `gateway.port`, типово `18791`).
|
||||
- Порядок автовиявлення: браузер за замовчуванням, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
|
||||
- `browser.executablePath` приймає `~` для домашнього каталогу вашої ОС.
|
||||
- Служба керування: лише local loopback (порт визначається з `gateway.port`, за замовчуванням `18791`).
|
||||
- `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад,
|
||||
`--disable-gpu`, розмір вікна або прапорці налагодження).
|
||||
|
||||
@ -253,8 +291,8 @@ bundled каналами (автентифікація, контроль дос
|
||||
}
|
||||
```
|
||||
|
||||
- `seamColor`: колір акценту для chrome інтерфейсу нативного застосунку (відтінок бульбашки Talk Mode тощо).
|
||||
- `assistant`: перевизначення ідентичності в Control UI. Використовує резервне значення з ідентичності активного агента.
|
||||
- `seamColor`: акцентний колір для chrome інтерфейсу нативного застосунку (відтінок бульбашки режиму Talk тощо).
|
||||
- `assistant`: перевизначення ідентичності для Control UI. Якщо не задано, використовується ідентичність активного агента.
|
||||
|
||||
---
|
||||
|
||||
@ -329,71 +367,70 @@ bundled каналами (автентифікація, контроль дос
|
||||
}
|
||||
```
|
||||
|
||||
<Accordion title="Докладно про поля Gateway">
|
||||
<Accordion title="Відомості про поля Gateway">
|
||||
|
||||
- `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`.
|
||||
- `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо не вказано `local`.
|
||||
- `port`: єдиний мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`.
|
||||
- `bind`: `auto`, `loopback` (типово), `lan` (`0.0.0.0`), `tailnet` (лише Tailscale IP) або `custom`.
|
||||
- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми host (`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**: обов’язкова за замовчуванням. Прив’язки не до loopback вимагають auth gateway. На практиці це означає спільний token/password або reverse proxy з контролем ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер onboarding типово генерує token.
|
||||
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно встановіть `gateway.auth.mode` у `token` або `password`. Під час запуску та в потоках встановлення/відновлення сервісу виникає помилка, якщо налаштовано обидва, а mode не задано.
|
||||
- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних налаштувань local loopback; цей варіант навмисно не пропонується в підказках onboarding.
|
||||
- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з контролем ідентичності та довіряти заголовкам ідентичності від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy на тому самому хості через loopback не задовольняють auth trusted-proxy.
|
||||
- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти auth Control UI/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цю auth через заголовки Tailscale; для них застосовується звичайний режим HTTP auth gateway. Цей безтокенний потік припускає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`.
|
||||
- `gateway.auth.rateLimit`: необов’язковий лімітатор невдалих auth-спроб. Застосовується окремо для кожного IP клієнта та для кожного scope auth (спільний секрет і token пристрою відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`.
|
||||
- На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні помилкові спроби від того самого клієнта можуть спровокувати лімітатор на другому запиті замість того, щоб обидві просто завершилися звичайною невідповідністю.
|
||||
- `gateway.auth.rateLimit.exemptLoopback` типово дорівнює `true`; встановіть `false`, якщо свідомо хочете також обмежувати трафік localhost (для тестових налаштувань або строгих proxy-розгортань).
|
||||
- Спроби WS auth із browser-origin завжди обмежуються з вимкненим винятком loopback (додатковий захист від brute force localhost через браузер).
|
||||
- На loopback ці блокування для browser-origin ізольовані за нормалізованим значенням `Origin`,
|
||||
тому повторні збої з одного origin localhost не блокують автоматично інший origin.
|
||||
- `tailscale.mode`: `serve` (лише tailnet, bind до loopback) або `funnel` (публічний, потребує auth).
|
||||
- `controlUi.allowedOrigins`: явний allowlist browser-origin для підключень WebSocket до Gateway. Обов’язковий, коли очікуються клієнти браузера з не-loopback origin.
|
||||
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, що вмикає fallback origin за заголовком Host для розгортань, які навмисно покладаються на політику origin за заголовком Host.
|
||||
- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`.
|
||||
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійний client-side override
|
||||
у середовищі процесу, який дозволяє незашифрований `ws://` до довірених IP
|
||||
приватної мережі; за замовчуванням незашифрований трафік як і раніше дозволено лише для loopback. Еквівалента в `openclaw.json` немає, а конфігурація приватної мережі браузера, така як
|
||||
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на клієнти
|
||||
WebSocket Gateway.
|
||||
- `gateway.remote.token` / `.password`: поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway.
|
||||
- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL зовнішнього relay APNs, який використовується офіційними/TestFlight збірками iOS після публікації relay-backed реєстрацій у gateway. Цей URL має збігатися з URL relay, зібраним у збірку iOS.
|
||||
- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. Типово `10000`.
|
||||
- Реєстрації з relay-backed прив’язуються до конкретної ідентичності gateway. Сполучений застосунок iOS викликає `gateway.identity.get`, включає цю ідентичність до реєстрації relay і пересилає до gateway send grant на рівні реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію.
|
||||
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові env-перевизначення для наведеної вище конфігурації relay.
|
||||
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: лише для розробки — аварійний дозвіл на loopback HTTP relay URL. У production URL relay мають залишатися на HTTPS.
|
||||
- `gateway.channelHealthCheckMinutes`: інтервал моніторингу здоров’я каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типово: `5`.
|
||||
- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`.
|
||||
- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor на канал/обліковий запис за ковзну годину. Типово: `10`.
|
||||
- `channels.<provider>.healthMonitor.enabled`: відмова від перезапусків health-monitor на рівні каналу зі збереженням увімкненого глобального монітора.
|
||||
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`: перевизначення на рівні облікового запису для каналів із кількома обліковими записами. Якщо задано, має пріоритет над перевизначенням на рівні каналу.
|
||||
- Локальні шляхи викликів gateway можуть використовувати `gateway.remote.*` як fallback лише тоді, коли `gateway.auth.*` не задано.
|
||||
- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і їх не вдається розв’язати, розв’язання завершується fail-closed (без маскування через fallback на remote).
|
||||
- `trustedProxies`: IP reverse proxy, які завершують TLS або вставляють заголовки forwarded-client. Додавайте лише ті proxy, які ви контролюєте. Записи loopback усе ще валідні для налаштувань proxy/local-detection на тому самому хості (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. Типово `false` для fail-closed поведінки.
|
||||
- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий allowlist CIDR/IP для автоматичного підтвердження першого сполучення пристрою вузла без запитаних scope. Якщо не задано, вимкнено. Це не підтверджує автоматично сполучення operator/browser/Control UI/WebChat і не підтверджує автоматично оновлення role, scope, metadata чи public-key.
|
||||
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування allow/deny для оголошених команд вузлів після сполучення та перевірки allowlist.
|
||||
- `gateway.tools.deny`: додаткові імена інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий deny list).
|
||||
- `gateway.tools.allow`: прибрати імена інструментів із типового HTTP deny list.
|
||||
- `bind`: `auto`, `loopback` (за замовчуванням), `lan` (`0.0.0.0`), `tailnet` (лише IP Tailscale) або `custom`.
|
||||
- **Застарілі псевдоніми 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**: за замовчуванням обов’язкова. Прив’язки не до loopback вимагають auth gateway. На практиці це означає спільний token/password або reverse proxy з урахуванням ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер початкового налаштування за замовчуванням генерує token.
|
||||
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно встановіть `gateway.auth.mode` у `token` або `password`. Запуск і потоки встановлення/відновлення сервісу завершуються помилкою, якщо налаштовано обидва, а режим не задано.
|
||||
- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних налаштувань local loopback; цей варіант навмисно не пропонується в запитах початкового налаштування.
|
||||
- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з урахуванням ідентичності та довіряти заголовкам ідентичності від `gateway.trustedProxies` (див. [Auth через Trusted Proxy](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy loopback на тому ж хості не задовольняють auth trusted-proxy.
|
||||
- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цю auth через заголовки Tailscale; вони натомість дотримуються звичайного режиму HTTP auth gateway. Цей безтокеновий потік передбачає, що хост gateway є довіреним. За замовчуванням `true`, коли `tailscale.mode = "serve"`.
|
||||
- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб auth. Застосовується окремо до IP клієнта і до області auth (спільний секрет і токен пристрою відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`.
|
||||
- В асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом збою. Тому одночасні хибні спроби від того самого клієнта можуть активувати ліміт уже на другому запиті, замість того щоб обидві пройшли як звичайні невідповідності.
|
||||
- `gateway.auth.rateLimit.exemptLoopback` за замовчуванням має значення `true`; установіть `false`, якщо ви навмисно хочете також застосовувати rate limit до localhost-трафіку (для тестових середовищ або суворих proxy-розгортань).
|
||||
- Спроби WS auth з походження browser завжди обмежуються без винятку для loopback (додатковий захист від brute force localhost через browser).
|
||||
- У loopback ці блокування для походження browser ізольовані за нормалізованим значенням `Origin`,
|
||||
тож повторні збої з одного localhost-origin не блокують автоматично
|
||||
інше origin.
|
||||
- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічний доступ, потребує auth).
|
||||
- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язково, якщо очікуються browser-клієнти з origin не-loopback.
|
||||
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає резервне визначення origin через заголовок Host для розгортань, що навмисно покладаються на політику origin за заголовком Host.
|
||||
- `remote.transport`: `ssh` (за замовчуванням) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`.
|
||||
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійний client-side override через змінну середовища процесу,
|
||||
що дозволяє відкритий `ws://` до довірених IP приватної мережі; за замовчуванням відкритий текст лишається дозволеним лише для loopback. Еквівалента в `openclaw.json` немає, а конфігурація приватної мережі browser, така як
|
||||
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на WebSocket-клієнти Gateway.
|
||||
- `gateway.remote.token` / `.password`: поля облікових даних віддаленого клієнта. Самі по собі вони не налаштовують auth gateway.
|
||||
- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL зовнішнього relay APNs, який використовують офіційні/TestFlight збірки iOS після публікації в gateway реєстрацій на основі relay. Цей URL має збігатися з URL relay, скомпільованим у збірку iOS.
|
||||
- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. За замовчуванням `10000`.
|
||||
- Реєстрації на основі relay делегуються конкретній ідентичності gateway. Зв’язаний застосунок iOS отримує `gateway.identity.get`, включає цю ідентичність у реєстрацію relay і пересилає в gateway право надсилання в межах реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію.
|
||||
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові env override для конфігурації relay вище.
|
||||
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний виняток лише для розробки для loopback HTTP URL relay. У production URL relay мають залишатися на HTTPS.
|
||||
- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналів у хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски монітором стану. За замовчуванням: `5`.
|
||||
- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого socket у хвилинах. Зберігайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. За замовчуванням: `30`.
|
||||
- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітором стану на канал/обліковий запис за ковзну годину. За замовчуванням: `10`.
|
||||
- `channels.<provider>.healthMonitor.enabled`: відмова від перезапусків монітором стану для окремого каналу, зберігаючи глобальний монітор увімкненим.
|
||||
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`: перевизначення на рівні облікового запису для каналів з кількома обліковими записами. Якщо задано, має пріоритет над перевизначенням на рівні каналу.
|
||||
- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано.
|
||||
- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання завершується за принципом fail closed (без маскування резервним віддаленим варіантом).
|
||||
- `trustedProxies`: IP reverse proxy, які завершують TLS або додають заголовки forwarded-client. Додавайте лише proxy, які ви контролюєте. Записи loopback усе ще коректні для налаштувань proxy/локального виявлення на тому самому хості (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. За замовчуванням `false` для поведінки fail closed.
|
||||
- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий список дозволу CIDR/IP для автоматичного схвалення першого pairing пристроїв node без запитаних областей доступу. Якщо не задано, вимкнено. Це не схвалює автоматично pairing operator/browser/Control UI/WebChat, а також не схвалює автоматично оновлення ролей, областей доступу, метаданих або публічних ключів.
|
||||
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування дозволу/заборони для оголошених команд node після pairing та оцінки списку дозволу.
|
||||
- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює стандартний список заборон).
|
||||
- `gateway.tools.allow`: прибрати назви інструментів зі стандартного HTTP-списку заборон.
|
||||
|
||||
</Accordion>
|
||||
|
||||
### OpenAI-сумісні кінцеві точки
|
||||
### Кінцеві точки, сумісні з OpenAI
|
||||
|
||||
- Chat Completions: вимкнено за замовчуванням. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`.
|
||||
- Responses API: `gateway.http.endpoints.responses.enabled`.
|
||||
- Посилення захисту URL-входів Responses:
|
||||
- Посилене захист URL-входів Responses:
|
||||
- `gateway.http.endpoints.responses.maxUrlParts`
|
||||
- `gateway.http.endpoints.responses.files.urlAllowlist`
|
||||
- `gateway.http.endpoints.responses.images.urlAllowlist`
|
||||
Порожні allowlist трактуються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false`
|
||||
і/або `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.endpoints.responses.files.allowUrl=false`
|
||||
та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL.
|
||||
- Необов’язковий заголовок посиленого захисту відповіді:
|
||||
- `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для HTTPS-origin, які ви контролюєте; див. [Auth через Trusted Proxy](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts))
|
||||
|
||||
### Ізоляція кількох екземплярів
|
||||
|
||||
Запускайте кілька gateway на одному хості з унікальними портами й каталогами стану:
|
||||
Запускайте кілька gateway на одному хості з унікальними портами та каталогами стану:
|
||||
|
||||
```bash
|
||||
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
|
||||
@ -403,7 +440,7 @@ openclaw gateway --port 19001
|
||||
|
||||
Зручні прапорці: `--dev` (використовує `~/.openclaw-dev` + порт `19001`), `--profile <name>` (використовує `~/.openclaw-<name>`).
|
||||
|
||||
Див. [Multiple Gateways](/uk/gateway/multiple-gateways).
|
||||
Див. [Кілька Gateway](/uk/gateway/multiple-gateways).
|
||||
|
||||
### `gateway.tls`
|
||||
|
||||
@ -421,11 +458,11 @@ openclaw gateway --port 19001
|
||||
}
|
||||
```
|
||||
|
||||
- `enabled`: вмикає завершення TLS на listener gateway (HTTPS/WSS) (типово: `false`).
|
||||
- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для local/dev.
|
||||
- `certPath`: шлях у файловій системі до файлу сертифіката TLS.
|
||||
- `keyPath`: шлях у файловій системі до приватного ключа TLS; обмежте права доступу.
|
||||
- `caPath`: необов’язковий шлях до пакета CA для верифікації клієнта або власних ланцюгів довіри.
|
||||
- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (за замовчуванням: `false`).
|
||||
- `autoGenerate`: автоматично генерує локальну самопідписану пару сертифікат/ключ, якщо явні файли не налаштовано; лише для local/dev.
|
||||
- `certPath`: шлях у файловій системі до файла TLS-сертифіката.
|
||||
- `keyPath`: шлях у файловій системі до файла приватного ключа TLS; обмежуйте доступ правами.
|
||||
- `caPath`: необов’язковий шлях до bundle CA для перевірки клієнта або користувацьких ланцюжків довіри.
|
||||
|
||||
### `gateway.reload`
|
||||
|
||||
@ -441,13 +478,13 @@ openclaw gateway --port 19001
|
||||
}
|
||||
```
|
||||
|
||||
- `mode`: керує тим, як зміни конфігурації застосовуються під час runtime.
|
||||
- `"off"`: ігнорувати live-зміни; для змін потрібен явний перезапуск.
|
||||
- `mode`: керує тим, як редагування конфігурації застосовуються під час виконання.
|
||||
- `"off"`: ігнорувати живі зміни; зміни потребують явного перезапуску.
|
||||
- `"restart"`: завжди перезапускати процес gateway після зміни конфігурації.
|
||||
- `"hot"`: застосовувати зміни в процесі без перезапуску.
|
||||
- `"hybrid"` (типово): спочатку спробувати hot reload; за потреби перейти до перезапуску.
|
||||
- `"hot"`: застосовувати зміни в межах процесу без перезапуску.
|
||||
- `"hybrid"` (за замовчуванням): спочатку пробувати hot reload; за потреби переходити до перезапуску.
|
||||
- `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число).
|
||||
- `deferralTimeoutMs`: максимальний час у мс очікування завершення операцій у процесі перед примусовим перезапуском (типово: `300000` = 5 хвилин).
|
||||
- `deferralTimeoutMs`: максимальний час у мс очікування завершення поточних операцій перед примусовим перезапуском (за замовчуванням: `300000` = 5 хвилин).
|
||||
|
||||
---
|
||||
|
||||
@ -485,46 +522,46 @@ openclaw gateway --port 19001
|
||||
```
|
||||
|
||||
Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
Токени hook у query string відхиляються.
|
||||
Hook-токени в query string відхиляються.
|
||||
|
||||
Примітки щодо валідації та безпеки:
|
||||
|
||||
- `hooks.enabled=true` вимагає непорожній `hooks.token`.
|
||||
- `hooks.token` має бути **відмінним** від `gateway.auth.token`; повторне використання token Gateway відхиляється.
|
||||
- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання токена Gateway відхиляється.
|
||||
- `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`.
|
||||
- Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`).
|
||||
- Якщо mapping або preset використовує шаблонний `sessionKey`, установіть `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не потребують цього opt-in.
|
||||
- Якщо mapping або preset використовує шаблонний `sessionKey`, установіть `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не потребують цього явного ввімкнення.
|
||||
|
||||
**Кінцеві точки:**
|
||||
|
||||
- `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` з тіла запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (за замовчуванням: `false`).
|
||||
- `POST /hooks/<name>` → розв’язується через `hooks.mappings`
|
||||
- Значення `sessionKey` у mapping, згенеровані шаблоном, розглядаються як зовнішньо передані й також потребують `hooks.allowRequestSessionKey=true`.
|
||||
- Значення `sessionKey` у mapping, згенеровані шаблоном, вважаються зовнішньо наданими й також потребують `hooks.allowRequestSessionKey=true`.
|
||||
|
||||
<Accordion title="Докладно про mapping">
|
||||
<Accordion title="Відомості про mapping">
|
||||
|
||||
- `match.path` відповідає підшляху після `/hooks` (наприклад `/hooks/gmail` → `gmail`).
|
||||
- `match.path` відповідає підшляху після `/hooks` (наприклад, `/hooks/gmail` → `gmail`).
|
||||
- `match.source` відповідає полю payload для загальних шляхів.
|
||||
- Шаблони на кшталт `{{messages[0].subject}}` читають значення з payload.
|
||||
- Шаблони на кшталт `{{messages[0].subject}}` читають дані з payload.
|
||||
- `transform` може вказувати на модуль JS/TS, який повертає дію hook.
|
||||
- `transform.module` має бути відносним шляхом і лишатися в межах `hooks.transformsDir` (абсолютні шляхи й traversal відхиляються).
|
||||
- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до типового значення.
|
||||
- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або не задано = дозволити всі, `[]` = заборонити всі).
|
||||
- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків агента через hook без явного `sessionKey`.
|
||||
- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і ключам сесій mapping, керованим шаблонами, задавати `sessionKey` (типово: `false`).
|
||||
- `allowedSessionKeyPrefixes`: необов’язковий allowlist префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Стає обов’язковим, коли будь-який mapping або preset використовує шаблонний `sessionKey`.
|
||||
- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово `last`.
|
||||
- `model` перевизначає LLM для цього запуску hook (має бути дозволена, якщо задано каталог моделей).
|
||||
- `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються).
|
||||
- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до значення за замовчуванням.
|
||||
- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або без значення = дозволити всі, `[]` = заборонити всі).
|
||||
- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook agent без явного `sessionKey`.
|
||||
- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і ключам сесії в mapping, керованим шаблонами, задавати `sessionKey` (за замовчуванням: `false`).
|
||||
- `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Він стає обов’язковим, коли будь-який mapping або preset використовує шаблонний `sessionKey`.
|
||||
- `deliver: true` надсилає фінальну відповідь у канал; `channel` за замовчуванням — `last`.
|
||||
- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо задано каталог моделей).
|
||||
|
||||
</Accordion>
|
||||
|
||||
### Інтеграція Gmail
|
||||
### Інтеграція з 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: false`, перевизначте preset статичним `sessionKey` замість шаблонного значення за замовчуванням.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -564,18 +601,18 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- Обслуговує HTML/CSS/JS, які агент може редагувати, і A2UI через HTTP на порту Gateway:
|
||||
- Обслуговує редаговані агентом HTML/CSS/JS і A2UI через HTTP на порту Gateway:
|
||||
- `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
|
||||
- `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
|
||||
- Лише локально: зберігайте `gateway.bind: "loopback"` (типово).
|
||||
- Прив’язки не до loopback: маршрути canvas вимагають auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway.
|
||||
- Node WebView зазвичай не надсилають заголовки auth; після сполучення й підключення вузла Gateway рекламує URL можливостей із scope вузла для доступу до canvas/A2UI.
|
||||
- URL можливостей прив’язані до активної WS-сесії вузла та швидко спливають. Fallback на основі IP не використовується.
|
||||
- Впроваджує клієнт live-reload у HTML, що обслуговується.
|
||||
- Автоматично створює стартовий `index.html`, якщо каталог порожній.
|
||||
- Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`.
|
||||
- Лише локально: використовуйте `gateway.bind: "loopback"` (за замовчуванням).
|
||||
- Bind не до loopback: маршрути canvas потребують auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway.
|
||||
- Node WebView зазвичай не надсилають заголовки auth; після pairing і підключення 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`.
|
||||
|
||||
---
|
||||
|
||||
@ -593,11 +630,11 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `minimal` (типово): не включає `cliPath` + `sshPort` до TXT-записів.
|
||||
- `minimal` (за замовчуванням): не включає `cliPath` + `sshPort` із TXT-записів.
|
||||
- `full`: включає `cliPath` + `sshPort`.
|
||||
- Ім’я хоста типово `openclaw`. Перевизначте через `OPENCLAW_MDNS_HOSTNAME`.
|
||||
- Ім’я хоста за замовчуванням — `openclaw`. Перевизначте через `OPENCLAW_MDNS_HOSTNAME`.
|
||||
|
||||
### Wide-area (DNS-SD)
|
||||
### Глобальне виявлення (DNS-SD)
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -607,7 +644,7 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + Tailscale split DNS.
|
||||
Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднайте це із DNS-сервером (рекомендовано CoreDNS) + Tailscale split DNS.
|
||||
|
||||
Налаштування: `openclaw dns setup --apply`.
|
||||
|
||||
@ -615,7 +652,7 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
|
||||
## Середовище
|
||||
|
||||
### `env` (вбудовані env-змінні)
|
||||
### `env` (вбудовані змінні середовища)
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -632,14 +669,14 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- Вбудовані env-змінні застосовуються лише якщо в середовищі процесу відсутній цей ключ.
|
||||
- Вбудовані змінні середовища застосовуються лише тоді, коли у змінних середовища процесу немає цього ключа.
|
||||
- Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні).
|
||||
- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell.
|
||||
- Повний пріоритет див. у [Environment](/uk/help/environment).
|
||||
- Див. [Середовище](/uk/help/environment) для повного порядку пріоритетів.
|
||||
|
||||
### Підстановка env-змінних
|
||||
### Підстановка змінних середовища
|
||||
|
||||
Посилайтеся на env-змінні в будь-якому рядку конфігурації через `${VAR_NAME}`:
|
||||
Посилайтеся на змінні середовища в будь-якому рядку конфігурації за допомогою `${VAR_NAME}`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -649,7 +686,7 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`.
|
||||
- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`.
|
||||
- Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації.
|
||||
- Екрануйте через `$${VAR}` для буквального `${VAR}`.
|
||||
- Працює з `$include`.
|
||||
@ -658,7 +695,7 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
|
||||
## Секрети
|
||||
|
||||
Посилання на секрети є адитивними: значення відкритим текстом також працюють.
|
||||
Посилання на секрети є адитивними: значення у відкритому тексті теж продовжують працювати.
|
||||
|
||||
### `SecretRef`
|
||||
|
||||
@ -671,16 +708,16 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
Валідація:
|
||||
|
||||
- шаблон `provider`: `^[a-z][a-z0-9_-]{0,63}$`
|
||||
- шаблон id для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$`
|
||||
- `source: "file"` id: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`)
|
||||
- шаблон id для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
|
||||
- id для `source: "exec"` не мають містити сегменти шляху `.` або `..`, розділені слешами (наприклад `a/../b` відхиляється)
|
||||
- шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$`
|
||||
- `id` для `source: "file"`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`)
|
||||
- шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
|
||||
- `id` для `source: "exec"` не повинні містити сегменти шляху `.` або `..`, розділені слешами (наприклад, `a/../b` відхиляється)
|
||||
|
||||
### Підтримувана поверхня облікових даних
|
||||
|
||||
- Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface)
|
||||
- Канонічна матриця: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface)
|
||||
- `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`.
|
||||
- Посилання в `auth-profiles.json` включено до runtime-розв’язання та покриття аудиту.
|
||||
- Посилання в `auth-profiles.json` включаються в runtime-розв’язання та покриття аудиту.
|
||||
|
||||
### Конфігурація провайдерів секретів
|
||||
|
||||
@ -713,13 +750,13 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
Примітки:
|
||||
|
||||
- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue значення `id` має бути `"value"`).
|
||||
- Шляхи провайдера file та exec завершуються fail-closed, якщо перевірка Windows ACL недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити.
|
||||
- Провайдер `exec` вимагає абсолютний шлях `command` і використовує payload-и протоколу через stdin/stdout.
|
||||
- За замовчуванням шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання, водночас перевіряючи шлях до розв’язаного цільового файлу.
|
||||
- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до шляху розв’язаного цільового файлу.
|
||||
- Дочірнє середовище `exec` за замовчуванням мінімальне; явно передайте потрібні змінні через `passEnv`.
|
||||
- Посилання на секрети розв’язуються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок.
|
||||
- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на ввімкнених поверхнях призводять до помилки запуску/reload, а неактивні поверхні пропускаються з діагностикою.
|
||||
- Шляхи провайдерів file і exec працюють за принципом fail closed, коли перевірка ACL Windows недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити.
|
||||
- Провайдер `exec` вимагає абсолютний шлях `command` і використовує payload протоколу через stdin/stdout.
|
||||
- За замовчуванням шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи symlink із перевіркою розв’язаного цільового шляху.
|
||||
- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до розв’язаного цільового шляху.
|
||||
- Середовище дочірнього процесу `exec` за замовчуванням мінімальне; передавайте потрібні змінні явно через `passEnv`.
|
||||
- Посилання на секрети розв’язуються під час активації в snapshot у пам’яті, після чого шляхи запитів читають лише цей snapshot.
|
||||
- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на увімкнених поверхнях спричиняють збій запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою.
|
||||
|
||||
---
|
||||
|
||||
@ -741,13 +778,13 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- Профілі для кожного агента зберігаються в `<agentDir>/auth-profiles.json`.
|
||||
- Профілі для окремих агентів зберігаються в `<agentDir>/auth-profiles.json`.
|
||||
- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних.
|
||||
- Профілі режиму OAuth (`auth.profiles.<id>.mode = "oauth"`) не підтримують облікові дані профілів auth на основі SecretRef.
|
||||
- Статичні runtime-облікові дані надходять із розв’язаних знімків у пам’яті; застарілі статичні записи `auth.json` очищаються, коли їх виявлено.
|
||||
- Застарілий імпорт OAuth із `~/.openclaw/credentials/oauth.json`.
|
||||
- Профілі в режимі OAuth (`auth.profiles.<id>.mode = "oauth"`) не підтримують облікові дані профілів auth на основі SecretRef.
|
||||
- Статичні runtime-облікові дані надходять із розв’язаних snapshot у пам’яті; застарілі статичні записи `auth.json` очищуються після виявлення.
|
||||
- Застарілий імпорт OAuth відбувається з `~/.openclaw/credentials/oauth.json`.
|
||||
- Див. [OAuth](/uk/concepts/oauth).
|
||||
- Поведінка runtime секретів і інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets).
|
||||
- Поведінка runtime для секретів і інструменти `audit/configure/apply`: [Керування секретами](/uk/gateway/secrets).
|
||||
|
||||
### `auth.cooldowns`
|
||||
|
||||
@ -769,20 +806,15 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `billingBackoffHours`: базова затримка в годинах, коли профіль завершується помилкою через справжні помилки білінгу/недостатнього кредиту (типово: `5`). Явний текст про білінг
|
||||
усе ще може потрапляти сюди навіть для відповідей `401`/`403`, але
|
||||
провайдер-специфічні текстові зіставлення лишаються обмеженими тим провайдером,
|
||||
якому вони належать (наприклад, OpenRouter
|
||||
`Key limit exceeded`). Повторювані повідомлення HTTP `402` про usage-window або
|
||||
ліміти витрат organization/workspace натомість лишаються в гілці `rate_limit`.
|
||||
- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин затримки білінгу для кожного провайдера.
|
||||
- `billingMaxHours`: межа в годинах для експоненційного зростання затримки білінгу (типово: `24`).
|
||||
- `authPermanentBackoffMinutes`: базова затримка в хвилинах для high-confidence збоїв `auth_permanent` (типово: `10`).
|
||||
- `authPermanentMaxMinutes`: межа в хвилинах для зростання затримки `auth_permanent` (типово: `60`).
|
||||
- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників затримок (типово: `24`).
|
||||
- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок перевантаження перед переходом до fallback моделі (типово: `1`). Сюди потрапляють форми зайнятості провайдера, як-от `ModelNotReadyException`.
|
||||
- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`).
|
||||
- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілю в межах того самого провайдера для помилок rate-limit перед переходом до fallback моделі (типово: `1`). Цей bucket rate-limit включає характерний для провайдерів текст, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`.
|
||||
- `billingBackoffHours`: базовий backoff у годинах, коли профіль зазнає збою через справжні помилки billing/недостатнього кредиту (за замовчуванням: `5`). Явний текст billing усе ще може потрапити сюди навіть для відповідей `401`/`403`, але зіставлювачі тексту, специфічні для провайдера, залишаються обмеженими провайдером, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Повторно придатні помилки використання `402` у вікні usage-window або повідомлення про ліміт витрат organization/workspace натомість залишаються в шляху `rate_limit`.
|
||||
- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff billing для кожного провайдера.
|
||||
- `billingMaxHours`: межа в годинах для експоненційного зростання backoff billing (за замовчуванням: `24`).
|
||||
- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для збоїв `auth_permanent` з високою впевненістю (за замовчуванням: `10`).
|
||||
- `authPermanentMaxMinutes`: межа в хвилинах для зростання backoff `auth_permanent` (за замовчуванням: `60`).
|
||||
- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників backoff (за замовчуванням: `24`).
|
||||
- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілю в межах одного провайдера для помилок перевантаження перед перемиканням на резервну модель (за замовчуванням: `1`). Сюди потрапляють форми «провайдер зайнятий», як-от `ModelNotReadyException`.
|
||||
- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (за замовчуванням: `0`).
|
||||
- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілю в межах одного провайдера для помилок rate limit перед перемиканням на резервну модель (за замовчуванням: `1`). Цей кошик rate limit включає текст у формі провайдера, наприклад `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`.
|
||||
|
||||
---
|
||||
|
||||
@ -801,10 +833,10 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`.
|
||||
- Установіть `logging.file` для сталого шляху.
|
||||
- `consoleLevel` підвищується до `debug`, коли використано `--verbose`.
|
||||
- `maxFileBytes`: максимальний розмір файлу журналу в байтах, після якого записи пригнічуються (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів.
|
||||
- Файл журналу за замовчуванням: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`.
|
||||
- Установіть `logging.file` для стабільного шляху.
|
||||
- `consoleLevel` підвищується до `debug`, коли використовується `--verbose`.
|
||||
- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого записи пригнічуються (додатне ціле число; за замовчуванням: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів.
|
||||
|
||||
---
|
||||
|
||||
@ -849,21 +881,22 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `enabled`: головний перемикач для виводу інструментування (типово: `true`).
|
||||
- `flags`: масив рядків-прапорців, які вмикають цільовий вивід журналу (підтримуються wildcard, як-от `"telegram.*"` або `"*"`).
|
||||
- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислі сесії, поки сесія лишається в стані обробки.
|
||||
- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`).
|
||||
- `otel.endpoint`: URL collector для експорту OTel.
|
||||
- `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`.
|
||||
- `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються з запитами експорту OTel.
|
||||
- `otel.serviceName`: ім’я сервісу для атрибутів resource.
|
||||
- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнення експорту trace, metrics або logs.
|
||||
- `enabled`: головний перемикач для виводу інструментування (за замовчуванням: `true`).
|
||||
- `flags`: масив рядків-прапорців, які вмикають цільовий вивід журналу (підтримує шаблони з символами узагальнення, як-от `"telegram.*"` або `"*"`).
|
||||
- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислу сесію, поки сесія залишається у стані обробки.
|
||||
- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (за замовчуванням: `false`).
|
||||
- `otel.endpoint`: URL колектора для експорту OTel.
|
||||
- `otel.protocol`: `"http/protobuf"` (за замовчуванням) або `"grpc"`.
|
||||
- `otel.headers`: додаткові метадані-заголовки HTTP/gRPC, що надсилаються із запитами експорту OTel.
|
||||
- `otel.serviceName`: назва сервісу для атрибутів ресурсу.
|
||||
- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або logs.
|
||||
- `otel.sampleRate`: частота семплювання trace `0`–`1`.
|
||||
- `otel.flushIntervalMs`: періодичний інтервал flush телеметрії в мс.
|
||||
- `otel.captureContent`: opt-in захоплення сирого вмісту для атрибутів span OTEL. Типово вимкнено. Булеве значення `true` захоплює вміст повідомлень/інструментів, крім system; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`.
|
||||
- `cacheTrace.enabled`: журналювати знімки cache trace для embedded-запусків (типово: `false`).
|
||||
- `cacheTrace.filePath`: шлях виводу для JSONL cache trace (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`).
|
||||
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається до виводу cache trace (усі типово: `true`).
|
||||
- `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс.
|
||||
- `otel.captureContent`: явне ввімкнення захоплення сирого вмісту для атрибутів span OTEL. За замовчуванням вимкнено. Булеве значення `true` захоплює вміст повідомлень/інструментів, що не є системними; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`.
|
||||
- `OPENCLAW_OTEL_PRELOADED=1`: перемикач середовища для хостів, які вже зареєстрували глобальний SDK OpenTelemetry. Тоді OpenClaw пропускає запуск/завершення SDK, що належить Plugin, але зберігає активними діагностичні прослуховувачі.
|
||||
- `cacheTrace.enabled`: журналювати snapshot cache trace для вбудованих запусків (за замовчуванням: `false`).
|
||||
- `cacheTrace.filePath`: вихідний шлях для JSONL cache trace (за замовчуванням: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`).
|
||||
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід cache trace (усі за замовчуванням: `true`).
|
||||
|
||||
---
|
||||
|
||||
@ -886,11 +919,11 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
```
|
||||
|
||||
- `channel`: канал релізів для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`.
|
||||
- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`).
|
||||
- `auto.enabled`: увімкнути фонове автооновлення для пакетних встановлень (типово: `false`).
|
||||
- `auto.stableDelayHours`: мінімальна затримка в годинах перед автозастосуванням stable-каналу (типово: `6`; максимум: `168`).
|
||||
- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (типово: `12`; максимум: `168`).
|
||||
- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу в годинах (типово: `1`; максимум: `24`).
|
||||
- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (за замовчуванням: `true`).
|
||||
- `auto.enabled`: увімкнути фонове автооновлення для пакетних встановлень (за замовчуванням: `false`).
|
||||
- `auto.stableDelayHours`: мінімальна затримка в годинах перед автозастосуванням stable-каналу (за замовчуванням: `6`; максимум: `168`).
|
||||
- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (за замовчуванням: `12`; максимум: `168`).
|
||||
- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу, у годинах (за замовчуванням: `1`; максимум: `24`).
|
||||
|
||||
---
|
||||
|
||||
@ -923,22 +956,22 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `enabled`: глобальний feature gate для ACP (типово: `false`).
|
||||
- `dispatch.enabled`: незалежний gate для dispatch ходів сесії ACP (типово: `true`). Установіть `false`, щоб команди ACP лишалися доступними, але виконання блокувалося.
|
||||
- `backend`: id типового runtime backend ACP (має відповідати зареєстрованому runtime plugin ACP).
|
||||
- `defaultAgent`: fallback id цільового агента ACP, коли спавни не вказують явну ціль.
|
||||
- `allowedAgents`: allowlist id агентів, дозволених для runtime-сесій ACP; порожнє значення означає відсутність додаткових обмежень.
|
||||
- `enabled`: глобальний feature gate ACP (за замовчуванням: `false`).
|
||||
- `dispatch.enabled`: незалежний gate для диспетчеризації ходів сесії ACP (за замовчуванням: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання.
|
||||
- `backend`: id runtime backend ACP за замовчуванням (має відповідати зареєстрованому ACP runtime Plugin).
|
||||
- `defaultAgent`: резервний id цільового агента ACP, коли spawn не вказує явну ціль.
|
||||
- `allowedAgents`: список дозволу id агентів, дозволених для runtime-сесій ACP; порожній список означає відсутність додаткових обмежень.
|
||||
- `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP.
|
||||
- `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту.
|
||||
- `stream.maxChunkChars`: максимальний розмір chunk перед розбиттям проєкції потокового блока.
|
||||
- `stream.repeatSuppression`: пригнічувати повторювані рядки status/tool на хід (типово: `true`).
|
||||
- `stream.deliveryMode`: `"live"` передає потік інкрементально; `"final_only"` буферизує до термінальних подій ходу.
|
||||
- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій tool (типово: `"paragraph"`).
|
||||
- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, проєктованих за один хід ACP.
|
||||
- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків status/update ACP.
|
||||
- `stream.tagVisibility`: запис назв тегів у логічні перевизначення видимості для потокових подій.
|
||||
- `runtime.ttlMinutes`: idle TTL у хвилинах для воркерів сесій ACP до моменту можливого очищення.
|
||||
- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час bootstrap середовища runtime ACP.
|
||||
- `stream.coalesceIdleMs`: вікно скидання простою в мс для потокового тексту.
|
||||
- `stream.maxChunkChars`: максимальний розмір чанка перед розбиттям проєкції потокового блоку.
|
||||
- `stream.repeatSuppression`: пригнічувати повторювані рядки стану/інструментів у межах одного ходу (за замовчуванням: `true`).
|
||||
- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до кінцевих подій ходу.
|
||||
- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (за замовчуванням: `"paragraph"`).
|
||||
- `stream.maxOutputChars`: максимальна кількість символів виводу помічника, що проєктується за один хід ACP.
|
||||
- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків стану/оновлення ACP.
|
||||
- `stream.tagVisibility`: запис назв тегів із булевими перевизначеннями видимості для потокових подій.
|
||||
- `runtime.ttlMinutes`: TTL простою в хвилинах для worker сесій ACP до моменту, коли їх можна очищати.
|
||||
- `runtime.installCommand`: необов’язкова команда встановлення, яку слід виконати під час bootstrap середовища runtime ACP.
|
||||
|
||||
---
|
||||
|
||||
@ -954,17 +987,17 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `cli.banner.taglineMode` керує стилем tagline банера:
|
||||
- `"random"` (типово): змінні кумедні/сезонні tagline.
|
||||
- `"default"`: фіксований нейтральний tagline (`Усі ваші чати, один OpenClaw.`).
|
||||
- `"off"`: без тексту tagline (назва/версія банера все одно показуються).
|
||||
- Щоб приховати весь банер (а не лише tagline), установіть env `OPENCLAW_HIDE_BANNER=1`.
|
||||
- `cli.banner.taglineMode` керує стилем слогана банера:
|
||||
- `"random"` (за замовчуванням): ротаційні кумедні/сезонні слогани.
|
||||
- `"default"`: фіксований нейтральний слоган (`Усі ваші чати, один OpenClaw.`).
|
||||
- `"off"`: без тексту слогана (назва/версія банера все одно показуються).
|
||||
- Щоб приховати весь банер (а не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`.
|
||||
|
||||
---
|
||||
|
||||
## Wizard
|
||||
|
||||
Метадані, які записуються потоками покрокового налаштування CLI (`onboard`, `configure`, `doctor`):
|
||||
Метадані, які записуються керованими CLI потоками налаштування (`onboard`, `configure`, `doctor`):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -982,13 +1015,13 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
|
||||
## Ідентичність
|
||||
|
||||
Див. поля ідентичності `agents.list` у розділі [Agent defaults](/uk/gateway/config-agents#agent-defaults).
|
||||
Див. поля ідентичності `agents.list` у розділі [Значення агента за замовчуванням](/uk/gateway/config-agents#agent-defaults).
|
||||
|
||||
---
|
||||
|
||||
## Bridge (застарілий, видалено)
|
||||
## Bridge (застарілий, вилучений)
|
||||
|
||||
Поточні збірки більше не містять TCP bridge. Вузли підключаються через WebSocket Gateway. Ключі `bridge.*` більше не входять до схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі).
|
||||
Поточні збірки більше не містять TCP bridge. Node підключаються через WebSocket Gateway. Ключі `bridge.*` більше не входять до схеми конфігурації (валідація завершується помилкою, доки їх не буде вилучено; `openclaw doctor --fix` може прибрати невідомі ключі).
|
||||
|
||||
<Accordion title="Застаріла конфігурація bridge (історична довідка)">
|
||||
|
||||
@ -1028,11 +1061,11 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `sessionRetention`: як довго зберігати завершені ізольовані сесії запуску cron перед pruning із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. Типово: `24h`; установіть `false`, щоб вимкнути.
|
||||
- `runLog.maxBytes`: максимальний розмір файлу журналу одного запуску (`cron/runs/<jobId>.jsonl`) перед pruning. Типово: `2_000_000` байтів.
|
||||
- `runLog.keepLines`: найновіші рядки, що зберігаються, коли запускається pruning журналу запуску. Типово: `2000`.
|
||||
- `webhookToken`: bearer token, що використовується для POST-доставки webhook cron (`delivery.mode = "webhook"`); якщо не задано, заголовок auth не надсилається.
|
||||
- `webhook`: застарілий legacy fallback URL webhook (http/https), який використовується лише для збережених завдань, що все ще мають `notify: true`.
|
||||
- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. За замовчуванням: `24h`; установіть `false`, щоб вимкнути.
|
||||
- `runLog.maxBytes`: максимальний розмір файла журналу на один запуск (`cron/runs/<jobId>.jsonl`) перед очищенням. За замовчуванням: `2_000_000` байтів.
|
||||
- `runLog.keepLines`: кількість найновіших рядків, що зберігаються після спрацьовування очищення журналу запусків. За замовчуванням: `2000`.
|
||||
- `webhookToken`: bearer token, який використовується для POST-доставки Webhook cron (`delivery.mode = "webhook"`); якщо не задано, заголовок auth не надсилається.
|
||||
- `webhook`: застарілий резервний URL Webhook (http/https), який використовується лише для збережених завдань, у яких і далі встановлено `notify: true`.
|
||||
|
||||
### `cron.retry`
|
||||
|
||||
@ -1048,11 +1081,11 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <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`
|
||||
|
||||
@ -1070,11 +1103,11 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
}
|
||||
```
|
||||
|
||||
- `enabled`: увімкнути сповіщення про збої для cron-завдань (типово: `false`).
|
||||
- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мінімум: `1`).
|
||||
- `enabled`: увімкнути сповіщення про збої для cron-завдань (за замовчуванням: `false`).
|
||||
- `after`: кількість послідовних збоїв до спрацьовування сповіщення (додатне ціле число, мінімум: `1`).
|
||||
- `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число).
|
||||
- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST на налаштований webhook.
|
||||
- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки сповіщень.
|
||||
- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` надсилає POST на налаштований Webhook.
|
||||
- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки сповіщення.
|
||||
|
||||
### `cron.failureDestination`
|
||||
|
||||
@ -1091,51 +1124,51 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <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` на рівні завдання перевизначає це глобальне типове значення.
|
||||
- Коли не задано ні глобальне, ні рівень завдання failure destination, завдання, які вже доставляють через `announce`, у разі збою використовують як fallback цю основну announce-ціль.
|
||||
- `delivery.failureDestination` для окремого завдання перевизначає це глобальне значення за замовчуванням.
|
||||
- Якщо не задано ні глобальне, ні для окремого завдання місце призначення збоїв, завдання, які вже доставляють через `announce`, у разі збою використовують цей основний цільовий announce як резервний варіант.
|
||||
- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`.
|
||||
|
||||
Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [background tasks](/uk/automation/tasks).
|
||||
Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [фонові завдання](/uk/automation/tasks).
|
||||
|
||||
---
|
||||
|
||||
## Змінні шаблону моделі медіа
|
||||
## Змінні шаблонів моделі медіа
|
||||
|
||||
Заповнювачі шаблону, що розгортаються в `tools.media.models[].args`:
|
||||
Заповнювачі шаблонів, які розгортаються в `tools.media.models[].args`:
|
||||
|
||||
| Змінна | Опис |
|
||||
| ----------------- | ------------------------------------------------- |
|
||||
| `{{Body}}` | Повний текст вхідного повідомлення |
|
||||
| `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) |
|
||||
| `{{BodyStripped}}`| Текст без групових згадок |
|
||||
| `{{From}}` | Ідентифікатор відправника |
|
||||
| `{{To}}` | Ідентифікатор призначення |
|
||||
| `{{MessageSid}}` | id повідомлення каналу |
|
||||
| `{{SessionId}}` | UUID поточної сесії |
|
||||
| `{{IsNewSession}}`| `"true"`, коли створено нову сесію |
|
||||
| `{{MediaUrl}}` | Псевдо-URL вхідного медіа |
|
||||
| `{{MediaPath}}` | Локальний шлях до медіа |
|
||||
| `{{MediaType}}` | Тип медіа (image/audio/document/…) |
|
||||
| `{{Transcript}}` | Транскрипт аудіо |
|
||||
| `{{Prompt}}` | Розв’язаний 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}}` | Розв’язаний медіа-prompt для записів CLI |
|
||||
| `{{MaxChars}}` | Розв’язана максимальна кількість символів виводу для записів CLI |
|
||||
| `{{ChatType}}` | `"direct"` або `"group"` |
|
||||
| `{{GroupSubject}}` | Назва групи (за можливості) |
|
||||
| `{{GroupMembers}}` | Попередній перегляд учасників групи (за можливості) |
|
||||
| `{{SenderName}}` | Відображуване ім’я відправника (за можливості) |
|
||||
| `{{SenderE164}}` | Номер телефону відправника (за можливості) |
|
||||
| `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) |
|
||||
|
||||
---
|
||||
|
||||
## Включення конфігурації (`$include`)
|
||||
|
||||
Розбийте конфігурацію на кілька файлів:
|
||||
Розділіть конфігурацію на кілька файлів:
|
||||
|
||||
```json5
|
||||
// ~/.openclaw/openclaw.json
|
||||
@ -1151,19 +1184,19 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
|
||||
**Поведінка злиття:**
|
||||
|
||||
- Один файл: замінює об’єкт-контейнер.
|
||||
- Масив файлів: deep-merge у заданому порядку (пізніші перевизначають попередні).
|
||||
- Сусідні ключі: зливаються після includes (перевизначають включені значення).
|
||||
- Вкладені includes: до 10 рівнів углиб.
|
||||
- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли після розв’язання вони все одно лишаються в межах цієї границі.
|
||||
- Записи, керовані OpenClaw, які змінюють лише один розділ верхнього рівня, підкріплений include одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін.
|
||||
- Root includes, масиви include і includes із сусідніми перевизначеннями є read-only для записів, керованих OpenClaw; такі записи завершуються fail-closed замість сплощення конфігурації.
|
||||
- Помилки: чіткі повідомлення для відсутніх файлів, помилок парсингу та циклічних includes.
|
||||
- Масив файлів: глибоко зливається за порядком (пізніші перевизначають попередні).
|
||||
- Сусідні ключі: зливаються після включень (перевизначають включені значення).
|
||||
- Вкладені включення: до 10 рівнів глибини.
|
||||
- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/форми з `../` дозволені лише тоді, коли вони все одно розв’язуються в межах цієї межі.
|
||||
- Записи OpenClaw, які змінюють лише один розділ верхнього рівня, підкріплений включенням одного файла, записуються безпосередньо до цього включеного файла. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін.
|
||||
- Кореневі включення, масиви включень і включення із сусідніми перевизначеннями доступні лише для читання для записів, що виконуються OpenClaw; такі записи завершуються за принципом fail closed замість сплощення конфігурації.
|
||||
- Помилки: чіткі повідомлення для відсутніх файлів, помилок розбору та циклічних включень.
|
||||
|
||||
---
|
||||
|
||||
_Пов’язане: [Configuration](/uk/gateway/configuration) · [Configuration Examples](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_
|
||||
_Пов’язано: [Конфігурація](/uk/gateway/configuration) · [Приклади конфігурації](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Configuration](/uk/gateway/configuration)
|
||||
- [Configuration examples](/uk/gateway/configuration-examples)
|
||||
- [Конфігурація](/uk/gateway/configuration)
|
||||
- [Приклади конфігурації](/uk/gateway/configuration-examples)
|
||||
|
||||
@ -3,13 +3,13 @@ read_when:
|
||||
- Вам потрібен дружній до початківців огляд журналювання
|
||||
- Ви хочете налаштувати рівні журналювання або формати
|
||||
- Ви усуваєте несправності й хочете швидко знайти журнали
|
||||
summary: 'Огляд журналювання: журнали у файлах, вивід у консолі, відстеження в CLI та інтерфейс керування'
|
||||
summary: 'Огляд журналювання: журнали файлів, вивід у консоль, відстеження в CLI та інтерфейс керування'
|
||||
title: Огляд журналювання
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T23:44:42Z"
|
||||
generated_at: "2026-04-25T07:01:56Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 8e179c883d98caa7fd8d3ece8962d0b628562d35568ebf452c34bededba22e2c
|
||||
source_hash: 7f9593b117ef2ba76dbe91d5b38e3f463b358631961c9d44beed3aee6152f9a2
|
||||
source_path: logging.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -18,20 +18,20 @@ x-i18n:
|
||||
|
||||
OpenClaw має дві основні поверхні журналювання:
|
||||
|
||||
- **Журнали у файлах** (рядки JSON), які записує Gateway.
|
||||
- **Вивід у консолі**, що показується в терміналах і в інтерфейсі налагодження Gateway.
|
||||
- **Журнали файлів** (рядки JSON), які записує Gateway.
|
||||
- **Вивід у консоль**, що показується в терміналах і в інтерфейсі Gateway Debug UI.
|
||||
|
||||
Вкладка **Logs** в інтерфейсі керування відстежує журнал файлу gateway. На цій сторінці пояснюється, де зберігаються журнали, як їх читати та як налаштовувати рівні й формати журналювання.
|
||||
Вкладка **Logs** в інтерфейсі керування відстежує файл журналу gateway. На цій сторінці пояснюється, де зберігаються журнали, як їх читати та як налаштовувати рівні й формати журналювання.
|
||||
|
||||
## Де зберігаються журнали
|
||||
|
||||
За замовчуванням Gateway записує ротаційний файл журналу за шляхом:
|
||||
За замовчуванням Gateway записує ротаційний файл журналу в:
|
||||
|
||||
`/tmp/openclaw/openclaw-YYYY-MM-DD.log`
|
||||
|
||||
Дата використовує локальний часовий пояс хоста gateway.
|
||||
|
||||
Ви можете змінити це в `~/.openclaw/openclaw.json`:
|
||||
Ви можете перевизначити це в `~/.openclaw/openclaw.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -55,26 +55,26 @@ openclaw logs --follow
|
||||
|
||||
- `--local-time`: відображати часові мітки у вашому локальному часовому поясі
|
||||
- `--url <url>` / `--token <token>` / `--timeout <ms>`: стандартні прапорці Gateway RPC
|
||||
- `--expect-final`: прапорець очікування фінальної відповіді для RPC на основі агентів (тут приймається через спільний клієнтський шар)
|
||||
- `--expect-final`: прапорець очікування фінальної відповіді для RPC на основі агентів (приймається тут через спільний клієнтський шар)
|
||||
|
||||
Режими виводу:
|
||||
|
||||
- **Сеанси TTY**: гарні, кольорові, структуровані рядки журналу.
|
||||
- **Сеанси без TTY**: звичайний текст.
|
||||
- `--json`: JSON з розділенням по рядках (одна подія журналу на рядок).
|
||||
- `--plain`: примусово використовувати звичайний текст у сеансах TTY.
|
||||
- `--no-color`: вимкнути кольори ANSI.
|
||||
- **TTY-сеанси**: гарні, кольорові, структуровані рядки журналу.
|
||||
- **Не-TTY-сеанси**: звичайний текст.
|
||||
- `--json`: JSON із розділенням по рядках (одна подія журналу на рядок).
|
||||
- `--plain`: примусово використовувати звичайний текст у TTY-сеансах.
|
||||
- `--no-color`: вимкнути ANSI-кольори.
|
||||
|
||||
Коли ви передаєте явний `--url`, CLI не застосовує автоматично облікові дані з конфігурації або середовища; вкажіть `--token` самостійно, якщо цільовий Gateway вимагає автентифікації.
|
||||
Коли ви передаєте явний `--url`, CLI не застосовує автоматично облікові дані з конфігурації або середовища; самостійно додайте `--token`, якщо цільовий Gateway вимагає автентифікацію.
|
||||
|
||||
У режимі JSON CLI виводить об’єкти з тегом `type`:
|
||||
|
||||
- `meta`: метадані потоку (файл, курсор, розмір)
|
||||
- `log`: розібраний запис журналу
|
||||
- `notice`: підказки щодо обрізання / ротації
|
||||
- `notice`: підказки про обрізання / ротацію
|
||||
- `raw`: нерозібраний рядок журналу
|
||||
|
||||
Якщо Gateway на local loopback просить виконати pairing, `openclaw logs` автоматично переходить до налаштованого локального файла журналу. Явні цілі `--url` не використовують цей резервний варіант.
|
||||
Якщо локальний loopback Gateway запитує pair-налаштування, `openclaw logs` автоматично перемикається на налаштований локальний файл журналу. Явні цілі `--url` не використовують цей резервний режим.
|
||||
|
||||
Якщо Gateway недоступний, CLI виводить коротку підказку виконати:
|
||||
|
||||
@ -97,27 +97,27 @@ openclaw channels logs --channel whatsapp
|
||||
|
||||
## Формати журналів
|
||||
|
||||
### Журнали у файлах (JSONL)
|
||||
### Журнали файлів (JSONL)
|
||||
|
||||
Кожен рядок у файлі журналу є об’єктом JSON. CLI та інтерфейс керування розбирають ці записи, щоб відображати структурований вивід (час, рівень, підсистема, повідомлення).
|
||||
|
||||
### Вивід у консолі
|
||||
### Вивід у консоль
|
||||
|
||||
Журнали консолі **враховують TTY** і форматуються для зручності читання:
|
||||
|
||||
- Префікси підсистем (наприклад, `gateway/channels/whatsapp`)
|
||||
- Кольори рівнів (info/warn/error)
|
||||
- Необов’язковий компактний або JSON-режим
|
||||
- Кольорове позначення рівнів (info/warn/error)
|
||||
- Необов’язковий компактний режим або режим JSON
|
||||
|
||||
Форматування консолі керується через `logging.consoleStyle`.
|
||||
|
||||
### Журнали Gateway WebSocket
|
||||
### Журнали WebSocket Gateway
|
||||
|
||||
`openclaw gateway` також має журналювання протоколу WebSocket для RPC-трафіку:
|
||||
|
||||
- звичайний режим: лише цікаві результати (помилки, помилки розбору, повільні виклики)
|
||||
- звичайний режим: лише важливі результати (помилки, помилки розбору, повільні виклики)
|
||||
- `--verbose`: увесь трафік запитів/відповідей
|
||||
- `--ws-log auto|compact|full`: вибір стилю детального відображення
|
||||
- `--ws-log auto|compact|full`: вибір стилю розширеного відображення
|
||||
- `--compact`: псевдонім для `--ws-log compact`
|
||||
|
||||
Приклади:
|
||||
@ -130,7 +130,7 @@ openclaw gateway --verbose --ws-log full
|
||||
|
||||
## Налаштування журналювання
|
||||
|
||||
Усі параметри журналювання містяться в `logging` у `~/.openclaw/openclaw.json`.
|
||||
Уся конфігурація журналювання знаходиться в розділі `logging` у `~/.openclaw/openclaw.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -147,18 +147,18 @@ openclaw gateway --verbose --ws-log full
|
||||
|
||||
### Рівні журналювання
|
||||
|
||||
- `logging.level`: рівень **журналів у файлах** (JSONL).
|
||||
- `logging.level`: рівень **журналів файлів** (JSONL).
|
||||
- `logging.consoleLevel`: рівень деталізації **консолі**.
|
||||
|
||||
Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має вищий пріоритет за файл конфігурації, тому ви можете підвищити деталізацію для одного запуску без редагування `openclaw.json`. Ви також можете передати глобальний параметр CLI **`--log-level <level>`** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди.
|
||||
Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має вищий пріоритет, ніж файл конфігурації, тому ви можете підвищити деталізацію для одного запуску без редагування `openclaw.json`. Ви також можете передати глобальний параметр CLI **`--log-level <level>`** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди.
|
||||
|
||||
`--verbose` впливає лише на вивід у консоль і деталізацію журналів WS; він не змінює рівні журналів у файлах.
|
||||
`--verbose` впливає лише на вивід у консоль і деталізацію журналів WS; він не змінює рівні журналів файлів.
|
||||
|
||||
### Стилі консолі
|
||||
|
||||
`logging.consoleStyle`:
|
||||
|
||||
- `pretty`: зручний для людини, кольоровий, із часовими мітками.
|
||||
- `pretty`: зручний для людей, кольоровий, із часовими мітками.
|
||||
- `compact`: щільніший вивід (найкраще для довгих сеансів).
|
||||
- `json`: JSON у кожному рядку (для обробників журналів).
|
||||
|
||||
@ -169,56 +169,56 @@ openclaw gateway --verbose --ws-log full
|
||||
- `logging.redactSensitive`: `off` | `tools` (типово: `tools`)
|
||||
- `logging.redactPatterns`: список рядків regex для перевизначення типового набору
|
||||
|
||||
Редагування впливає **лише на вивід у консоль** і не змінює журнали у файлах.
|
||||
Редагування впливає **лише на вивід у консоль** і не змінює журнали файлів.
|
||||
|
||||
## Діагностика + OpenTelemetry
|
||||
|
||||
Діагностика — це структуровані, машинозчитувані події для запусків моделей **і**
|
||||
телеметрії потоку повідомлень (webhooks, постановка в чергу, стан сеансу). Вони **не**
|
||||
замінюють журнали; вони існують для передавання метрик, трасувань та інших експортерів.
|
||||
Діагностика — це структуровані, машиночитні події для запусків моделей **і**
|
||||
телеметрії потоку повідомлень (webhook, постановка в чергу, стан сеансу). Вони **не**
|
||||
замінюють журнали; вони існують для подачі метрик, трасувань та інших експортерів.
|
||||
|
||||
Події діагностики генеруються в процесі, але експортери підключаються лише тоді, коли
|
||||
Події діагностики створюються в процесі, але експортери підключаються лише тоді, коли
|
||||
увімкнено діагностику + Plugin експортера.
|
||||
|
||||
### OpenTelemetry проти OTLP
|
||||
### OpenTelemetry і OTLP
|
||||
|
||||
- **OpenTelemetry (OTel)**: модель даних + SDK для трасувань, метрик і журналів.
|
||||
- **OTLP**: мережевий протокол, який використовується для експорту даних OTel до колектора/бекенда.
|
||||
- **OTLP**: дротовий протокол, який використовується для експорту даних OTel до збирача/бекенда.
|
||||
- Сьогодні OpenClaw експортує через **OTLP/HTTP (protobuf)**.
|
||||
|
||||
### Експортовані сигнали
|
||||
|
||||
- **Метрики**: лічильники + гістограми (використання токенів, потік повідомлень, постановка в чергу).
|
||||
- **Трасування**: span-и для використання моделей + обробки webhook/повідомлень.
|
||||
- **Журнали**: експортуються через OTLP, коли ввімкнено `diagnostics.otel.logs`. Обсяг журналів
|
||||
може бути високим; враховуйте `logging.level` і фільтри експортера.
|
||||
- **Metrics**: лічильники + гістограми (використання токенів, потік повідомлень, черги).
|
||||
- **Traces**: span-и для використання моделей + обробки webhook/повідомлень.
|
||||
- **Logs**: експортуються через OTLP, коли ввімкнено `diagnostics.otel.logs`. Обсяг журналів
|
||||
може бути великим; пам’ятайте про `logging.level` і фільтри експортера.
|
||||
|
||||
### Каталог подій діагностики
|
||||
|
||||
Використання моделей:
|
||||
Використання моделі:
|
||||
|
||||
- `model.usage`: токени, вартість, тривалість, контекст, провайдер/модель/канал, ідентифікатори сеансів.
|
||||
- `model.usage`: токени, вартість, тривалість, контекст, provider/model/channel, ідентифікатори сеансів.
|
||||
|
||||
Потік повідомлень:
|
||||
|
||||
- `webhook.received`: вхід webhook для кожного каналу.
|
||||
- `webhook.processed`: webhook оброблено + тривалість.
|
||||
- `webhook.received`: вхідний webhook для кожного каналу.
|
||||
- `webhook.processed`: оброблений webhook + тривалість.
|
||||
- `webhook.error`: помилки обробника webhook.
|
||||
- `message.queued`: повідомлення поставлено в чергу на обробку.
|
||||
- `message.processed`: результат + тривалість + необов’язкова помилка.
|
||||
|
||||
Черга + сеанс:
|
||||
|
||||
- `queue.lane.enqueue`: постановка в lane черги команд + глибина.
|
||||
- `queue.lane.dequeue`: зняття з lane черги команд + час очікування.
|
||||
- `queue.lane.enqueue`: додавання в lane черги команд + глибина.
|
||||
- `queue.lane.dequeue`: виймання з lane черги команд + час очікування.
|
||||
- `session.state`: перехід стану сеансу + причина.
|
||||
- `session.stuck`: попередження про завислий сеанс + вік.
|
||||
- `run.attempt`: метадані повторної спроби/спроби запуску.
|
||||
- `diagnostic.heartbeat`: агреговані лічильники (webhooks/черга/сеанс).
|
||||
- `run.attempt`: метадані повтору/спроби запуску.
|
||||
- `diagnostic.heartbeat`: агреговані лічильники (webhook/черга/сеанс).
|
||||
|
||||
### Увімкнення діагностики (без експортера)
|
||||
|
||||
Використовуйте це, якщо хочете, щоб події діагностики були доступні для плагінів або власних приймачів:
|
||||
Використовуйте це, якщо хочете, щоб події діагностики були доступні для Plugin-ів або користувацьких приймачів:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -231,7 +231,7 @@ openclaw gateway --verbose --ws-log full
|
||||
### Прапорці діагностики (цільові журнали)
|
||||
|
||||
Використовуйте прапорці, щоб увімкнути додаткові, цільові журнали налагодження без підвищення `logging.level`.
|
||||
Прапорці нечутливі до регістру та підтримують шаблони з wildcard (наприклад, `telegram.*` або `*`).
|
||||
Прапорці нечутливі до регістру та підтримують шаблони (наприклад, `telegram.*` або `*`).
|
||||
|
||||
```json
|
||||
{
|
||||
@ -241,7 +241,7 @@ openclaw gateway --verbose --ws-log full
|
||||
}
|
||||
```
|
||||
|
||||
Перевизначення через змінну середовища (для разового запуску):
|
||||
Перевизначення через змінну середовища (разово):
|
||||
|
||||
```
|
||||
OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload
|
||||
@ -249,14 +249,14 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload
|
||||
|
||||
Примітки:
|
||||
|
||||
- Журнали за прапорцями записуються у стандартний файл журналу (той самий, що й `logging.file`).
|
||||
- Журнали за прапорцями записуються до стандартного файлу журналу (того самого, що й `logging.file`).
|
||||
- Вивід усе одно редагується відповідно до `logging.redactSensitive`.
|
||||
- Повний посібник: [/diagnostics/flags](/uk/diagnostics/flags).
|
||||
|
||||
### Експорт до OpenTelemetry
|
||||
|
||||
Діагностику можна експортувати через Plugin `diagnostics-otel` (OTLP/HTTP). Це
|
||||
працює з будь-яким колектором/бекендом OpenTelemetry, який приймає OTLP/HTTP.
|
||||
працює з будь-яким збирачем/бекендом OpenTelemetry, який приймає OTLP/HTTP.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -295,58 +295,62 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload
|
||||
|
||||
Примітки:
|
||||
|
||||
- Ви також можете ввімкнути Plugin за допомогою `openclaw plugins enable diagnostics-otel`.
|
||||
- Ви також можете ввімкнути Plugin командою `openclaw plugins enable diagnostics-otel`.
|
||||
- `protocol` наразі підтримує лише `http/protobuf`. `grpc` ігнорується.
|
||||
- Метрики включають використання токенів, вартість, розмір контексту, тривалість запуску та
|
||||
лічильники/гістограми потоку повідомлень (webhooks, постановка в чергу, стан сеансу, глибина/очікування черги).
|
||||
- Трасування/метрики можна перемикати через `traces` / `metrics` (типово: увімкнено). Трасування
|
||||
включають span-и використання моделей, а також span-и обробки webhook/повідомлень, коли це ввімкнено.
|
||||
- Вміст сирих моделей/інструментів типово не експортується. Використовуйте
|
||||
`diagnostics.otel.captureContent` лише тоді, коли ваш колектор і політика зберігання
|
||||
схвалені для тексту підказок, відповідей, інструментів або системних підказок.
|
||||
- Установіть `headers`, якщо ваш колектор вимагає автентифікації.
|
||||
- Metrics включають використання токенів, вартість, розмір контексту, тривалість запуску та
|
||||
лічильники/гістограми потоку повідомлень (webhook, черги, стан сеансу, глибина/очікування черги).
|
||||
- Traces/metrics можна вмикати або вимикати через `traces` / `metrics` (типово: увімкнено). Traces
|
||||
включають span-и використання моделей, а також span-и обробки webhook/повідомлень, якщо це ввімкнено.
|
||||
- Сирий вміст моделі/інструментів типово не експортується. Використовуйте
|
||||
`diagnostics.otel.captureContent` лише тоді, коли ваш збирач і політика зберігання
|
||||
схвалені для тексту prompt, відповіді, інструментів або системного prompt.
|
||||
- Установіть `headers`, якщо ваш збирач вимагає автентифікацію.
|
||||
- Підтримувані змінні середовища: `OTEL_EXPORTER_OTLP_ENDPOINT`,
|
||||
`OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_PROTOCOL`.
|
||||
- Установіть `OPENCLAW_OTEL_PRELOADED=1`, якщо інший preload або хост-процес уже
|
||||
зареєстрував глобальний OpenTelemetry SDK. У цьому режимі Plugin не запускає
|
||||
і не завершує власний SDK, але все одно підключає слухачі діагностики OpenClaw і
|
||||
враховує `diagnostics.otel.traces`, `metrics` і `logs`.
|
||||
|
||||
### Експортовані метрики (назви + типи)
|
||||
### Експортовані metrics (назви + типи)
|
||||
|
||||
Використання моделей:
|
||||
Використання моделі:
|
||||
|
||||
- `openclaw.tokens` (лічильник, атрибути: `openclaw.token`, `openclaw.channel`,
|
||||
- `openclaw.tokens` (counter, атрибути: `openclaw.token`, `openclaw.channel`,
|
||||
`openclaw.provider`, `openclaw.model`)
|
||||
- `openclaw.cost.usd` (лічильник, атрибути: `openclaw.channel`, `openclaw.provider`,
|
||||
- `openclaw.cost.usd` (counter, атрибути: `openclaw.channel`, `openclaw.provider`,
|
||||
`openclaw.model`)
|
||||
- `openclaw.run.duration_ms` (гістограма, атрибути: `openclaw.channel`,
|
||||
- `openclaw.run.duration_ms` (histogram, атрибути: `openclaw.channel`,
|
||||
`openclaw.provider`, `openclaw.model`)
|
||||
- `openclaw.context.tokens` (гістограма, атрибути: `openclaw.context`,
|
||||
- `openclaw.context.tokens` (histogram, атрибути: `openclaw.context`,
|
||||
`openclaw.channel`, `openclaw.provider`, `openclaw.model`)
|
||||
|
||||
Потік повідомлень:
|
||||
|
||||
- `openclaw.webhook.received` (лічильник, атрибути: `openclaw.channel`,
|
||||
- `openclaw.webhook.received` (counter, атрибути: `openclaw.channel`,
|
||||
`openclaw.webhook`)
|
||||
- `openclaw.webhook.error` (лічильник, атрибути: `openclaw.channel`,
|
||||
- `openclaw.webhook.error` (counter, атрибути: `openclaw.channel`,
|
||||
`openclaw.webhook`)
|
||||
- `openclaw.webhook.duration_ms` (гістограма, атрибути: `openclaw.channel`,
|
||||
- `openclaw.webhook.duration_ms` (histogram, атрибути: `openclaw.channel`,
|
||||
`openclaw.webhook`)
|
||||
- `openclaw.message.queued` (лічильник, атрибути: `openclaw.channel`,
|
||||
- `openclaw.message.queued` (counter, атрибути: `openclaw.channel`,
|
||||
`openclaw.source`)
|
||||
- `openclaw.message.processed` (лічильник, атрибути: `openclaw.channel`,
|
||||
- `openclaw.message.processed` (counter, атрибути: `openclaw.channel`,
|
||||
`openclaw.outcome`)
|
||||
- `openclaw.message.duration_ms` (гістограма, атрибути: `openclaw.channel`,
|
||||
- `openclaw.message.duration_ms` (histogram, атрибути: `openclaw.channel`,
|
||||
`openclaw.outcome`)
|
||||
|
||||
Черги + сеанси:
|
||||
|
||||
- `openclaw.queue.lane.enqueue` (лічильник, атрибути: `openclaw.lane`)
|
||||
- `openclaw.queue.lane.dequeue` (лічильник, атрибути: `openclaw.lane`)
|
||||
- `openclaw.queue.depth` (гістограма, атрибути: `openclaw.lane` або
|
||||
- `openclaw.queue.lane.enqueue` (counter, атрибути: `openclaw.lane`)
|
||||
- `openclaw.queue.lane.dequeue` (counter, атрибути: `openclaw.lane`)
|
||||
- `openclaw.queue.depth` (histogram, атрибути: `openclaw.lane` або
|
||||
`openclaw.channel=heartbeat`)
|
||||
- `openclaw.queue.wait_ms` (гістограма, атрибути: `openclaw.lane`)
|
||||
- `openclaw.session.state` (лічильник, атрибути: `openclaw.state`, `openclaw.reason`)
|
||||
- `openclaw.session.stuck` (лічильник, атрибути: `openclaw.state`)
|
||||
- `openclaw.session.stuck_age_ms` (гістограма, атрибути: `openclaw.state`)
|
||||
- `openclaw.run.attempt` (лічильник, атрибути: `openclaw.attempt`)
|
||||
- `openclaw.queue.wait_ms` (histogram, атрибути: `openclaw.lane`)
|
||||
- `openclaw.session.state` (counter, атрибути: `openclaw.state`, `openclaw.reason`)
|
||||
- `openclaw.session.stuck` (counter, атрибути: `openclaw.state`)
|
||||
- `openclaw.session.stuck_age_ms` (histogram, атрибути: `openclaw.state`)
|
||||
- `openclaw.run.attempt` (counter, атрибути: `openclaw.attempt`)
|
||||
|
||||
### Експортовані span-и (назви + ключові атрибути)
|
||||
|
||||
@ -374,14 +378,14 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload
|
||||
- `openclaw.session.stuck`
|
||||
- `openclaw.state`, `openclaw.ageMs`, `openclaw.queueDepth`
|
||||
|
||||
Коли захоплення вмісту явно ввімкнено, span-и моделі/інструментів також можуть містити
|
||||
Коли захоплення вмісту явно ввімкнено, span-и моделей/інструментів також можуть містити
|
||||
обмежені, відредаговані атрибути `openclaw.content.*` для конкретних класів вмісту,
|
||||
які ви дозволили.
|
||||
які ви явно дозволили.
|
||||
|
||||
### Вибірка + скидання
|
||||
### Вибірка + скидання буфера
|
||||
|
||||
- Вибірка трасувань: `diagnostics.otel.sampleRate` (0.0–1.0, лише кореневі span-и).
|
||||
- Інтервал експорту метрик: `diagnostics.otel.flushIntervalMs` (мінімум 1000 мс).
|
||||
- Вибірка traces: `diagnostics.otel.sampleRate` (0.0–1.0, лише кореневі span-и).
|
||||
- Інтервал експорту metrics: `diagnostics.otel.flushIntervalMs` (мінімум 1000ms).
|
||||
|
||||
### Примітки щодо протоколу
|
||||
|
||||
@ -389,23 +393,25 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload
|
||||
`OTEL_EXPORTER_OTLP_ENDPOINT`.
|
||||
- Якщо кінцева точка вже містить `/v1/traces` або `/v1/metrics`, вона використовується як є.
|
||||
- Якщо кінцева точка вже містить `/v1/logs`, вона використовується як є для журналів.
|
||||
- `diagnostics.otel.logs` вмикає експорт журналів OTLP для основного виводу журналювача.
|
||||
- `OPENCLAW_OTEL_PRELOADED=1` повторно використовує зовнішньо зареєстрований OpenTelemetry SDK
|
||||
для traces/metrics замість запуску NodeSDK, яким володіє Plugin.
|
||||
- `diagnostics.otel.logs` вмикає експорт журналів OTLP для основного виводу logger.
|
||||
|
||||
### Поведінка експорту журналів
|
||||
|
||||
- Журнали OTLP використовують ті самі структуровані записи, що записуються до `logging.file`.
|
||||
- Враховується `logging.level` (рівень журналів у файлах). Редагування консолі **не** застосовується
|
||||
- Дотримуються `logging.level` (рівень журналів файлів). Редагування консолі **не** застосовується
|
||||
до журналів OTLP.
|
||||
- Для інсталяцій із великим обсягом даних варто віддавати перевагу вибірці/фільтрації в колекторі OTLP.
|
||||
- Для інсталяцій із великим обсягом даних краще використовувати вибірку/фільтрацію на рівні OTLP collector.
|
||||
|
||||
## Поради з усунення несправностей
|
||||
|
||||
- **Gateway недоступний?** Спочатку виконайте `openclaw doctor`.
|
||||
- **Журнали порожні?** Перевірте, що Gateway запущений і записує у шлях файлу,
|
||||
- **Журнали порожні?** Перевірте, що Gateway запущено і він записує у шлях файлу,
|
||||
вказаний у `logging.file`.
|
||||
- **Потрібно більше деталей?** Установіть `logging.level` на `debug` або `trace` і повторіть спробу.
|
||||
- **Потрібно більше деталей?** Установіть `logging.level` у `debug` або `trace` і повторіть спробу.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Внутрішня будова журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі
|
||||
- [Внутрішня реалізація журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі
|
||||
- [Діагностика](/uk/gateway/configuration-reference#diagnostics) — експорт OpenTelemetry і конфігурація трасування кешу
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user