From 5d397d99fc8d29c24bf3c9b502c56b8dbfe06efc Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 24 Apr 2026 08:41:50 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/providers/google.md | 250 ++++++++++++-------- docs/uk/tools/capability-cookbook.md | 135 ++++++----- docs/uk/tools/plugin.md | 256 ++++++++++---------- docs/uk/web/control-ui.md | 338 ++++++++++++++------------- 4 files changed, 524 insertions(+), 455 deletions(-) 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=