chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
655472d67c
commit
d90f9ea587
@ -2,25 +2,25 @@
|
||||
read_when:
|
||||
- Ви хочете змінити моделі за замовчуванням або переглянути статус автентифікації провайдера
|
||||
- Ви хочете просканувати доступні моделі/провайдерів і налагодити профілі автентифікації
|
||||
summary: Довідка CLI для `openclaw models` (status/list/set/scan, псевдоніми, резервні варіанти, автентифікація)
|
||||
summary: Довідник CLI для `openclaw models` (`status`/`list`/`set`/`scan`, псевдоніми, резервні варіанти, автентифікація)
|
||||
title: Моделі
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T07:01:56Z"
|
||||
generated_at: "2026-04-25T09:52:27Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2755657b334b8722da06e31fa1d69a5dced3d74e5aeadd38d625039f15911d69
|
||||
source_hash: 2c8040159e23789221357dd60232012759ee540ebfd3e5d192a0a09419d40c9a
|
||||
source_path: cli/models.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# `openclaw models`
|
||||
|
||||
Виявлення моделей, сканування та конфігурація (модель за замовчуванням, резервні варіанти, профілі автентифікації).
|
||||
Виявлення моделей, сканування та налаштування (модель за замовчуванням, резервні варіанти, профілі автентифікації).
|
||||
|
||||
Пов’язане:
|
||||
|
||||
- Провайдери + моделі: [Моделі](/uk/providers/models)
|
||||
- Концепції вибору моделей + слеш-команда `/models`: [Концепція моделей](/uk/concepts/models)
|
||||
- Концепції вибору моделі + слеш-команда `/models`: [Концепція моделей](/uk/concepts/models)
|
||||
- Налаштування автентифікації провайдера: [Початок роботи](/uk/start/getting-started)
|
||||
|
||||
## Поширені команди
|
||||
@ -33,45 +33,73 @@ openclaw models scan
|
||||
```
|
||||
|
||||
`openclaw models status` показує визначені модель за замовчуванням/резервні варіанти, а також огляд автентифікації.
|
||||
Коли доступні знімки використання провайдера, розділ статусу OAuth/API-ключів містить
|
||||
вікна використання провайдера та знімки квот.
|
||||
Коли доступні знімки використання провайдерів, розділ статусу OAuth/API-ключів містить
|
||||
вікна використання провайдерів і знімки квот.
|
||||
Поточні провайдери з вікнами використання: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
|
||||
Codex, MiniMax, Xiaomi і z.ai. Автентифікація використання надходить із хуків,
|
||||
специфічних для провайдера, коли вони доступні; інакше OpenClaw використовує резервний варіант і підбирає OAuth/API-key
|
||||
облікові дані з профілів автентифікації, змінних середовища або конфігурації.
|
||||
Codex, MiniMax, Xiaomi і z.ai. Дані автентифікації для використання надходять із хуків,
|
||||
специфічних для провайдера, коли вони доступні; інакше OpenClaw використовує резервний варіант і зіставляє облікові дані OAuth/API-ключів
|
||||
із профілів автентифікації, змінних середовища або конфігурації.
|
||||
У виводі `--json` `auth.providers` — це огляд провайдера з урахуванням env/config/store,
|
||||
тоді як `auth.oauth` — це лише стан профілів у сховищі автентифікації.
|
||||
тоді як `auth.oauth` — це лише стан профілів сховища автентифікації.
|
||||
Додайте `--probe`, щоб виконати живі перевірки автентифікації для кожного налаштованого профілю провайдера.
|
||||
Перевірки є реальними запитами (можуть витрачати токени та спричиняти обмеження швидкості).
|
||||
Використовуйте `--agent <id>`, щоб перевірити стан моделі/автентифікації налаштованого агента. Якщо цей параметр не вказано,
|
||||
команда використовує `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`, якщо вони задані, інакше —
|
||||
Перевірки — це реальні запити (можуть споживати токени та викликати обмеження частоти).
|
||||
Використовуйте `--agent <id>`, щоб перевірити стан моделі/автентифікації налаштованого агента. Якщо параметр не вказано,
|
||||
команда використовує `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`, якщо їх задано, інакше —
|
||||
налаштованого агента за замовчуванням.
|
||||
Рядки перевірок можуть надходити з профілів автентифікації, облікових даних середовища або `models.json`.
|
||||
Рядки перевірок можуть надходити з профілів автентифікації, облікових даних env або `models.json`.
|
||||
|
||||
Примітки:
|
||||
|
||||
- `models set <model-or-alias>` приймає `provider/model` або псевдонім.
|
||||
- `models list` є лише для читання: команда читає конфігурацію, профілі автентифікації, наявний стан каталогу
|
||||
та рядки каталогу, що належать провайдеру, але не перезаписує
|
||||
- `models list` працює лише для читання: вона читає конфігурацію, профілі автентифікації, наявний
|
||||
стан каталогу та рядки каталогу, що належать провайдеру, але не переписує
|
||||
`models.json`.
|
||||
- `models list --all` включає вбудовані статичні рядки каталогу, що належать провайдеру, навіть
|
||||
якщо ви ще не автентифікувалися в цього провайдера. Такі рядки все одно показуються
|
||||
як недоступні, доки не буде налаштовано відповідну автентифікацію.
|
||||
- `models list` зберігає власні метадані моделі та обмеження середовища виконання окремо. У табличному
|
||||
- `models list` зберігає відокремленими власні метадані моделі та фактичні обмеження середовища виконання. У табличному
|
||||
виводі `Ctx` показує `contextTokens/contextWindow`, коли ефективне обмеження середовища виконання
|
||||
відрізняється від власного вікна контексту; рядки JSON містять `contextTokens`,
|
||||
якщо провайдер надає це обмеження.
|
||||
відрізняється від власного контекстного вікна; рядки JSON містять `contextTokens`,
|
||||
коли провайдер надає це обмеження.
|
||||
- `models list --provider <id>` фільтрує за ідентифікатором провайдера, наприклад `moonshot` або
|
||||
`openai-codex`. Команда не приймає відображувані мітки з інтерактивних засобів вибору провайдера,
|
||||
такі як `Moonshot AI`.
|
||||
- Посилання на моделі розбираються шляхом поділу за **першим** `/`. Якщо ідентифікатор моделі містить `/` (у стилі OpenRouter), додайте префікс провайдера (приклад: `openrouter/moonshotai/kimi-k2`).
|
||||
- Якщо ви не вказали провайдера, OpenClaw спочатку визначає введення як псевдонім, потім —
|
||||
як унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише потім
|
||||
використовує резервний варіант — налаштованого провайдера за замовчуванням — із попередженням про застарілість.
|
||||
`openai-codex`. Він не приймає відображувані мітки з інтерактивних засобів вибору провайдера,
|
||||
наприклад `Moonshot AI`.
|
||||
- Посилання на моделі розбираються шляхом розділення за **першим** `/`. Якщо ідентифікатор моделі містить `/` (у стилі OpenRouter), вкажіть префікс провайдера (приклад: `openrouter/moonshotai/kimi-k2`).
|
||||
- Якщо ви пропускаєте провайдера, OpenClaw спочатку визначає вхідне значення як псевдонім, потім —
|
||||
як унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише після цього
|
||||
використовує резервний варіант — налаштованого провайдера за замовчуванням — із попередженням про застарівання.
|
||||
Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw
|
||||
використовує резервний варіант — перший налаштований провайдер/модель — замість показу
|
||||
застарілого значення за замовчуванням для видаленого провайдера.
|
||||
- `models status` може показувати `marker(<value>)` у виводі автентифікації для незасекречених заповнювачів (наприклад `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) замість маскування їх як секретів.
|
||||
використовує резервний варіант — першу налаштовану пару провайдер/модель — замість того, щоб показувати
|
||||
застаріле значення за замовчуванням для видаленого провайдера.
|
||||
- `models status` може показувати `marker(<value>)` у виводі автентифікації для незасекречених заповнювачів (наприклад, `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) замість маскування їх як секретів.
|
||||
|
||||
### `models scan`
|
||||
|
||||
`models scan` читає публічний каталог OpenRouter `:free` і ранжує кандидатів для
|
||||
використання як резервних варіантів. Сам каталог є публічним, тому сканування лише метаданих не потребує
|
||||
ключа OpenRouter.
|
||||
|
||||
За замовчуванням OpenClaw намагається перевірити підтримку інструментів і зображень за допомогою живих викликів моделей.
|
||||
Якщо ключ OpenRouter не налаштовано, команда використовує резервний варіант — вивід лише метаданих — і пояснює, що для моделей `:free` усе одно потрібен `OPENROUTER_API_KEY` для
|
||||
перевірок і висновування.
|
||||
|
||||
Параметри:
|
||||
|
||||
- `--no-probe` (лише метадані; без пошуку конфігурації/секретів)
|
||||
- `--min-params <b>`
|
||||
- `--max-age-days <days>`
|
||||
- `--provider <name>`
|
||||
- `--max-candidates <n>`
|
||||
- `--timeout <ms>` (тайм-аут запиту до каталогу та тайм-аут кожної перевірки)
|
||||
- `--concurrency <n>`
|
||||
- `--yes`
|
||||
- `--no-input`
|
||||
- `--set-default`
|
||||
- `--set-image`
|
||||
- `--json`
|
||||
|
||||
`--set-default` і `--set-image` потребують живих перевірок; результати сканування
|
||||
лише метаданих є інформаційними й не застосовуються до конфігурації.
|
||||
|
||||
### `models status`
|
||||
|
||||
@ -79,7 +107,7 @@ Codex, MiniMax, Xiaomi і z.ai. Автентифікація використа
|
||||
|
||||
- `--json`
|
||||
- `--plain`
|
||||
- `--check` (код виходу 1=прострочено/відсутнє, 2=скоро спливає)
|
||||
- `--check` (код виходу 1=прострочено/відсутнє, 2=незабаром спливає)
|
||||
- `--probe` (жива перевірка налаштованих профілів автентифікації)
|
||||
- `--probe-provider <name>` (перевірити одного провайдера)
|
||||
- `--probe-profile <id>` (повторювані або розділені комами ідентифікатори профілів)
|
||||
@ -88,7 +116,7 @@ Codex, MiniMax, Xiaomi і z.ai. Автентифікація використа
|
||||
- `--probe-max-tokens <n>`
|
||||
- `--agent <id>` (ідентифікатор налаштованого агента; перевизначає `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
|
||||
|
||||
Групи статусів перевірки:
|
||||
Категорії статусу перевірки:
|
||||
|
||||
- `ok`
|
||||
- `auth`
|
||||
@ -99,15 +127,15 @@ Codex, MiniMax, Xiaomi і z.ai. Автентифікація використа
|
||||
- `unknown`
|
||||
- `no_model`
|
||||
|
||||
Варіанти detail/reason-code перевірки, яких варто очікувати:
|
||||
Варіанти detail/reason-code перевірки, яких слід очікувати:
|
||||
|
||||
- `excluded_by_auth_order`: збережений профіль існує, але явний
|
||||
`auth.order.<provider>` його пропустив, тому перевірка повідомляє про виключення замість
|
||||
спроби його використати.
|
||||
- `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
|
||||
профіль присутній, але не є придатним/не може бути визначений.
|
||||
- `no_model`: автентифікація провайдера існує, але OpenClaw не зміг визначити придатний для перевірки
|
||||
кандидат моделі для цього провайдера.
|
||||
профіль присутній, але не підходить/не може бути визначений.
|
||||
- `no_model`: автентифікація провайдера існує, але OpenClaw не зміг визначити
|
||||
придатного для перевірки кандидата моделі для цього провайдера.
|
||||
|
||||
## Псевдоніми + резервні варіанти
|
||||
|
||||
@ -126,10 +154,10 @@ openclaw models auth paste-token
|
||||
```
|
||||
|
||||
`models auth add` — це інтерактивний помічник автентифікації. Він може запускати потік автентифікації провайдера
|
||||
(OAuth/API key) або провести вас через ручне вставлення токена, залежно від
|
||||
обраного провайдера.
|
||||
(OAuth/API-ключ) або провести вас через ручне вставлення токена залежно від
|
||||
вибраного провайдера.
|
||||
|
||||
`models auth login` запускає потік автентифікації плагіна провайдера (OAuth/API key). Використовуйте
|
||||
`models auth login` запускає потік автентифікації плагіна провайдера (OAuth/API-ключ). Використовуйте
|
||||
`openclaw plugins list`, щоб побачити, які провайдери встановлено.
|
||||
|
||||
Приклади:
|
||||
@ -141,20 +169,21 @@ openclaw models auth login --provider openai-codex --set-default
|
||||
Примітки:
|
||||
|
||||
- `setup-token` і `paste-token` залишаються універсальними командами для роботи з токенами для провайдерів,
|
||||
які надають методи токен-автентифікації.
|
||||
- `setup-token` вимагає інтерактивного TTY і запускає метод токен-автентифікації провайдера
|
||||
(типово — метод `setup-token` цього провайдера, якщо він його надає).
|
||||
- `paste-token` приймає рядок токена, згенерований деінде або засобами автоматизації.
|
||||
- `paste-token` вимагає `--provider`, запитує значення токена й записує
|
||||
його до ідентифікатора профілю за замовчуванням `<provider>:manual`, якщо ви не передали
|
||||
які надають методи автентифікації через токен.
|
||||
- `setup-token` вимагає інтерактивний TTY і запускає метод автентифікації через токен провайдера
|
||||
(за замовчуванням використовується метод `setup-token` цього провайдера, якщо він
|
||||
доступний).
|
||||
- `paste-token` приймає рядок токена, згенерований в іншому місці або засобами автоматизації.
|
||||
- `paste-token` вимагає `--provider`, запитує значення токена і записує
|
||||
його до ідентифікатора профілю за замовчуванням `<provider>:manual`, якщо ви не передасте
|
||||
`--profile-id`.
|
||||
- `paste-token --expires-in <duration>` зберігає абсолютний строк дії токена на основі
|
||||
відносної тривалості, наприклад `365d` або `12h`.
|
||||
- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI та використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику.
|
||||
- `setup-token` / `paste-token` Anthropic залишаються доступними як підтримуваний шлях роботи з токенами в OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI та `claude -p`, коли це можливо.
|
||||
відносної тривалості, такої як `365d` або `12h`.
|
||||
- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw розглядає повторне використання Claude CLI та використання `claude -p` як санкціоновані для цієї інтеграції, якщо Anthropic не опублікує нову політику.
|
||||
- Anthropic `setup-token` / `paste-token` залишаються доступними як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли це можливо.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Довідка CLI](/uk/cli)
|
||||
- [Довідник CLI](/uk/cli)
|
||||
- [Вибір моделі](/uk/concepts/model-providers)
|
||||
- [Відмовостійке перемикання моделей](/uk/concepts/model-failover)
|
||||
- [Відмовостійкість моделей](/uk/concepts/model-failover)
|
||||
|
||||
@ -1,24 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- Додавання або зміна CLI моделей (models list/set/scan/aliases/fallbacks)
|
||||
- Зміна поведінки резервних варіантів моделей або UX вибору моделей
|
||||
- Оновлення перевірок сканування моделей (інструменти/зображення)
|
||||
summary: 'CLI моделей: список, налаштування, псевдоніми, резервні варіанти, сканування, статус'
|
||||
- Додавання або зміна CLI моделей (`models list/set/scan/aliases/fallbacks`)
|
||||
- Зміна поведінки резервних варіантів моделі або UX вибору
|
||||
- Оновлення перевірок сканування моделі (`tools/images`)
|
||||
summary: 'CLI моделей: список, встановлення, псевдоніми, резервні варіанти, сканування, статус'
|
||||
title: CLI моделей
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T01:53:14Z"
|
||||
generated_at: "2026-04-25T09:52:32Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f6a98f44872d5de81f02dc7318bb8ecdff3860996d286b6aa9d42abbd8ce6670
|
||||
source_hash: 370453529596e87e724c4de7d2ae9d20334c29393116059bc01363b47c017d5d
|
||||
source_path: concepts/models.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Див. [/concepts/model-failover](/uk/concepts/model-failover) для ротації профілів автентифікації, cooldowns і того, як це взаємодіє з резервними варіантами.
|
||||
Короткий огляд постачальників + приклади: [/concepts/model-providers](/uk/concepts/model-providers).
|
||||
Посилання на моделі вибирають постачальника і модель. Зазвичай вони не вибирають
|
||||
Див. [/concepts/model-failover](/uk/concepts/model-failover) щодо ротації профілів автентифікації, періодів охолодження та того, як це взаємодіє з резервними варіантами.
|
||||
Короткий огляд провайдерів + приклади: [/concepts/model-providers](/uk/concepts/model-providers).
|
||||
Посилання на моделі вибирають провайдера й модель. Зазвичай вони не вибирають
|
||||
низькорівневе середовище виконання агента. Наприклад, `openai/gpt-5.5` може працювати через
|
||||
звичайний шлях постачальника OpenAI або через середовище виконання app-server Codex, залежно
|
||||
звичайний шлях провайдера OpenAI або через середовище виконання застосунку-сервера Codex, залежно
|
||||
від `agents.defaults.embeddedHarness.runtime`. Див.
|
||||
[/concepts/agent-runtimes](/uk/concepts/agent-runtimes).
|
||||
|
||||
@ -28,25 +28,25 @@ OpenClaw вибирає моделі в такому порядку:
|
||||
|
||||
1. **Основна** модель (`agents.defaults.model.primary` або `agents.defaults.model`).
|
||||
2. **Резервні варіанти** в `agents.defaults.model.fallbacks` (по порядку).
|
||||
3. **Резервне перемикання автентифікації постачальника** відбувається всередині постачальника перед переходом до
|
||||
3. **Резервне перемикання автентифікації провайдера** відбувається всередині провайдера перед переходом до
|
||||
наступної моделі.
|
||||
|
||||
Пов’язане:
|
||||
Пов’язано:
|
||||
|
||||
- `agents.defaults.models` — це allowlist/каталог моделей, які OpenClaw може використовувати (плюс псевдоніми).
|
||||
- `agents.defaults.models` — це список дозволених моделей/каталог моделей, які OpenClaw може використовувати (разом із псевдонімами).
|
||||
- `agents.defaults.imageModel` використовується **лише тоді**, коли основна модель не може приймати зображення.
|
||||
- `agents.defaults.pdfModel` використовується інструментом `pdf`. Якщо його не вказано, інструмент
|
||||
повертається до `agents.defaults.imageModel`, а потім до визначеної для сесії/типової
|
||||
моделі.
|
||||
- `agents.defaults.imageGenerationModel` використовується спільною можливістю генерації зображень. Якщо його не вказано, `image_generate` усе ще може визначити типовий постачальник із підтримкою автентифікації. Спочатку він пробує поточного типового постачальника, а потім решту зареєстрованих постачальників генерації зображень у порядку provider-id. Якщо ви встановлюєте конкретного постачальника/модель, також налаштуйте автентифікацію/API key цього постачальника.
|
||||
- `agents.defaults.musicGenerationModel` використовується спільною можливістю генерації музики. Якщо його не вказано, `music_generate` усе ще може визначити типовий постачальник із підтримкою автентифікації. Спочатку він пробує поточного типового постачальника, а потім решту зареєстрованих постачальників генерації музики у порядку provider-id. Якщо ви встановлюєте конкретного постачальника/модель, також налаштуйте автентифікацію/API key цього постачальника.
|
||||
- `agents.defaults.videoGenerationModel` використовується спільною можливістю генерації відео. Якщо його не вказано, `video_generate` усе ще може визначити типовий постачальник із підтримкою автентифікації. Спочатку він пробує поточного типового постачальника, а потім решту зареєстрованих постачальників генерації відео у порядку provider-id. Якщо ви встановлюєте конкретного постачальника/модель, також налаштуйте автентифікацію/API key цього постачальника.
|
||||
- Типові значення для окремих агентів можуть перевизначати `agents.defaults.model` через `agents.list[].model` плюс прив’язки (див. [/concepts/multi-agent](/uk/concepts/multi-agent)).
|
||||
- `agents.defaults.pdfModel` використовується інструментом `pdf`. Якщо не вказано, інструмент
|
||||
переключається на `agents.defaults.imageModel`, а потім на визначену для сесії/типову
|
||||
модель.
|
||||
- `agents.defaults.imageGenerationModel` використовується спільною можливістю генерації зображень. Якщо не вказано, `image_generate` усе одно може вивести типовий провайдер із підтримкою автентифікації. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів. Якщо ви задаєте конкретного провайдера/модель, також налаштуйте автентифікацію/API-ключ цього провайдера.
|
||||
- `agents.defaults.musicGenerationModel` використовується спільною можливістю генерації музики. Якщо не вказано, `music_generate` усе одно може вивести типовий провайдер із підтримкою автентифікації. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів. Якщо ви задаєте конкретного провайдера/модель, також налаштуйте автентифікацію/API-ключ цього провайдера.
|
||||
- `agents.defaults.videoGenerationModel` використовується спільною можливістю генерації відео. Якщо не вказано, `video_generate` усе одно може вивести типовий провайдер із підтримкою автентифікації. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів. Якщо ви задаєте конкретного провайдера/модель, також налаштуйте автентифікацію/API-ключ цього провайдера.
|
||||
- Типові значення для окремого агента можуть перевизначати `agents.defaults.model` через `agents.list[].model` разом із прив’язками (див. [/concepts/multi-agent](/uk/concepts/multi-agent)).
|
||||
|
||||
## Коротка політика щодо моделей
|
||||
## Швидка політика щодо моделей
|
||||
|
||||
- Встановіть основною найсильнішу модель останнього покоління, яка вам доступна.
|
||||
- Використовуйте резервні варіанти для чутливих до вартості/затримки завдань і менш критичних чатів.
|
||||
- Встановіть як основну найсильнішу модель останнього покоління, доступну вам.
|
||||
- Використовуйте резервні варіанти для завдань, чутливих до вартості/затримки, і для менш критичних чатів.
|
||||
- Для агентів з увімкненими інструментами або недовірених вхідних даних уникайте старіших/слабших рівнів моделей.
|
||||
|
||||
## Онбординг (рекомендовано)
|
||||
@ -57,8 +57,8 @@ OpenClaw вибирає моделі в такому порядку:
|
||||
openclaw onboard
|
||||
```
|
||||
|
||||
Він може налаштувати модель + автентифікацію для поширених постачальників, включно з **підпискою OpenAI Code (Codex)**
|
||||
(OAuth) і **Anthropic** (API key або Claude CLI).
|
||||
Він може налаштувати модель + автентифікацію для поширених провайдерів, зокрема **OpenAI Code (Codex)
|
||||
subscription** (OAuth) і **Anthropic** (API-ключ або Claude CLI).
|
||||
|
||||
## Ключі конфігурації (огляд)
|
||||
|
||||
@ -67,55 +67,55 @@ openclaw onboard
|
||||
- `agents.defaults.pdfModel.primary` і `agents.defaults.pdfModel.fallbacks`
|
||||
- `agents.defaults.imageGenerationModel.primary` і `agents.defaults.imageGenerationModel.fallbacks`
|
||||
- `agents.defaults.videoGenerationModel.primary` і `agents.defaults.videoGenerationModel.fallbacks`
|
||||
- `agents.defaults.models` (allowlist + псевдоніми + параметри постачальника)
|
||||
- `models.providers` (користувацькі постачальники, записані в `models.json`)
|
||||
- `agents.defaults.models` (список дозволених + псевдоніми + параметри провайдера)
|
||||
- `models.providers` (власні провайдери, записані в `models.json`)
|
||||
|
||||
Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми постачальників, як-от `z.ai/*`, нормалізуються
|
||||
Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми провайдерів, як-от `z.ai/*`, нормалізуються
|
||||
до `zai/*`.
|
||||
|
||||
Приклади конфігурації постачальників (зокрема OpenCode) наведено в
|
||||
Приклади конфігурації провайдерів (зокрема OpenCode) наведено в
|
||||
[/providers/opencode](/uk/providers/opencode).
|
||||
|
||||
### Безпечне редагування allowlist
|
||||
### Безпечне редагування списку дозволених
|
||||
|
||||
Використовуйте адитивні записи, коли оновлюєте `agents.defaults.models` вручну:
|
||||
Під час ручного оновлення `agents.defaults.models` використовуйте адитивні записи:
|
||||
|
||||
```bash
|
||||
openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
|
||||
```
|
||||
|
||||
`openclaw config set` захищає мапи моделей/постачальників від випадкового перезапису. Звичайне
|
||||
присвоєння об’єкта для `agents.defaults.models`, `models.providers` або
|
||||
`openclaw config set` захищає мапи моделей/провайдерів від випадкового перезапису. Звичайне
|
||||
присвоєння об’єкта до `agents.defaults.models`, `models.providers` або
|
||||
`models.providers.<id>.models` відхиляється, якщо воно призведе до видалення наявних
|
||||
записів. Використовуйте `--merge` для адитивних змін; використовуйте `--replace` лише тоді, коли
|
||||
надане значення має стати повним цільовим значенням.
|
||||
|
||||
Інтерактивне налаштування постачальника і `openclaw configure --section model` також об’єднують
|
||||
вибори в межах постачальника в наявний allowlist, тож додавання Codex,
|
||||
Ollama або іншого постачальника не видаляє незв’язані записи моделей.
|
||||
Configure зберігає наявний `agents.defaults.model.primary`, коли автентифікацію постачальника
|
||||
застосовано повторно. Явні команди встановлення типового значення, такі як
|
||||
Інтерактивне налаштування провайдера та `openclaw configure --section model` також зливають
|
||||
вибірки в межах провайдера в наявний список дозволених, тому додавання Codex,
|
||||
Ollama або іншого провайдера не видаляє не пов’язані записи моделей.
|
||||
Configure зберігає наявне `agents.defaults.model.primary`, коли автентифікацію провайдера
|
||||
застосовано повторно. Явні команди встановлення типових значень, як-от
|
||||
`openclaw models auth login --provider <id> --set-default` і
|
||||
`openclaw models set <model>`, як і раніше, замінюють `agents.defaults.model.primary`.
|
||||
`openclaw models set <model>`, усе одно замінюють `agents.defaults.model.primary`.
|
||||
|
||||
## «Модель не дозволена» (і чому відповіді припиняються)
|
||||
## «Model is not allowed» (і чому відповіді зупиняються)
|
||||
|
||||
Якщо встановлено `agents.defaults.models`, воно стає **allowlist** для `/model` і для
|
||||
перевизначень сесії. Коли користувач вибирає модель, якої немає в цьому allowlist,
|
||||
Якщо задано `agents.defaults.models`, він стає **списком дозволених** для `/model` і для
|
||||
перевизначень у сесії. Коли користувач вибирає модель, якої немає в цьому списку дозволених,
|
||||
OpenClaw повертає:
|
||||
|
||||
```
|
||||
Model "provider/model" is not allowed. Use /model to list available models.
|
||||
```
|
||||
|
||||
Це відбувається **до** створення звичайної відповіді, тому повідомлення може створювати враження,
|
||||
ніби воно «не відповіло». Щоб виправити це, потрібно:
|
||||
Це відбувається **до** генерації звичайної відповіді, тому може здаватися, що на повідомлення
|
||||
«не відповіли». Виправити це можна так:
|
||||
|
||||
- Додати модель до `agents.defaults.models`, або
|
||||
- Очистити allowlist (видалити `agents.defaults.models`), або
|
||||
- Вибрати модель із `/model list`.
|
||||
- Додайте модель до `agents.defaults.models`, або
|
||||
- Очистьте список дозволених (видаліть `agents.defaults.models`), або
|
||||
- Виберіть модель із `/model list`.
|
||||
|
||||
Приклад конфігурації allowlist:
|
||||
Приклад конфігурації списку дозволених:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -143,26 +143,26 @@ Model "provider/model" is not allowed. Use /model to list available models.
|
||||
|
||||
Примітки:
|
||||
|
||||
- `/model` (і `/model list`) — це компактний нумерований вибір (сімейство моделей + доступні постачальники).
|
||||
- У Discord команди `/model` і `/models` відкривають інтерактивний вибір із випадними списками постачальника та моделі, а також кроком Submit.
|
||||
- `/models add` застаріла і тепер повертає повідомлення про застарілість замість реєстрації моделей із чату.
|
||||
- `/model <#>` вибирає зі списку цього вибору.
|
||||
- `/model` негайно зберігає новий вибір сесії.
|
||||
- `/model` (і `/model list`) — це компактний нумерований засіб вибору (сімейство моделей + доступні провайдери).
|
||||
- У Discord `/model` і `/models` відкривають інтерактивний засіб вибору зі списками провайдера та моделі, а також кроком Submit.
|
||||
- `/models add` застаріла команда й тепер повертає повідомлення про застарілість замість реєстрації моделей із чату.
|
||||
- `/model <#>` вибирає модель із цього засобу вибору.
|
||||
- `/model` негайно зберігає новий вибір для сесії.
|
||||
- Якщо агент простоює, наступний запуск одразу використовує нову модель.
|
||||
- Якщо запуск уже активний, OpenClaw позначає живе перемикання як очікуване й перезапускається з новою моделлю лише в чистій точці повторної спроби.
|
||||
- Якщо активність інструмента або виведення відповіді вже розпочалися, очікуване перемикання може залишатися в черзі до пізнішої можливості повторної спроби або до наступного ходу користувача.
|
||||
- `/model status` — це докладний перегляд (кандидати автентифікації і, коли налаштовано, `baseUrl` кінцевої точки постачальника + режим `api`).
|
||||
- Посилання на моделі аналізуються шляхом розділення за **першим** `/`. Використовуйте `provider/model`, коли вводите `/model <ref>`.
|
||||
- Якщо сам ID моделі містить `/` (у стилі OpenRouter), ви повинні вказати префікс постачальника (приклад: `/model openrouter/moonshotai/kimi-k2`).
|
||||
- Якщо ви пропускаєте постачальника, OpenClaw визначає введення в такому порядку:
|
||||
- Якщо запуск уже активний, OpenClaw позначає живе перемикання як таке, що очікує, і перезапускає нову модель лише в чистій точці повторної спроби.
|
||||
- Якщо активність інструмента або виведення відповіді вже почалися, відкладене перемикання може залишатися в черзі до пізнішої можливості повторної спроби або до наступного ходу користувача.
|
||||
- `/model status` — це докладне подання (кандидати автентифікації та, коли налаштовано, `baseUrl` кінцевої точки провайдера + режим `api`).
|
||||
- Посилання на моделі розбираються поділом за **першим** `/`. Під час введення `/model <ref>` використовуйте `provider/model`.
|
||||
- Якщо сам ідентифікатор моделі містить `/` (у стилі OpenRouter), ви маєте вказати префікс провайдера (приклад: `/model openrouter/moonshotai/kimi-k2`).
|
||||
- Якщо ви не вказали провайдера, OpenClaw визначає введене значення в такому порядку:
|
||||
1. збіг псевдоніма
|
||||
2. унікальний збіг налаштованого постачальника для цього точного ID моделі без префікса
|
||||
3. застарілий резервний перехід до налаштованого типового постачальника
|
||||
Якщо цей постачальник більше не надає налаштовану типову модель, OpenClaw
|
||||
натомість повертається до першого налаштованого постачальника/моделі, щоб
|
||||
уникнути показу застарілого типового значення видаленого постачальника.
|
||||
2. унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі без префікса
|
||||
3. застаріле резервне перемикання на налаштованого типового провайдера
|
||||
Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw
|
||||
натомість переключається на першу налаштовану пару провайдер/модель, щоб уникнути
|
||||
показу застарілого типового значення видаленого провайдера.
|
||||
|
||||
Повна поведінка команди/конфігурація: [Слеш-команди](/uk/tools/slash-commands).
|
||||
Повна поведінка команди/конфігурація: [Slash commands](/uk/tools/slash-commands).
|
||||
|
||||
## Команди CLI
|
||||
|
||||
@ -194,36 +194,35 @@ openclaw models image-fallbacks clear
|
||||
Типово показує налаштовані моделі. Корисні прапорці:
|
||||
|
||||
- `--all`: повний каталог
|
||||
- `--local`: лише локальні постачальники
|
||||
- `--provider <id>`: фільтр за id постачальника, наприклад `moonshot`; мітки відображення з інтерактивних вибірників не приймаються
|
||||
- `--local`: лише локальні провайдери
|
||||
- `--provider <id>`: фільтр за ідентифікатором провайдера, наприклад `moonshot`; мітки відображення з інтерактивних засобів вибору не підтримуються
|
||||
- `--plain`: одна модель на рядок
|
||||
- `--json`: machine-readable вивід
|
||||
- `--json`: машиночитний вивід
|
||||
|
||||
`--all` включає статичні рядки каталогу, що входять до складу постачальника, до
|
||||
налаштування автентифікації, тому представлення лише для виявлення можуть показувати
|
||||
моделі, недоступні, доки ви не додасте відповідні облікові дані постачальника.
|
||||
`--all` включає вбудовані рядки статичного каталогу, що належать провайдеру, ще до
|
||||
налаштування автентифікації, тому подання лише для виявлення може показувати моделі, які недоступні,
|
||||
доки ви не додасте відповідні облікові дані провайдера.
|
||||
|
||||
### `models status`
|
||||
|
||||
Показує визначену основну модель, резервні варіанти, модель зображень і огляд автентифікації
|
||||
налаштованих постачальників. Також показує статус закінчення строку дії OAuth для профілів, знайдених
|
||||
у сховищі автентифікації (типово попереджає за 24 год до закінчення). `--plain` виводить лише
|
||||
налаштованих провайдерів. Також показує стан строку дії OAuth для профілів, знайдених
|
||||
у сховищі автентифікації (типово попереджає за 24 год). `--plain` виводить лише
|
||||
визначену основну модель.
|
||||
Статус OAuth показується завжди (і включається у вивід `--json`). Якщо налаштований
|
||||
постачальник не має облікових даних, `models status` виводить розділ **Відсутня автентифікація**.
|
||||
JSON містить `auth.oauth` (вікно попередження + профілі) і `auth.providers`
|
||||
(ефективна автентифікація для кожного постачальника, зокрема облікові дані з env). `auth.oauth`
|
||||
стосується лише стану профілів у сховищі автентифікації; постачальники лише з env там не з’являються.
|
||||
Використовуйте `--check` для автоматизації (exit `1` за відсутності/простроченні, `2` якщо строк скоро спливає).
|
||||
Використовуйте `--probe` для живих перевірок автентифікації; рядки probe можуть надходити з профілів автентифікації, облікових даних env
|
||||
Стан OAuth показується завжди (і включається у вивід `--json`). Якщо налаштований
|
||||
провайдер не має облікових даних, `models status` виводить розділ **Missing auth**.
|
||||
JSON включає `auth.oauth` (вікно попередження + профілі) і `auth.providers`
|
||||
(ефективна автентифікація для кожного провайдера, зокрема облікові дані з env). `auth.oauth`
|
||||
— це лише стан профілів у сховищі автентифікації; провайдери лише з env там не з’являються.
|
||||
Для автоматизації використовуйте `--check` (код виходу `1`, якщо дані відсутні/прострочені, `2`, якщо скоро спливають).
|
||||
Для живих перевірок автентифікації використовуйте `--probe`; рядки перевірки можуть походити з профілів автентифікації, облікових даних env
|
||||
або `models.json`.
|
||||
Якщо явний `auth.order.<provider>` пропускає збережений профіль, probe повідомляє
|
||||
`excluded_by_auth_order` замість спроби використати його. Якщо автентифікація є, але не вдається визначити модель,
|
||||
яку можна probe для цього постачальника, probe повідомляє `status: no_model`.
|
||||
Якщо явний `auth.order.<provider>` пропускає збережений профіль, перевірка повідомляє
|
||||
`excluded_by_auth_order` замість спроби його використати. Якщо автентифікація є, але для цього провайдера неможливо визначити модель для перевірки, перевірка повідомляє `status: no_model`.
|
||||
|
||||
Вибір автентифікації залежить від постачальника/облікового запису. Для постійно ввімкнених хостів gateway API
|
||||
keys зазвичай є найпередбачуванішими; повторне використання Claude CLI та наявних профілів Anthropic OAuth/token
|
||||
також підтримується.
|
||||
Вибір автентифікації залежить від провайдера/облікового запису. Для постійно активних хостів Gateway
|
||||
API-ключі зазвичай найпередбачуваніші; також підтримується повторне використання Claude CLI і наявні
|
||||
OAuth/токен-профілі Anthropic.
|
||||
|
||||
Приклад (Claude CLI):
|
||||
|
||||
@ -235,20 +234,22 @@ openclaw models status
|
||||
## Сканування (безкоштовні моделі OpenRouter)
|
||||
|
||||
`openclaw models scan` перевіряє **каталог безкоштовних моделей** OpenRouter і може
|
||||
за бажанням виконувати probe моделей на підтримку інструментів і зображень.
|
||||
за бажанням перевіряти моделі на підтримку інструментів і зображень.
|
||||
|
||||
Основні прапорці:
|
||||
|
||||
- `--no-probe`: пропустити живі probe (лише метадані)
|
||||
- `--no-probe`: пропустити живі перевірки (лише метадані)
|
||||
- `--min-params <b>`: мінімальний розмір параметрів (у мільярдах)
|
||||
- `--max-age-days <days>`: пропустити старіші моделі
|
||||
- `--provider <name>`: фільтр за префіксом постачальника
|
||||
- `--provider <name>`: фільтр префікса провайдера
|
||||
- `--max-candidates <n>`: розмір списку резервних варіантів
|
||||
- `--set-default`: встановити `agents.defaults.model.primary` на перший вибір
|
||||
- `--set-image`: встановити `agents.defaults.imageModel.primary` на перший вибір зображень
|
||||
- `--set-image`: встановити `agents.defaults.imageModel.primary` на перший вибір для зображень
|
||||
|
||||
Для probe потрібен API key OpenRouter (з профілів автентифікації або
|
||||
`OPENROUTER_API_KEY`). Без ключа використовуйте `--no-probe`, щоб лише перелічити кандидатів.
|
||||
Каталог OpenRouter `/models` є публічним, тому сканування лише метаданих може
|
||||
показувати безкоштовних кандидатів без ключа. Перевірки й інференс однаково потребують
|
||||
API-ключ OpenRouter (з профілів автентифікації або `OPENROUTER_API_KEY`). Якщо ключ недоступний,
|
||||
`openclaw models scan` переключається на вивід лише метаданих і не змінює конфігурацію. Використовуйте `--no-probe`, щоб явно запросити режим лише метаданих.
|
||||
|
||||
Результати сканування ранжуються за:
|
||||
|
||||
@ -257,40 +258,42 @@ openclaw models status
|
||||
3. Розміром контексту
|
||||
4. Кількістю параметрів
|
||||
|
||||
Ввід
|
||||
Вхідні дані
|
||||
|
||||
- Список OpenRouter `/models` (фільтр `:free`)
|
||||
- Потребує API key OpenRouter з профілів автентифікації або `OPENROUTER_API_KEY` (див. [/environment](/uk/help/environment))
|
||||
- Для живих перевірок потрібен API-ключ OpenRouter із профілів автентифікації або `OPENROUTER_API_KEY` (див. [/environment](/uk/help/environment))
|
||||
- Необов’язкові фільтри: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates`
|
||||
- Керування probe: `--timeout`, `--concurrency`
|
||||
- Керування запитами/перевірками: `--timeout`, `--concurrency`
|
||||
|
||||
Під час запуску в TTY ви можете інтерактивно вибирати резервні варіанти. У неінтерактивному
|
||||
режимі передайте `--yes`, щоб прийняти типові значення.
|
||||
Коли живі перевірки виконуються в TTY, ви можете інтерактивно вибирати резервні варіанти. У
|
||||
неінтерактивному режимі передайте `--yes`, щоб прийняти типові значення. Результати лише з метаданими є
|
||||
інформаційними; `--set-default` і `--set-image` потребують живих перевірок, щоб
|
||||
OpenClaw не налаштував непридатну модель OpenRouter без ключа.
|
||||
|
||||
## Реєстр моделей (`models.json`)
|
||||
|
||||
Користувацькі постачальники в `models.providers` записуються у `models.json` у каталозі
|
||||
Власні провайдери в `models.providers` записуються в `models.json` у каталозі
|
||||
агента (типово `~/.openclaw/agents/<agentId>/agent/models.json`). Цей файл
|
||||
типово об’єднується, якщо лише `models.mode` не встановлено в `replace`.
|
||||
типово зливається, якщо лише `models.mode` не встановлено в `replace`.
|
||||
|
||||
Пріоритет у режимі merge для відповідних ID постачальників:
|
||||
Пріоритет у режимі злиття для відповідних ідентифікаторів провайдерів:
|
||||
|
||||
- Непорожній `baseUrl`, який уже присутній в агентському `models.json`, має пріоритет.
|
||||
- Непорожній `apiKey` в агентському `models.json` має пріоритет лише тоді, коли цей постачальник не керується через SecretRef у поточному контексті конфігурації/профілю автентифікації.
|
||||
- Значення `apiKey` для постачальників, керованих через SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження визначених секретів.
|
||||
- Значення заголовків постачальника, керованих через SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань).
|
||||
- Порожні або відсутні агентські `apiKey`/`baseUrl` повертаються до конфігураційного `models.providers`.
|
||||
- Інші поля постачальника оновлюються з конфігурації та нормалізованих даних каталогу.
|
||||
- Непорожній `baseUrl`, уже наявний в `models.json` агента, має пріоритет.
|
||||
- Непорожній `apiKey` у `models.json` агента має пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті конфігурації/профілю автентифікації.
|
||||
- Значення `apiKey` для провайдерів, керованих через SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для посилань env, `secretref-managed` для посилань file/exec) замість збереження розв’язаних секретів.
|
||||
- Значення заголовків для провайдерів, керованих через SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для посилань env, `secretref-managed` для посилань file/exec).
|
||||
- Порожні або відсутні `apiKey`/`baseUrl` агента переключаються на конфігураційні `models.providers`.
|
||||
- Інші поля провайдера оновлюються з конфігурації та нормалізованих даних каталогу.
|
||||
|
||||
Збереження маркерів є авторитетним на рівні джерела: OpenClaw записує маркери з активного знімка конфігурації джерела (до визначення), а не з визначених значень секретів часу виконання.
|
||||
Це застосовується щоразу, коли OpenClaw повторно генерує `models.json`, зокрема в шляхах, ініційованих командами, таких як `openclaw agent`.
|
||||
Збереження маркерів є авторитетним щодо джерела: OpenClaw записує маркери з активного знімка конфігурації джерела (до розв’язання), а не з розв’язаних значень секретів під час виконання.
|
||||
Це застосовується щоразу, коли OpenClaw повторно генерує `models.json`, зокрема в шляхах, керованих командами, як-от `openclaw agent`.
|
||||
|
||||
## Пов’язане
|
||||
## Пов’язано
|
||||
|
||||
- [Постачальники моделей](/uk/concepts/model-providers) — маршрутизація постачальників і автентифікація
|
||||
- [Середовища виконання агентів](/uk/concepts/agent-runtimes) — PI, Codex та інші середовища виконання циклу агента
|
||||
- [Резервне перемикання моделей](/uk/concepts/model-failover) — ланцюжки резервних варіантів
|
||||
- [Генерація зображень](/uk/tools/image-generation) — конфігурація моделі зображень
|
||||
- [Генерація музики](/uk/tools/music-generation) — конфігурація моделі музики
|
||||
- [Генерація відео](/uk/tools/video-generation) — конфігурація моделі відео
|
||||
- [Довідник із конфігурації](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей
|
||||
- [Model Providers](/uk/concepts/model-providers) — маршрутизація провайдерів і автентифікація
|
||||
- [Agent Runtimes](/uk/concepts/agent-runtimes) — PI, Codex та інші середовища виконання циклу агента
|
||||
- [Model Failover](/uk/concepts/model-failover) — ланцюжки резервних варіантів
|
||||
- [Image Generation](/uk/tools/image-generation) — конфігурація моделі зображень
|
||||
- [Music Generation](/uk/tools/music-generation) — конфігурація моделі генерації музики
|
||||
- [Video Generation](/uk/tools/video-generation) — конфігурація моделі генерації відео
|
||||
- [Configuration Reference](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей
|
||||
|
||||
@ -1,208 +1,207 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете керувати Gateway із браузера
|
||||
- Вам потрібен доступ Tailnet без SSH-тунелів
|
||||
summary: Вебінтерфейс керування для Gateway (чат, Node, конфігурація)
|
||||
title: Control UI
|
||||
- Ви хочете керувати Gateway з браузера
|
||||
- Ви хочете доступ Tailnet без SSH-тунелів
|
||||
summary: Вебінтерфейс керування для Gateway (чат, вузли, конфігурація)
|
||||
title: Інтерфейс керування
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T05:59:25Z"
|
||||
generated_at: "2026-04-25T09:52:27Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 0c41605af9972b2ec0a8f23724f0279c1890740b150b37814d2f879a466d36b0
|
||||
source_hash: d63d2e6a33fe87103c6265532a8742e08b3dd15124ce8b876ed280aea5f55a9d
|
||||
source_path: web/control-ui.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Control UI — це невеликий односторінковий застосунок **Vite + Lit**, який обслуговується Gateway:
|
||||
Інтерфейс керування — це невеликий односторінковий застосунок **Vite + Lit**, який обслуговується Gateway:
|
||||
|
||||
- за замовчуванням: `http://<host>:18789/`
|
||||
- необов’язковий префікс: задайте `gateway.controlUi.basePath` (наприклад, `/openclaw`)
|
||||
- необов’язковий префікс: встановіть `gateway.controlUi.basePath` (наприклад, `/openclaw`)
|
||||
|
||||
Він звертається **безпосередньо до WebSocket Gateway** на тому самому порту.
|
||||
Він взаємодіє **безпосередньо з WebSocket Gateway** на тому самому порту.
|
||||
|
||||
## Швидке відкриття (локально)
|
||||
|
||||
Якщо Gateway запущений на тому самому комп’ютері, відкрийте:
|
||||
Якщо Gateway запущено на тому самому комп’ютері, відкрийте:
|
||||
|
||||
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (або [http://localhost:18789/](http://localhost:18789/))
|
||||
|
||||
Якщо сторінка не завантажується, спочатку запустіть Gateway: `openclaw gateway`.
|
||||
|
||||
Auth передається під час handshake WebSocket через:
|
||||
Автентифікація передається під час рукостискання WebSocket через:
|
||||
|
||||
- `connect.params.auth.token`
|
||||
- `connect.params.auth.password`
|
||||
- заголовки ідентичності Tailscale Serve, коли `gateway.auth.allowTailscale: true`
|
||||
- заголовки ідентичності trusted-proxy, коли `gateway.auth.mode: "trusted-proxy"`
|
||||
|
||||
Панель налаштувань інформаційної панелі зберігає токен для поточної сесії вкладки браузера
|
||||
і вибрану URL-адресу Gateway; паролі не зберігаються. Onboarding зазвичай
|
||||
генерує токен Gateway для auth зі спільним секретом під час першого підключення, але
|
||||
auth за паролем теж працює, коли `gateway.auth.mode` має значення `"password"`.
|
||||
Панель налаштувань на інформаційній панелі зберігає токен для поточної сесії вкладки браузера
|
||||
та вибрану URL-адресу gateway; паролі не зберігаються. Під час початкового налаштування зазвичай
|
||||
генерується токен gateway для автентифікації за спільним секретом при першому підключенні, але
|
||||
автентифікація паролем також працює, коли `gateway.auth.mode` має значення `"password"`.
|
||||
|
||||
## Сполучення пристрою (перше підключення)
|
||||
|
||||
Коли ви підключаєтеся до Control UI з нового браузера або пристрою, Gateway
|
||||
вимагає **одноразового схвалення сполучення** — навіть якщо ви в тій самій Tailnet
|
||||
із `gateway.auth.allowTailscale: true`. Це захід безпеки, щоб запобігти
|
||||
вимагає **одноразове підтвердження сполучення** — навіть якщо ви перебуваєте в тій самій Tailnet
|
||||
із `gateway.auth.allowTailscale: true`. Це захід безпеки для запобігання
|
||||
несанкціонованому доступу.
|
||||
|
||||
**Що ви побачите:** `disconnected (1008): pairing required`
|
||||
**Що ви побачите:** "disconnected (1008): pairing required"
|
||||
|
||||
**Щоб схвалити пристрій:**
|
||||
**Щоб підтвердити пристрій:**
|
||||
|
||||
```bash
|
||||
# Показати очікувані запити
|
||||
# Перелічити очікувальні запити
|
||||
openclaw devices list
|
||||
|
||||
# Схвалити за ID запиту
|
||||
# Підтвердити за ID запиту
|
||||
openclaw devices approve <requestId>
|
||||
```
|
||||
|
||||
Якщо браузер повторює спробу сполучення зі зміненими деталями auth (роль/scopes/public
|
||||
key), попередній очікуваний запит витісняється і створюється новий `requestId`.
|
||||
Перед схваленням знову виконайте `openclaw devices list`.
|
||||
Якщо браузер повторно намагається виконати сполучення зі зміненими даними автентифікації (роль/області доступу/публічний
|
||||
ключ), попередній очікувальний запит замінюється, і створюється новий `requestId`.
|
||||
Перед підтвердженням знову виконайте `openclaw devices list`.
|
||||
|
||||
Якщо браузер уже сполучений і ви змінюєте його з доступу лише для читання на
|
||||
доступ для запису/admin, це вважається оновленням схвалення, а не тихим
|
||||
повторним підключенням. OpenClaw зберігає старе схвалення активним, блокує ширше
|
||||
повторне підключення і просить вас явно схвалити новий набір scopes.
|
||||
доступ для запису/адміністратора, це розглядається як підвищення рівня схвалення, а не як
|
||||
тихе повторне підключення. OpenClaw зберігає старе схвалення активним, блокує ширше повторне підключення
|
||||
і просить вас явно підтвердити новий набір областей доступу.
|
||||
|
||||
Після схвалення пристрій запам’ятовується й не вимагатиме повторного схвалення, якщо
|
||||
ви не відкличете його через `openclaw devices revoke --device <id> --role <role>`. Див.
|
||||
[CLI Devices](/uk/cli/devices) для ротації токенів і відкликання.
|
||||
Після підтвердження пристрій буде запам’ятовано й не потребуватиме повторного підтвердження, якщо
|
||||
ви не відкличете його за допомогою `openclaw devices revoke --device <id> --role <role>`. Див.
|
||||
[Devices CLI](/uk/cli/devices) для ротації токенів і відкликання.
|
||||
|
||||
**Примітки:**
|
||||
|
||||
- Прямі локальні браузерні підключення через local loopback (`127.0.0.1` / `localhost`) автоматично схвалюються.
|
||||
- Підключення браузера через Tailnet і LAN усе одно вимагають явного схвалення, навіть якщо
|
||||
вони походять з тієї самої машини.
|
||||
- Прямі локальні браузерні підключення через local loopback (`127.0.0.1` / `localhost`)
|
||||
підтверджуються автоматично.
|
||||
- Підключення браузера через Tailnet і LAN усе одно потребують явного підтвердження, навіть якщо
|
||||
вони ініціюються з тієї самої машини.
|
||||
- Кожен профіль браузера генерує унікальний ID пристрою, тому зміна браузера або
|
||||
очищення даних браузера вимагатиме повторного сполучення.
|
||||
|
||||
## Персональна ідентичність (локально в браузері)
|
||||
## Особиста ідентичність (локально в браузері)
|
||||
|
||||
Control UI підтримує персональну ідентичність для кожного браузера (відображуване ім’я та
|
||||
аватар), яка додається до вихідних повідомлень для атрибуції в спільних сесіях. Вона
|
||||
зберігається в сховищі браузера, прив’язана до поточного профілю браузера і не
|
||||
синхронізується з іншими пристроями та не зберігається на сервері поза звичайними
|
||||
метаданими авторства transcript у повідомленнях, які ви фактично надсилаєте. Очищення
|
||||
даних сайту або зміна браузера скидає її до порожнього значення.
|
||||
аватар), яка додається до вихідних повідомлень для атрибуції у спільних сесіях. Вона
|
||||
зберігається в сховищі браузера, прив’язана до поточного профілю браузера й не
|
||||
синхронізується з іншими пристроями та не зберігається на сервері поза звичайними метаданими
|
||||
авторства в транскрипті для повідомлень, які ви фактично надсилаєте. Очищення даних сайту або
|
||||
зміна браузера скидає її до порожнього значення.
|
||||
|
||||
## Endpoint runtime-конфігурації
|
||||
## Кінцева точка конфігурації runtime
|
||||
|
||||
Control UI отримує свої runtime-налаштування з
|
||||
`/__openclaw/control-ui-config.json`. Цей endpoint захищений тією самою auth Gateway, що
|
||||
й решта HTTP-поверхні: неавтентифіковані браузери не можуть його отримати, а
|
||||
успішне отримання вимагає або вже дійсного токена/пароля Gateway, або ідентичності
|
||||
Tailscale Serve, або ідентичності trusted-proxy.
|
||||
Control UI отримує свої налаштування runtime з
|
||||
`/__openclaw/control-ui-config.json`. Доступ до цієї кінцевої точки захищено тією самою
|
||||
автентифікацією gateway, що й решта HTTP-поверхні: неавтентифіковані браузери не можуть
|
||||
отримати її, а успішне отримання вимагає або вже чинного токена/пароля gateway,
|
||||
ідентичності Tailscale Serve або ідентичності trusted-proxy.
|
||||
|
||||
## Підтримка мов
|
||||
|
||||
Control UI може локалізуватися під час першого завантаження на основі локалі вашого браузера.
|
||||
Щоб змінити це пізніше, відкрийте **Overview -> Gateway Access -> Language**. Вибір
|
||||
Щоб змінити її пізніше, відкрийте **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`; браузер
|
||||
надсилає аудіо мікрофона безпосередньо до OpenAI і повертає виклики інструмента
|
||||
- Спілкуватися з моделлю через 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.
|
||||
- Потокові виклики інструментів + картки виводу live-інструментів у Chat (події агента)
|
||||
- Канали: статус вбудованих і bundled/external каналів Plugin, QR-вхід і конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`)
|
||||
- Instances: список присутності + оновлення (`system-presence`)
|
||||
- Sessions: список + перевизначення моделі/thinking/fast/verbose/trace/reasoning для кожної сесії (`sessions.list`, `sessions.patch`)
|
||||
- Dreams: статус Dreaming, перемикач увімкнення/вимкнення і читач Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)
|
||||
- Завдання Cron: список/додавання/редагування/запуск/увімкнення/вимкнення + історія запусків (`cron.*`)
|
||||
- Skills: статус, увімкнення/вимкнення, встановлення, оновлення API key (`skills.*`)
|
||||
- Node: список + caps (`node.list`)
|
||||
- Погодження exec: редагування allowlist для gateway або Node + політика запиту для `exec host=gateway/node` (`exec.approvals.*`)
|
||||
- Потоково передавати виклики інструментів + картки живого виводу інструментів у Chat (події агента)
|
||||
- Канали: статус вбудованих і підключених/зовнішніх каналів Plugin, вхід за QR, і конфігурація для кожного каналу (`channels.status`, `web.login.*`, `config.patch`)
|
||||
- Екземпляри: список присутності + оновлення (`system-presence`)
|
||||
- Сесії: список + перевизначення моделі/мислення/fast/verbose/trace/reasoning для окремої сесії (`sessions.list`, `sessions.patch`)
|
||||
- Dreams: статус Dreaming, перемикач увімкнення/вимкнення та читач Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)
|
||||
- Завдання Cron: перегляд/додавання/редагування/запуск/увімкнення/вимкнення + історія запусків (`cron.*`)
|
||||
- Skills: статус, увімкнення/вимкнення, встановлення, оновлення API-ключів (`skills.*`)
|
||||
- Nodes: список + caps (`node.list`)
|
||||
- Підтвердження exec: редагування списків дозволів gateway або node + політика запитів для `exec host=gateway/node` (`exec.approvals.*`)
|
||||
- Конфігурація: перегляд/редагування `~/.openclaw/openclaw.json` (`config.get`, `config.set`)
|
||||
- Конфігурація: застосування + перезапуск із валідацією (`config.apply`) і пробудження останньої активної сесії
|
||||
- Записи конфігурації включають guard на основі base-hash, щоб запобігти перезапису паралельних змін
|
||||
- Записи конфігурації (`config.set`/`config.apply`/`config.patch`) також виконують preflight для активного визначення SecretRef для посилань у надісланому payload конфігурації; невизначені активні надіслані посилання відхиляються до запису
|
||||
- Schema конфігурації + рендеринг форми (`config.schema` / `config.schema.lookup`,
|
||||
включно з `title` / `description` полів, відповідними UI hints, підсумками
|
||||
безпосередніх дочірніх елементів, метаданими docs на вузлах nested object/wildcard/array/composition,
|
||||
а також schema Plugin + каналів, коли вони доступні); редактор Raw JSON
|
||||
доступний лише тоді, коли snapshot має безпечне raw round-trip
|
||||
- Якщо snapshot не може безпечно виконати raw round-trip, Control UI примусово використовує режим Form і вимикає режим Raw для цього snapshot
|
||||
- У редакторі Raw JSON дія "Reset to saved" зберігає форму, створену в raw (форматування, коментарі, макет `$include`), замість повторного рендерингу сплющеного snapshot, тому зовнішні зміни переживають скидання, коли snapshot може безпечно виконати raw round-trip
|
||||
- Структуровані значення об’єктів SecretRef у формі відображаються лише для читання в текстових полях, щоб запобігти випадковому пошкодженню object-to-string
|
||||
- Налагодження: snapshots статусу/здоров’я/моделей + журнал подій + ручні RPC-виклики (`status`, `health`, `models.list`)
|
||||
- Журнали: live-tail файлових журналів gateway із фільтрацією/експортом (`logs.tail`)
|
||||
- Оновлення: запуск package/git update + перезапуск (`update.run`) зі звітом про перезапуск
|
||||
- Записи конфігурації містять захист base-hash, щоб запобігти перезапису одночасних змін
|
||||
- Записи конфігурації (`config.set`/`config.apply`/`config.patch`) також попередньо перевіряють активне розв’язання SecretRef для посилань у надісланому корисному навантаженні конфігурації; нерозв’язані активні надіслані посилання відхиляються до запису
|
||||
- Схема конфігурації + рендеринг форми (`config.schema` / `config.schema.lookup`,
|
||||
включно з полями `title` / `description`, відповідними підказками UI, підсумками
|
||||
безпосередніх дочірніх елементів, метаданими документації для вузлів вкладених object/wildcard/array/composition,
|
||||
а також схемами plugin + channel, коли вони доступні); редактор Raw JSON
|
||||
доступний лише тоді, коли знімок підтримує безпечне проходження raw туди й назад
|
||||
- Якщо знімок не може безпечно пройти raw-цикл туди й назад, Control UI примусово вмикає режим Form і вимикає режим Raw для цього знімка
|
||||
- У редакторі Raw JSON дія "Reset to saved" зберігає форму, створену в raw (форматування, коментарі, розкладку `$include`), замість повторного рендерингу сплощеного знімка, тож зовнішні зміни переживають скидання, коли знімок може безпечно пройти raw-цикл туди й назад
|
||||
- Структуровані значення об’єктів SecretRef відображаються лише для читання в текстових полях форми, щоб запобігти випадковому пошкодженню через перетворення object у string
|
||||
- Налагодження: знімки status/health/models + журнал подій + ручні виклики RPC (`status`, `health`, `models.list`)
|
||||
- Логи: живий tail логів файлів gateway із фільтрацією/експортом (`logs.tail`)
|
||||
- Оновлення: запуск оновлення пакунка/git + перезапуск (`update.run`) зі звітом про перезапуск
|
||||
|
||||
Примітки до панелі завдань Cron:
|
||||
|
||||
- Для ізольованих завдань доставлення за замовчуванням оголошує підсумок. Ви можете перемкнути на none, якщо хочете лише внутрішні запуски.
|
||||
- Для ізольованих завдань доставлення за замовчуванням — оголошення підсумку. Ви можете перемкнути на none, якщо хочете лише внутрішні запуски.
|
||||
- Поля channel/target з’являються, коли вибрано announce.
|
||||
- Режим Webhook використовує `delivery.mode = "webhook"` з `delivery.to`, установленим на дійсну HTTP(S) URL Webhook.
|
||||
- Режим Webhook використовує `delivery.mode = "webhook"` з `delivery.to`, установленим на дійсну URL-адресу HTTP(S) Webhook.
|
||||
- Для завдань main-session доступні режими доставлення webhook і none.
|
||||
- Розширені елементи редагування включають delete-after-run, clear agent override, точні/зміщені параметри Cron,
|
||||
перевизначення model/thinking агента та перемикачі best-effort delivery.
|
||||
- Валідація форми вбудована, з помилками на рівні полів; невалідні значення вимикають кнопку збереження, доки їх не буде виправлено.
|
||||
- Задайте `cron.webhookToken`, щоб надсилати окремий bearer token; якщо його не вказано, Webhook надсилається без заголовка auth.
|
||||
- Застарілий fallback: збережені застарілі завдання з `notify: true` і далі можуть використовувати `cron.webhook`, доки їх не буде мігровано.
|
||||
- Розширені елементи керування редагуванням включають delete-after-run, clear agent override, параметри exact/stagger для cron,
|
||||
перевизначення model/thinking для агента та перемикачі best-effort delivery.
|
||||
- Валідація форми виконується вбудовано з помилками на рівні полів; недійсні значення вимикають кнопку збереження, доки їх не буде виправлено.
|
||||
- Установіть `cron.webhookToken`, щоб надсилати окремий bearer-токен; якщо його не вказано, webhook надсилається без заголовка автентифікації.
|
||||
- Застарілий запасний варіант: збережені застарілі завдання з `notify: true` усе ще можуть використовувати `cron.webhook`, доки їх не буде мігровано.
|
||||
|
||||
## Поведінка чату
|
||||
|
||||
- `chat.send` є **неблокувальним**: він одразу підтверджує через `{ runId, status: "started" }`, а відповідь передається потоком через події `chat`.
|
||||
- `chat.send` є **неблокувальним**: він негайно підтверджує запитом `{ runId, status: "started" }`, а відповідь передається потоком через події `chat`.
|
||||
- Повторне надсилання з тим самим `idempotencyKey` повертає `{ status: "in_flight" }` під час виконання та `{ status: "ok" }` після завершення.
|
||||
- Відповіді `chat.history` обмежені за розміром для безпеки UI. Коли записи transcript занадто великі, Gateway може обрізати довгі текстові поля, пропускати великі блоки метаданих і замінювати надмірно великі повідомлення заповнювачем (`[chat.history omitted: message too large]`).
|
||||
- Згенеровані помічником зображення зберігаються як керовані посилання media і повертаються через автентифіковані URL media Gateway, тому перезавантаження не залежить від того, що сирі payload зображень base64 залишаються у відповіді історії чату.
|
||||
- `chat.history` також прибирає теги inline directive, які призначені лише для відображення, із видимого тексту помічника (наприклад, `[[reply_to_*]]` і `[[audio_as_voice]]`), payload XML викликів інструментів у plain-text (включно з `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізаними блоками викликів інструментів), а також витіклі токени керування моделлю ASCII/full-width і пропускає записи помічника, у яких увесь видимий текст — це лише точний тихий токен `NO_REPLY` / `no_reply`.
|
||||
- Під час активного надсилання та остаточного оновлення історії вигляд чату зберігає локальні
|
||||
оптимістичні повідомлення користувача/помічника видимими, якщо `chat.history` тимчасово повертає
|
||||
старіший snapshot; канонічний transcript замінює ці локальні повідомлення, щойно
|
||||
історія Gateway наздожене.
|
||||
- `chat.inject` додає примітку помічника до transcript сесії та розсилає подію `chat` для оновлень лише UI (без запуску агента, без доставлення в канал).
|
||||
- Вибір моделі та thinking у заголовку чату одразу змінює активну сесію через `sessions.patch`; це стійкі перевизначення сесії, а не параметри надсилання лише на один хід.
|
||||
- Коли свіжі звіти Gateway про використання сесії показують високий тиск контексту, область компонування чату
|
||||
показує сповіщення про контекст і, на рекомендованих рівнях Compaction, кнопку
|
||||
compact, яка запускає звичайний шлях Compaction сесії. Застарілі snapshots
|
||||
токенів приховуються, доки Gateway знову не повідомить про свіже використання.
|
||||
- Talk mode використовує зареєстрований provider realtime voice, який підтримує браузерні
|
||||
WebRTC-сесії. Налаштуйте OpenAI через `talk.provider: "openai"` плюс
|
||||
`talk.providers.openai.apiKey`, або повторно використайте конфігурацію provider-а realtime для Voice Call. Браузер ніколи не отримує стандартний API key OpenAI; він отримує
|
||||
лише тимчасовий секрет клієнта Realtime. Realtime voice Google Live підтримується
|
||||
для backend-мостів Voice Call і Google Meet, але ще не для цього шляху
|
||||
браузерного WebRTC. Prompt сесії Realtime збирається Gateway;
|
||||
`talk.realtime.session` не приймає перевизначення інструкцій від викликача.
|
||||
- У компонувальнику Chat елемент керування Talk — це кнопка хвиль поруч із
|
||||
кнопкою диктування мікрофоном. Коли Talk запускається, рядок стану компонувальника показує
|
||||
- Відповіді `chat.history` обмежені за розміром для безпеки UI. Коли записи транскрипту надто великі, Gateway може усікати довгі текстові поля, пропускати важкі блоки метаданих і замінювати надмірно великі повідомлення заповнювачем (`[chat.history omitted: message too large]`).
|
||||
- Згенеровані асистентом зображення зберігаються як керовані посилання на медіа й повторно віддаються через автентифіковані URL-адреси медіа Gateway, тому перезавантаження не залежать від того, чи залишаються сирі base64-корисні навантаження зображень у відповіді історії чату.
|
||||
- `chat.history` також прибирає вбудовані теги директив, призначені лише для відображення, із видимого тексту асистента (наприклад, `[[reply_to_*]]` і `[[audio_as_voice]]`), XML-корисні навантаження викликів інструментів у звичайному тексті (включно з `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і усіченими блоками викликів інструментів), а також витеклі ASCII/повноширинні токени керування моделлю, і пропускає записи асистента, у яких весь видимий текст — це лише точний тихий токен `NO_REPLY` / `no_reply`.
|
||||
- Під час активного надсилання та остаточного оновлення історії подання чату зберігає локальні
|
||||
оптимістичні повідомлення користувача/асистента видимими, якщо `chat.history` тимчасово повертає
|
||||
старіший знімок; канонічний транскрипт замінює ці локальні повідомлення, щойно
|
||||
історія Gateway наздожене їх.
|
||||
- `chat.inject` додає нотатку асистента до транскрипту сесії та транслює подію `chat` для оновлень лише UI (без запуску агента, без доставлення в канал).
|
||||
- Перемикачі моделі та мислення в заголовку чату негайно змінюють активну сесію через `sessions.patch`; це сталі перевизначення сесії, а не параметри надсилання лише для одного ходу.
|
||||
- Коли свіжі звіти про використання сесії Gateway показують високий тиск контексту, область
|
||||
компонувальника чату показує сповіщення про контекст і, на рекомендованих рівнях Compaction,
|
||||
кнопку compact, яка запускає звичайний шлях Compaction сесії. Застарілі
|
||||
знімки токенів приховуються, доки Gateway знову не повідомить про свіже використання.
|
||||
- Режим Talk використовує зареєстрованого realtime-провайдера голосу, який підтримує сесії WebRTC у браузері. Налаштуйте OpenAI через `talk.provider: "openai"` разом із
|
||||
`talk.providers.openai.apiKey`, або повторно використайте конфігурацію realtime-провайдера Voice Call. Браузер ніколи не отримує стандартний API-ключ OpenAI; він отримує
|
||||
лише ефемерний секрет клієнта Realtime. Голос Google Live realtime підтримується для бекендового Voice Call і мостів Google Meet, але ще не для цього браузерного
|
||||
шляху WebRTC. Підказка сесії Realtime збирається Gateway;
|
||||
`talk.realtime.session` не приймає перевизначення інструкцій, надані викликачем.
|
||||
- У компонувальнику Chat елемент керування Talk — це кнопка з хвилями поруч із
|
||||
кнопкою диктування з мікрофона. Коли Talk запускається, у рядку стану компонувальника відображається
|
||||
`Connecting Talk...`, потім `Talk live`, поки аудіо підключено, або
|
||||
`Asking OpenClaw...`, поки виклик інструмента realtime консультується з налаштованою
|
||||
`Asking OpenClaw...`, поки виклик realtime-інструмента консультується з налаштованою
|
||||
більшою моделлю через `chat.send`.
|
||||
- Зупинка:
|
||||
- Натисніть **Stop** (викликає `chat.abort`)
|
||||
- Поки запуск активний, звичайні наступні повідомлення стають у чергу. Натисніть **Steer** на повідомленні в черзі, щоб вставити це продовження в поточний хід.
|
||||
- Поки запуск активний, звичайні наступні повідомлення ставляться в чергу. Натисніть **Steer** на повідомленні в черзі, щоб вбудувати це наступне повідомлення в поточний хід.
|
||||
- Введіть `/stop` (або окремі фрази переривання, як-от `stop`, `stop action`, `stop run`, `stop openclaw`, `please stop`), щоб перервати поза смугою
|
||||
- `chat.abort` підтримує `{ sessionKey }` (без `runId`) для переривання всіх активних запусків для цієї сесії
|
||||
- Часткове збереження після переривання:
|
||||
- Коли запуск перервано, частковий текст помічника все ще може показуватися в UI
|
||||
- Gateway зберігає частковий текст помічника після переривання в історії transcript, коли є буферизований вивід
|
||||
- Збережені записи включають метадані переривання, щоб споживачі transcript могли відрізняти часткові записи після переривання від звичайного завершеного виводу
|
||||
- `chat.abort` підтримує `{ sessionKey }` (без `runId`) для переривання всіх активних запусків цієї сесії
|
||||
- Часткове збереження при перериванні:
|
||||
- Коли запуск перервано, частковий текст асистента все ще може відображатися в UI
|
||||
- Gateway зберігає частковий текст асистента, перерваний під час виконання, в історії транскрипту, коли існує буферизований вивід
|
||||
- Збережені записи містять метадані переривання, щоб споживачі транскрипту могли відрізнити часткові перервані фрагменти від звичайно завершеного виводу
|
||||
|
||||
## Вбудовані hosted-елементи
|
||||
|
||||
Повідомлення помічника можуть відображати вбудований hosted web content через shortcode `[embed ...]`.
|
||||
Політика sandbox для iframe керується через
|
||||
Повідомлення асистента можуть відображати вбудований hosted вебвміст за допомогою шорткоду `[embed ...]`.
|
||||
Політика пісочниці iframe керується параметром
|
||||
`gateway.controlUi.embedSandbox`:
|
||||
|
||||
- `strict`: вимикає виконання скриптів усередині вбудованих hosted-елементів
|
||||
- `scripts`: дозволяє інтерактивні вбудовані елементи, зберігаючи ізоляцію походження; це
|
||||
значення за замовчуванням, і його зазвичай достатньо для самодостатніх браузерних ігор/віджетів
|
||||
- `trusted`: додає `allow-same-origin` поверх `allow-scripts` для документів того самого сайту,
|
||||
яким навмисно потрібні ширші привілеї
|
||||
- `strict`: вимикає виконання скриптів усередині hosted-вбудовувань
|
||||
- `scripts`: дозволяє інтерактивні вбудовування, зберігаючи ізоляцію origin; це
|
||||
значення за замовчуванням і зазвичай його достатньо для самодостатніх браузерних ігор/віджетів
|
||||
- `trusted`: додає `allow-same-origin` поверх `allow-scripts` для same-site
|
||||
документів, яким навмисно потрібні ширші привілеї
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -216,19 +215,19 @@ Control UI може локалізуватися під час першого з
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте `trusted` лише тоді, коли вбудованому документу справді потрібна
|
||||
поведінка same-origin. Для більшості згенерованих агентом ігор та інтерактивних canvas
|
||||
безпечнішим вибором є `scripts`.
|
||||
Використовуйте `trusted` лише тоді, коли вбудований документ справді потребує
|
||||
поведінки same-origin. Для більшості згенерованих агентом ігор та інтерактивних полотен `scripts` —
|
||||
безпечніший вибір.
|
||||
|
||||
Абсолютні зовнішні URL вбудованих елементів `http(s)` за замовчуванням залишаються заблокованими. Якщо ви
|
||||
навмисно хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, задайте
|
||||
Абсолютні зовнішні URL-адреси вбудовувань `http(s)` залишаються заблокованими за замовчуванням. Якщо ви
|
||||
навмисно хочете, щоб `[embed url="https://..."]` завантажував сторонні сторінки, встановіть
|
||||
`gateway.controlUi.allowExternalEmbedUrls: true`.
|
||||
|
||||
## Доступ Tailnet (рекомендовано)
|
||||
|
||||
### Інтегрований Tailscale Serve (бажано)
|
||||
|
||||
Залиште Gateway на local loopback і дозвольте Tailscale Serve проксувати його через HTTPS:
|
||||
Тримайте Gateway на loopback і дозвольте Tailscale Serve проксувати його через HTTPS:
|
||||
|
||||
```bash
|
||||
openclaw gateway --tailscale serve
|
||||
@ -238,20 +237,20 @@ openclaw gateway --tailscale serve
|
||||
|
||||
- `https://<magicdns>/` (або ваш налаштований `gateway.controlUi.basePath`)
|
||||
|
||||
За замовчуванням запити Serve до Control UI/WebSocket можуть проходити auth через заголовки ідентичності Tailscale
|
||||
За замовчуванням запити Serve для Control UI/WebSocket можуть автентифікуватися через заголовки ідентичності Tailscale
|
||||
(`tailscale-user-login`), коли `gateway.auth.allowTailscale` має значення `true`. OpenClaw
|
||||
перевіряє ідентичність, визначаючи адресу `x-forwarded-for` через
|
||||
`tailscale whois` і звіряючи її із заголовком, і приймає це лише тоді, коли
|
||||
запит потрапляє на local loopback із заголовками Tailscale `x-forwarded-*`. Задайте
|
||||
перевіряє ідентичність, розв’язуючи адресу `x-forwarded-for` за допомогою
|
||||
`tailscale whois` і звіряючи її із заголовком, і приймає їх лише тоді, коли
|
||||
запит потрапляє на loopback із заголовками Tailscale `x-forwarded-*`. Установіть
|
||||
`gateway.auth.allowTailscale: false`, якщо хочете вимагати явні облікові дані зі спільним секретом
|
||||
навіть для трафіку Serve. Тоді використовуйте `gateway.auth.mode: "token"` або
|
||||
`"password"`.
|
||||
Для цього асинхронного шляху ідентичності Serve невдалі спроби auth для тієї самої IP-адреси клієнта
|
||||
і того самого scope auth серіалізуються до записів rate-limit. Тому одночасні помилкові повторні спроби
|
||||
з того самого браузера можуть показувати `retry later` для другого запиту
|
||||
замість двох звичайних невідповідностей, які змагаються паралельно.
|
||||
Auth Serve без токена припускає, що host Gateway є довіреним. Якщо на цьому host може працювати
|
||||
недовірений локальний код, вимагайте auth через токен/пароль.
|
||||
Для цього асинхронного шляху ідентичності Serve невдалі спроби автентифікації для тієї самої IP-адреси клієнта
|
||||
та тієї самої області автентифікації серіалізуються перед записами обмеження частоти.
|
||||
Тому одночасні невдалі повторні спроби з того самого браузера можуть показувати `retry later` у другому запиті
|
||||
замість двох звичайних невідповідностей, що змагаються паралельно.
|
||||
Автентифікація Serve без токена припускає, що хост gateway є довіреним. Якщо на цьому хості
|
||||
може виконуватися недовірений локальний код, вимагайте автентифікацію токеном/паролем.
|
||||
|
||||
### Прив’язка до tailnet + токен
|
||||
|
||||
@ -266,22 +265,22 @@ openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
|
||||
Вставте відповідний спільний секрет у налаштування UI (він надсилається як
|
||||
`connect.params.auth.token` або `connect.params.auth.password`).
|
||||
|
||||
## Небезпечний HTTP
|
||||
## Незахищений HTTP
|
||||
|
||||
Якщо ви відкриваєте dashboard через звичайний HTTP (`http://<lan-ip>` або `http://<tailscale-ip>`),
|
||||
браузер працює в **незахищеному контексті** й блокує WebCrypto. За замовчуванням
|
||||
Якщо ви відкриваєте інформаційну панель через звичайний HTTP (`http://<lan-ip>` або `http://<tailscale-ip>`),
|
||||
браузер працює в **незахищеному контексті** та блокує WebCrypto. За замовчуванням
|
||||
OpenClaw **блокує** підключення Control UI без ідентичності пристрою.
|
||||
|
||||
Задокументовані винятки:
|
||||
|
||||
- сумісність незахищеного HTTP лише для localhost з `gateway.controlUi.allowInsecureAuth=true`
|
||||
- успішний auth оператора Control UI через `gateway.auth.mode: "trusted-proxy"`
|
||||
- аварійний режим `gateway.controlUi.dangerouslyDisableDeviceAuth=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/` (на host Gateway)
|
||||
- `http://127.0.0.1:18789/` (на хості gateway)
|
||||
|
||||
**Поведінка перемикача insecure-auth:**
|
||||
|
||||
@ -297,12 +296,12 @@ OpenClaw **блокує** підключення Control UI без іденти
|
||||
|
||||
`allowInsecureAuth` — це лише локальний перемикач сумісності:
|
||||
|
||||
- Він дозволяє сесіям localhost у Control UI продовжуватися без ідентичності пристрою в
|
||||
- Він дозволяє сесіям Control UI на localhost продовжувати роботу без ідентичності пристрою в
|
||||
незахищених HTTP-контекстах.
|
||||
- Він не обходить перевірки сполучення.
|
||||
- Він не послаблює вимоги до ідентичності віддалених пристроїв (не localhost).
|
||||
- Він не послаблює вимоги до ідентичності віддаленого (не localhost) пристрою.
|
||||
|
||||
**Лише для аварійного використання:**
|
||||
**Лише аварійний варіант:**
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -315,76 +314,77 @@ OpenClaw **блокує** підключення Control UI без іденти
|
||||
```
|
||||
|
||||
`dangerouslyDisableDeviceAuth` вимикає перевірки ідентичності пристрою в Control UI і є
|
||||
серйозним послабленням безпеки. Після аварійного використання швидко поверніть попередні налаштування.
|
||||
серйозним зниженням рівня безпеки. Швидко скасуйте це після аварійного використання.
|
||||
|
||||
Примітка щодо trusted-proxy:
|
||||
|
||||
- успішний trusted-proxy auth може допустити сесії **оператора** Control UI без
|
||||
- успішна автентифікація trusted-proxy може допускати **операторські** сесії Control UI без
|
||||
ідентичності пристрою
|
||||
- це **не** поширюється на сесії Control UI з роллю Node
|
||||
- reverse proxy на тому самому host для local loopback усе одно не задовольняють trusted-proxy auth; див.
|
||||
[Auth trusted proxy](/uk/gateway/trusted-proxy-auth)
|
||||
- це **не** поширюється на сесії Control UI з роллю node
|
||||
- reverse proxy на loopback того самого хоста все одно не задовольняють автентифікацію trusted-proxy; див.
|
||||
[Trusted proxy auth](/uk/gateway/trusted-proxy-auth)
|
||||
|
||||
Див. [Tailscale](/uk/gateway/tailscale) для інструкцій із налаштування HTTPS.
|
||||
Див. [Tailscale](/uk/gateway/tailscale) для вказівок щодо налаштування HTTPS.
|
||||
|
||||
## Content Security Policy
|
||||
## Політика безпеки вмісту
|
||||
|
||||
Control UI постачається із жорсткою політикою `img-src`: дозволені лише ресурси **того самого походження** і URL `data:`. Віддалені URL `http(s)` і URL з відносним до протоколу записом браузер відхиляє і не виконує мережевих запитів.
|
||||
Control UI постачається з жорсткою політикою `img-src`: дозволені лише ресурси **same-origin**, URL `data:` і локально згенеровані URL `blob:`. Віддалені URL `http(s)` та відносні до протоколу URL зображень відхиляються браузером і не ініціюють мережевих запитів.
|
||||
|
||||
Що це означає на практиці:
|
||||
|
||||
- Аватари й зображення, які віддаються за відносними шляхами (наприклад `/avatars/<id>`), і далі відображаються.
|
||||
- Вбудовані URL `data:image/...` і далі відображаються (це корисно для payload у межах протоколу).
|
||||
- Віддалені URL аватарів, які надає метадані каналу, прибираються helper-ами аватарів у Control UI і замінюються вбудованим логотипом/значком, тому скомпрометований або зловмисний канал не може змусити браузер оператора виконувати довільні віддалені запити зображень.
|
||||
- Аватари та зображення, які обслуговуються за відносними шляхами (наприклад, `/avatars/<id>`), як і раніше відображаються, зокрема автентифіковані маршрути аватарів, які UI отримує та перетворює на локальні URL `blob:`.
|
||||
- Вбудовані URL `data:image/...` як і раніше відображаються (це корисно для корисних навантажень усередині протоколу).
|
||||
- Локальні URL `blob:`, створені Control UI, як і раніше відображаються.
|
||||
- Віддалені URL аватарів, які надходять із метаданих каналів, видаляються в допоміжних функціях аватарів Control UI і замінюються вбудованим логотипом/значком, тож скомпрометований або зловмисний канал не може змусити браузер оператора виконувати довільні віддалені запити зображень.
|
||||
|
||||
Щоб отримати цю поведінку, нічого змінювати не потрібно — вона завжди ввімкнена й не налаштовується.
|
||||
Щоб отримати таку поведінку, нічого змінювати не потрібно — вона завжди ввімкнена й не налаштовується.
|
||||
|
||||
## Auth для маршруту аватарів
|
||||
## Автентифікація маршруту аватара
|
||||
|
||||
Коли налаштовано auth Gateway, endpoint аватарів у Control UI вимагає той самий токен Gateway, що й решта API:
|
||||
Коли налаштовано автентифікацію gateway, кінцева точка аватарів Control UI вимагає той самий токен gateway, що й решта API:
|
||||
|
||||
- `GET /avatar/<agentId>` повертає зображення аватара лише автентифікованим викликачам. `GET /avatar/<agentId>?meta=1` повертає метадані аватара за тим самим правилом.
|
||||
- Неавтентифіковані запити до обох маршрутів відхиляються (аналогічно сусідньому маршруту media помічника). Це запобігає витоку ідентичності агента через маршрут аватарів на host, які в іншому разі захищені.
|
||||
- Сам Control UI передає токен Gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані blob URL, тому зображення все одно відображається в dashboard.
|
||||
- Неавтентифіковані запити до будь-якого з цих маршрутів відхиляються (аналогічно до сусіднього маршруту assistant-media). Це запобігає витоку ідентичності агента через маршрут аватара на хостах, які в іншому захищені.
|
||||
- Сам Control UI пересилає токен gateway як bearer-заголовок під час отримання аватарів і використовує автентифіковані URL `blob:`, тож зображення все одно відображається в інформаційних панелях.
|
||||
|
||||
Якщо ви вимкнете auth Gateway (не рекомендується на спільних host), маршрут аватарів також стане неавтентифікованим, як і решта gateway.
|
||||
Якщо ви вимкнете автентифікацію gateway (не рекомендовано на спільних хостах), маршрут аватара також стане неавтентифікованим, узгоджено з рештою gateway.
|
||||
|
||||
## Збирання UI
|
||||
|
||||
Gateway віддає статичні файли з `dist/control-ui`. Збирайте їх командою:
|
||||
Gateway обслуговує статичні файли з `dist/control-ui`. Зберіть їх за допомогою:
|
||||
|
||||
```bash
|
||||
pnpm ui:build
|
||||
```
|
||||
|
||||
Необов’язкова абсолютна база (коли вам потрібні фіксовані URL ресурсів):
|
||||
Необов’язкова абсолютна база (коли вам потрібні фіксовані 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
|
||||
|
||||
Control UI — це статичні файли; ціль WebSocket налаштовується і може
|
||||
відрізнятися від HTTP-походження. Це зручно, коли ви хочете локальний Vite dev server,
|
||||
але Gateway працює в іншому місці.
|
||||
відрізнятися від HTTP origin. Це зручно, коли ви хочете використовувати dev-сервер Vite
|
||||
локально, але Gateway працює в іншому місці.
|
||||
|
||||
1. Запустіть dev server UI: `pnpm ui:dev`
|
||||
1. Запустіть dev-сервер UI: `pnpm ui:dev`
|
||||
2. Відкрийте URL на кшталт:
|
||||
|
||||
```text
|
||||
http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789
|
||||
```
|
||||
|
||||
Необов’язковий одноразовий auth (за потреби):
|
||||
Необов’язкова одноразова автентифікація (за потреби):
|
||||
|
||||
```text
|
||||
http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-token>
|
||||
@ -392,20 +392,20 @@ http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-toke
|
||||
|
||||
Примітки:
|
||||
|
||||
- `gatewayUrl` після завантаження зберігається в localStorage і прибирається з URL.
|
||||
- `token` слід передавати через fragment URL (`#token=...`) щоразу, коли це можливо. Fragments не надсилаються на сервер, що запобігає витоку в журналах запитів і через Referer. Застарілі параметри запиту `?token=` і далі одноразово імпортуються для сумісності, але лише як fallback і негайно прибираються після bootstrap.
|
||||
- `gatewayUrl` зберігається в localStorage після завантаження й видаляється з URL.
|
||||
- `token` слід передавати через фрагмент URL (`#token=...`) щоразу, коли це можливо. Фрагменти не надсилаються на сервер, що запобігає витоку через журнали запитів і Referer. Застарілі параметри запиту `?token=` усе ще одноразово імпортуються для сумісності, але лише як запасний варіант, і видаляються відразу після bootstrap.
|
||||
- `password` зберігається лише в пам’яті.
|
||||
- Коли задано `gatewayUrl`, UI не повертається до облікових даних із config або середовища.
|
||||
- Коли встановлено `gatewayUrl`, UI не повертається до облікових даних із конфігурації або середовища.
|
||||
Явно надайте `token` (або `password`). Відсутність явних облікових даних є помилкою.
|
||||
- Використовуйте `wss://`, коли Gateway знаходиться за TLS (Tailscale Serve, HTTPS proxy тощо).
|
||||
- `gatewayUrl` приймається лише у вікні верхнього рівня (не у вбудованому), щоб запобігти clickjacking.
|
||||
- Розгортання Control UI поза loopback мають явно задавати `gateway.controlUi.allowedOrigins`
|
||||
(повні origins). Це також стосується віддалених dev-конфігурацій.
|
||||
- Не використовуйте `gateway.controlUi.allowedOrigins: ["*"]`, окрім жорстко контрольованого
|
||||
локального тестування. Це означає дозволити будь-яке browser origin, а не «збігатися з будь-яким host, який я
|
||||
- Використовуйте `wss://`, коли Gateway працює за TLS (Tailscale Serve, HTTPS-проксі тощо).
|
||||
- `gatewayUrl` приймається лише у вікні верхнього рівня (не у вбудованому режимі), щоб запобігти clickjacking.
|
||||
- Розгортання Control UI поза loopback повинні явно встановлювати `gateway.controlUi.allowedOrigins`
|
||||
(повні origin). Це також стосується віддалених dev-конфігурацій.
|
||||
- Не використовуйте `gateway.controlUi.allowedOrigins: ["*"]`, окрім як для жорстко контрольованого
|
||||
локального тестування. Це означає дозвіл для будь-якого browser origin, а не «підібрати будь-який хост, який я
|
||||
використовую».
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` вмикає
|
||||
fallback-режим origin за заголовком Host, але це небезпечний режим безпеки.
|
||||
режим резервного origin через заголовок Host, але це небезпечний режим безпеки.
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -419,11 +419,11 @@ http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-toke
|
||||
}
|
||||
```
|
||||
|
||||
Деталі налаштування віддаленого доступу: [Віддалений доступ](/uk/gateway/remote).
|
||||
Докладніше про налаштування віддаленого доступу: [Remote access](/uk/gateway/remote).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Dashboard](/uk/web/dashboard) — dashboard Gateway
|
||||
- [WebChat](/uk/web/webchat) — інтерфейс чату в браузері
|
||||
- [TUI](/uk/web/tui) — термінальний користувацький інтерфейс
|
||||
- [Health Checks](/uk/gateway/health) — моніторинг стану Gateway
|
||||
- [Dashboard](/uk/web/dashboard) — інформаційна панель gateway
|
||||
- [WebChat](/uk/web/webchat) — чат-інтерфейс у браузері
|
||||
- [TUI](/uk/web/tui) — термінальний інтерфейс користувача
|
||||
- [Health Checks](/uk/gateway/health) — моніторинг стану gateway
|
||||
|
||||
Loading…
Reference in New Issue
Block a user