diff --git a/docs/uk/providers/google.md b/docs/uk/providers/google.md
index 7fdf4f45e..6ed9d789c 100644
--- a/docs/uk/providers/google.md
+++ b/docs/uk/providers/google.md
@@ -1,42 +1,42 @@
---
read_when:
- Ви хочете використовувати моделі Google Gemini з OpenClaw
- - Вам потрібен API-ключ або потік автентифікації OAuth
-summary: Налаштування Google Gemini (API-ключ + OAuth, генерація зображень, розуміння медіа, TTS, вебпошук)
+ - Вам потрібен ключ API або потік автентифікації OAuth
+summary: Налаштування Google Gemini (ключ API + OAuth, генерація зображень, розуміння медіа, TTS, вебпошук)
title: Google (Gemini)
x-i18n:
- generated_at: "2026-04-23T21:06:07Z"
+ generated_at: "2026-04-24T08:40:13Z"
model: gpt-5.4
provider: openai
- source_hash: b43d7171f56ecdfb49a25256783433e64f99a02760b3bc6f0e1055195f556f5d
+ source_hash: 7e66c9dd637e26976659d04b9b7e2452e6881945dab6011970f9e1c5e4a9a685
source_path: providers/google.md
workflow: 15
---
-Plugin Google надає доступ до моделей Gemini через Google AI Studio, а також до
-генерації зображень, розуміння медіа (image/audio/video), text-to-speech і web search через
+Плагін Google надає доступ до моделей Gemini через Google AI Studio, а також до
+генерації зображень, розуміння медіа (зображення/аудіо/відео), text-to-speech і вебпошуку через
Gemini Grounding.
-- Provider: `google`
-- Auth: `GEMINI_API_KEY` або `GOOGLE_API_KEY`
+- Провайдер: `google`
+- Автентифікація: `GEMINI_API_KEY` або `GOOGLE_API_KEY`
- API: Google Gemini API
-- Альтернативний provider: `google-gemini-cli` (OAuth)
+- Альтернативний провайдер: `google-gemini-cli` (OAuth)
## Початок роботи
-Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування.
+Оберіть бажаний спосіб автентифікації та виконайте кроки налаштування.
-
+
**Найкраще для:** стандартного доступу до Gemini API через Google AI Studio.
-
+
```bash
openclaw onboard --auth-choice gemini-api-key
```
- Або передайте ключ безпосередньо:
+ Або передайте ключ напряму:
```bash
openclaw onboard --non-interactive \
@@ -45,7 +45,7 @@ Gemini Grounding.
--gemini-api-key "$GEMINI_API_KEY"
```
-
+
```json5
{
agents: {
@@ -56,7 +56,7 @@ Gemini Grounding.
}
```
-
+
```bash
openclaw models list --provider google
```
@@ -64,47 +64,47 @@ Gemini Grounding.
- Підтримуються обидві змінні середовища: `GEMINI_API_KEY` і `GOOGLE_API_KEY`. Використовуйте ту, яка у вас уже налаштована.
+ Змінні середовища `GEMINI_API_KEY` і `GOOGLE_API_KEY` обидві підтримуються. Використовуйте ту, яка у вас уже налаштована.
- **Найкраще для:** повторного використання наявного входу Gemini CLI через PKCE OAuth замість окремого API-ключа.
+ **Найкраще для:** повторного використання наявного входу Gemini CLI через PKCE OAuth замість окремого ключа API.
- Provider `google-gemini-cli` є неофіційною інтеграцією. Деякі користувачі
- повідомляють про обмеження облікового запису при такому використанні OAuth. Використовуйте на власний ризик.
+ Провайдер `google-gemini-cli` є неофіційною інтеграцією. Деякі користувачі
+ повідомляють про обмеження облікового запису при використанні OAuth у такий спосіб. Використовуйте на власний ризик.
-
+
Локальна команда `gemini` має бути доступною в `PATH`.
```bash
# Homebrew
brew install gemini-cli
- # or npm
+ # або npm
npm install -g @google/gemini-cli
```
- OpenClaw підтримує як встановлення через Homebrew, так і глобальні встановлення npm, включно з
- поширеними схемами Windows/npm.
+ OpenClaw підтримує як встановлення через Homebrew, так і глобальні встановлення через npm, зокрема
+ поширені схеми Windows/npm.
-
+
```bash
openclaw models auth login --provider google-gemini-cli --set-default
```
-
+
```bash
openclaw models list --provider google-gemini-cli
```
- - Типова модель: `google-gemini-cli/gemini-3-flash-preview`
+ - Модель за замовчуванням: `google-gemini-cli/gemini-3-flash-preview`
- Псевдонім: `gemini-cli`
**Змінні середовища:**
@@ -115,60 +115,61 @@ Gemini Grounding.
(Або варіанти `GEMINI_CLI_*`.)
- Якщо запити Gemini CLI OAuth не працюють після входу, задайте `GOOGLE_CLOUD_PROJECT` або
+ Якщо OAuth-запити Gemini CLI не вдаються після входу, задайте `GOOGLE_CLOUD_PROJECT` або
`GOOGLE_CLOUD_PROJECT_ID` на хості gateway і повторіть спробу.
- Якщо вхід завершується помилкою до початку browser flow, переконайтеся, що локальну команду `gemini`
- встановлено й додано до `PATH`.
+ Якщо вхід не вдається ще до запуску потоку в браузері, переконайтеся, що локальна команда `gemini`
+ встановлена й доступна в `PATH`.
- Provider `google-gemini-cli`, який працює лише через OAuth, є окремою
- поверхнею text inference. Генерація зображень, розуміння медіа та Gemini Grounding залишаються на
- id provider `google`.
+ Провайдер `google-gemini-cli`, який працює лише через OAuth, є окремою поверхнею
+ текстового інференсу. Генерація зображень, розуміння медіа та Gemini Grounding залишаються на
+ ідентифікаторі провайдера `google`.
## Можливості
-| Можливість | Підтримується |
-| ---------------------- | ------------------------------ |
-| Chat completions | Так |
-| Генерація зображень | Так |
-| Генерація музики | Так |
-| Text-to-speech | Так |
-| Розуміння зображень | Так |
-| Транскрибування аудіо | Так |
-| Розуміння відео | Так |
-| Web search (Grounding) | Так |
-| Thinking/reasoning | Так (Gemini 2.5+ / Gemini 3+) |
-| Моделі Gemma 4 | Так |
+| Можливість | Підтримка |
+| --------------------- | ------------------------------ |
+| Завершення чату | Так |
+| Генерація зображень | Так |
+| Генерація музики | Так |
+| Text-to-speech | Так |
+| Голос у реальному часі| Так (Google Live API) |
+| Розуміння зображень | Так |
+| Транскрипція аудіо | Так |
+| Розуміння відео | Так |
+| Вебпошук (Grounding) | Так |
+| Thinking/reasoning | Так (Gemini 2.5+ / Gemini 3+) |
+| Моделі Gemma 4 | Так |
-Моделі Gemini 3 використовують `thinkingLevel`, а не `thinkingBudget`. OpenClaw зіставляє
-керування міркуваннями для Gemini 3, Gemini 3.1 і псевдонімів `gemini-*-latest` з
+Моделі Gemini 3 використовують `thinkingLevel` замість `thinkingBudget`. OpenClaw зіставляє
+керування міркуванням для Gemini 3, Gemini 3.1 і псевдоніма `gemini-*-latest` з
`thinkingLevel`, щоб типові/низьколатентні запуски не надсилали вимкнені
значення `thinkingBudget`.
Моделі Gemma 4 (наприклад, `gemma-4-26b-a4b-it`) підтримують режим thinking. OpenClaw
переписує `thinkingBudget` у підтримуваний Google `thinkingLevel` для Gemma 4.
-Установлення thinking у `off` зберігає вимкнений thinking замість зіставлення з
+Установлення thinking у `off` зберігає thinking вимкненим замість зіставлення з
`MINIMAL`.
## Генерація зображень
-Вбудований provider генерації зображень `google` типово використовує
+Вбудований провайдер генерації зображень `google` за замовчуванням використовує
`google/gemini-3.1-flash-image-preview`.
- Також підтримує `google/gemini-3-pro-image-preview`
- Генерація: до 4 зображень на запит
-- Режим редагування: увімкнений, до 5 вхідних зображень
+- Режим редагування: увімкнено, до 5 вхідних зображень
- Керування геометрією: `size`, `aspectRatio` і `resolution`
-Щоб використовувати Google як типовий provider зображень:
+Щоб використовувати Google як провайдер зображень за замовчуванням:
```json5
{
@@ -183,20 +184,20 @@ Gemini Grounding.
```
-Див. [Image Generation](/uk/tools/image-generation) щодо спільних параметрів tool, вибору provider і поведінки failover.
+Див. [Генерація зображень](/uk/tools/image-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover.
## Генерація відео
Вбудований Plugin `google` також реєструє генерацію відео через спільний
-tool `video_generate`.
+інструмент `video_generate`.
-- Типова модель відео: `google/veo-3.1-fast-generate-preview`
-- Режими: text-to-video, image-to-video і потоки з одним референсним відео
+- Модель відео за замовчуванням: `google/veo-3.1-fast-generate-preview`
+- Режими: text-to-video, image-to-video і потоки з посиланням на одне відео
- Підтримує `aspectRatio`, `resolution` і `audio`
- Поточне обмеження тривалості: **від 4 до 8 секунд**
-Щоб використовувати Google як типовий provider відео:
+Щоб використовувати Google як провайдер відео за замовчуванням:
```json5
{
@@ -211,22 +212,22 @@ tool `video_generate`.
```
-Див. [Video Generation](/uk/tools/video-generation) щодо спільних параметрів tool, вибору provider і поведінки failover.
+Див. [Генерація відео](/uk/tools/video-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover.
## Генерація музики
Вбудований Plugin `google` також реєструє генерацію музики через спільний
-tool `music_generate`.
+інструмент `music_generate`.
-- Типова модель музики: `google/lyria-3-clip-preview`
+- Модель музики за замовчуванням: `google/lyria-3-clip-preview`
- Також підтримує `google/lyria-3-pro-preview`
-- Керування prompt: `lyrics` і `instrumental`
-- Формат виводу: типово `mp3`, а також `wav` для `google/lyria-3-pro-preview`
-- Референсні входи: до 10 зображень
-- Запуски з підтримкою сесій відокремлюються через спільний потік task/status, включно з `action: "status"`
+- Керування підказкою: `lyrics` і `instrumental`
+- Формат виводу: `mp3` за замовчуванням, а також `wav` у `google/lyria-3-pro-preview`
+- Опорні входи: до 10 зображень
+- Запуски з підтримкою сесій відокремлюються через спільний потік задач/статусу, зокрема `action: "status"`
-Щоб використовувати Google як типовий provider музики:
+Щоб використовувати Google як провайдер музики за замовчуванням:
```json5
{
@@ -241,20 +242,20 @@ tool `music_generate`.
```
-Див. [Music Generation](/uk/tools/music-generation) щодо спільних параметрів tool, вибору provider і поведінки failover.
+Див. [Генерація музики](/uk/tools/music-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover.
## Text-to-speech
-Вбудований speech provider `google` використовує шлях Gemini API TTS з
+Вбудований мовний провайдер `google` використовує шлях Gemini API TTS з
`gemini-3.1-flash-tts-preview`.
-- Типовий голос: `Kore`
-- Auth: `messages.tts.providers.google.apiKey`, `models.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_API_KEY`
-- Вивід: WAV для звичайних вкладень TTS, PCM для Talk/telephony
-- Нативний вивід голосових повідомлень: не підтримується на цьому шляху Gemini API, оскільки API повертає PCM, а не Opus
+- Голос за замовчуванням: `Kore`
+- Автентифікація: `messages.tts.providers.google.apiKey`, `models.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_API_KEY`
+- Вивід: WAV для звичайних TTS-вкладень, PCM для Talk/телефонії
+- Нативний вивід голосових нотаток: не підтримується на цьому шляху Gemini API, оскільки API повертає PCM, а не Opus
-Щоб використовувати Google як типовий TTS provider:
+Щоб використовувати Google як TTS-провайдер за замовчуванням:
```json5
{
@@ -273,34 +274,91 @@ tool `music_generate`.
}
```
-Gemini API TTS приймає виразні аудіотеги у квадратних дужках у тексті, наприклад
-`[whispers]` або `[laughs]`. Щоб теги не потрапляли у видиму відповідь чату, але
-надсилалися до TTS, помістіть їх у блок `[[tts:text]]...[[/tts:text]]`:
+Gemini API TTS приймає виразні аудіотеги в квадратних дужках у тексті, наприклад
+`[whispers]` або `[laughs]`. Щоб приховати теги з видимої відповіді чату, але
+надсилати їх до TTS, помістіть їх у блок `[[tts:text]]...[[/tts:text]]`:
```text
-Here is the clean reply text.
+Ось чистий текст відповіді.
-[[tts:text]][whispers] Here is the spoken version.[[/tts:text]]
+[[tts:text]][whispers] Ось озвучена версія.[[/tts:text]]
```
-API-ключ Google Cloud Console, обмежений Gemini API, є валідним для цього
-provider. Це не окремий шлях Cloud Text-to-Speech API.
+Ключ API Google Cloud Console, обмежений Gemini API, є дійсним для цього
+провайдера. Це не окремий шлях Cloud Text-to-Speech API.
-## Розширена конфігурація
+## Голос у реальному часі
+
+Вбудований Plugin `google` реєструє провайдера голосу в реальному часі на базі
+Gemini Live API для серверних аудіомостів, таких як Voice Call і Google Meet.
+
+| Налаштування | Шлях конфігурації | За замовчуванням |
+| --------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| Модель | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
+| Голос | `...google.voice` | `Kore` |
+| Temperature | `...google.temperature` | (не задано) |
+| Чутливість початку VAD| `...google.startSensitivity` | (не задано) |
+| Чутливість кінця VAD | `...google.endSensitivity` | (не задано) |
+| Тривалість тиші | `...google.silenceDurationMs` | (не задано) |
+| Ключ API | `...google.apiKey` | Використовує `models.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_API_KEY` як запасний варіант |
+
+Приклад конфігурації Voice Call для роботи в реальному часі:
+
+```json5
+{
+ plugins: {
+ entries: {
+ "voice-call": {
+ enabled: true,
+ config: {
+ realtime: {
+ enabled: true,
+ provider: "google",
+ providers: {
+ google: {
+ model: "gemini-2.5-flash-native-audio-preview-12-2025",
+ voice: "Kore",
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+}
+```
+
+
+Google Live API використовує двоспрямоване аудіо та виклик функцій через WebSocket.
+OpenClaw адаптує аудіо телефонії/Meet-мосту до потоку PCM Live API Gemini і
+зберігає виклики інструментів у межах спільного контракту голосу в реальному часі. Залишайте `temperature`
+не заданим, якщо вам не потрібні зміни семплювання; OpenClaw пропускає недодатні значення,
+оскільки Google Live може повертати транскрипти без аудіо для `temperature: 0`.
+Транскрипція Gemini API вмикається без `languageCodes`; поточний Google
+SDK відхиляє підказки кодів мов на цьому шляху API.
+
+
+
+Сесії Talk у браузері в UI Control, як і раніше, потребують провайдера голосу в реальному часі з
+реалізацією сеансу браузерного WebRTC. Наразі цим шляхом є OpenAI Realtime; провайдер
+Google призначений для серверних мостів реального часу.
+
+
+## Розширене налаштування
-
+
Для прямих запусків Gemini API (`api: "google-generative-ai"`) OpenClaw
- передає налаштований дескриптор `cachedContent` далі в запити Gemini.
+ передає налаштований дескриптор `cachedContent` у запити Gemini.
- - Налаштовуйте параметри для конкретної моделі або глобальні параметри через
- `cachedContent` або застарілий `cached_content`
- - Якщо присутні обидва, `cachedContent` має пріоритет
+ - Налаштовуйте параметри для моделі або глобально за допомогою
+ `cachedContent` або застарілого `cached_content`
+ - Якщо присутні обидва, пріоритет має `cachedContent`
- Приклад значення: `cachedContents/prebuilt-context`
- - Використання Gemini cache-hit нормалізується в OpenClaw `cacheRead` з
- upstream `cachedContentTokenCount`
+ - Використання влучань кешу Gemini нормалізується в OpenClaw `cacheRead` з
+ висхідного `cachedContentTokenCount`
```json5
{
@@ -320,20 +378,20 @@ provider. Це не окремий шлях Cloud Text-to-Speech API.
-
- Під час використання OAuth-provider `google-gemini-cli` OpenClaw нормалізує
- JSON-вивід CLI так:
+
+ Під час використання OAuth-провайдера `google-gemini-cli` OpenClaw нормалізує
+ JSON-вивід CLI таким чином:
- Текст відповіді береться з поля CLI JSON `response`.
- - Usage резервно береться з `stats`, коли CLI залишає `usage` порожнім.
+ - Використання бере `stats` як запасний варіант, якщо CLI залишає `usage` порожнім.
- `stats.cached` нормалізується в OpenClaw `cacheRead`.
- - Якщо `stats.input` відсутній, OpenClaw виводить вхідні токени з
+ - Якщо `stats.input` відсутнє, OpenClaw обчислює вхідні токени з
`stats.input_tokens - stats.cached`.
-
- Якщо Gateway працює як daemon (launchd/systemd), переконайтеся, що `GEMINI_API_KEY`
+
+ Якщо Gateway працює як демон (launchd/systemd), переконайтеся, що `GEMINI_API_KEY`
доступний цьому процесу (наприклад, у `~/.openclaw/.env` або через
`env.shellEnv`).
@@ -343,15 +401,15 @@ provider. Це не окремий шлях Cloud Text-to-Speech API.
- Вибір provider, refs моделей і поведінки failover.
+ Вибір провайдерів, посилань на моделі та поведінки failover.
- Спільні параметри tool для зображень і вибір provider.
+ Спільні параметри інструмента зображень і вибір провайдера.
- Спільні параметри tool для відео і вибір provider.
+ Спільні параметри інструмента відео і вибір провайдера.
- Спільні параметри tool для музики і вибір provider.
+ Спільні параметри інструмента музики і вибір провайдера.
diff --git a/docs/uk/tools/capability-cookbook.md b/docs/uk/tools/capability-cookbook.md
index b962288f4..8e1157c4d 100644
--- a/docs/uk/tools/capability-cookbook.md
+++ b/docs/uk/tools/capability-cookbook.md
@@ -1,84 +1,92 @@
---
read_when:
- - Додавання нової основної можливості та поверхні реєстрації Plugin
- - Визначення, чи має код належати ядру, vendor Plugin чи feature Plugin
- - Підключення нового допоміжного засобу runtime для каналів або інструментів
+ - Додавання нової базової можливості та поверхні реєстрації Pluginів
+ - Визначення того, чи має код належати ядру, плагіну постачальника чи функціональному плагіну
+ - Підключення нового допоміжного компонента середовища виконання для каналів або інструментів
sidebarTitle: Adding Capabilities
-summary: Посібник для контриб’юторів із додавання нової спільної можливості до системи Plugin OpenClaw
-title: Додавання можливостей (посібник для контриб’юторів)
+summary: Посібник для учасників щодо додавання нової спільної можливості до системи Plugin в OpenClaw
+title: Додавання можливостей (посібник для учасників)
x-i18n:
- generated_at: "2026-04-23T23:07:26Z"
+ generated_at: "2026-04-24T08:40:13Z"
model: gpt-5.4
provider: openai
- source_hash: f1e3251b9150c9744d967e91f531dfce01435b13aea3a17088ccd54f2145d14f
+ source_hash: 864506dd3f61aa64e7c997c9d9e05ce0ad70c80a26a734d4f83b2e80331be4ab
source_path: tools/capability-cookbook.md
workflow: 15
---
- Це **посібник для контриб’юторів** для розробників ядра OpenClaw. Якщо ви
- створюєте зовнішній Plugin, див. [Створення Plugins](/uk/plugins/building-plugins)
- натомість.
+ Це **посібник для учасників** для розробників ядра OpenClaw. Якщо ви
+ створюєте зовнішній Plugin, натомість перегляньте [Building Plugins](/uk/plugins/building-plugins).
-Використовуйте це, коли OpenClaw потребує нового домену, такого як image generation, video
-generation або якоїсь майбутньої функціональної області з підтримкою vendor.
+Використовуйте це, коли OpenClaw потребує нової доменної області, такої як генерація зображень, генерація відео або якась майбутня функціональна область на основі постачальника.
Правило:
-- plugin = межа володіння
+- plugin = межа відповідальності
- capability = спільний контракт ядра
-Це означає, що не слід починати з прямого підключення vendor до каналу або
-інструмента. Починайте з визначення capability.
+Це означає, що не слід починати з прямого підключення постачальника до каналу або інструмента. Починайте з визначення можливості.
-## Коли створювати capability
+## Коли створювати можливість
-Створюйте нову capability, коли всі ці умови істинні:
+Створюйте нову можливість, коли всі ці умови істинні:
-1. її потенційно може реалізувати більше ніж один vendor
-2. канали, інструменти або feature Plugin мають споживати її, не зважаючи на
- vendor
-3. ядро має володіти поведінкою fallback, policy, config або delivery
+1. її потенційно може реалізувати більше ніж один постачальник
+2. канали, інструменти або функціональні Pluginи мають споживати її, не зважаючи на постачальника
+3. ядро має володіти поведінкою резервування, політики, конфігурації або доставки
-Якщо робота стосується лише vendor і спільного контракту ще не існує, зупиніться й спочатку визначте
-контракт.
+Якщо робота стосується лише постачальника й спільного контракту ще не існує, зупиніться й спочатку визначте контракт.
## Стандартна послідовність
1. Визначте типізований контракт ядра.
2. Додайте реєстрацію Plugin для цього контракту.
-3. Додайте спільний допоміжний засіб runtime.
-4. Підключіть один реальний vendor Plugin як доказ.
-5. Переведіть feature/channel-споживачів на допоміжний засіб runtime.
-6. Додайте contract-тести.
-7. Задокументуйте операторський config і модель володіння.
+3. Додайте спільний допоміжний компонент середовища виконання.
+4. Підключіть один реальний Plugin постачальника як доказ.
+5. Переведіть споживачів функцій/каналів на допоміжний компонент середовища виконання.
+6. Додайте тести контракту.
+7. Задокументуйте операторську конфігурацію та модель відповідальності.
## Що куди належить
Ядро:
-- типи request/response
-- registry провайдерів + resolution
-- поведінка fallback
-- schema config плюс поширені метадані docs `title` / `description` у вузлах вкладених об’єктів, wildcard, елементів масивів і composition
-- поверхня допоміжного засобу runtime
+- типи запиту/відповіді
+- реєстр провайдерів + визначення
+- поведінка резервування
+- схема конфігурації плюс поширені метадані документації `title` / `description` на вкладених об’єктах, wildcard, елементах масиву та вузлах композиції
+- поверхня допоміжного компонента середовища виконання
-Vendor Plugin:
+Plugin постачальника:
-- виклики API vendor
-- обробка auth vendor
-- vendor-специфічна нормалізація request
-- реєстрація реалізації capability
+- виклики API постачальника
+- обробка автентифікації постачальника
+- нормалізація запитів, специфічна для постачальника
+- реєстрація реалізації можливості
-Feature/channel Plugin:
+Функціональний/канальний Plugin:
-- викликає `api.runtime.*` або відповідний допоміжний засіб `plugin-sdk/*-runtime`
-- ніколи не викликає реалізацію vendor напряму
+- викликає `api.runtime.*` або відповідний допоміжний компонент `plugin-sdk/*-runtime`
+- ніколи не викликає реалізацію постачальника безпосередньо
+
+## Межі провайдера та Harness
+
+Використовуйте хуки провайдера, коли поведінка належить контракту провайдера моделі, а не загальному циклу агента. Приклади включають параметри запиту, специфічні для провайдера після вибору транспорту, пріоритет профілю автентифікації, накладання промптів і маршрутизацію подальшого резервування після перемикання моделі/профілю.
+
+Використовуйте хуки agent harness, коли поведінка належить середовищу виконання, яке виконує хід. Harness можуть класифікувати успішні, але непридатні результати спроб, такі як порожні відповіді, відповіді лише з міркуванням або лише з плануванням, щоб зовнішня політика резервування моделі могла прийняти рішення про повторну спробу.
+
+Зберігайте обидві межі вузькими:
+
+- ядро володіє політикою повторних спроб/резервування
+- Pluginи провайдерів володіють підказками щодо запитів/автентифікації/маршрутизації, специфічними для провайдера
+- Pluginи harness володіють класифікацією спроб, специфічною для середовища виконання
+- сторонні Pluginи повертають підказки, а не напряму змінюють стан ядра
## Контрольний список файлів
-Для нової capability очікуйте, що доведеться змінити такі області:
+Для нової можливості очікуйте зміни в таких ділянках:
- `src//types.ts`
- `src//...registry/runtime.ts`
@@ -90,41 +98,40 @@ Feature/channel Plugin:
- `src/plugins/runtime/index.ts`
- `src/plugin-sdk/.ts`
- `src/plugin-sdk/-runtime.ts`
-- один або кілька пакетів вбудованих Plugin
+- один або кілька пакетів вбудованих Pluginів
- config/docs/tests
-## Приклад: image generation
+## Приклад: генерація зображень
-Image generation дотримується стандартної форми:
+Генерація зображень дотримується стандартної форми:
1. ядро визначає `ImageGenerationProvider`
-2. ядро відкриває `registerImageGenerationProvider(...)`
-3. ядро відкриває `runtime.imageGeneration.generate(...)`
-4. Plugin `openai`, `google`, `fal` і `minimax` реєструють реалізації з підтримкою vendor
-5. майбутні vendor можуть реєструвати той самий контракт без зміни каналів/інструментів
+2. ядро надає `registerImageGenerationProvider(...)`
+3. ядро надає `runtime.imageGeneration.generate(...)`
+4. Pluginи `openai`, `google`, `fal` і `minimax` реєструють реалізації на основі постачальників
+5. майбутні постачальники можуть реєструвати той самий контракт без змін у каналах/інструментах
-Ключ config відокремлений від маршрутизації vision-analysis:
+Ключ конфігурації відокремлений від маршрутизації аналізу зображень:
-- `agents.defaults.imageModel` = аналіз зображень
-- `agents.defaults.imageGenerationModel` = генерація зображень
+- `agents.defaults.imageModel` = аналізувати зображення
+- `agents.defaults.imageGenerationModel` = генерувати зображення
-Тримайте їх окремо, щоб fallback і policy залишалися явними.
+Зберігайте їх окремими, щоб резервування та політика залишалися явними.
-## Контрольний список перевірки
+## Контрольний список для перевірки
-Перед випуском нової capability перевірте:
+Перш ніж випускати нову можливість, перевірте:
-- жоден канал/інструмент не імпортує код vendor напряму
-- допоміжний засіб runtime є спільним шляхом
-- принаймні один contract-тест перевіряє вбудоване володіння
-- docs config називають новий ключ model/config
-- docs Plugin пояснюють межу володіння
+- жоден канал/інструмент не імпортує код постачальника напряму
+- допоміжний компонент середовища виконання є спільним шляхом
+- принаймні один тест контракту перевіряє вбудовану відповідальність
+- документація config називає нову модель/ключ конфігурації
+- документація Pluginів пояснює межу відповідальності
-Якщо PR пропускає шар capability і жорстко вбудовує поведінку vendor у
-канал/інструмент, повертайте його назад і спочатку визначайте контракт.
+Якщо PR пропускає рівень можливості й жорстко вбудовує поведінку постачальника в канал/інструмент, поверніть його назад і спочатку визначте контракт.
## Пов’язане
- [Plugin](/uk/tools/plugin)
-- [Створення Skills](/uk/tools/creating-skills)
-- [Інструменти та Plugins](/uk/tools)
+- [Creating skills](/uk/tools/creating-skills)
+- [Tools and plugins](/uk/tools)
diff --git a/docs/uk/tools/plugin.md b/docs/uk/tools/plugin.md
index fe4631b7b..4d5e4eec8 100644
--- a/docs/uk/tools/plugin.md
+++ b/docs/uk/tools/plugin.md
@@ -2,29 +2,29 @@
read_when:
- Встановлення або налаштування плагінів
- Розуміння правил виявлення та завантаження плагінів
- - Робота з сумісними з Codex/Claude пакетами плагінів
+ - Робота з сумісними з Codex/Claude наборами плагінів
sidebarTitle: Install and Configure
summary: Встановлюйте, налаштовуйте та керуйте плагінами OpenClaw
title: Плагіни
x-i18n:
- generated_at: "2026-04-24T05:42:16Z"
+ generated_at: "2026-04-24T08:40:12Z"
model: gpt-5.4
provider: openai
- source_hash: a93114ddb312552f4c321b6e318f3e19810cf5059dd0c68fde93da41936566b8
+ source_hash: 83ab1218d6677ad518a4991ca546d55eed9648e1fa92b76b7433ecd5df569e28
source_path: tools/plugin.md
workflow: 15
---
-Плагіни розширюють OpenClaw новими можливостями: канали, постачальники моделей,
-інструменти, Skills, мовлення, транскрипція в реальному часі, голос у реальному часі,
-розуміння медіа, генерація зображень, генерація відео, отримання даних з вебу, вебпошук
-та інше. Деякі плагіни є **core** (постачаються разом з OpenClaw), інші —
-**external** (опубліковані спільнотою в npm).
+Плагіни розширюють OpenClaw новими можливостями: канали, провайдери моделей,
+каркаси агентів, інструменти, Skills, мовлення, транскрипція в реальному часі, голос у реальному
+часі, розуміння медіа, генерація зображень, генерація відео, веб-завантаження, веб-пошук
+та інше. Деякі плагіни є **core** (постачаються з OpenClaw), інші
+є **external** (опубліковані спільнотою в npm).
-## Швидкий початок
+## Швидкий старт
-
+
```bash
openclaw plugins list
```
@@ -35,7 +35,7 @@ x-i18n:
# З npm
openclaw plugins install @openclaw/voice-call
- # З локального каталогу або архіву
+ # Із локального каталогу або архіву
openclaw plugins install ./my-plugin
openclaw plugins install ./my-plugin.tgz
```
@@ -61,52 +61,51 @@ x-i18n:
```
Шлях встановлення використовує той самий механізм визначення, що й CLI: локальний
-шлях/архів, явний `clawhub:` або специфікація пакета без префікса
-(спочатку ClawHub, потім резервно npm).
+шлях/архів, явний `clawhub:` або специфікація пакета без префікса (спочатку ClawHub, потім резервно npm).
-Якщо конфігурація недійсна, встановлення зазвичай безпечно завершується з помилкою і вказує на
+Якщо конфігурація некоректна, встановлення зазвичай завершується відмовою й вказує вам на
`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях
-перевстановлення вбудованого плагіна для плагінів, які явно підтримують
+перевстановлення вбудованого плагіна для плагінів, які підтримують
`openclaw.install.allowInvalidConfigRecovery`.
-У пакетних інсталяціях OpenClaw не виконується завчасне встановлення всього дерева
-runtime-залежностей кожного вбудованого плагіна. Коли вбудований плагін, що належить OpenClaw, активний через
+Пакетні встановлення OpenClaw не встановлюють завчасно все дерево залежностей
+середовища виконання кожного вбудованого плагіна. Коли вбудований плагін, що належить OpenClaw, активний через
конфігурацію плагіна, застарілу конфігурацію каналу або маніфест із увімкненням за замовчуванням,
-під час запуску відновлюються лише оголошені runtime-залежності цього плагіна перед його імпортом.
-External-плагіни та користувацькі шляхи завантаження, як і раніше, потрібно встановлювати через
+під час запуску відновлюються лише оголошені залежності середовища виконання цього плагіна перед його імпортом.
+Зовнішні плагіни та користувацькі шляхи завантаження, як і раніше, потрібно встановлювати через
`openclaw plugins install`.
## Типи плагінів
OpenClaw розпізнає два формати плагінів:
-| Формат | Як це працює | Приклади |
-| ---------- | ----------------------------------------------------------------- | ------------------------------------------------------ |
-| **Native** | `openclaw.plugin.json` + runtime-модуль; виконується в тому ж процесі | Офіційні плагіни, пакети npm від спільноти |
+| Формат | Як це працює | Приклади |
+| ---------- | -------------------------------------------------------------- | ------------------------------------------------------ |
+| **Native** | `openclaw.plugin.json` + модуль середовища виконання; виконується в тому самому процесі | Офіційні плагіни, пакети npm від спільноти |
| **Bundle** | Сумісне з Codex/Claude/Cursor компонування; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
-Обидва відображаються в `openclaw plugins list`. Див. [Пакети плагінів](/uk/plugins/bundles) для деталей про пакети.
+Обидва відображаються в `openclaw plugins list`. Докладніше про набори плагінів див. у [Plugin Bundles](/uk/plugins/bundles).
-Якщо ви пишете native-плагін, почніть з [Створення плагінів](/uk/plugins/building-plugins)
-та [Огляд Plugin SDK](/uk/plugins/sdk-overview).
+Якщо ви пишете native плагін, почніть із [Building Plugins](/uk/plugins/building-plugins)
+та [Plugin SDK Overview](/uk/plugins/sdk-overview).
## Офіційні плагіни
### Доступні для встановлення (npm)
| Плагін | Пакет | Документація |
-| --------------- | --------------------- | ------------------------------------ |
-| Matrix | `@openclaw/matrix` | [Matrix](/uk/channels/matrix) |
-| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/uk/channels/msteams) |
-| Nostr | `@openclaw/nostr` | [Nostr](/uk/channels/nostr) |
-| Voice Call | `@openclaw/voice-call` | [Voice Call](/uk/plugins/voice-call) |
-| Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) |
-| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) |
+| --------------- | ---------------------- | ------------------------------------ |
+| Matrix | `@openclaw/matrix` | [Matrix](/uk/channels/matrix) |
+| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/uk/channels/msteams) |
+| Nostr | `@openclaw/nostr` | [Nostr](/uk/channels/nostr) |
+| Voice Call | `@openclaw/voice-call` | [Voice Call](/uk/plugins/voice-call) |
+| Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) |
+| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) |
-### Core (постачаються разом з OpenClaw)
+### Core (постачаються з OpenClaw)
-
+
`anthropic`, `byteplus`, `cloudflare-ai-gateway`, `github-copilot`, `google`,
`huggingface`, `kilocode`, `kimi-coding`, `minimax`, `mistral`, `qwen`,
`moonshot`, `nvidia`, `openai`, `opencode`, `opencode-go`, `openrouter`,
@@ -116,20 +115,20 @@ OpenClaw розпізнає два формати плагінів:
- `memory-core` — вбудований пошук у пам’яті (типово через `plugins.slots.memory`)
- - `memory-lancedb` — довготривала пам’ять зі встановленням на вимогу з автоматичним пригадуванням/захопленням (встановіть `plugins.slots.memory = "memory-lancedb"`)
+ - `memory-lancedb` — довготривала пам’ять із встановленням на вимогу та автоматичним пригадуванням/захопленням (установіть `plugins.slots.memory = "memory-lancedb"`)
-
+
`elevenlabs`, `microsoft`
- - `browser` — вбудований browser-плагін для browser-інструмента, CLI `openclaw browser`, методу Gateway `browser.request`, browser runtime та стандартного сервісу керування browser (увімкнений за замовчуванням; вимкніть його перед заміною)
+ - `browser` — вбудований browser Plugin для browser tool, CLI `openclaw browser`, методу Gateway `browser.request`, browser runtime та служби керування браузером за замовчуванням (увімкнений за замовчуванням; вимкніть його перед заміною)
- `copilot-proxy` — міст VS Code Copilot Proxy (вимкнений за замовчуванням)
-Шукаєте сторонні плагіни? Див. [Плагіни спільноти](/uk/plugins/community).
+Шукаєте сторонні плагіни? Див. [Community Plugins](/uk/plugins/community).
## Конфігурація
@@ -150,29 +149,29 @@ OpenClaw розпізнає два формати плагінів:
| Поле | Опис |
| ---------------- | --------------------------------------------------------- |
| `enabled` | Головний перемикач (типово: `true`) |
-| `allow` | Список дозволених плагінів (необов’язково) |
-| `deny` | Список заборонених плагінів (необов’язково; deny має пріоритет) |
+| `allow` | Дозволений список плагінів (необов’язково) |
+| `deny` | Заборонений список плагінів (необов’язково; заборона має пріоритет) |
| `load.paths` | Додаткові файли/каталоги плагінів |
| `slots` | Селектори ексклюзивних слотів (наприклад, `memory`, `contextEngine`) |
| `entries.\` | Перемикачі та конфігурація для окремого плагіна |
-Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway працює з увімкненими
-відстеженням конфігурації та внутрішньопроцесним перезапуском (типовий шлях `openclaw gateway`),
+Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway запущено з відстеженням
+конфігурації та увімкненим перезапуском у процесі (типовий шлях `openclaw gateway`),
цей перезапуск зазвичай виконується автоматично невдовзі після запису змін у конфігурацію.
-
- - **Вимкнений**: плагін існує, але правила ввімкнення його вимкнули. Конфігурація зберігається.
- - **Відсутній**: конфігурація посилається на ідентифікатор плагіна, який не було знайдено під час виявлення.
- - **Недійсний**: плагін існує, але його конфігурація не відповідає оголошеній схемі.
+
+ - **Вимкнений**: плагін існує, але правила ввімкнення вимкнули його. Конфігурація зберігається.
+ - **Відсутній**: конфігурація посилається на ідентифікатор плагіна, який не знайдено під час виявлення.
+ - **Некоректний**: плагін існує, але його конфігурація не відповідає оголошеній схемі.
## Виявлення та пріоритет
-OpenClaw сканує плагіни в такому порядку (перше співпадіння перемагає):
+OpenClaw сканує плагіни в такому порядку (перше знайдене співпадіння перемагає):
- `plugins.load.paths` — явні шляхи до файлів або каталогів.
+ `plugins.load.paths` — явні шляхи до файлу або каталогу.
@@ -184,7 +183,7 @@ OpenClaw сканує плагіни в такому порядку (перше
- Постачаються разом з OpenClaw. Багато з них увімкнено за замовчуванням (постачальники моделей, мовлення).
+ Постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (провайдери моделей, мовлення).
Інші потребують явного ввімкнення.
@@ -194,44 +193,44 @@ OpenClaw сканує плагіни в такому порядку (перше
- `plugins.enabled: false` вимикає всі плагіни
- `plugins.deny` завжди має пріоритет над allow
- `plugins.entries.\.enabled: false` вимикає цей плагін
-- Плагіни з робочого простору **вимкнені за замовчуванням** (їх треба явно ввімкнути)
-- Вбудовані плагіни дотримуються вбудованого набору, увімкненого за замовчуванням, якщо не перевизначено
+- Плагіни з робочого простору **вимкнені за замовчуванням** (їх потрібно явно ввімкнути)
+- Вбудовані плагіни дотримуються вбудованого набору, увімкненого за замовчуванням, якщо це не перевизначено
- Ексклюзивні слоти можуть примусово ввімкнути вибраний для цього слота плагін
-- Деякі вбудовані плагіни з режимом явного підключення автоматично вмикаються, коли конфігурація вказує
- на поверхню, що належить плагіну, наприклад посилання на модель постачальника, конфігурацію каналу або runtime
- harness
+- Деякі вбудовані opt-in плагіни вмикаються автоматично, коли конфігурація називає
+ поверхню, що належить плагіну, наприклад посилання на модель провайдера, конфігурацію каналу або
+ runtime каркаса
- Маршрути Codex сімейства OpenAI зберігають окремі межі плагінів:
- `openai-codex/*` належить плагіну OpenAI, тоді як вбудований плагін
- app-server Codex вибирається через `embeddedHarness.runtime: "codex"` або застарілі
- посилання на модель `codex/*`
+ `openai-codex/*` належить плагіну OpenAI, тоді як вбудований
+ app-server Plugin Codex вибирається через `embeddedHarness.runtime: "codex"` або застарілі
+ посилання на моделі `codex/*`
## Слоти плагінів (ексклюзивні категорії)
-Деякі категорії є ексклюзивними (одночасно активний лише один плагін):
+Деякі категорії є ексклюзивними (одночасно може бути активним лише один):
```json5
{
plugins: {
slots: {
- memory: "memory-core", // або "none", щоб вимкнути
+ memory: "memory-core", // або "none" для вимкнення
contextEngine: "legacy", // або ідентифікатор плагіна
},
},
}
```
-| Слот | Що він контролює | Типове значення |
-| --------------- | ----------------------- | ------------------- |
-| `memory` | Active Memory plugin | `memory-core` |
-| `contextEngine` | Активний механізм контексту | `legacy` (вбудований) |
+| Слот | Чим керує | Типове значення |
+| --------------- | ------------------------ | ------------------- |
+| `memory` | Active Memory Plugin | `memory-core` |
+| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) |
## Довідка CLI
```bash
-openclaw plugins list # стислий перелік
+openclaw plugins list # компактний список
openclaw plugins list --enabled # лише завантажені плагіни
-openclaw plugins list --verbose # детальні рядки для кожного плагіна
-openclaw plugins list --json # перелік у машиночитному форматі
+openclaw plugins list --verbose # докладні рядки для кожного плагіна
+openclaw plugins list --json # інвентар у машиночитному форматі
openclaw plugins inspect # докладна інформація
openclaw plugins inspect --json # машиночитний формат
openclaw plugins inspect --all # таблиця для всього набору
@@ -242,10 +241,10 @@ openclaw plugins install # встановити (спочат
openclaw plugins install clawhub: # встановити лише з ClawHub
openclaw plugins install --force # перезаписати наявне встановлення
openclaw plugins install # встановити з локального шляху
-openclaw plugins install -l # підключити (без копіювання) для розробки
+openclaw plugins install -l # під’єднати (без копіювання) для розробки
openclaw plugins install --marketplace
openclaw plugins install --marketplace https://github.com//
-openclaw plugins install --pin # зберегти точну розв’язану npm-специфікацію
+openclaw plugins install --pin # записати точну визначену специфікацію npm
openclaw plugins install --dangerously-force-unsafe-install
openclaw plugins update # оновити один плагін
openclaw plugins update --dangerously-force-unsafe-install
@@ -259,59 +258,60 @@ openclaw plugins enable
openclaw plugins disable
```
-Вбудовані плагіни постачаються разом з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад,
-вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований browser-плагін).
-Інші вбудовані плагіни все одно потребують `openclaw plugins enable `.
+Вбудовані плагіни постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад,
+вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований browser
+Plugin). Інші вбудовані плагіни все одно потребують `openclaw plugins enable `.
-`--force` перезаписує наявний встановлений плагін або пакет хуків на місці. Використовуйте
-`openclaw plugins update ` для звичайних оновлень відстежуваних npm-плагінів.
-Він не підтримується з `--link`, який повторно використовує шлях до джерела замість
-копіювання в кероване місце встановлення.
+`--force` перезаписує наявний встановлений плагін або пакет хуків на місці. Для
+звичайних оновлень відстежуваних npm плагінів використовуйте
+`openclaw plugins update `. Цей параметр не підтримується з `--link`, який повторно використовує шлях до джерела
+замість копіювання в кероване цільове місце встановлення.
Коли `plugins.allow` уже задано, `openclaw plugins install` додає
-ідентифікатор встановленого плагіна до цього списку allow перед його ввімкненням, щоб установлені
-плагіни можна було одразу завантажити після перезапуску.
+ідентифікатор встановленого плагіна до цього списку allow перед його ввімкненням, щоб установлені плагіни
+можна було одразу завантажити після перезапуску.
-`openclaw plugins update ` застосовується до відстежуваних установлень. Передача
-специфікації npm-пакета з dist-tag або точною версією зіставляє назву пакета
-назад із записом відстежуваного плагіна і зберігає нову специфікацію для майбутніх оновлень.
-Передача назви пакета без версії переводить точне закріплене встановлення назад на
-типову лінійку релізів реєстру. Якщо встановлений npm-плагін уже відповідає
-розв’язаній версії та збереженій ідентичності артефакту, OpenClaw пропускає оновлення
+`openclaw plugins update ` застосовується до відстежуваних встановлень. Передавання
+специфікації npm пакета з dist-tag або точною версією зіставляє назву пакета
+назад із записом відстежуваного плагіна та записує нову специфікацію для майбутніх оновлень.
+Передавання назви пакета без версії переводить точно закріплене встановлення назад на
+типову лінійку випусків реєстру. Якщо встановлений npm плагін уже відповідає
+визначеній версії та записаній ідентичності артефакту, OpenClaw пропускає оновлення
без завантаження, перевстановлення чи перезапису конфігурації.
-`--pin` працює лише для npm. Він не підтримується з `--marketplace`, оскільки
-встановлення з marketplace зберігають метадані джерела marketplace замість npm-специфікації.
+`--pin` стосується лише npm. Він не підтримується з `--marketplace`, оскільки
+встановлення з marketplace зберігають метадані джерела marketplace замість специфікації npm.
-`--dangerously-force-unsafe-install` — це аварійний режим обходу для хибних
-спрацьовувань вбудованого сканера небезпечного коду. Він дозволяє продовжити встановлення
-та оновлення плагінів попри вбудовані результати `critical`, але все одно
-не обходить блокування політики плагіна `before_install` або блокування через помилки сканування.
+`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибних
+спрацьовувань вбудованого сканера небезпечного коду. Воно дозволяє продовжити встановлення
+й оновлення плагінів попри вбудовані результати рівня `critical`, але все одно
+не обходить блокування політикою плагіна `before_install` або блокування через збій сканування.
-Цей прапорець CLI застосовується лише до процесів встановлення/оновлення плагінів. Встановлення залежностей Skills через Gateway
-натомість використовують відповідний параметр запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install`
-залишається окремим процесом завантаження/встановлення Skills через ClawHub.
+Цей прапорець CLI застосовується лише до потоків встановлення/оновлення плагінів. Встановлення залежностей Skills через Gateway
+натомість використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install`
+залишається окремим потоком завантаження/встановлення Skills через ClawHub.
-Сумісні пакети беруть участь у тому самому процесі list/inspect/enable/disable
-для плагінів. Поточна підтримка runtime охоплює bundle Skills, Claude command-skills,
+Сумісні набори беруть участь у тому самому процесі list/inspect/enable/disable
+для плагінів. Поточна підтримка середовища виконання включає bundle Skills, Claude command-skills,
типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і
-оголошені в маніфесті типові значення `lspServers`, Cursor command-skills і сумісні каталоги хуків Codex.
+оголошені в маніфесті типові значення `lspServers`, Cursor command-skills та сумісні каталоги
+хуків Codex.
-`openclaw plugins inspect ` також повідомляє про виявлені можливості пакета, а також
-підтримувані чи непідтримувані записи серверів MCP і LSP для плагінів на основі пакетів.
+`openclaw plugins inspect ` також повідомляє про виявлені можливості набору, а також
+підтримувані або непідтримувані записи серверів MCP і LSP для плагінів на основі наборів.
-Джерелами marketplace можуть бути відома назва Claude marketplace з
+Джерелами marketplace можуть бути відома назва marketplace Claude з
`~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або шлях до
`marketplace.json`, скорочений запис GitHub на кшталт `owner/repo`, URL репозиторію GitHub
-або git URL. Для віддалених marketplace записи плагінів мають залишатися в межах
-клонованого репозиторію marketplace і використовувати лише відносні шляхи як джерела.
+або URL git. Для віддалених marketplace записи плагінів повинні залишатися в межах
+клонованого репозиторію marketplace і використовувати лише відносні шляхи до джерел.
-Див. [довідку CLI `openclaw plugins`](/uk/cli/plugins) для повної інформації.
+Повні відомості див. у [довідці CLI `openclaw plugins`](/uk/cli/plugins).
-## Огляд Plugin API
+## Огляд API плагінів
-Native-плагіни експортують об’єкт entry, який надає `register(api)`. Старіші
-плагіни все ще можуть використовувати `activate(api)` як застарілий псевдонім, але нові плагіни мають
+Native плагіни експортують об’єкт входу, який надає `register(api)`. Старіші
+плагіни все ще можуть використовувати `activate(api)` як застарілий псевдонім, але нові плагіни повинні
використовувати `register`.
```typescript
@@ -332,49 +332,49 @@ export default definePluginEntry({
});
```
-OpenClaw завантажує об’єкт entry і викликає `register(api)` під час активації
-плагіна. Завантажувач усе ще використовує `activate(api)` як запасний варіант для старіших плагінів,
-але вбудовані плагіни та нові external-плагіни мають розглядати `register` як
+OpenClaw завантажує об’єкт входу та викликає `register(api)` під час
+активації плагіна. Завантажувач усе ще повертається до `activate(api)` для старіших плагінів,
+але вбудовані плагіни й нові зовнішні плагіни повинні розглядати `register` як
публічний контракт.
Поширені методи реєстрації:
-| Метод | Що він реєструє |
+| Метод | Що реєструє |
| --------------------------------------- | -------------------------- |
-| `registerProvider` | Постачальник моделей (LLM) |
+| `registerProvider` | Провайдер моделі (LLM) |
| `registerChannel` | Канал чату |
| `registerTool` | Інструмент агента |
| `registerHook` / `on(...)` | Хуки життєвого циклу |
-| `registerSpeechProvider` | Синтез мовлення / STT |
+| `registerSpeechProvider` | Text-to-speech / STT |
| `registerRealtimeTranscriptionProvider` | Потоковий STT |
-| `registerRealtimeVoiceProvider` | Двоспрямований голос у реальному часі |
+| `registerRealtimeVoiceProvider` | Двобічний голос у реальному часі |
| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо |
| `registerImageGenerationProvider` | Генерація зображень |
| `registerMusicGenerationProvider` | Генерація музики |
| `registerVideoGenerationProvider` | Генерація відео |
-| `registerWebFetchProvider` | Постачальник отримання/скрапінгу з вебу |
-| `registerWebSearchProvider` | Вебпошук |
-| `registerHttpRoute` | HTTP-ендпоінт |
+| `registerWebFetchProvider` | Провайдер веб-завантаження / скрапінгу |
+| `registerWebSearchProvider` | Веб-пошук |
+| `registerHttpRoute` | HTTP endpoint |
| `registerCommand` / `registerCli` | Команди CLI |
-| `registerContextEngine` | Механізм контексту |
+| `registerContextEngine` | Рушій контексту |
| `registerService` | Фонова служба |
Поведінка guard-хуків для типізованих хуків життєвого циклу:
-- `before_tool_call`: `{ block: true }` є остаточним; обробники з нижчим пріоритетом пропускаються.
-- `before_tool_call`: `{ block: false }` не має ефекту і не скасовує попереднє блокування.
-- `before_install`: `{ block: true }` є остаточним; обробники з нижчим пріоритетом пропускаються.
-- `before_install`: `{ block: false }` не має ефекту і не скасовує попереднє блокування.
-- `message_sending`: `{ cancel: true }` є остаточним; обробники з нижчим пріоритетом пропускаються.
-- `message_sending`: `{ cancel: false }` не має ефекту і не скасовує попереднє скасування.
+- `before_tool_call`: `{ block: true }` є фінальним; обробники з нижчим пріоритетом пропускаються.
+- `before_tool_call`: `{ block: false }` не виконує жодної дії та не скасовує попереднє блокування.
+- `before_install`: `{ block: true }` є фінальним; обробники з нижчим пріоритетом пропускаються.
+- `before_install`: `{ block: false }` не виконує жодної дії та не скасовує попереднє блокування.
+- `message_sending`: `{ cancel: true }` є фінальним; обробники з нижчим пріоритетом пропускаються.
+- `message_sending`: `{ cancel: false }` не виконує жодної дії та не скасовує попереднє скасування.
-Для повної інформації про поведінку типізованих хуків див. [Огляд SDK](/uk/plugins/sdk-overview#hook-decision-semantics).
+Повну інформацію про поведінку типізованих хуків див. в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics).
## Пов’язане
-- [Створення плагінів](/uk/plugins/building-plugins) — створіть власний плагін
-- [Пакети плагінів](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor
-- [Маніфест плагіна](/uk/plugins/manifest) — схема маніфесту
-- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додавання агентських інструментів у плагін
-- [Внутрішня архітектура плагінів](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження
-- [Плагіни спільноти](/uk/plugins/community) — сторонні каталоги
+- [Building Plugins](/uk/plugins/building-plugins) — створіть власний плагін
+- [Plugin Bundles](/uk/plugins/bundles) — сумісність наборів Codex/Claude/Cursor
+- [Plugin Manifest](/uk/plugins/manifest) — схема маніфесту
+- [Registering Tools](/uk/plugins/building-plugins#registering-agent-tools) — додавання інструментів агента до плагіна
+- [Plugin Internals](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження
+- [Community Plugins](/uk/plugins/community) — сторонні списки
diff --git a/docs/uk/web/control-ui.md b/docs/uk/web/control-ui.md
index 46c1ebffd..1001e9480 100644
--- a/docs/uk/web/control-ui.md
+++ b/docs/uk/web/control-ui.md
@@ -1,24 +1,24 @@
---
read_when:
- Ви хочете керувати Gateway з браузера
- - Ви хочете доступ Tailnet без SSH-тунелів
-summary: Браузерний UI керування для Gateway (чат, вузли, конфігурація)
-title: UI керування
+ - Ви хочете доступ через Tailnet без SSH-тунелів
+summary: Веб-інтерфейс керування для Gateway (чат, вузли, конфігурація)
+title: Інтерфейс керування
x-i18n:
- generated_at: "2026-04-24T04:49:08Z"
+ generated_at: "2026-04-24T08:40:13Z"
model: gpt-5.4
provider: openai
- source_hash: 2ad0d0cef7d842eddf665ba50f37403df258b17d4c072d22a30d1bc3830dc467
+ source_hash: c84a74e20d6c8829168025830ff4ec8f650f10f72fcaed7c8d2f5d92ab98d616
source_path: web/control-ui.md
workflow: 15
---
-UI керування — це невеликий односторінковий застосунок **Vite + Lit**, який Gateway віддає:
+Інтерфейс керування — це невеликий односторінковий застосунок **Vite + Lit**, який обслуговується Gateway:
-- за замовчуванням: `http://:18789/`
+- типово: `http://:18789/`
- необов’язковий префікс: задайте `gateway.controlUi.basePath` (наприклад, `/openclaw`)
-Він звертається **безпосередньо до WebSocket Gateway** на тому самому порту.
+Він взаємодіє **безпосередньо з WebSocket Gateway** на тому самому порту.
## Швидке відкриття (локально)
@@ -32,168 +32,172 @@ UI керування — це невеликий односторінковий
- `connect.params.auth.token`
- `connect.params.auth.password`
-- заголовки ідентифікації Tailscale Serve, коли `gateway.auth.allowTailscale: true`
-- заголовки ідентифікації trusted-proxy, коли `gateway.auth.mode: "trusted-proxy"`
+- заголовки ідентичності Tailscale Serve, коли `gateway.auth.allowTailscale: true`
+- заголовки ідентичності trusted-proxy, коли `gateway.auth.mode: "trusted-proxy"`
-Панель налаштувань інформаційної панелі зберігає токен для поточної сесії вкладки браузера
-та вибрану URL-адресу gateway; паролі не зберігаються. Під час початкового налаштування зазвичай
-створюється токен gateway для автентифікації зі спільним секретом при першому підключенні, але
-автентифікація паролем також працює, коли `gateway.auth.mode` має значення `"password"`.
+Панель налаштувань дашборду зберігає токен для поточної сесії вкладки браузера
+та вибрану URL-адресу gateway; паролі не зберігаються. Під час онбордингу
+зазвичай створюється токен gateway для автентифікації зі спільним секретом при
+першому підключенні, але автентифікація паролем також працює, коли
+`gateway.auth.mode` має значення `"password"`.
## Сполучення пристрою (перше підключення)
-Коли ви підключаєтеся до UI керування з нового браузера або пристрою, Gateway
-вимагає **одноразове підтвердження сполучення** — навіть якщо ви в тій самій Tailnet
-із `gateway.auth.allowTailscale: true`. Це захід безпеки для запобігання
-несанкціонованому доступу.
+Коли ви підключаєтеся до Control UI з нового браузера або пристрою, Gateway
+вимагає **одноразове підтвердження сполучення** — навіть якщо ви перебуваєте в
+тому самому Tailnet з `gateway.auth.allowTailscale: true`. Це захід безпеки для
+запобігання несанкціонованому доступу.
**Що ви побачите:** "disconnected (1008): pairing required"
**Щоб підтвердити пристрій:**
```bash
-# Показати список запитів, що очікують
+# Показати запити, що очікують
openclaw devices list
# Підтвердити за ID запиту
openclaw devices approve
```
-Якщо браузер повторно надсилає запит на сполучення зі зміненими даними автентифікації (роль/області доступу/public
-key), попередній запит, що очікує, замінюється, і створюється новий `requestId`.
+Якщо браузер повторює спробу сполучення зі зміненими даними автентифікації (роль/області доступу/публічний
+ключ), попередній запит, що очікує, замінюється новим, і створюється новий `requestId`.
Перед підтвердженням знову виконайте `openclaw devices list`.
-Якщо браузер уже сполучений і ви змінюєте доступ із читання на
-доступ запису/адміністратора, це вважається підвищенням рівня підтвердження, а не
-тихим повторним підключенням. OpenClaw зберігає старе підтвердження активним, блокує ширше повторне підключення
-і просить вас явно підтвердити новий набір областей доступу.
+Якщо браузер уже сполучений і ви змінюєте його доступ із читання на
+запис/адміністрування, це вважається підвищенням підтвердження, а не тихим
+повторним підключенням. OpenClaw залишає попереднє підтвердження активним,
+блокує ширше повторне підключення й просить вас явно підтвердити новий набір
+областей доступу.
-Після підтвердження пристрій запам’ятовується і не вимагатиме повторного підтвердження, якщо
-ви не відкличете його через `openclaw devices revoke --device --role `. Див.
-[Devices CLI](/uk/cli/devices) щодо ротації токенів і відкликання.
+Після підтвердження пристрій запам’ятовується і не вимагатиме повторного
+підтвердження, доки ви не відкличете його за допомогою `openclaw devices revoke --device --role `. Див.
+[Devices CLI](/uk/cli/devices) для ротації токенів і відкликання.
**Примітки:**
- Прямі локальні браузерні підключення через local loopback (`127.0.0.1` / `localhost`)
підтверджуються автоматично.
-- Підключення браузера через Tailnet і LAN все одно вимагають явного підтвердження, навіть якщо
- вони виконуються з тієї самої машини.
+- Браузерні підключення через Tailnet і LAN однаково вимагають явного
+ підтвердження, навіть якщо вони походять з тієї самої машини.
- Кожен профіль браузера генерує унікальний ID пристрою, тому зміна браузера або
очищення даних браузера вимагатиме повторного сполучення.
## Особиста ідентичність (локально в браузері)
-UI керування підтримує особисту ідентичність для кожного браузера (відображуване ім’я та
+Control UI підтримує особисту ідентичність для кожного браузера (відображуване ім’я та
аватар), яка додається до вихідних повідомлень для атрибуції в спільних сесіях. Вона
-зберігається в сховищі браузера, прив’язана до поточного профілю браузера і не
-синхронізується з іншими пристроями та не зберігається на сервері понад звичайні
-метадані авторства в стенограмі для повідомлень, які ви фактично надсилаєте. Очищення даних сайту або
-зміна браузера скидає її до порожнього значення.
+зберігається у сховищі браузера, прив’язана до поточного профілю браузера і не
+синхронізується з іншими пристроями та не зберігається на сервері поза звичайними
+метаданими авторства транскрипту для повідомлень, які ви фактично надсилаєте. Очищення
+даних сайту або зміна браузера скидає її до порожнього стану.
-## Кінцева точка конфігурації виконання
+## Кінцева точка конфігурації runtime
-UI керування отримує свої налаштування виконання з
+Control UI отримує свої runtime-налаштування з
`/__openclaw/control-ui-config.json`. Доступ до цієї кінцевої точки захищений тією самою
-автентифікацією gateway, що й решта HTTP-поверхні: неавтентифіковані браузери не можуть
-отримати її, а успішне отримання вимагає або вже дійсного токена/пароля gateway,
-ідентифікації Tailscale Serve, або ідентифікації trusted-proxy.
+автентифікацією gateway, що й решта HTTP-поверхні: неавтентифіковані браузери не
+можуть її отримати, а успішне отримання вимагає або вже чинного токена/пароля
+gateway, або ідентичності Tailscale Serve, або ідентичності trusted-proxy.
## Підтримка мов
-UI керування може локалізуватися під час першого завантаження на основі локалі вашого браузера.
-Щоб пізніше перевизначити її, відкрийте **Огляд -> Доступ до Gateway -> Мова**. Перемикач
-локалі знаходиться в картці доступу до Gateway, а не в розділі «Зовнішній вигляд».
+Control UI може локалізувати себе під час першого завантаження на основі локалі вашого браузера.
+Щоб перевизначити її пізніше, відкрийте **Overview -> Gateway Access -> Language**. Перемикач
+локалі розташований у картці Gateway Access, а не в розділі Appearance.
- Підтримувані локалі: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `tr`, `uk`, `id`, `pl`, `th`
-- Переклади, відмінні від англійської, ледаче завантажуються в браузері.
-- Вибрана локаль зберігається в сховищі браузера й повторно використовується під час майбутніх відвідувань.
+- Неанглійські переклади ліниво завантажуються в браузері.
+- Вибрана локаль зберігається у сховищі браузера і повторно використовується під час наступних відвідувань.
- Відсутні ключі перекладу повертаються до англійської.
## Що він може робити (сьогодні)
-- Чат із моделлю через Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`)
-- Напряму взаємодіяти з OpenAI Realtime з браузера через WebRTC. Gateway
- випускає короткоживучий клієнтський секрет Realtime через `talk.realtime.session`; браузер
+- Спілкуватися з моделлю через Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`)
+- Підключатися до OpenAI Realtime безпосередньо з браузера через WebRTC. Gateway
+ випускає короткоживучий секрет клієнта Realtime через `talk.realtime.session`; браузер
надсилає аудіо з мікрофона безпосередньо до OpenAI і пересилає виклики інструмента
- `openclaw_agent_consult` назад через `chat.send` для більшої
- налаштованої моделі OpenClaw.
-- Потокове передавання викликів інструментів + картки виводу інструментів у реальному часі в чаті (події агента)
-- Канали: вбудовані, а також стан bundled/external plugin каналів, QR-вхід і конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`)
-- Екземпляри: список присутності + оновлення (`system-presence`)
-- Сесії: список + перевизначення для кожної сесії моделі/thinking/fast/verbose/trace/reasoning (`sessions.list`, `sessions.patch`)
-- Dreams: статус Dreaming, перемикач увімкнення/вимкнення та читач Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)
+ `openclaw_agent_consult` назад через `chat.send` для більшої налаштованої
+ моделі OpenClaw.
+- Потоково передавати виклики інструментів і картки живого виводу інструментів у Chat (події агента)
+- Канали: статус вбудованих, bundled і зовнішніх plugin-каналів, вхід через QR та конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`)
+- Екземпляри: список присутності та оновлення (`system-presence`)
+- Сесії: список і перевизначення моделі/мислення/швидко/докладно/трасування/міркування для кожної сесії (`sessions.list`, `sessions.patch`)
+- Dreams: статус dreaming, перемикач увімкнення/вимкнення та читач Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)
- Завдання Cron: список/додавання/редагування/запуск/увімкнення/вимкнення + історія запусків (`cron.*`)
- Skills: статус, увімкнення/вимкнення, встановлення, оновлення API-ключів (`skills.*`)
-- Node: список + обмеження (`node.list`)
-- Підтвердження exec: редагування списків дозволів gateway або node + політика запитів для `exec host=gateway/node` (`exec.approvals.*`)
+- Вузли: список і можливості (`node.list`)
+- Підтвердження exec: редагування allowlist для gateway або node + політика запиту для `exec host=gateway/node` (`exec.approvals.*`)
- Конфігурація: перегляд/редагування `~/.openclaw/openclaw.json` (`config.get`, `config.set`)
- Конфігурація: застосування + перезапуск із валідацією (`config.apply`) і пробудження останньої активної сесії
-- Записи конфігурації містять захист base-hash, щоб запобігти перезапису одночасних змін
-- Записи конфігурації (`config.set`/`config.apply`/`config.patch`) також виконують попередню перевірку активного розв’язання SecretRef для посилань у надісланому конфігураційному payload; нерозв’язані активні надіслані посилання відхиляються до запису
-- Схема конфігурації + рендеринг форми (`config.schema` / `config.schema.lookup`,
- включно з `title` / `description` поля, відповідними UI-підказками, зведеннями
- безпосередніх дочірніх елементів, метаданими документації для вузлів вкладених об’єктів/wildcard/масивів/композицій,
+- Записи конфігурації включають захист base-hash, щоб запобігти перезапису одночасних змін
+- Записи конфігурації (`config.set`/`config.apply`/`config.patch`) також попередньо перевіряють активне розв’язання SecretRef для посилань у надісланому payload конфігурації; нерозв’язані активні надіслані посилання відхиляються до запису
+- Схема конфігурації + рендеринг форм (`config.schema` / `config.schema.lookup`,
+ включно з полями `title` / `description`, відповідними UI-підказками, негайними
+ зведеннями дочірніх елементів, метаданими документації для вузлів nested object/wildcard/array/composition,
а також схемами plugin і каналів, коли вони доступні); редактор Raw JSON
- доступний лише тоді, коли snapshot має безпечний round-trip необробленого вигляду
-- Якщо snapshot не можна безпечно виконати round-trip як необроблений текст, UI керування примусово вмикає режим Form і вимикає режим Raw для цього snapshot
-- У редакторі Raw JSON кнопка "Reset to saved" зберігає форму, створену в raw (форматування, коментарі, розмітку `$include`), замість повторного рендерингу сплощеного snapshot, тож зовнішні зміни переживають скидання, коли snapshot можна безпечно виконати round-trip
-- Структуровані значення об’єктів SecretRef рендеряться як лише для читання в текстових полях форми, щоб запобігти випадковому пошкодженню через перетворення об’єкта на рядок
+ доступний лише тоді, коли знімок має безпечний raw round-trip
+- Якщо знімок не може безпечно пройти raw round-trip, Control UI примусово вмикає режим Form і вимикає режим Raw для цього знімка
+- У редакторі Raw JSON дія "Reset to saved" зберігає форму, створену в raw-режимі (форматування, коментарі, макет `$include`), замість повторного рендерингу сплощеного знімка, тож зовнішні зміни зберігаються після скидання, якщо знімок може безпечно пройти raw round-trip
+- Значення структурованих об’єктів SecretRef у формі відображаються лише для читання в текстових полях, щоб запобігти випадковому пошкодженню через перетворення об’єкта на рядок
- Налагодження: знімки status/health/models + журнал подій + ручні RPC-виклики (`status`, `health`, `models.list`)
- Журнали: live tail журналів файлів gateway із фільтрацією/експортом (`logs.tail`)
-- Оновлення: запуск оновлення пакунка/git + перезапуск (`update.run`) зі звітом про перезапуск
+- Оновлення: запуск оновлення пакета/git + перезапуск (`update.run`) зі звітом про перезапуск
Примітки до панелі завдань Cron:
-- Для ізольованих завдань доставлення за замовчуванням оголошує зведення. Ви можете перемкнути на none, якщо хочете лише внутрішні запуски.
+- Для ізольованих завдань типово використовується delivery з оголошенням зведення. Ви можете перемкнути на none, якщо хочете лише внутрішні запуски.
- Поля channel/target з’являються, коли вибрано announce.
-- Режим Webhook використовує `delivery.mode = "webhook"` із `delivery.to`, установленим на дійсну HTTP(S) URL-адресу Webhook.
-- Для завдань main-session доступні режими доставлення webhook і none.
-- Розширені елементи редагування містять видалення після запуску, очищення перевизначення агента, точні/зміщені параметри cron,
- перевизначення model/thinking агента та перемикачі доставлення best-effort.
-- Валідація форми вбудована з помилками на рівні полів; некоректні значення вимикають кнопку збереження, доки їх не буде виправлено.
-- Установіть `cron.webhookToken`, щоб надсилати окремий bearer token; якщо його не задано, webhook надсилається без заголовка auth.
-- Застарілий fallback: збережені legacy-завдання з `notify: true` все ще можуть використовувати `cron.webhook`, доки не буде виконано міграцію.
+- Режим Webhook використовує `delivery.mode = "webhook"` з `delivery.to`, встановленим на дійсну URL-адресу HTTP(S) Webhook.
+- Для завдань main-session доступні режими доставки webhook і none.
+- Розширені елементи керування редагуванням включають delete-after-run, очищення перевизначення агента, точні/ступінчасті параметри cron,
+ перевизначення моделі/мислення агента та перемикачі delivery у режимі best-effort.
+- Валідація форми виконується вбудовано, з помилками на рівні полів; некоректні значення вимикають кнопку збереження, доки їх не буде виправлено.
+- Встановіть `cron.webhookToken`, щоб надсилати окремий bearer-токен; якщо його не вказано, webhook надсилається без заголовка автентифікації.
+- Застарілий запасний варіант: збережені застарілі завдання з `notify: true` усе ще можуть використовувати `cron.webhook`, доки їх не буде мігровано.
-## Поведінка чату
+## Поведінка Chat
-- `chat.send` є **неблокувальним**: він одразу підтверджується з `{ runId, status: "started" }`, а відповідь передається потоком через події `chat`.
-- Повторне надсилання з тим самим `idempotencyKey` повертає `{ status: "in_flight" }` під час виконання і `{ status: "ok" }` після завершення.
-- Відповіді `chat.history` обмежені за розміром для безпеки UI. Коли записи стенограми надто великі, Gateway може усікати довгі текстові поля, пропускати важкі блоки метаданих і замінювати надмірно великі повідомлення заповнювачем (`[chat.history omitted: message too large]`).
-- Зображення помічника/згенеровані зображення зберігаються як керовані медіапосилання і знову віддаються через автентифіковані медіа-URL Gateway, тож перезавантаження не залежать від того, чи залишаються необроблені payload-и зображень base64 у відповіді історії чату.
-- `chat.history` також прибирає inline-теги директив, призначені лише для відображення, із видимого тексту помічника (наприклад, `[[reply_to_*]]` і `[[audio_as_voice]]`), XML payload-и викликів інструментів у звичайному тексті (зокрема `...`, `...`, `...`, `...` і усічені блоки викликів інструментів), а також leaked ASCII/full-width токени керування моделлю, і пропускає записи помічника, у яких увесь видимий текст — це лише точний тихий токен `NO_REPLY` / `no_reply`.
-- `chat.inject` додає примітку помічника до стенограми сесії та розсилає подію `chat` для оновлень лише UI (без запуску агента, без доставлення через канал).
-- Перемикачі моделі й thinking у заголовку чату одразу змінюють активну сесію через `sessions.patch`; це постійні перевизначення сесії, а не параметри надсилання лише на один хід.
-- Режим Talk використовує зареєстрованого постачальника голосу realtime. Налаштуйте OpenAI за допомогою
- `talk.provider: "openai"` разом із `talk.providers.openai.apiKey`, або повторно використайте
- конфігурацію realtime-постачальника Voice Call. Браузер ніколи не отримує стандартний
- API-ключ OpenAI; він отримує лише ефемерний клієнтський секрет Realtime. Підказка сесії
- Realtime збирається Gateway; `talk.realtime.session` не приймає перевизначення інструкцій, надані викликачем.
-- У composer чату елемент керування Talk — це кнопка з хвилями поруч із
- кнопкою диктування з мікрофона. Коли Talk запускається, рядок статусу composer показує
+- `chat.send` є **неблокувальним**: він негайно підтверджує запит з `{ runId, status: "started" }`, а відповідь потоково передається через події `chat`.
+- Повторне надсилання з тим самим `idempotencyKey` повертає `{ status: "in_flight" }` під час виконання та `{ status: "ok" }` після завершення.
+- Відповіді `chat.history` обмежені за розміром для безпеки UI. Якщо записи транскрипту надто великі, Gateway може обрізати довгі текстові поля, пропускати важкі блоки метаданих і замінювати надмірно великі повідомлення заглушкою (`[chat.history omitted: message too large]`).
+- Зображення assistant/generated зберігаються як керовані медіапосилання і повертаються через автентифіковані медіа-URL Gateway, тому повторне завантаження не залежить від того, чи залишаються в відповіді історії чату сирі base64-пayload зображень.
+- `chat.history` також прибирає з видимого тексту assistant вбудовані теги директив лише для відображення (наприклад, `[[reply_to_*]]` і `[[audio_as_voice]]`), XML-payload простого тексту для викликів інструментів (включно з `...`, `...`, `...`, `...` і обрізаними блоками викликів інструментів), а також витеклі токени керування моделлю ASCII/full-width, і пропускає записи assistant, де весь видимий текст — це лише точний silent token `NO_REPLY` / `no_reply`.
+- `chat.inject` додає примітку assistant до транскрипту сесії та транслює подію `chat` для оновлень лише UI (без запуску агента, без доставки в канал).
+- Перемикачі моделі й мислення в заголовку чату негайно застосовують зміни до активної сесії через `sessions.patch`; це постійні перевизначення сесії, а не параметри надсилання лише на один хід.
+- Режим Talk використовує зареєстрований realtime voice provider, який підтримує
+ браузерні WebRTC-сесії. Налаштуйте OpenAI через `talk.provider: "openai"` разом із
+ `talk.providers.openai.apiKey`, або повторно використайте конфігурацію realtime provider для Voice Call. Браузер ніколи не отримує стандартний API-ключ OpenAI; він отримує
+ лише ефемерний секрет клієнта Realtime. Google Live realtime voice підтримується
+ для серверного Voice Call і мостів Google Meet, але поки що не для цього
+ браузерного шляху WebRTC. Підказка сесії Realtime збирається Gateway;
+ `talk.realtime.session` не приймає перевизначення інструкцій, надані викликачем.
+- У composer Chat елемент керування Talk — це кнопка з хвилями поруч із
+ кнопкою диктування з мікрофона. Коли Talk запускається, рядок стану composer показує
`Connecting Talk...`, потім `Talk live`, поки підключено аудіо, або
- `Asking OpenClaw...`, поки realtime-виклик інструмента консультується з налаштованою
+ `Asking OpenClaw...`, поки виклик realtime-інструмента консультується з налаштованою
більшою моделлю через `chat.send`.
- Зупинка:
- Натисніть **Stop** (викликає `chat.abort`)
- - Поки запуск активний, звичайні подальші повідомлення стають у чергу. Натисніть **Steer** на повідомленні в черзі, щоб вставити це подальше повідомлення в поточний хід.
- - Введіть `/stop` (або окремі фрази переривання, як-от `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), щоб перервати поза смугою
- - `chat.abort` підтримує `{ sessionKey }` (без `runId`) для переривання всіх активних запусків для цієї сесії
-- Часткове збереження під час переривання:
- - Коли запуск переривається, частковий текст помічника все одно може відображатися в UI
- - Gateway зберігає частковий текст помічника в історію стенограми перерваного запуску, коли існує буферизований вивід
- - Збережені записи містять метадані переривання, щоб споживачі стенограми могли відрізнити часткові фрагменти переривання від звичайного завершеного виводу
+ - Поки запуск активний, звичайні наступні повідомлення стають у чергу. Натисніть **Steer** на повідомленні в черзі, щоб вставити це продовження в поточний хід.
+ - Введіть `/stop` (або окремі фрази переривання, як-от `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), щоб перервати поза чергою
+ - `chat.abort` підтримує `{ sessionKey }` (без `runId`) для переривання всіх активних запусків цієї сесії
+- Збереження часткового результату після переривання:
+ - Коли запуск перервано, частковий текст assistant усе ще може відображатися в UI
+ - Gateway зберігає частковий текст assistant у історії транскрипту, якщо існує буферизований вивід
+ - Збережені записи містять метадані переривання, щоб споживачі транскрипту могли відрізнити часткові результати після переривання від звичайного завершеного виводу
## Hosted embeds
-Повідомлення помічника можуть відображати вбудований розміщений вебвміст за допомогою shortcode `[embed ...]`.
-Політика sandbox iframe керується через
+Повідомлення assistant можуть відображати вбудований hosted вебвміст за допомогою shortcode `[embed ...]`.
+Політика sandbox для iframe керується параметром
`gateway.controlUi.embedSandbox`:
- `strict`: вимикає виконання скриптів усередині hosted embeds
-- `scripts`: дозволяє інтерактивні embeds, зберігаючи ізоляцію origin; це
- значення за замовчуванням і зазвичай його достатньо для самодостатніх браузерних ігор/віджетів
-- `trusted`: додає `allow-same-origin` поверх `allow-scripts` для документів того самого сайту,
- яким навмисно потрібні ширші привілеї
+- `scripts`: дозволяє інтерактивні embeds, зберігаючи ізоляцію походження; це
+ типове значення, і його зазвичай достатньо для самодостатніх браузерних ігор/віджетів
+- `trusted`: додає `allow-same-origin` поверх `allow-scripts` для same-site
+ документів, яким навмисно потрібні розширені привілеї
Приклад:
@@ -207,19 +211,19 @@ UI керування може локалізуватися під час пер
}
```
-Використовуйте `trusted` лише тоді, коли вбудованому документу справді потрібна
-поведінка same-origin. Для більшості згенерованих агентом ігор та інтерактивних canvas
-`cripts` є безпечнішим вибором.
+Використовуйте `trusted` лише тоді, коли вбудованому документу справді потрібна поведінка
+same-origin. Для більшості створених агентом ігор та інтерактивних canvas `scripts` —
+безпечніший вибір.
-Абсолютні зовнішні URL-адреси embed `http(s)` за замовчуванням залишаються заблокованими. Якщо ви
-свідомо хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, установіть
+Абсолютні зовнішні URL для embed `http(s)` залишаються заблокованими типово. Якщо ви
+свідомо хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, задайте
`gateway.controlUi.allowExternalEmbedUrls: true`.
-## Доступ Tailnet (рекомендовано)
+## Доступ через Tailnet (рекомендовано)
-### Інтегрований Tailscale Serve (рекомендовано)
+### Інтегрований Tailscale Serve (бажано)
-Залиште Gateway на loopback і дозвольте Tailscale Serve проксіювати його через HTTPS:
+Залиште Gateway на loopback і дозвольте Tailscale Serve проксувати його через HTTPS:
```bash
openclaw gateway --tailscale serve
@@ -227,22 +231,22 @@ openclaw gateway --tailscale serve
Відкрийте:
-- `https:///` (або ваш налаштований `gateway.controlUi.basePath`)
+- `https:///` (або налаштований вами `gateway.controlUi.basePath`)
-За замовчуванням запити Serve до UI керування/WebSocket можуть автентифікуватися через заголовки ідентифікації Tailscale
+Типово запити Control UI/WebSocket Serve можуть проходити автентифікацію через заголовки ідентичності Tailscale
(`tailscale-user-login`), коли `gateway.auth.allowTailscale` має значення `true`. OpenClaw
-перевіряє ідентичність, розв’язуючи адресу `x-forwarded-for` за допомогою
+перевіряє ідентичність, визначаючи адресу `x-forwarded-for` за допомогою
`tailscale whois` і звіряючи її із заголовком, і приймає їх лише тоді, коли
-запит потрапляє на loopback із заголовками Tailscale `x-forwarded-*`. Установіть
+запит потрапляє на loopback із заголовками Tailscale `x-forwarded-*`. Задайте
`gateway.auth.allowTailscale: false`, якщо хочете вимагати явні облікові дані зі спільним секретом
навіть для трафіку Serve. Тоді використовуйте `gateway.auth.mode: "token"` або
`"password"`.
-Для цього асинхронного шляху ідентифікації Serve невдалі спроби автентифікації для тієї самої IP-адреси клієнта
-та області автентифікації серіалізуються перед записами обмеження швидкості. Тому одночасні хибні повторні спроби
-з того самого браузера можуть показувати `retry later` у другому запиті
+Для цього асинхронного шляху ідентичності Serve невдалі спроби автентифікації для тієї самої IP-адреси клієнта
+та області автентифікації серіалізуються перед записами обмеження швидкості.
+Тому одночасні хибні повторні спроби з того самого браузера можуть показувати `retry later` у другому запиті
замість двох звичайних невідповідностей, що змагаються паралельно.
-Автентифікація Serve без токена припускає, що хост gateway є довіреним. Якщо на цьому хості
-може виконуватися недовірений локальний код, вимагайте автентифікацію токеном/паролем.
+Автентифікація Serve без токена передбачає, що хост gateway є довіреним. Якщо на цьому хості може виконуватися
+недовірений локальний код, вимагайте автентифікацію токеном/паролем.
### Прив’язка до tailnet + токен
@@ -252,29 +256,29 @@ openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
Потім відкрийте:
-- `http://:18789/` (або ваш налаштований `gateway.controlUi.basePath`)
+- `http://:18789/` (або налаштований вами `gateway.controlUi.basePath`)
Вставте відповідний спільний секрет у налаштування UI (він надсилається як
`connect.params.auth.token` або `connect.params.auth.password`).
## Незахищений HTTP
-Якщо ви відкриваєте інформаційну панель через звичайний HTTP (`http://` або `http://`),
-браузер працює в **незахищеному контексті** і блокує WebCrypto. За замовчуванням
-OpenClaw **блокує** підключення UI керування без ідентичності пристрою.
+Якщо ви відкриваєте дашборд через звичайний HTTP (`http://` або `http://`),
+браузер працює в **незахищеному контексті** й блокує WebCrypto. Типово
+OpenClaw **блокує** підключення Control UI без ідентичності пристрою.
Задокументовані винятки:
-- сумісність localhost-only для незахищеного HTTP з `gateway.controlUi.allowInsecureAuth=true`
-- успішна автентифікація оператора UI керування через `gateway.auth.mode: "trusted-proxy"`
+- сумісність із незахищеним HTTP лише для localhost з `gateway.controlUi.allowInsecureAuth=true`
+- успішна автентифікація оператора в Control UI через `gateway.auth.mode: "trusted-proxy"`
- аварійний варіант `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
-**Рекомендоване виправлення:** використовуйте HTTPS (Tailscale Serve) або відкрийте UI локально:
+**Рекомендоване виправлення:** використовуйте HTTPS (Tailscale Serve) або відкривайте UI локально:
- `https:///` (Serve)
- `http://127.0.0.1:18789/` (на хості gateway)
-**Поведінка перемикача незахищеної автентифікації:**
+**Поведінка перемикача insecure-auth:**
```json5
{
@@ -288,7 +292,7 @@ OpenClaw **блокує** підключення UI керування без і
`allowInsecureAuth` — це лише локальний перемикач сумісності:
-- Він дозволяє сесіям UI керування на localhost продовжуватися без ідентичності пристрою в
+- Він дозволяє сесіям Control UI на localhost продовжувати роботу без ідентичності пристрою в
незахищених HTTP-контекстах.
- Він не обходить перевірки сполучення.
- Він не послаблює вимоги до ідентичності пристрою для віддалених підключень (не localhost).
@@ -305,71 +309,71 @@ OpenClaw **блокує** підключення UI керування без і
}
```
-`dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою в UI керування і є
-серйозним зниженням безпеки. Після аварійного використання швидко скасуйте цю зміну.
+`dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою для Control UI і є
+серйозним зниженням рівня безпеки. Після аварійного використання швидко поверніть усе назад.
Примітка щодо trusted-proxy:
-- успішна автентифікація trusted-proxy може допускати **операторські** сесії UI керування без
+- успішна автентифікація trusted-proxy може допускати **operator**-сесії Control UI без
ідентичності пристрою
-- це **не** поширюється на сесії UI керування з роллю node
+- це **не** поширюється на Control UI-сесії з роллю node
- reverse proxy на loopback того самого хоста все одно не задовольняють автентифікацію trusted-proxy; див.
- [Автентифікація Trusted Proxy](/uk/gateway/trusted-proxy-auth)
+ [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)
Див. [Tailscale](/uk/gateway/tailscale) для рекомендацій щодо налаштування HTTPS.
## Політика безпеки вмісту
-UI керування постачається зі суворою політикою `img-src`: дозволені лише ресурси **same-origin** і URL `data:`. Віддалені URL з `http(s)` і відносні до протоколу URL зображень відхиляються браузером і не ініціюють мережевих запитів.
+Control UI постачається з жорсткою політикою `img-src`: дозволено лише ресурси **того самого походження** та URL `data:`. Віддалені URL з `http(s)` і URL з відносним до протоколу записом відхиляються браузером і не спричиняють мережевих запитів.
Що це означає на практиці:
-- Аватари й зображення, що віддаються за відносними шляхами (наприклад, `/avatars/`), як і раніше відображаються.
-- Вбудовані URL `data:image/...` як і раніше відображаються (це корисно для payload-ів усередині протоколу).
-- Віддалені URL аватарів, які надсилає метадані каналу, видаляються в допоміжних функціях аватарів UI керування та замінюються вбудованим логотипом/значком, тому скомпрометований або зловмисний канал не може змусити браузер оператора виконувати довільні віддалені запити зображень.
+- Аватари та зображення, що обслуговуються за відносними шляхами (наприклад, `/avatars/`), як і раніше відображаються.
+- Вбудовані URL `data:image/...` як і раніше відображаються (це корисно для payload у межах протоколу).
+- Віддалені URL аватарів, які надходять із метаданих каналу, відсікаються у допоміжних функціях аватарів Control UI і замінюються вбудованим логотипом/бейджем, тож скомпрометований або зловмисний канал не може змусити браузер оператора виконувати довільні віддалені запити зображень.
-Щоб отримати таку поведінку, нічого змінювати не потрібно — вона завжди ввімкнена й не налаштовується.
+Щоб отримати таку поведінку, вам не потрібно нічого змінювати — вона завжди ввімкнена і не налаштовується.
## Автентифікація маршруту аватара
-Коли налаштовано автентифікацію gateway, кінцева точка аватарів UI керування вимагає той самий токен gateway, що й решта API:
+Коли налаштовано автентифікацію gateway, кінцева точка аватара в Control UI вимагає той самий токен gateway, що й решта API:
- `GET /avatar/` повертає зображення аватара лише автентифікованим викликачам. `GET /avatar/?meta=1` повертає метадані аватара за тим самим правилом.
-- Неавтентифіковані запити до будь-якого з маршрутів відхиляються (аналогічно до сусіднього маршруту медіа помічника). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які в іншому разі захищені.
-- Сам UI керування пересилає токен gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані blob URL, тож зображення як і раніше відображається в інформаційних панелях.
+- Неавтентифіковані запити до будь-якого з цих маршрутів відхиляються (так само, як і до спорідненого маршруту assistant-media). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які в іншому випадку захищені.
+- Сам Control UI під час отримання аватарів пересилає токен gateway як bearer-заголовок і використовує автентифіковані blob URL, тож зображення все одно відображається в дашбордах.
Якщо ви вимкнете автентифікацію gateway (не рекомендовано на спільних хостах), маршрут аватара також стане неавтентифікованим, відповідно до решти gateway.
## Збирання UI
-Gateway віддає статичні файли з `dist/control-ui`. Зберіть їх за допомогою:
+Gateway обслуговує статичні файли з `dist/control-ui`. Зберіть їх командою:
```bash
pnpm ui:build
```
-Необов’язкова абсолютна база (коли потрібні фіксовані URL ресурсів):
+Необов’язкова абсолютна base-адреса (коли потрібні фіксовані URL ресурсів):
```bash
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
```
-Для локальної розробки (окремий dev server):
+Для локальної розробки (окремий dev-сервер):
```bash
pnpm ui:dev
```
-Потім вкажіть для UI URL вашого Gateway WS (наприклад, `ws://127.0.0.1:18789`).
+Потім вкажіть UI URL вашого Gateway WS (наприклад, `ws://127.0.0.1:18789`).
-## Налагодження/тестування: dev server + віддалений Gateway
+## Налагодження/тестування: dev-сервер + віддалений Gateway
-UI керування — це статичні файли; ціль WebSocket налаштовується і може
-відрізнятися від HTTP origin. Це зручно, коли ви хочете використовувати Vite dev server
-локально, але Gateway працює в іншому місці.
+Control UI — це статичні файли; ціль WebSocket налаштовується і може
+відрізнятися від HTTP-походження. Це зручно, коли ви хочете використовувати локальний
+dev-сервер Vite, але Gateway працює деінде.
-1. Запустіть dev server UI: `pnpm ui:dev`
-2. Відкрийте URL такого вигляду:
+1. Запустіть dev-сервер UI: `pnpm ui:dev`
+2. Відкрийте URL такого виду:
```text
http://localhost:5173/?gatewayUrl=ws://:18789
@@ -384,19 +388,19 @@ http://localhost:5173/?gatewayUrl=wss://:18789#token=:18789#token=