diff --git a/docs/uk/concepts/models.md b/docs/uk/concepts/models.md index 1222ca16e..4ea84a7fd 100644 --- a/docs/uk/concepts/models.md +++ b/docs/uk/concepts/models.md @@ -1,50 +1,50 @@ --- read_when: - Додавання або зміна CLI моделей (models list/set/scan/aliases/fallbacks) - - Зміна поведінки fallback моделей або UX вибору + - Зміна поведінки резервного перемикання моделей або UX вибору - Оновлення перевірок сканування моделей (tools/images) -summary: 'CLI моделей: список, встановлення, псевдоніми, fallback, сканування, статус' +summary: 'CLI моделей: список, налаштування, псевдоніми, резервні варіанти, сканування, статус' title: CLI моделей x-i18n: - generated_at: "2026-04-05T18:01:52Z" + generated_at: "2026-04-05T21:59:07Z" model: gpt-5.4 provider: openai - source_hash: b6a24f7621b0dd573571164b6690731eb318f7f78972dd310b9b6a9a3888489e + source_hash: 09507720942af72bf7027c733879935d53c79c72b607d737a131eaa02b9b2576 source_path: concepts/models.md workflow: 15 --- # CLI моделей -Див. [/concepts/model-failover](/concepts/model-failover) щодо ротації профілів -автентифікації, cooldown і того, як це взаємодіє з fallback. -Короткий огляд провайдерів + приклади: [/concepts/model-providers](/concepts/model-providers). +Див. [/concepts/model-failover](/uk/concepts/model-failover) щодо ротації +профілів автентифікації, періодів охолодження та того, як це взаємодіє з резервними варіантами. +Короткий огляд провайдерів + приклади: [/concepts/model-providers](/uk/concepts/model-providers). ## Як працює вибір моделі OpenClaw вибирає моделі в такому порядку: 1. **Основна** модель (`agents.defaults.model.primary` або `agents.defaults.model`). -2. **Fallback** у `agents.defaults.model.fallbacks` (у порядку списку). -3. **Failover автентифікації провайдера** відбувається всередині провайдера перед переходом до - наступної моделі. +2. **Резервні варіанти** в `agents.defaults.model.fallbacks` (по порядку). +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-ключ цього провайдера. -- `agents.defaults.videoGenerationModel` використовується спільною поверхнею можливостей генерації відео. Якщо його не вказано, `video_generate` усе одно може визначити типовий провайдер із автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку provider-id. Якщо ви задаєте конкретного провайдера/модель, також налаштуйте автентифікацію/API-ключ цього провайдера. -- Типові значення для окремого агента можуть перевизначати `agents.defaults.model` через `agents.list[].model` плюс bindings (див. [/concepts/multi-agent](/concepts/multi-agent)). + переходить на `agents.defaults.imageModel`, а потім на визначену для сесії/типову + модель. +- `agents.defaults.imageGenerationModel` використовується спільною можливістю генерації зображень. Якщо не вказано, `image_generate` усе одно може визначити типовий провайдер з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів. Якщо ви задаєте конкретний провайдер/модель, також налаштуйте автентифікацію/API-ключ цього провайдера. +- `agents.defaults.videoGenerationModel` використовується спільною можливістю генерації відео. Якщо не вказано, `video_generate` усе одно може визначити типовий провайдер з автентифікацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів. Якщо ви задаєте конкретний провайдер/модель, також налаштуйте автентифікацію/API-ключ цього провайдера. +- Типові значення для окремих агентів можуть перевизначати `agents.defaults.model` через `agents.list[].model` разом із прив’язками (див. [/concepts/multi-agent](/uk/concepts/multi-agent)). -## Швидка політика щодо моделей +## Коротка політика щодо моделей -- Установіть основною найсильнішу модель останнього покоління, доступну вам. -- Використовуйте fallback для завдань, чутливих до вартості/затримки, і для менш критичних чатів. -- Для агентів із увімкненими tools або недовірених вхідних даних уникайте старіших/слабших рівнів моделей. +- Встановіть основною найсильнішу доступну вам модель останнього покоління. +- Використовуйте резервні варіанти для завдань, чутливих до вартості/затримки, та для менш критичних чатів. +- Для агентів з увімкненими інструментами або для недовірених вхідних даних уникайте старіших/слабших рівнів моделей. ## Онбординг (рекомендовано) @@ -64,19 +64,19 @@ subscription** (OAuth) і **Anthropic** (API-ключ або Claude CLI). - `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 + псевдоніми + параметри провайдера) +- `agents.defaults.models` (список дозволених + псевдоніми + параметри провайдера) - `models.providers` (власні провайдери, записані в `models.json`) -Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми провайдерів на кшталт `z.ai/*` нормалізуються +Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми провайдерів, як-от `z.ai/*`, нормалізуються до `zai/*`. Приклади конфігурації провайдерів (зокрема OpenCode) наведено в -[/providers/opencode](/providers/opencode). +[/providers/opencode](/uk/providers/opencode). -## «Model is not allowed» (і чому відповіді зупиняються) +## «Модель не дозволена» (і чому відповіді зупиняються) -Якщо встановлено `agents.defaults.models`, воно стає **allowlist** для `/model` і для -перевизначень сесії. Коли користувач вибирає модель, якої немає в цьому allowlist, +Якщо задано `agents.defaults.models`, він стає **списком дозволених** для `/model` і для +перевизначень у сесії. Коли користувач вибирає модель, якої немає в цьому списку, OpenClaw повертає: ``` @@ -84,13 +84,13 @@ Model "provider/model" is not allowed. Use /model to list available models. ``` Це відбувається **до** генерації звичайної відповіді, тому може здаватися, -що на повідомлення «не відповіли». Виправлення полягає в тому, щоб: +ніби повідомлення «не отримало відповіді». Вирішити це можна так: - Додати модель до `agents.defaults.models`, або -- Очистити allowlist (видалити `agents.defaults.models`), або +- Очистити список дозволених (видалити `agents.defaults.models`), або - Вибрати модель із `/model list`. -Приклад конфігурації allowlist: +Приклад конфігурації списку дозволених: ```json5 { @@ -106,7 +106,7 @@ Model "provider/model" is not allowed. Use /model to list available models. ## Перемикання моделей у чаті (`/model`) -Ви можете перемикати моделі для поточної сесії без перезапуску: +Ви можете переключати моделі для поточної сесії без перезапуску: ``` /model @@ -119,24 +119,24 @@ Model "provider/model" is not allowed. Use /model to list available models. Примітки: - `/model` (і `/model list`) — це компактний нумерований засіб вибору (сімейство моделей + доступні провайдери). -- У Discord `/model` і `/models` відкривають інтерактивний засіб вибору з випадними списками провайдера й моделі та кроком Submit. -- `/model <#>` вибирає зі списку цього засобу вибору. -- `/model` негайно зберігає новий вибір сесії. +- У Discord `/model` і `/models` відкривають інтерактивний засіб вибору з випадними списками провайдера та моделі, а також кроком Submit. +- `/model <#>` вибирає елемент із цього засобу вибору. +- `/model` негайно зберігає новий вибір для сесії. - Якщо агент неактивний, наступний запуск одразу використовуватиме нову модель. -- Якщо запуск уже активний, OpenClaw позначає живе перемикання як відкладене й перезапускає з новою моделлю лише в чистій точці повторної спроби. -- Якщо активність tools або виведення відповіді вже розпочалися, відкладене перемикання може залишатися в черзі до наступної можливості повторної спроби або до наступного ходу користувача. -- `/model status` — це докладний режим перегляду (кандидати автентифікації і, коли налаштовано, `baseUrl` кінцевої точки провайдера + режим `api`). -- Посилання на моделі розбираються за розділенням на **першому** `/`. Використовуйте `provider/model`, коли вводите `/model `. -- Якщо сам ID моделі містить `/` (стиль OpenRouter), ви маєте включити префікс провайдера (приклад: `/model openrouter/moonshotai/kimi-k2`). -- Якщо ви пропускаєте провайдера, OpenClaw визначає введення в такому порядку: +- Якщо запуск уже активний, OpenClaw позначає перемикання в реальному часі як відкладене й перезапускає нову модель лише в чистій точці повторної спроби. +- Якщо активність інструмента або виведення відповіді вже почалися, відкладене перемикання може залишатися в черзі до пізнішої можливості повторної спроби або до наступного ходу користувача. +- `/model status` — це докладне подання (кандидати автентифікації та, якщо налаштовано, `baseUrl` кінцевої точки провайдера + режим `api`). +- Посилання на моделі розбираються поділом за **першим** `/`. Під час введення `/model ` використовуйте формат `provider/model`. +- Якщо сам ідентифікатор моделі містить `/` (у стилі OpenRouter), ви повинні вказати префікс провайдера (приклад: `/model openrouter/moonshotai/kimi-k2`). +- Якщо ви не вказуєте провайдера, OpenClaw визначає введення в такому порядку: 1. збіг псевдоніма - 2. унікальний збіг налаштованого провайдера для цього точного ID моделі без префікса - 3. застарілий fallback до налаштованого типового провайдера + 2. унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі без префікса + 3. застарілий резервний перехід до налаштованого типового провайдера Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw - замість цього переходить до першої налаштованої пари провайдер/модель, щоб - не показувати застаріле типове значення видаленого провайдера. + натомість переходить до першого налаштованого провайдера/моделі, щоб уникнути + показу застарілого типового значення від видаленого провайдера. -Повна поведінка команди/конфігурації: [Slash commands](/tools/slash-commands). +Повна поведінка команди/конфігурація: [Slash commands](/uk/tools/slash-commands). ## Команди CLI @@ -175,22 +175,25 @@ openclaw models image-fallbacks clear ### `models status` -Показує визначену основну модель, fallback, модель для зображень і огляд автентифікації -налаштованих провайдерів. Також показує стан завершення строку дії OAuth для профілів, знайдених -у сховищі автентифікації (типово попереджає за 24 год). `--plain` виводить лише +Показує визначену основну модель, резервні варіанти, модель зображень та огляд автентифікації +налаштованих провайдерів. Також показує статус завершення дії OAuth для профілів, знайдених +у сховищі автентифікації (типово попереджає протягом 24 годин). `--plain` виводить лише визначену основну модель. -Стан OAuth показується завжди (і включається у вивід `--json`). Якщо налаштований -провайдер не має облікових даних, `models status` виводить розділ **Missing auth**. -JSON включає `auth.oauth` (вікно попередження + профілі) і `auth.providers` -(ефективна автентифікація для кожного провайдера). -Використовуйте `--check` для автоматизації (код виходу `1` для відсутньої/простроченої автентифікації, `2` для такої, що скоро спливає). -Використовуйте `--probe` для живих перевірок автентифікації; рядки перевірки можуть надходити з профілів автентифікації, облікових даних середовища +Статус OAuth показується завжди (і включається у вивід `--json`). Якщо налаштований +провайдер не має облікових даних, `models status` виводить розділ **Відсутня автентифікація**. +JSON містить `auth.oauth` (вікно попередження + профілі) і `auth.providers` +(ефективна автентифікація для кожного провайдера, зокрема облікові дані з env). `auth.oauth` +містить лише стан профілів зі сховища автентифікації; провайдери лише з env там не відображаються. +Використовуйте `--check` для автоматизації (код виходу `1`, якщо відсутні/прострочені, `2`, якщо скоро завершуються). +Використовуйте `--probe` для живих перевірок автентифікації; рядки перевірки можуть походити з профілів автентифікації, облікових даних env або `models.json`. Якщо явний `auth.order.` пропускає збережений профіль, перевірка повідомляє -`excluded_by_auth_order` замість спроби використати його. Якщо автентифікація є, але для цього провайдера не вдається визначити модель для перевірки, перевірка повертає `status: no_model`. +`excluded_by_auth_order` замість спроби використати його. Якщо автентифікація є, але для цього провайдера не вдається визначити модель для перевірки, +перевірка повідомляє `status: no_model`. -Вибір автентифікації залежить від провайдера/облікового запису. Для постійно активних gateway-хостів -API-ключі зазвичай є найпередбачуванішими; також підтримуються повторне використання Claude CLI та наявні профілі OAuth/токенів Anthropic. +Вибір автентифікації залежить від провайдера/облікового запису. Для хостів шлюзу, що працюють постійно, API-ключі +зазвичай є найпередбачуванішими; також підтримуються повторне використання Claude CLI +та наявні профілі Anthropic OAuth/токенів. Приклад (Claude CLI): @@ -202,7 +205,7 @@ openclaw models status ## Сканування (безкоштовні моделі OpenRouter) `openclaw models scan` перевіряє **каталог безкоштовних моделей** OpenRouter і може -за бажанням перевіряти моделі на підтримку tools і зображень. +за бажанням перевіряти моделі на підтримку інструментів і зображень. Основні прапорці: @@ -210,9 +213,9 @@ openclaw models status - `--min-params `: мінімальний розмір параметрів (мільярди) - `--max-age-days `: пропускати старіші моделі - `--provider `: фільтр за префіксом провайдера -- `--max-candidates `: розмір списку fallback -- `--set-default`: встановити `agents.defaults.model.primary` на перший вибір -- `--set-image`: встановити `agents.defaults.imageModel.primary` на перший вибір для зображень +- `--max-candidates `: розмір списку резервних варіантів +- `--set-default`: встановити `agents.defaults.model.primary` на перший вибраний елемент +- `--set-image`: встановити `agents.defaults.imageModel.primary` на перший вибраний елемент для зображень Для перевірок потрібен API-ключ OpenRouter (із профілів автентифікації або `OPENROUTER_API_KEY`). Без ключа використовуйте `--no-probe`, щоб лише переглянути кандидатів. @@ -220,42 +223,42 @@ openclaw models status Результати сканування ранжуються за: 1. Підтримкою зображень -2. Затримкою tools +2. Затримкою інструментів 3. Розміром контексту 4. Кількістю параметрів Вхідні дані - Список OpenRouter `/models` (фільтр `:free`) -- Потрібен API-ключ OpenRouter із профілів автентифікації або `OPENROUTER_API_KEY` (див. [/environment](/help/environment)) +- Потрібен API-ключ OpenRouter із профілів автентифікації або `OPENROUTER_API_KEY` (див. [/environment](/uk/help/environment)) - Необов’язкові фільтри: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates` - Керування перевірками: `--timeout`, `--concurrency` -Під час запуску в TTY ви можете інтерактивно вибрати fallback. У неінтерактивному +Під час запуску в TTY ви можете інтерактивно вибрати резервні варіанти. У неінтерактивному режимі передайте `--yes`, щоб прийняти типові значення. ## Реєстр моделей (`models.json`) -Власні провайдери в `models.providers` записуються в `models.json` у каталозі -агента (типово `~/.openclaw/agents//agent/models.json`). Цей файл -типово об’єднується, якщо лише `models.mode` не встановлено в `replace`. +Власні провайдери в `models.providers` записуються в `models.json` у +каталозі агента (типово `~/.openclaw/agents//agent/models.json`). Цей файл +типово об’єднується, якщо тільки `models.mode` не встановлено в `replace`. -Пріоритет у режимі злиття для однакових 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 записує маркери з активного знімка конфігурації джерела (до розв’язання), а не з розв’язаних значень секретів runtime. -Це застосовується щоразу, коли OpenClaw перегенеровує `models.json`, зокрема під час командних шляхів, таких як `openclaw agent`. +Збереження маркерів є авторитетним щодо джерела: OpenClaw записує маркери з активного знімка конфігурації джерела (до визначення), а не з визначених значень секретів під час виконання. +Це застосовується щоразу, коли OpenClaw повторно генерує `models.json`, зокрема в шляхах, ініційованих командами, як-от `openclaw agent`. ## Пов’язане -- [Провайдери моделей](/concepts/model-providers) — маршрутизація провайдерів і автентифікація -- [Failover моделей](/concepts/model-failover) — ланцюжки fallback -- [Генерація зображень](/tools/image-generation) — конфігурація моделей зображень -- [Генерація відео](/tools/video-generation) — конфігурація моделей відео -- [Довідник з конфігурації](/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделей +- [Провайдери моделей](/uk/concepts/model-providers) — маршрутизація провайдерів і автентифікація +- [Резервне перемикання моделей](/uk/concepts/model-failover) — ланцюжки резервних варіантів +- [Генерація зображень](/uk/tools/image-generation) — конфігурація моделей зображень +- [Генерація відео](/uk/tools/video-generation) — конфігурація моделей відео +- [Довідник з конфігурації](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделей diff --git a/docs/uk/gateway/protocol.md b/docs/uk/gateway/protocol.md index 3e4f06ee0..7ca8459c0 100644 --- a/docs/uk/gateway/protocol.md +++ b/docs/uk/gateway/protocol.md @@ -1,34 +1,34 @@ --- read_when: - - Реалізація або оновлення клієнтів gateway WS + - Реалізація або оновлення WS-клієнтів gateway - Налагодження невідповідностей протоколу або збоїв підключення - Повторна генерація схеми/моделей протоколу -summary: 'Протокол Gateway WebSocket: handshake, frame, версіонування' +summary: 'Протокол Gateway WebSocket: рукостискання, фрейми, версіонування' title: Протокол Gateway x-i18n: - generated_at: "2026-04-05T18:05:12Z" + generated_at: "2026-04-05T21:59:53Z" model: gpt-5.4 provider: openai - source_hash: c37f5b686562dda3ba3516ac6982ad87b2f01d8148233284e9917099c6e96d87 + source_hash: dcf6b4a88bb213e0704a767bf466329c8b33656919e933668f5f6ef06864ea55 source_path: gateway/protocol.md workflow: 15 --- # Протокол Gateway (WebSocket) -Протокол Gateway WS — це **єдина керуюча площина + транспорт node** для -OpenClaw. Усі клієнти (CLI, web UI, застосунок macOS, iOS/Android node, headless -node) підключаються через WebSocket і оголошують свої **role** + **scope** під час -handshake. +Протокол Gateway WS — це **єдина контрольна площина + транспорт вузлів** для +OpenClaw. Усі клієнти (CLI, web UI, macOS app, iOS/Android вузли, headless +вузли) підключаються через WebSocket і оголошують свою **роль** + **область** +під час рукостискання. ## Транспорт -- WebSocket, текстові frame з JSON payload. -- Перший frame **обов’язково** має бути request `connect`. +- WebSocket, текстові фрейми з JSON-навантаженнями. +- Перший фрейм **має** бути запитом `connect`. -## Handshake (connect) +## Рукостискання (connect) -Gateway → Client (виклик до підключення): +Gateway → Client (виклик перед підключенням): ```json { @@ -84,7 +84,7 @@ Gateway → Client: } ``` -Коли видається токен пристрою, `hello-ok` також містить: +Коли видається токен пристрою, `hello-ok` також включає: ```json { @@ -96,8 +96,8 @@ Gateway → Client: } ``` -Під час вбудованого передавання довіреного bootstrap `hello-ok.auth` також може містити додаткові -обмежені записи role у `deviceTokens`: +Під час довіреної передачі bootstrap `hello-ok.auth` також може включати +додаткові записи ролей з обмеженнями в `deviceTokens`: ```json { @@ -116,14 +116,15 @@ Gateway → Client: } ``` -Для вбудованого потоку bootstrap node/operator основний токен node зберігає -`scopes: []`, а будь-який переданий токен operator залишається обмеженим -bootstrap allowlist для operator (`operator.approvals`, `operator.read`, -`operator.talk.secrets`, `operator.write`). Перевірки bootstrap scope залишаються -role-prefixed: записи operator задовольняють лише запити operator, а ролі, що не є operator, -усе ще потребують scope під власним префіксом role. +Для вбудованого bootstrap-потоку node/operator первинний токен вузла +залишається `scopes: []`, а будь-який переданий токен оператора залишається +обмеженим allowlist bootstrap-оператора (`operator.approvals`, `operator.read`, +`operator.talk.secrets`, `operator.write`). Перевірки bootstrap-областей +залишаються прив'язаними до префікса ролі: записи operator задовольняють лише +запити operator, а ролям, що не є operator, усе одно потрібні області під їхнім +власним префіксом ролі. -### Приклад node +### Приклад вузла ```json { @@ -158,24 +159,24 @@ role-prefixed: записи operator задовольняють лише зап } ``` -## Формат frame +## Фреймування -- **Request**: `{type:"req", id, method, params}` -- **Response**: `{type:"res", id, ok, payload|error}` -- **Event**: `{type:"event", event, payload, seq?, stateVersion?}` +- **Запит**: `{type:"req", id, method, params}` +- **Відповідь**: `{type:"res", id, ok, payload|error}` +- **Подія**: `{type:"event", event, payload, seq?, stateVersion?}` -Methods із побічними ефектами потребують **ключів ідемпотентності** (див. schema). +Методи з побічними ефектами потребують **ключів ідемпотентності** (див. схему). -## Roles + scopes +## Ролі + області -### Roles +### Ролі -- `operator` = клієнт керуючої площини (CLI/UI/automation). +- `operator` = клієнт контрольної площини (CLI/UI/автоматизація). - `node` = хост можливостей (camera/screen/canvas/system.run). -### Scopes (operator) +### Області (operator) -Поширені scope: +Поширені області: - `operator.read` - `operator.write` @@ -187,398 +188,410 @@ Methods із побічними ефектами потребують **ключ Для `talk.config` з `includeSecrets: true` потрібен `operator.talk.secrets` (або `operator.admin`). -Gateway RPC methods, зареєстровані plugin, можуть запитувати власний scope operator, але -зарезервовані core admin-префікси (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) завжди зіставляються з `operator.admin`. +Зареєстровані плагінами gateway RPC-методи можуть вимагати власну область +operator, але зарезервовані префікси core admin (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) завжди зводяться до +`operator.admin`. -Scope method — лише перший бар’єр. Деякі slash-команди, доступні через -`chat.send`, поверх цього застосовують суворіші перевірки на рівні команд. Наприклад, постійні -записи `/config set` і `/config unset` потребують `operator.admin`. +Область методу — це лише перший бар'єр. Деякі slash-команди, що досягаються +через `chat.send`, додатково застосовують суворіші перевірки на рівні команд. +Наприклад, постійні записи `/config set` і `/config unset` потребують +`operator.admin`. -`node.pair.approve` також має додаткову перевірку scope під час схвалення поверх -базового scope method: +`node.pair.approve` також має додаткову перевірку області під час схвалення +поверх базової області методу: - запити без команд: `operator.pairing` -- запити з командами node, що не є exec: `operator.pairing` + `operator.write` -- запити, які включають `system.run`, `system.run.prepare` або `system.which`: +- запити з командами вузла, що не є exec: `operator.pairing` + `operator.write` +- запити, що включають `system.run`, `system.run.prepare` або `system.which`: `operator.pairing` + `operator.admin` ### Caps/commands/permissions (node) -Node оголошують claims можливостей під час connect: +Вузли оголошують твердження про можливості під час підключення: - `caps`: високорівневі категорії можливостей. - `commands`: allowlist команд для invoke. -- `permissions`: детальні перемикачі (наприклад `screen.record`, `camera.capture`). +- `permissions`: деталізовані перемикачі (наприклад, `screen.record`, `camera.capture`). -Gateway трактує їх як **claims** і примусово застосовує allowlist на боці сервера. +Gateway розглядає їх як **твердження** і застосовує серверні allowlist. -## Presence +## Присутність -- `system-presence` повертає записи, прив’язані до ідентичності пристрою. -- Записи presence містять `deviceId`, `roles` і `scopes`, щоб UI могли показувати один рядок на пристрій, +- `system-presence` повертає записи, згруповані за ідентичністю пристрою. +- Записи присутності включають `deviceId`, `roles` і `scopes`, щоб UI могли показувати один рядок на пристрій навіть коли він підключається і як **operator**, і як **node**. -## Поширені сімейства RPC method +## Поширені сімейства RPC-методів -Ця сторінка не є згенерованим повним дампом, але публічна поверхня WS є ширшою -за наведені вище приклади handshake/auth. Ось основні сімейства methods, які -Gateway надає сьогодні. +Ця сторінка не є згенерованим повним вивантаженням, але публічна WS-поверхня +ширша, ніж наведені вище приклади рукостискання/автентифікації. Це основні +сімейства методів, які Gateway надає сьогодні. -`hello-ok.features.methods` — це консервативний список discovery, побудований з -`src/gateway/server-methods-list.ts` плюс експортів method завантажених plugins/каналів. -Ставтеся до нього як до discovery можливостей, а не як до згенерованого дампу кожного callable helper, -реалізованого в `src/gateway/server-methods/*.ts`. +`hello-ok.features.methods` — це консервативний список виявлення, побудований з +`src/gateway/server-methods-list.ts` плюс експортів методів завантажених +плагінів/каналів. Сприймайте його як механізм виявлення можливостей, а не як +згенерований вивантаження кожного викликаного хелпера, реалізованого в +`src/gateway/server-methods/*.ts`. -### System та identity +### Система та ідентичність -- `health` повертає кешований або щойно перевірений snapshot стану gateway. -- `status` повертає зведення gateway у стилі `/status`; чутливі поля - включаються лише для клієнтів operator зі scope admin. -- `gateway.identity.get` повертає ідентичність пристрою gateway, яка використовується в relay і - потоках pairing. -- `system-presence` повертає поточний snapshot presence для підключених +- `health` повертає кешований або щойно перевірений знімок стану gateway. +- `status` повертає підсумок gateway у стилі `/status`; чутливі поля + включаються лише для operator-клієнтів з admin-областю. +- `gateway.identity.get` повертає ідентичність пристрою gateway, що + використовується в relay і pairing-потоках. +- `system-presence` повертає поточний знімок присутності для підключених пристроїв operator/node. -- `system-event` додає system event і може оновлювати/транслювати контекст - presence. -- `last-heartbeat` повертає останній збережений heartbeat event. -- `set-heartbeats` перемикає обробку heartbeat на gateway. +- `system-event` додає системну подію і може оновлювати/транслювати контекст + присутності. +- `last-heartbeat` повертає останню збережену подію heartbeat. +- `set-heartbeats` вмикає або вимикає обробку heartbeat у gateway. -### Models та usage +### Моделі та використання -- `models.list` повертає runtime allowlist каталогу моделей. -- `usage.status` повертає зведення usage вікон/залишку квоти провайдера. -- `usage.cost` повертає агреговані зведення вартості за діапазон дат. -- `doctor.memory.status` повертає готовність vector-memory / embedding для - активного workspace типового агента. -- `sessions.usage` повертає зведення usage по сесіях. -- `sessions.usage.timeseries` повертає timeseries usage для однієї сесії. -- `sessions.usage.logs` повертає записи журналу usage для однієї сесії. +- `models.list` повертає каталог моделей, дозволених у runtime. +- `usage.status` повертає зведення вікон використання провайдерів/залишкових квот. +- `usage.cost` повертає агреговані зведення витрат за діапазон дат. +- `doctor.memory.status` повертає стан готовності vector-memory / embedding для + активного робочого простору агента за замовчуванням. +- `sessions.usage` повертає зведення використання для кожної сесії. +- `sessions.usage.timeseries` повертає часовий ряд використання для однієї сесії. +- `sessions.usage.logs` повертає записи журналу використання для однієї сесії. -### Channels та helper для login +### Канали та хелпери входу -- `channels.status` повертає зведення стану вбудованих + bundled каналів/plugins. -- `channels.logout` виконує logout для конкретного каналу/облікового запису там, де канал - підтримує logout. -- `web.login.start` запускає потік login через QR/web для поточного провайдера web-каналу з підтримкою QR. -- `web.login.wait` очікує завершення цього потоку login через QR/web і запускає +- `channels.status` повертає зведення статусу вбудованих і bundled каналів/плагінів. +- `channels.logout` виходить із конкретного каналу/акаунта, якщо канал + підтримує вихід. +- `web.login.start` запускає потік QR/web входу для поточного web-провайдера + каналу, що підтримує QR. +- `web.login.wait` очікує завершення цього потоку QR/web входу і запускає канал у разі успіху. -- `push.test` надсилає тестовий APNs push на зареєстрований iOS node. +- `push.test` надсилає тестовий APNs push до зареєстрованого iOS-вузла. - `voicewake.get` повертає збережені тригери wake-word. -- `voicewake.set` оновлює тригери wake-word і транслює зміну. +- `voicewake.set` оновлює тригери wake-word і транслює зміни. -### Messaging та logs +### Повідомлення та журнали -- `send` — це RPC прямої вихідної доставки для надсилань із прив’язкою до - каналу/облікового запису/thread поза chat runner. -- `logs.tail` повертає tail налаштованого file-log gateway з cursor/limit і - контролем максимального розміру в байтах. +- `send` — це прямий RPC для вихідної доставки для + каналу/акаунта/потоку поза chat runner. +- `logs.tail` повертає tail налаштованого файлового журналу gateway з + керуванням cursor/limit і max-byte. -### Talk та TTS +### Talk і TTS -- `talk.config` повертає effective payload конфігурації Talk; для `includeSecrets` - потрібен `operator.talk.secrets` (або `operator.admin`). -- `talk.mode` задає/транслює поточний стан режиму Talk для клієнтів WebChat/Control UI. -- `talk.speak` синтезує мовлення через активний провайдер мовлення Talk. +- `talk.config` повертає ефективне навантаження конфігурації Talk; `includeSecrets` + потребує `operator.talk.secrets` (або `operator.admin`). +- `talk.mode` встановлює/транслює поточний стан режиму Talk для клієнтів + WebChat/Control UI. +- `talk.speak` синтезує мовлення через активний speech-провайдер Talk. - `tts.status` повертає стан увімкнення TTS, активного провайдера, резервних провайдерів і стан конфігурації провайдера. -- `tts.providers` повертає видимий inventory провайдерів TTS. +- `tts.providers` повертає видимий інвентар TTS-провайдерів. - `tts.enable` і `tts.disable` перемикають стан налаштувань TTS. -- `tts.setProvider` оновлює бажаного провайдера TTS. -- `tts.convert` виконує одноразове перетворення тексту в мовлення. +- `tts.setProvider` оновлює бажаного TTS-провайдера. +- `tts.convert` запускає одноразове перетворення text-to-speech. -### Secrets, config, update та wizard +### Secrets, config, update і wizard -- `secrets.reload` повторно визначає активні SecretRef і замінює runtime secret state - лише за умови повного успіху. -- `secrets.resolve` визначає призначення secret для команд для конкретного набору command/target. -- `config.get` повертає поточний snapshot конфігурації та hash. -- `config.set` записує валідований payload конфігурації. -- `config.patch` об’єднує часткове оновлення конфігурації. -- `config.apply` перевіряє + замінює весь payload конфігурації. -- `config.schema` повертає live payload schema конфігурації, який використовують Control UI і - інструменти CLI: schema, `uiHints`, версію та метадані генерації, включно з - метаданими schema plugins + каналів, коли runtime може їх завантажити. Schema - містить метадані полів `title` / `description`, отримані з тих самих label - і довідкового тексту, які використовує UI, включно з вкладеними об’єктами, - wildcard, елементами масиву та гілками композиції `anyOf` / `oneOf` / `allOf`, коли - існує відповідна документація полів. -- `config.schema.lookup` повертає payload lookup для одного шляху конфігурації: - нормалізований шлях, неглибокий вузол schema, зіставлені `hint` + `hintPath` і - зведення безпосередніх дочірніх елементів для drill-down у UI/CLI. - - Вузли lookup schema зберігають документацію для користувача й типові поля валідації: +- `secrets.reload` повторно розв'язує активні SecretRef і замінює runtime-стан + секретів лише за повного успіху. +- `secrets.resolve` розв'язує прив'язки секретів до команд-цілей для конкретного + набору command/target. +- `config.get` повертає поточний знімок config і hash. +- `config.set` записує перевірене навантаження config. +- `config.patch` об'єднує часткове оновлення config. +- `config.apply` перевіряє і замінює повне навантаження config. +- `config.schema` повертає live-навантаження схеми config, яке використовують Control UI і + CLI tooling: schema, `uiHints`, version і метадані генерації, включно з + метаданими схем плагінів + каналів, коли runtime може їх завантажити. Схема + включає метадані полів `title` / `description`, отримані з тих самих labels + і тексту довідки, які використовує UI, включно з вкладеними object, wildcard, + array-item і гілками композиції `anyOf` / `oneOf` / `allOf`, коли існує + відповідна документація поля. +- `config.schema.lookup` повертає навантаження lookup для одного шляху config: + нормалізований шлях, вузол поверхневої схеми, знайдений hint + `hintPath` та + підсумки безпосередніх дочірніх елементів для деталізації в UI/CLI. + - Вузли схеми lookup зберігають документацію для користувача та поширені поля валідації: `title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, - числові/рядкові/масивні/об’єктні межі та boolean-прапорці на кшталт + межі numeric/string/array/object і булеві прапорці на кшталт `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`. - - Зведення дочірніх елементів відкривають `key`, нормалізований `path`, `type`, `required`, - `hasChildren`, а також зіставлені `hint` / `hintPath`. -- `update.run` запускає потік оновлення gateway і планує перезапуск лише коли - саме оновлення завершилося успішно. -- `wizard.start`, `wizard.next`, `wizard.status` і `wizard.cancel` відкривають - onboarding wizard через WS RPC. + - Підсумки дочірніх елементів показують `key`, нормалізований `path`, `type`, `required`, + `hasChildren`, а також знайдені `hint` / `hintPath`. +- `update.run` запускає потік оновлення gateway і планує перезапуск лише тоді, + коли саме оновлення було успішним. +- `wizard.start`, `wizard.next`, `wizard.status` і `wizard.cancel` надають + wizard онбордингу через WS RPC. ### Наявні основні сімейства -#### Agent та helper workspace +#### Хелпери агента та робочого простору - `agents.list` повертає налаштовані записи агентів. - `agents.create`, `agents.update` і `agents.delete` керують записами агентів і - прив’язкою workspace. -- `agents.files.list`, `agents.files.get` і `agents.files.set` керують - bootstrap-файлами workspace, відкритими для агента. -- `agent.identity.get` повертає effective identity асистента для агента або + прив'язкою робочого простору. +- `agents.files.list`, `agents.files.get` і `agents.files.set` керують файлами + bootstrap-робочого простору, доступними для агента. +- `agent.identity.get` повертає ефективну ідентичність помічника для агента або сесії. -- `agent.wait` чекає завершення запуску й повертає фінальний snapshot, коли він - доступний. +- `agent.wait` очікує завершення запуску і повертає термінальний знімок, коли + він доступний. #### Керування сесіями - `sessions.list` повертає поточний індекс сесій. -- `sessions.subscribe` і `sessions.unsubscribe` вмикають/вимикають - підписки на події змін сесії для поточного WS-клієнта. -- `sessions.messages.subscribe` і `sessions.messages.unsubscribe` вмикають/вимикають +- `sessions.subscribe` і `sessions.unsubscribe` вмикають або вимикають + підписки на події змін сесій для поточного WS-клієнта. +- `sessions.messages.subscribe` і `sessions.messages.unsubscribe` вмикають або вимикають підписки на події transcript/message для однієї сесії. -- `sessions.preview` повертає обмежені прев’ю transcript для конкретних ключів сесій. -- `sessions.resolve` визначає або канонізує ціль сесії. +- `sessions.preview` повертає обмежені попередні перегляди transcript для вказаних + ключів сесій. +- `sessions.resolve` розв'язує або канонізує ціль сесії. - `sessions.create` створює новий запис сесії. - `sessions.send` надсилає повідомлення в наявну сесію. - `sessions.steer` — це варіант interrupt-and-steer для активної сесії. - `sessions.abort` перериває активну роботу для сесії. -- `sessions.patch` оновлює метадані/перевизначення сесії. +- `sessions.patch` оновлює метадані/override сесії. - `sessions.reset`, `sessions.delete` і `sessions.compact` виконують - обслуговування сесії. + обслуговування сесій. - `sessions.get` повертає повний збережений рядок сесії. -- виконання chat усе ще використовує `chat.history`, `chat.send`, `chat.abort` і +- виконання chat, як і раніше, використовує `chat.history`, `chat.send`, `chat.abort` і `chat.inject`. -- `chat.history` нормалізується для відображення клієнтам UI: inline directive tags - прибираються з видимого тексту, plain-text payload XML викликів інструментів (включно з +- `chat.history` нормалізований для відображення в UI-клієнтах: вбудовані теги директив + видаляються з видимого тексту, XML-навантаження plain-text викликів інструментів (включно з `...`, `...`, `...`, `...` і - обрізаними блоками викликів інструментів) та витоки ASCII/full-width керівних токенів моделі прибираються, - чисті рядки асистента з тихими токенами на кшталт точних `NO_REPLY` / - `no_reply` пропускаються, а надто великі рядки можуть замінюватися placeholder. + усіченими блоками викликів інструментів) та витоки ASCII/full-width токенів керування моделі + видаляються, чисті рядки помічника з silent-token, як-от точні `NO_REPLY` / + `no_reply`, пропускаються, а надто великі рядки можуть замінюватися заповнювачами. #### Pairing пристроїв і токени пристроїв -- `device.pair.list` повертає пристрої pairing, які очікують схвалення, і вже схвалені. +- `device.pair.list` повертає очікувані та схвалені пов'язані пристрої. - `device.pair.approve`, `device.pair.reject` і `device.pair.remove` керують записами pairing пристроїв. -- `device.token.rotate` обертає токен спареного пристрою в межах затверджених role - і scope. -- `device.token.revoke` відкликає токен спареного пристрою. +- `device.token.rotate` ротує токен пов'язаного пристрою в межах схвалених для нього ролей + і областей. +- `device.token.revoke` відкликає токен пов'язаного пристрою. -#### Pairing node, invoke і pending work +#### Pairing вузлів, invoke і відкладена робота - `node.pair.request`, `node.pair.list`, `node.pair.approve`, - `node.pair.reject` і `node.pair.verify` покривають pairing node та bootstrap - verification. -- `node.list` і `node.describe` повертають стан відомих/підключених node. -- `node.rename` оновлює label спареного node. -- `node.invoke` пересилає команду підключеному node. -- `node.invoke.result` повертає результат для запиту invoke. -- `node.event` переносить події походженням із node назад у gateway. -- `node.canvas.capability.refresh` оновлює токени canvas-capability з обмеженим scope. -- `node.pending.pull` і `node.pending.ack` — це API черги для підключених node. -- `node.pending.enqueue` і `node.pending.drain` керують durable pending work - для offline/disconnected node. + `node.pair.reject` і `node.pair.verify` охоплюють pairing вузлів і bootstrap- + перевірку. +- `node.list` і `node.describe` повертають стан відомих/підключених вузлів. +- `node.rename` оновлює мітку пов'язаного вузла. +- `node.invoke` пересилає команду до підключеного вузла. +- `node.invoke.result` повертає результат запиту invoke. +- `node.event` переносить події, що походять від вузла, назад у gateway. +- `node.canvas.capability.refresh` оновлює токени можливостей canvas з обмеженою областю. +- `node.pending.pull` і `node.pending.ack` — це API черги підключених вузлів. +- `node.pending.enqueue` і `node.pending.drain` керують надійною відкладеною роботою + для офлайн/відключених вузлів. -#### Сімейства approval +#### Сімейства схвалень -- `exec.approval.request` і `exec.approval.resolve` покривають одноразові - запити на approval exec. -- `exec.approval.waitDecision` очікує рішення по одному pending approval exec і повертає - фінальне рішення (або `null` у разі timeout). -- `exec.approvals.get` і `exec.approvals.set` керують snapshot політики approval exec gateway. -- `exec.approvals.node.get` і `exec.approvals.node.set` керують локальною політикою approval exec node - через relay-команди node. +- `exec.approval.request` і `exec.approval.resolve` охоплюють одноразові + запити на схвалення exec. +- `exec.approval.waitDecision` очікує на одне відкладене схвалення exec і повертає + фінальне рішення (або `null` за timeout). +- `exec.approvals.get` і `exec.approvals.set` керують знімками політик + схвалення exec у gateway. +- `exec.approvals.node.get` і `exec.approvals.node.set` керують локальною для вузла + політикою схвалення exec через relay-команди вузла. - `plugin.approval.request`, `plugin.approval.waitDecision` і - `plugin.approval.resolve` покривають потоки approval, визначені plugin. + `plugin.approval.resolve` охоплюють потоки схвалення, визначені плагінами. #### Інші основні сімейства - automation: - - `wake` планує негайну або на наступний heartbeat ін’єкцію тексту wake + - `wake` планує негайне або наступне через heartbeat вставлення тексту wake - `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` - skills/tools: `skills.*`, `tools.catalog`, `tools.effective` -### Поширені сімейства event +### Поширені сімейства подій -- `chat`: оновлення UI chat на кшталт `chat.inject` та інших подій chat лише для transcript. +- `chat`: оновлення UI chat, такі як `chat.inject`, та інші події chat лише для transcript. - `session.message` і `session.tool`: оновлення transcript/event-stream для - підписаної сесії. -- `sessions.changed`: змінився індекс або метадані сесій. -- `presence`: оновлення snapshot system presence. -- `tick`: періодичний keepalive / event живості. -- `health`: оновлення snapshot стану gateway. + сесії, на яку оформлено підписку. +- `sessions.changed`: індекс сесій або метадані змінено. +- `presence`: оновлення знімка системної присутності. +- `tick`: періодична подія keepalive / liveness. +- `health`: оновлення знімка стану gateway. - `heartbeat`: оновлення потоку подій heartbeat. - `cron`: подія зміни запуску/завдання cron. - `shutdown`: сповіщення про вимкнення gateway. -- `node.pair.requested` / `node.pair.resolved`: життєвий цикл pairing node. -- `node.invoke.request`: трансляція запиту invoke node. -- `device.pair.requested` / `device.pair.resolved`: життєвий цикл спарених пристроїв. -- `voicewake.changed`: змінилася конфігурація тригерів wake-word. +- `node.pair.requested` / `node.pair.resolved`: життєвий цикл pairing вузлів. +- `node.invoke.request`: трансляція запиту invoke вузла. +- `device.pair.requested` / `device.pair.resolved`: життєвий цикл пов'язаних пристроїв. +- `voicewake.changed`: змінено конфігурацію тригерів wake-word. - `exec.approval.requested` / `exec.approval.resolved`: життєвий цикл - approval exec. -- `plugin.approval.requested` / `plugin.approval.resolved`: життєвий цикл - approval plugin. + схвалення exec. +- `plugin.approval.requested` / `plugin.approval.resolved`: життєвий цикл схвалення плагіна. -### Helper methods для node +### Хелпер-методи вузлів -- Node можуть викликати `skills.bins`, щоб отримати поточний список виконуваних файлів skill - для автоматичних allow-перевірок. +- Вузли можуть викликати `skills.bins`, щоб отримати поточний список виконуваних файлів skill + для перевірок auto-allow. -### Helper methods для operator +### Хелпер-методи operator - Operator можуть викликати `tools.catalog` (`operator.read`), щоб отримати runtime-каталог інструментів для - агента. Відповідь включає згруповані інструменти й метадані походження: + агента. Відповідь включає згруповані інструменти та метадані походження: - `source`: `core` або `plugin` - - `pluginId`: власник plugin, коли `source="plugin"` - - `optional`: чи є інструмент plugin необов’язковим -- Operator можуть викликати `tools.effective` (`operator.read`), щоб отримати runtime-effective - inventory інструментів для сесії. - - `sessionKey` обов’язковий. + - `pluginId`: власник плагіна, коли `source="plugin"` + - `optional`: чи є інструмент плагіна optional +- Operator можуть викликати `tools.effective` (`operator.read`), щоб отримати runtime-ефективний + інвентар інструментів для сесії. + - `sessionKey` є обов'язковим. - Gateway виводить довірений runtime-контекст із сесії на боці сервера замість приймати - auth або контекст доставки, надані викликачем. - - Відповідь прив’язана до сесії та відображає те, що активна розмова може використовувати просто зараз, + auth або контекст доставки, наданий викликачем. + - Відповідь прив'язана до сесії й відображає те, що активна розмова може використовувати просто зараз, включно з core, plugin і channel tools. - Operator можуть викликати `skills.status` (`operator.read`), щоб отримати видимий - inventory skill для агента. - - `agentId` необов’язковий; не вказуйте його, щоб читати workspace типового агента. + інвентар skills для агента. + - `agentId` необов'язковий; пропустіть його, щоб читати робочий простір агента за замовчуванням. - Відповідь включає eligibility, відсутні вимоги, перевірки config і - очищені параметри install без розкриття сирих значень secret. + санітизовані параметри встановлення без розкриття сирих секретних значень. - Operator можуть викликати `skills.search` і `skills.detail` (`operator.read`) для - метаданих discovery ClawHub. + метаданих виявлення ClawHub. - Operator можуть викликати `skills.install` (`operator.admin`) у двох режимах: - - режим ClawHub: `{ source: "clawhub", slug, version?, force? }` встановлює - теку skill до каталогу `skills/` workspace типового агента. - - режим installer gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` + - Режим ClawHub: `{ source: "clawhub", slug, version?, force? }` встановлює + папку skill до каталогу `skills/` робочого простору агента за замовчуванням. + - Режим установника gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` запускає оголошену дію `metadata.openclaw.install` на хості gateway. - Operator можуть викликати `skills.update` (`operator.admin`) у двох режимах: - - режим ClawHub оновлює один відстежуваний slug або всі відстежувані встановлення ClawHub у - workspace типового агента. - - режим Config оновлює значення `skills.entries.`, як-от `enabled`, + - Режим ClawHub оновлює один відстежуваний slug або всі відстежувані встановлення ClawHub у + робочому просторі агента за замовчуванням. + - Режим Config патчить значення `skills.entries.`, такі як `enabled`, `apiKey` і `env`. -## Approval exec +## Схвалення exec -- Коли запит exec потребує approval, gateway транслює `exec.approval.requested`. -- Клієнти operator виконують resolve через виклик `exec.approval.resolve` (потрібен scope `operator.approvals`). +- Коли запит exec потребує схвалення, gateway транслює `exec.approval.requested`. +- Клієнти operator розв'язують це, викликаючи `exec.approval.resolve` (потребує області `operator.approvals`). - Для `host=node` `exec.approval.request` має включати `systemRunPlan` (канонічні `argv`/`cwd`/`rawCommand`/метадані сесії). Запити без `systemRunPlan` відхиляються. - Після схвалення переслані виклики `node.invoke system.run` повторно використовують цей канонічний `systemRunPlan` як авторитетний контекст command/cwd/session. - Якщо викликач змінює `command`, `rawCommand`, `cwd`, `agentId` або - `sessionKey` між prepare і фінальним пересиланням схваленого `system.run`, gateway - відхиляє запуск замість того, щоб довіряти зміненому payload. + `sessionKey` між prepare і фінальним пересиланням схваленого `system.run`, + gateway відхиляє запуск замість довіряти зміненому навантаженню. ## Резервна доставка агента -- Запити `agent` можуть включати `deliver=true`, щоб запитувати вихідну доставку. -- `bestEffortDeliver=false` зберігає сувору поведінку: нерозв’язані або внутрішні цілі доставки повертають `INVALID_REQUEST`. -- `bestEffortDeliver=true` дозволяє повертатися до виконання лише в межах сесії, коли неможливо визначити зовнішній маршрут доставки (наприклад, внутрішні/webchat сесії або неоднозначні конфігурації з кількома каналами). +- Запити `agent` можуть включати `deliver=true`, щоб запитати вихідну доставку. +- `bestEffortDeliver=false` зберігає сувору поведінку: нерозв'язані або лише внутрішні цілі доставки повертають `INVALID_REQUEST`. +- `bestEffortDeliver=true` дозволяє резервний перехід до виконання лише в межах сесії, коли жоден зовнішній маршрут доставки не може бути розв'язаний (наприклад, для внутрішніх/webchat-сесій або неоднозначних багатоканальних конфігурацій). ## Версіонування -- `PROTOCOL_VERSION` міститься в `src/gateway/protocol/schema.ts`. +- `PROTOCOL_VERSION` розміщений у `src/gateway/protocol/schema.ts`. - Клієнти надсилають `minProtocol` + `maxProtocol`; сервер відхиляє невідповідності. -- Schemas + моделі генеруються з визначень TypeBox: +- Схеми + моделі генеруються з визначень TypeBox: - `pnpm protocol:gen` - `pnpm protocol:gen:swift` - `pnpm protocol:check` -## Auth +## Автентифікація -- Автентифікація gateway через спільний secret використовує `connect.params.auth.token` або - `connect.params.auth.password` залежно від налаштованого режиму auth. -- Режими з ідентичністю, як-от Tailscale Serve - (`gateway.auth.allowTailscale: true`) або не-loopback - `gateway.auth.mode: "trusted-proxy"`, задовольняють перевірку auth connect із - заголовків запиту, а не з `connect.params.auth.*`. -- Приватний ingress `gateway.auth.mode: "none"` повністю пропускає auth connect через спільний secret; - не відкривайте цей режим на публічному/недовіреному ingress. -- Після pairing Gateway видає **токен пристрою** з прив’язкою до role + scopes підключення. Він повертається в `hello-ok.auth.deviceToken`, і клієнт має - зберегти його для майбутніх підключень. -- Клієнти мають зберігати основний `hello-ok.auth.deviceToken` після кожного - успішного connect. +- Автентифікація gateway зі спільним секретом використовує `connect.params.auth.token` або + `connect.params.auth.password` залежно від налаштованого режиму автентифікації. +- Режими, що несуть ідентичність, як-от Tailscale Serve + (`gateway.auth.allowTailscale: true`) або режим не-loopback + `gateway.auth.mode: "trusted-proxy"`, задовольняють перевірку автентифікації connect через + заголовки запиту замість `connect.params.auth.*`. +- Приватний вхідний трафік `gateway.auth.mode: "none"` повністю пропускає автентифікацію connect зі спільним секретом; не виставляйте цей режим у публічний/недовірений ingress. +- Після pairing Gateway видає **токен пристрою**, обмежений роллю + областями + підключення. Він повертається в `hello-ok.auth.deviceToken` і має + бути збережений клієнтом для майбутніх підключень. +- Клієнти мають зберігати основний `hello-ok.auth.deviceToken` після будь-якого + успішного підключення. - Повторне підключення з цим **збереженим** токеном пристрою також має повторно використовувати збережений - набір схвалених scope для цього токена. Це зберігає вже наданий доступ для read/probe/status - і запобігає тихому звуженню повторних підключень до - вужчого неявного admin-only scope. -- Звичайний порядок пріоритету auth для connect: спершу явний спільний token/password, - потім явний `deviceToken`, потім збережений токен для конкретного пристрою, потім bootstrap token. -- Додаткові записи `hello-ok.auth.deviceTokens` — це токени передавання bootstrap. - Зберігайте їх лише коли connect використовував bootstrap auth на довіреному транспорті, - як-от `wss://` або loopback/local pairing. -- Якщо клієнт передає **явний** `deviceToken` або явні `scopes`, цей набір scope, запитаний викликачем, залишається авторитетним; кешовані scope повторно використовуються лише коли клієнт повторно використовує збережений токен для конкретного пристрою. -- Токени пристроїв можна обертати/відкликати через `device.token.rotate` і - `device.token.revoke` (потрібен scope `operator.pairing`). -- Видача/обертання токенів залишається обмеженою затвердженим набором role, записаним у - записі pairing цього пристрою; обертання токена не може розширити пристрій до - role, яку схвалення pairing ніколи не дозволяло. -- Для сесій токенів спарених пристроїв керування пристроєм обмежене самим пристроєм, якщо - викликач також не має `operator.admin`: викликачі без admin можуть видаляти/відкликати/обертати + набір схвалених областей для цього токена. Це зберігає вже наданий доступ + до читання/перевірки/status і запобігає тихому звуженню повторних підключень до + вужчої неявної admin-only області. +- Звичайний пріоритет автентифікації підключення: спочатку явний спільний token/password, потім + явний `deviceToken`, потім збережений токен для пристрою, потім bootstrap-токен. +- Додаткові записи `hello-ok.auth.deviceTokens` — це токени передачі bootstrap. + Зберігайте їх лише тоді, коли підключення використовувало bootstrap-автентифікацію на довіреному транспорті, + такому як `wss://` або loopback/local pairing. +- Якщо клієнт надає **явний** `deviceToken` або явні `scopes`, цей + запитаний викликачем набір областей залишається авторитетним; кешовані області + повторно використовуються лише тоді, коли клієнт повторно використовує збережений токен для пристрою. +- Токени пристроїв можна ротувати/відкликати через `device.token.rotate` і + `device.token.revoke` (потребує області `operator.pairing`). +- Видача/ротація токенів залишається обмеженою схваленим набором ролей, записаним у + записі pairing цього пристрою; ротація токена не може розширити пристрій до + ролі, якої схвалення pairing ніколи не надавало. +- Для сесій з токеном пов'язаного пристрою керування пристроєм обмежене власним контекстом, якщо тільки + викликач також не має `operator.admin`: викликачі без admin можуть видаляти/відкликати/ротувати лише **власний** запис пристрою. -- `device.token.rotate` також перевіряє запитуваний набір scope operator щодо - поточних scope сесії викликача. Викликачі без admin не можуть обертати токен до - ширшого набору scope operator, ніж той, який уже мають. -- Помилки auth включають `error.details.code` плюс підказки для відновлення: +- `device.token.rotate` також перевіряє запитаний набір operator-областей щодо + поточних областей сесії викликача. Викликачі без admin не можуть ротувати токен у + ширший набір operator-областей, ніж уже мають. +- Збої автентифікації включають `error.details.code` плюс підказки для відновлення: - `error.details.canRetryWithDeviceToken` (boolean) - `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`) - Поведінка клієнта для `AUTH_TOKEN_MISMATCH`: - - Довірені клієнти можуть виконати одну обмежену повторну спробу із кешованим токеном для конкретного пристрою. - - Якщо ця повторна спроба не вдається, клієнти мають зупинити автоматичні цикли перепідключення й показати оператору вказівки для подальших дій. + - Довірені клієнти можуть виконати одну обмежену повторну спробу з кешованим токеном для пристрою. + - Якщо ця повторна спроба не вдається, клієнти мають зупинити автоматичні цикли повторного підключення й показати вказівки для дій оператора. ## Ідентичність пристрою + pairing -- Node мають включати стабільну ідентичність пристрою (`device.id`), похідну від +- Вузли мають включати стабільну ідентичність пристрою (`device.id`), похідну від відбитка keypair. -- Gateway видає токени для кожного пристрою + role. -- Для нових `device.id` потрібні схвалення pairing, якщо не ввімкнено локальне автоматичне схвалення. -- Автоматичне схвалення pairing зосереджене на прямих локальних loopback-підключеннях. -- OpenClaw також має вузький шлях backend/container-local self-connect для - довірених helper-потоків зі спільним secret. -- Підключення з tailnet або LAN на тому самому хості все одно вважаються віддаленими для pairing і +- Gateway видає токени для кожного пристрою + ролі. +- Для нових `device.id` потрібні схвалення pairing, якщо не ввімкнено локальне auto-approval. +- Auto-approval pairing зосереджене на прямих локальних loopback-підключеннях. +- OpenClaw також має вузький шлях self-connect для backend/container-local + для довірених helper-потоків зі спільним секретом. +- Локальне auto-approval для operator-пристроїв ініціалізує обмежений базовий токен для пристрою замість збереження довільно запитаних operator-областей. Сесія зі shared- + secret усе одно може бути ширшою, ніж тихо виданий токен пристрою. +- Підключення через tailnet або LAN з того самого хоста все одно вважаються віддаленими для pairing і потребують схвалення. - Усі WS-клієнти мають включати ідентичність `device` під час `connect` (operator + node). - Control UI може не вказувати її лише в таких режимах: - - `gateway.controlUi.allowInsecureAuth=true` для сумісності з небезпечним HTTP лише на localhost. - - успішна auth operator у `gateway.auth.mode: "trusted-proxy"` для Control UI. - - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (аварійний режим, серйозне зниження безпеки). -- Усі підключення мають підписувати nonce `connect.challenge`, наданий сервером. + Control UI може пропускати її лише в таких режимах: + - `gateway.controlUi.allowInsecureAuth=true` для сумісності з localhost-only insecure HTTP. + - успішна operator-автентифікація Control UI через `gateway.auth.mode: "trusted-proxy"`. + - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (аварійний варіант, серйозне зниження безпеки). +- Усі підключення мають підписувати наданий сервером nonce `connect.challenge`. -### Діагностика міграції auth пристрою +### Діагностика міграції автентифікації пристрою -Для застарілих клієнтів, які все ще використовують поведінку підпису до challenge, `connect` тепер повертає +Для застарілих клієнтів, які все ще використовують поведінку підписування до challenge, `connect` тепер повертає коди деталей `DEVICE_AUTH_*` у `error.details.code` зі стабільним `error.details.reason`. Поширені збої міграції: -| Повідомлення | details.code | details.reason | Значення | -| --------------------------- | -------------------------------- | ------------------------ | --------------------------------------------------- | -| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Клієнт не передав `device.nonce` (або передав порожнє значення). | -| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Клієнт підписав застарілий/неправильний nonce. | -| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Payload підпису не відповідає payload версії v2. | -| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Підписана мітка часу виходить за межі дозволеного зсуву. | -| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` не відповідає відбитку public key. | -| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Не вдалася перевірка формату/канонізації public key. | +| Повідомлення | details.code | details.reason | Значення | +| ---------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- | +| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Клієнт не вказав `device.nonce` (або надіслав порожнє значення). | +| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Клієнт підписав зі застарілим/неправильним nonce. | +| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Навантаження підпису не відповідає навантаженню v2. | +| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Підписана позначка часу поза межами дозволеного skew. | +| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` не відповідає відбитку public key. | +| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Формат public key/канонізація не пройшли. | Ціль міграції: -- Завжди чекайте на `connect.challenge`. -- Підписуйте payload v2, який включає nonce сервера. +- Завжди дочікуйтеся `connect.challenge`. +- Підписуйте навантаження v2, яке включає серверний nonce. - Надсилайте той самий nonce у `connect.params.device.nonce`. -- Бажаний payload підпису — `v3`, який прив’язує `platform` і `deviceFamily` +- Бажане навантаження підпису — `v3`, яке прив'язує `platform` і `deviceFamily` на додачу до полів device/client/role/scopes/token/nonce. -- Застарілі підписи `v2` усе ще приймаються для сумісності, але pinning метаданих - спареного пристрою все одно керує політикою команд при повторному підключенні. +- Застарілі підписи `v2` усе ще приймаються для сумісності, але прив'язка метаданих + пов'язаного пристрою все одно контролює політику команд під час повторного підключення. ## TLS + pinning -- Для WS-підключень підтримується TLS. -- Клієнти можуть необов’язково виконувати pinning відбитка сертифіката gateway (див. конфігурацію `gateway.tls`, а також `gateway.remote.tlsFingerprint` або прапорець CLI `--tls-fingerprint`). +- TLS підтримується для WS-підключень. +- Клієнти можуть за бажанням pin-ити відбиток сертифіката gateway (див. config `gateway.tls` + плюс `gateway.remote.tlsFingerprint` або CLI `--tls-fingerprint`). ## Область дії -Цей протокол відкриває **повний API gateway** (status, channels, models, chat, -agent, sessions, nodes, approvals тощо). Точна поверхня визначена +Цей протокол надає **повний API gateway** (status, channels, models, chat, +agent, sessions, nodes, approvals тощо). Точна поверхня визначається схемами TypeBox у `src/gateway/protocol/schema.ts`.