chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
5ef9bc7152
commit
5d397d99fc
@ -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)
|
||||
|
||||
## Початок роботи
|
||||
|
||||
Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування.
|
||||
Оберіть бажаний спосіб автентифікації та виконайте кроки налаштування.
|
||||
|
||||
<Tabs>
|
||||
<Tab title="API-ключ">
|
||||
<Tab title="API key">
|
||||
**Найкраще для:** стандартного доступу до Gemini API через Google AI Studio.
|
||||
|
||||
<Steps>
|
||||
<Step title="Запустіть онбординг">
|
||||
<Step title="Run onboarding">
|
||||
```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"
|
||||
```
|
||||
</Step>
|
||||
<Step title="Установіть типову модель">
|
||||
<Step title="Set a default model">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -56,7 +56,7 @@ Gemini Grounding.
|
||||
}
|
||||
```
|
||||
</Step>
|
||||
<Step title="Переконайтеся, що модель доступна">
|
||||
<Step title="Verify the model is available">
|
||||
```bash
|
||||
openclaw models list --provider google
|
||||
```
|
||||
@ -64,47 +64,47 @@ Gemini Grounding.
|
||||
</Steps>
|
||||
|
||||
<Tip>
|
||||
Підтримуються обидві змінні середовища: `GEMINI_API_KEY` і `GOOGLE_API_KEY`. Використовуйте ту, яка у вас уже налаштована.
|
||||
Змінні середовища `GEMINI_API_KEY` і `GOOGLE_API_KEY` обидві підтримуються. Використовуйте ту, яка у вас уже налаштована.
|
||||
</Tip>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Gemini CLI (OAuth)">
|
||||
**Найкраще для:** повторного використання наявного входу Gemini CLI через PKCE OAuth замість окремого API-ключа.
|
||||
**Найкраще для:** повторного використання наявного входу Gemini CLI через PKCE OAuth замість окремого ключа API.
|
||||
|
||||
<Warning>
|
||||
Provider `google-gemini-cli` є неофіційною інтеграцією. Деякі користувачі
|
||||
повідомляють про обмеження облікового запису при такому використанні OAuth. Використовуйте на власний ризик.
|
||||
Провайдер `google-gemini-cli` є неофіційною інтеграцією. Деякі користувачі
|
||||
повідомляють про обмеження облікового запису при використанні OAuth у такий спосіб. Використовуйте на власний ризик.
|
||||
</Warning>
|
||||
|
||||
<Steps>
|
||||
<Step title="Установіть Gemini CLI">
|
||||
<Step title="Install the Gemini CLI">
|
||||
Локальна команда `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.
|
||||
</Step>
|
||||
<Step title="Увійдіть через OAuth">
|
||||
<Step title="Log in via OAuth">
|
||||
```bash
|
||||
openclaw models auth login --provider google-gemini-cli --set-default
|
||||
```
|
||||
</Step>
|
||||
<Step title="Переконайтеся, що модель доступна">
|
||||
<Step title="Verify the model is available">
|
||||
```bash
|
||||
openclaw models list --provider google-gemini-cli
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
- Типова модель: `google-gemini-cli/gemini-3-flash-preview`
|
||||
- Модель за замовчуванням: `google-gemini-cli/gemini-3-flash-preview`
|
||||
- Псевдонім: `gemini-cli`
|
||||
|
||||
**Змінні середовища:**
|
||||
@ -115,60 +115,61 @@ Gemini Grounding.
|
||||
(Або варіанти `GEMINI_CLI_*`.)
|
||||
|
||||
<Note>
|
||||
Якщо запити Gemini CLI OAuth не працюють після входу, задайте `GOOGLE_CLOUD_PROJECT` або
|
||||
Якщо OAuth-запити Gemini CLI не вдаються після входу, задайте `GOOGLE_CLOUD_PROJECT` або
|
||||
`GOOGLE_CLOUD_PROJECT_ID` на хості gateway і повторіть спробу.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Якщо вхід завершується помилкою до початку browser flow, переконайтеся, що локальну команду `gemini`
|
||||
встановлено й додано до `PATH`.
|
||||
Якщо вхід не вдається ще до запуску потоку в браузері, переконайтеся, що локальна команда `gemini`
|
||||
встановлена й доступна в `PATH`.
|
||||
</Note>
|
||||
|
||||
Provider `google-gemini-cli`, який працює лише через OAuth, є окремою
|
||||
поверхнею text inference. Генерація зображень, розуміння медіа та Gemini Grounding залишаються на
|
||||
id provider `google`.
|
||||
Провайдер `google-gemini-cli`, який працює лише через OAuth, є окремою поверхнею
|
||||
текстового інференсу. Генерація зображень, розуміння медіа та Gemini Grounding залишаються на
|
||||
ідентифікаторі провайдера `google`.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Можливості
|
||||
|
||||
| Можливість | Підтримується |
|
||||
| ---------------------- | ------------------------------ |
|
||||
| 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 | Так |
|
||||
|
||||
<Tip>
|
||||
Моделі 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`.
|
||||
</Tip>
|
||||
|
||||
## Генерація зображень
|
||||
|
||||
Вбудований 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.
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Image Generation](/uk/tools/image-generation) щодо спільних параметрів tool, вибору provider і поведінки failover.
|
||||
Див. [Генерація зображень](/uk/tools/image-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover.
|
||||
</Note>
|
||||
|
||||
## Генерація відео
|
||||
|
||||
Вбудований 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`.
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Video Generation](/uk/tools/video-generation) щодо спільних параметрів tool, вибору provider і поведінки failover.
|
||||
Див. [Генерація відео](/uk/tools/video-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover.
|
||||
</Note>
|
||||
|
||||
## Генерація музики
|
||||
|
||||
Вбудований 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`.
|
||||
```
|
||||
|
||||
<Note>
|
||||
Див. [Music Generation](/uk/tools/music-generation) щодо спільних параметрів tool, вибору provider і поведінки failover.
|
||||
Див. [Генерація музики](/uk/tools/music-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover.
|
||||
</Note>
|
||||
|
||||
## 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]]
|
||||
```
|
||||
|
||||
<Note>
|
||||
API-ключ Google Cloud Console, обмежений Gemini API, є валідним для цього
|
||||
provider. Це не окремий шлях Cloud Text-to-Speech API.
|
||||
Ключ API Google Cloud Console, обмежений Gemini API, є дійсним для цього
|
||||
провайдера. Це не окремий шлях Cloud Text-to-Speech API.
|
||||
</Note>
|
||||
|
||||
## Розширена конфігурація
|
||||
## Голос у реальному часі
|
||||
|
||||
Вбудований 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",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
Google Live API використовує двоспрямоване аудіо та виклик функцій через WebSocket.
|
||||
OpenClaw адаптує аудіо телефонії/Meet-мосту до потоку PCM Live API Gemini і
|
||||
зберігає виклики інструментів у межах спільного контракту голосу в реальному часі. Залишайте `temperature`
|
||||
не заданим, якщо вам не потрібні зміни семплювання; OpenClaw пропускає недодатні значення,
|
||||
оскільки Google Live може повертати транскрипти без аудіо для `temperature: 0`.
|
||||
Транскрипція Gemini API вмикається без `languageCodes`; поточний Google
|
||||
SDK відхиляє підказки кодів мов на цьому шляху API.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Сесії Talk у браузері в UI Control, як і раніше, потребують провайдера голосу в реальному часі з
|
||||
реалізацією сеансу браузерного WebRTC. Наразі цим шляхом є OpenAI Realtime; провайдер
|
||||
Google призначений для серверних мостів реального часу.
|
||||
</Note>
|
||||
|
||||
## Розширене налаштування
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Пряме повторне використання кешу Gemini">
|
||||
<Accordion title="Direct Gemini cache reuse">
|
||||
Для прямих запусків 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.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Примітки щодо JSON usage у Gemini CLI">
|
||||
Під час використання OAuth-provider `google-gemini-cli` OpenClaw нормалізує
|
||||
JSON-вивід CLI так:
|
||||
<Accordion title="Примітки щодо використання JSON у Gemini 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`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Середовище та налаштування daemon">
|
||||
Якщо Gateway працює як daemon (launchd/systemd), переконайтеся, що `GEMINI_API_KEY`
|
||||
<Accordion title="Налаштування середовища та демона">
|
||||
Якщо Gateway працює як демон (launchd/systemd), переконайтеся, що `GEMINI_API_KEY`
|
||||
доступний цьому процесу (наприклад, у `~/.openclaw/.env` або через
|
||||
`env.shellEnv`).
|
||||
</Accordion>
|
||||
@ -343,15 +401,15 @@ provider. Це не окремий шлях Cloud Text-to-Speech API.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Вибір моделі" href="/uk/concepts/model-providers" icon="layers">
|
||||
Вибір provider, refs моделей і поведінки failover.
|
||||
Вибір провайдерів, посилань на моделі та поведінки failover.
|
||||
</Card>
|
||||
<Card title="Генерація зображень" href="/uk/tools/image-generation" icon="image">
|
||||
Спільні параметри tool для зображень і вибір provider.
|
||||
Спільні параметри інструмента зображень і вибір провайдера.
|
||||
</Card>
|
||||
<Card title="Генерація відео" href="/uk/tools/video-generation" icon="video">
|
||||
Спільні параметри tool для відео і вибір provider.
|
||||
Спільні параметри інструмента відео і вибір провайдера.
|
||||
</Card>
|
||||
<Card title="Генерація музики" href="/uk/tools/music-generation" icon="music">
|
||||
Спільні параметри tool для музики і вибір provider.
|
||||
Спільні параметри інструмента музики і вибір провайдера.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -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
|
||||
---
|
||||
|
||||
<Info>
|
||||
Це **посібник для контриб’юторів** для розробників ядра OpenClaw. Якщо ви
|
||||
створюєте зовнішній Plugin, див. [Створення Plugins](/uk/plugins/building-plugins)
|
||||
натомість.
|
||||
Це **посібник для учасників** для розробників ядра OpenClaw. Якщо ви
|
||||
створюєте зовнішній Plugin, натомість перегляньте [Building Plugins](/uk/plugins/building-plugins).
|
||||
</Info>
|
||||
|
||||
Використовуйте це, коли 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/<capability>/types.ts`
|
||||
- `src/<capability>/...registry/runtime.ts`
|
||||
@ -90,41 +98,40 @@ Feature/channel Plugin:
|
||||
- `src/plugins/runtime/index.ts`
|
||||
- `src/plugin-sdk/<capability>.ts`
|
||||
- `src/plugin-sdk/<capability>-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)
|
||||
|
||||
@ -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).
|
||||
|
||||
## Швидкий початок
|
||||
## Швидкий старт
|
||||
|
||||
<Steps>
|
||||
<Step title="Подивіться, що завантажено">
|
||||
<Step title="Перегляньте, що завантажено">
|
||||
```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:<pkg>` або специфікація пакета без префікса
|
||||
(спочатку ClawHub, потім резервно npm).
|
||||
шлях/архів, явний `clawhub:<pkg>` або специфікація пакета без префікса (спочатку 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)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Постачальники моделей (увімкнені за замовчуванням)">
|
||||
<Accordion title="Провайдери моделей (увімкнені за замовчуванням)">
|
||||
`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 розпізнає два формати плагінів:
|
||||
|
||||
<Accordion title="Плагіни пам’яті">
|
||||
- `memory-core` — вбудований пошук у пам’яті (типово через `plugins.slots.memory`)
|
||||
- `memory-lancedb` — довготривала пам’ять зі встановленням на вимогу з автоматичним пригадуванням/захопленням (встановіть `plugins.slots.memory = "memory-lancedb"`)
|
||||
- `memory-lancedb` — довготривала пам’ять із встановленням на вимогу та автоматичним пригадуванням/захопленням (установіть `plugins.slots.memory = "memory-lancedb"`)
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Постачальники мовлення (увімкнені за замовчуванням)">
|
||||
<Accordion title="Провайдери мовлення (увімкнені за замовчуванням)">
|
||||
`elevenlabs`, `microsoft`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Інше">
|
||||
- `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 (вимкнений за замовчуванням)
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Шукаєте сторонні плагіни? Див. [Плагіни спільноти](/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.\<id\>` | Перемикачі та конфігурація для окремого плагіна |
|
||||
|
||||
Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway працює з увімкненими
|
||||
відстеженням конфігурації та внутрішньопроцесним перезапуском (типовий шлях `openclaw gateway`),
|
||||
Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway запущено з відстеженням
|
||||
конфігурації та увімкненим перезапуском у процесі (типовий шлях `openclaw gateway`),
|
||||
цей перезапуск зазвичай виконується автоматично невдовзі після запису змін у конфігурацію.
|
||||
|
||||
<Accordion title="Стани плагінів: вимкнений, відсутній, недійсний">
|
||||
- **Вимкнений**: плагін існує, але правила ввімкнення його вимкнули. Конфігурація зберігається.
|
||||
- **Відсутній**: конфігурація посилається на ідентифікатор плагіна, який не було знайдено під час виявлення.
|
||||
- **Недійсний**: плагін існує, але його конфігурація не відповідає оголошеній схемі.
|
||||
<Accordion title="Стани плагіна: вимкнений, відсутній або некоректний">
|
||||
- **Вимкнений**: плагін існує, але правила ввімкнення вимкнули його. Конфігурація зберігається.
|
||||
- **Відсутній**: конфігурація посилається на ідентифікатор плагіна, який не знайдено під час виявлення.
|
||||
- **Некоректний**: плагін існує, але його конфігурація не відповідає оголошеній схемі.
|
||||
</Accordion>
|
||||
|
||||
## Виявлення та пріоритет
|
||||
|
||||
OpenClaw сканує плагіни в такому порядку (перше співпадіння перемагає):
|
||||
OpenClaw сканує плагіни в такому порядку (перше знайдене співпадіння перемагає):
|
||||
|
||||
<Steps>
|
||||
<Step title="Шляхи з конфігурації">
|
||||
`plugins.load.paths` — явні шляхи до файлів або каталогів.
|
||||
`plugins.load.paths` — явні шляхи до файлу або каталогу.
|
||||
</Step>
|
||||
|
||||
<Step title="Плагіни робочого простору">
|
||||
@ -184,7 +183,7 @@ OpenClaw сканує плагіни в такому порядку (перше
|
||||
</Step>
|
||||
|
||||
<Step title="Вбудовані плагіни">
|
||||
Постачаються разом з OpenClaw. Багато з них увімкнено за замовчуванням (постачальники моделей, мовлення).
|
||||
Постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (провайдери моделей, мовлення).
|
||||
Інші потребують явного ввімкнення.
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -194,44 +193,44 @@ OpenClaw сканує плагіни в такому порядку (перше
|
||||
- `plugins.enabled: false` вимикає всі плагіни
|
||||
- `plugins.deny` завжди має пріоритет над allow
|
||||
- `plugins.entries.\<id\>.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 <id> # докладна інформація
|
||||
openclaw plugins inspect <id> --json # машиночитний формат
|
||||
openclaw plugins inspect --all # таблиця для всього набору
|
||||
@ -242,10 +241,10 @@ openclaw plugins install <package> # встановити (спочат
|
||||
openclaw plugins install clawhub:<pkg> # встановити лише з ClawHub
|
||||
openclaw plugins install <spec> --force # перезаписати наявне встановлення
|
||||
openclaw plugins install <path> # встановити з локального шляху
|
||||
openclaw plugins install -l <path> # підключити (без копіювання) для розробки
|
||||
openclaw plugins install -l <path> # під’єднати (без копіювання) для розробки
|
||||
openclaw plugins install <plugin> --marketplace <source>
|
||||
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
|
||||
openclaw plugins install <spec> --pin # зберегти точну розв’язану npm-специфікацію
|
||||
openclaw plugins install <spec> --pin # записати точну визначену специфікацію npm
|
||||
openclaw plugins install <spec> --dangerously-force-unsafe-install
|
||||
openclaw plugins update <id-or-npm-spec> # оновити один плагін
|
||||
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
|
||||
@ -259,59 +258,60 @@ openclaw plugins enable <id>
|
||||
openclaw plugins disable <id>
|
||||
```
|
||||
|
||||
Вбудовані плагіни постачаються разом з OpenClaw. Багато з них увімкнено за замовчуванням (наприклад,
|
||||
вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований browser-плагін).
|
||||
Інші вбудовані плагіни все одно потребують `openclaw plugins enable <id>`.
|
||||
Вбудовані плагіни постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад,
|
||||
вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований browser
|
||||
Plugin). Інші вбудовані плагіни все одно потребують `openclaw plugins enable <id>`.
|
||||
|
||||
`--force` перезаписує наявний встановлений плагін або пакет хуків на місці. Використовуйте
|
||||
`openclaw plugins update <id-or-npm-spec>` для звичайних оновлень відстежуваних npm-плагінів.
|
||||
Він не підтримується з `--link`, який повторно використовує шлях до джерела замість
|
||||
копіювання в кероване місце встановлення.
|
||||
`--force` перезаписує наявний встановлений плагін або пакет хуків на місці. Для
|
||||
звичайних оновлень відстежуваних npm плагінів використовуйте
|
||||
`openclaw plugins update <id-or-npm-spec>`. Цей параметр не підтримується з `--link`, який повторно використовує шлях до джерела
|
||||
замість копіювання в кероване цільове місце встановлення.
|
||||
|
||||
Коли `plugins.allow` уже задано, `openclaw plugins install` додає
|
||||
ідентифікатор встановленого плагіна до цього списку allow перед його ввімкненням, щоб установлені
|
||||
плагіни можна було одразу завантажити після перезапуску.
|
||||
ідентифікатор встановленого плагіна до цього списку allow перед його ввімкненням, щоб установлені плагіни
|
||||
можна було одразу завантажити після перезапуску.
|
||||
|
||||
`openclaw plugins update <id-or-npm-spec>` застосовується до відстежуваних установлень. Передача
|
||||
специфікації npm-пакета з dist-tag або точною версією зіставляє назву пакета
|
||||
назад із записом відстежуваного плагіна і зберігає нову специфікацію для майбутніх оновлень.
|
||||
Передача назви пакета без версії переводить точне закріплене встановлення назад на
|
||||
типову лінійку релізів реєстру. Якщо встановлений npm-плагін уже відповідає
|
||||
розв’язаній версії та збереженій ідентичності артефакту, OpenClaw пропускає оновлення
|
||||
`openclaw plugins update <id-or-npm-spec>` застосовується до відстежуваних встановлень. Передавання
|
||||
специфікації 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 <id>` також повідомляє про виявлені можливості пакета, а також
|
||||
підтримувані чи непідтримувані записи серверів MCP і LSP для плагінів на основі пакетів.
|
||||
`openclaw plugins inspect <id>` також повідомляє про виявлені можливості набору, а також
|
||||
підтримувані або непідтримувані записи серверів 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) — сторонні списки
|
||||
|
||||
@ -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://<host>:18789/`
|
||||
- типово: `http://<host>: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 <requestId>
|
||||
```
|
||||
|
||||
Якщо браузер повторно надсилає запит на сполучення зі зміненими даними автентифікації (роль/області доступу/public
|
||||
key), попередній запит, що очікує, замінюється, і створюється новий `requestId`.
|
||||
Якщо браузер повторює спробу сполучення зі зміненими даними автентифікації (роль/області доступу/публічний
|
||||
ключ), попередній запит, що очікує, замінюється новим, і створюється новий `requestId`.
|
||||
Перед підтвердженням знову виконайте `openclaw devices list`.
|
||||
|
||||
Якщо браузер уже сполучений і ви змінюєте доступ із читання на
|
||||
доступ запису/адміністратора, це вважається підвищенням рівня підтвердження, а не
|
||||
тихим повторним підключенням. OpenClaw зберігає старе підтвердження активним, блокує ширше повторне підключення
|
||||
і просить вас явно підтвердити новий набір областей доступу.
|
||||
Якщо браузер уже сполучений і ви змінюєте його доступ із читання на
|
||||
запис/адміністрування, це вважається підвищенням підтвердження, а не тихим
|
||||
повторним підключенням. OpenClaw залишає попереднє підтвердження активним,
|
||||
блокує ширше повторне підключення й просить вас явно підтвердити новий набір
|
||||
областей доступу.
|
||||
|
||||
Після підтвердження пристрій запам’ятовується і не вимагатиме повторного підтвердження, якщо
|
||||
ви не відкличете його через `openclaw devices revoke --device <id> --role <role>`. Див.
|
||||
[Devices CLI](/uk/cli/devices) щодо ротації токенів і відкликання.
|
||||
Після підтвердження пристрій запам’ятовується і не вимагатиме повторного
|
||||
підтвердження, доки ви не відкличете його за допомогою `openclaw devices revoke --device <id> --role <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-и викликів інструментів у звичайному тексті (зокрема `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і усічені блоки викликів інструментів), а також 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 простого тексту для викликів інструментів (включно з `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізаними блоками викликів інструментів), а також витеклі токени керування моделлю 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://<magicdns>/` (або ваш налаштований `gateway.controlUi.basePath`)
|
||||
- `https://<magicdns>/` (або налаштований вами `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://<tailscale-ip>:18789/` (або ваш налаштований `gateway.controlUi.basePath`)
|
||||
- `http://<tailscale-ip>:18789/` (або налаштований вами `gateway.controlUi.basePath`)
|
||||
|
||||
Вставте відповідний спільний секрет у налаштування UI (він надсилається як
|
||||
`connect.params.auth.token` або `connect.params.auth.password`).
|
||||
|
||||
## Незахищений HTTP
|
||||
|
||||
Якщо ви відкриваєте інформаційну панель через звичайний HTTP (`http://<lan-ip>` або `http://<tailscale-ip>`),
|
||||
браузер працює в **незахищеному контексті** і блокує WebCrypto. За замовчуванням
|
||||
OpenClaw **блокує** підключення UI керування без ідентичності пристрою.
|
||||
Якщо ви відкриваєте дашборд через звичайний HTTP (`http://<lan-ip>` або `http://<tailscale-ip>`),
|
||||
браузер працює в **незахищеному контексті** й блокує 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://<magicdns>/` (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/<id>`), як і раніше відображаються.
|
||||
- Вбудовані URL `data:image/...` як і раніше відображаються (це корисно для payload-ів усередині протоколу).
|
||||
- Віддалені URL аватарів, які надсилає метадані каналу, видаляються в допоміжних функціях аватарів UI керування та замінюються вбудованим логотипом/значком, тому скомпрометований або зловмисний канал не може змусити браузер оператора виконувати довільні віддалені запити зображень.
|
||||
- Аватари та зображення, що обслуговуються за відносними шляхами (наприклад, `/avatars/<id>`), як і раніше відображаються.
|
||||
- Вбудовані URL `data:image/...` як і раніше відображаються (це корисно для payload у межах протоколу).
|
||||
- Віддалені URL аватарів, які надходять із метаданих каналу, відсікаються у допоміжних функціях аватарів Control UI і замінюються вбудованим логотипом/бейджем, тож скомпрометований або зловмисний канал не може змусити браузер оператора виконувати довільні віддалені запити зображень.
|
||||
|
||||
Щоб отримати таку поведінку, нічого змінювати не потрібно — вона завжди ввімкнена й не налаштовується.
|
||||
Щоб отримати таку поведінку, вам не потрібно нічого змінювати — вона завжди ввімкнена і не налаштовується.
|
||||
|
||||
## Автентифікація маршруту аватара
|
||||
|
||||
Коли налаштовано автентифікацію gateway, кінцева точка аватарів UI керування вимагає той самий токен gateway, що й решта API:
|
||||
Коли налаштовано автентифікацію gateway, кінцева точка аватара в Control UI вимагає той самий токен gateway, що й решта API:
|
||||
|
||||
- `GET /avatar/<agentId>` повертає зображення аватара лише автентифікованим викликачам. `GET /avatar/<agentId>?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://<gateway-host>:18789
|
||||
@ -384,19 +388,19 @@ http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-toke
|
||||
Примітки:
|
||||
|
||||
- `gatewayUrl` зберігається в localStorage після завантаження і видаляється з URL.
|
||||
- `token` слід передавати через фрагмент URL (`#token=...`) щоразу, коли це можливо. Фрагменти не надсилаються на сервер, що запобігає витоку через журнали запитів і Referer. Застарілі параметри запиту `?token=` усе ще одноразово імпортуються для сумісності, але лише як fallback, і видаляються одразу після bootstrap.
|
||||
- `token` слід, коли можливо, передавати через фрагмент URL (`#token=...`). Фрагменти не надсилаються на сервер, що запобігає витоку через журнали запитів і Referer. Застарілі параметри запиту `?token=` усе ще одноразово імпортуються для сумісності, але лише як запасний варіант, і негайно видаляються після bootstrap.
|
||||
- `password` зберігається лише в пам’яті.
|
||||
- Коли встановлено `gatewayUrl`, UI не повертається до облікових даних із конфігурації чи середовища.
|
||||
Явно вкажіть `token` (або `password`). Відсутність явних облікових даних є помилкою.
|
||||
- Використовуйте `wss://`, коли Gateway знаходиться за TLS (Tailscale Serve, HTTPS proxy тощо).
|
||||
- `gatewayUrl` приймається лише у вікні верхнього рівня (не у вбудованому), щоб запобігти clickjacking.
|
||||
- Розгортання UI керування не на loopback мають явно задавати `gateway.controlUi.allowedOrigins`
|
||||
(повні origin). Це також стосується віддалених dev-налаштувань.
|
||||
- Не використовуйте `gateway.controlUi.allowedOrigins: ["*"]`, окрім жорстко контрольованого
|
||||
локального тестування. Це означає дозвіл для будь-якого origin браузера, а не «відповідати будь-якому хосту, який я
|
||||
- Коли встановлено `gatewayUrl`, UI не повертається до конфігурації або облікових даних із середовища.
|
||||
Надайте `token` (або `password`) явно. Відсутність явних облікових даних є помилкою.
|
||||
- Використовуйте `wss://`, коли Gateway працює за TLS (Tailscale Serve, HTTPS-проксі тощо).
|
||||
- `gatewayUrl` приймається лише у вікні верхнього рівня (не у вбудованому), щоб запобігти клікджекінгу.
|
||||
- Розгортання Control UI не на loopback повинні явно задавати `gateway.controlUi.allowedOrigins`
|
||||
(повні origin). Це включає віддалені налаштування розробки.
|
||||
- Не використовуйте `gateway.controlUi.allowedOrigins: ["*"]`, окрім ретельно контрольованого
|
||||
локального тестування. Це означає дозвіл для будь-якого origin браузера, а не «зіставити з будь-яким хостом, який я
|
||||
використовую».
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає
|
||||
режим fallback origin за заголовком Host, але це небезпечний режим безпеки.
|
||||
резервний режим origin через заголовок Host, але це небезпечний режим безпеки.
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -410,11 +414,11 @@ http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-toke
|
||||
}
|
||||
```
|
||||
|
||||
Докладніше про налаштування віддаленого доступу: [Віддалений доступ](/uk/gateway/remote).
|
||||
Подробиці налаштування віддаленого доступу: [Віддалений доступ](/uk/gateway/remote).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Інформаційна панель](/uk/web/dashboard) — інформаційна панель gateway
|
||||
- [WebChat](/uk/web/webchat) — чат-інтерфейс у браузері
|
||||
- [Dashboard](/uk/web/dashboard) — дашборд gateway
|
||||
- [WebChat](/uk/web/webchat) — браузерний інтерфейс чату
|
||||
- [TUI](/uk/web/tui) — термінальний інтерфейс користувача
|
||||
- [Перевірки справності](/uk/gateway/health) — моніторинг справності gateway
|
||||
- [Health Checks](/uk/gateway/health) — моніторинг стану gateway
|
||||
|
||||
Loading…
Reference in New Issue
Block a user