chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
1eddf3a87a
commit
9851a77428
407
docs/uk/ci.md
407
docs/uk/ci.md
File diff suppressed because one or more lines are too long
@ -2,34 +2,35 @@
|
||||
read_when:
|
||||
- Реалізація або оновлення WS-клієнтів Gateway
|
||||
- Налагодження невідповідностей протоколу або збоїв підключення
|
||||
- Повторне генерування схеми/моделей протоколу
|
||||
summary: 'Протокол WebSocket для Gateway: рукостискання, кадри, версіонування'
|
||||
- Повторна генерація схеми/моделей протоколу
|
||||
summary: 'Протокол WebSocket Gateway: рукостискання, кадри, версіонування'
|
||||
title: Протокол Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-04-29T04:06:19Z"
|
||||
generated_at: "2026-04-29T04:57:34Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: c2923919857e430b2db1d9c731025dc18499e5dbe01f248c0f873bd30041cf0e
|
||||
source_hash: 713a72b15f029aad00a4c6427fefeef08643aee830f23eac05e53b50f43d048c
|
||||
source_path: gateway/protocol.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Gateway WS-протокол є **єдиною площиною керування + транспортом Node** для
|
||||
OpenClaw. Усі клієнти (CLI, вебінтерфейс, застосунок macOS, iOS/Android Node, headless
|
||||
Node) підключаються через WebSocket і оголошують свою **роль** + **область доступу** під
|
||||
час рукостискання.
|
||||
Протокол Gateway WS є **єдиною площиною керування + транспортом вузлів** для
|
||||
OpenClaw. Усі клієнти (CLI, вебінтерфейс, застосунок macOS, вузли iOS/Android,
|
||||
безголові вузли) підключаються через WebSocket і оголошують свою **роль** +
|
||||
**область дії** під час рукостискання.
|
||||
|
||||
## Транспорт
|
||||
|
||||
- WebSocket, текстові фрейми з JSON-пейлоадами.
|
||||
- Перший фрейм **має** бути запитом `connect`.
|
||||
- Фрейми до підключення обмежені 64 KiB. Після успішного рукостискання клієнти
|
||||
- WebSocket, текстові кадри з JSON-навантаженнями.
|
||||
- Перший кадр **обов’язково** має бути запитом `connect`.
|
||||
- Кадри до підключення обмежені 64 KiB. Після успішного рукостискання клієнти
|
||||
мають дотримуватися обмежень `hello-ok.policy.maxPayload` і
|
||||
`hello-ok.policy.maxBufferedBytes`. Коли діагностику ввімкнено,
|
||||
завеликі вхідні фрейми та повільні вихідні буфери створюють події `payload.large`
|
||||
до того, як gateway закриє або відкине відповідний фрейм. Ці події зберігають
|
||||
розміри, ліміти, поверхні та безпечні коди причин. Вони не зберігають тіло
|
||||
повідомлення, вміст вкладень, сире тіло фрейму, токени, cookies або секретні значення.
|
||||
завеликі вхідні кадри та повільні вихідні буфери створюють події `payload.large`
|
||||
до того, як gateway закриє або відкине відповідний кадр. Ці події зберігають
|
||||
розміри, обмеження, поверхні та безпечні коди причин. Вони не зберігають тіло
|
||||
повідомлення, вміст вкладень, сире тіло кадру, токени, cookie або секретні
|
||||
значення.
|
||||
|
||||
## Рукостискання (connect)
|
||||
|
||||
@ -105,11 +106,11 @@ Gateway → Клієнт:
|
||||
```
|
||||
|
||||
`server`, `features`, `snapshot` і `policy` усі є обов’язковими за схемою
|
||||
(`src/gateway/protocol/schema/frames.ts`). `auth` також є обов’язковим і повідомляє
|
||||
узгоджену роль/області доступу. `canvasHostUrl` є необов’язковим.
|
||||
(`src/gateway/protocol/schema/frames.ts`). `auth` також обов’язковий і повідомляє
|
||||
узгоджену роль/області дії. `canvasHostUrl` необов’язковий.
|
||||
|
||||
Коли токен пристрою не видається, `hello-ok.auth` повідомляє узгоджені
|
||||
дозволи без полів токена:
|
||||
Коли токен пристрою не видано, `hello-ok.auth` повідомляє узгоджені дозволи без
|
||||
полів токена:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -120,15 +121,16 @@ Gateway → Клієнт:
|
||||
}
|
||||
```
|
||||
|
||||
Довірені клієнти бекенда в тому самому процесі (`client.id: "gateway-client"`,
|
||||
`client.mode: "backend"`) можуть опускати `device` у прямих підключеннях local loopback, коли
|
||||
вони автентифікуються спільним токеном/паролем gateway. Цей шлях зарезервовано
|
||||
для внутрішніх RPC площини керування й не дає застарілим базовим даним прив’язки CLI/пристрою
|
||||
блокувати локальну роботу бекенда, як-от оновлення сесій субагентів. Віддалені клієнти,
|
||||
клієнти з браузерним походженням, клієнти Node, а також явні клієнти з токеном пристрою/ідентичністю пристрою
|
||||
далі використовують звичайні перевірки прив’язки та підвищення області доступу.
|
||||
Довірені backend-клієнти в тому самому процесі (`client.id: "gateway-client"`,
|
||||
`client.mode: "backend"`) можуть опускати `device` на прямих loopback-з’єднаннях,
|
||||
коли вони автентифікуються спільним токеном/паролем gateway. Цей шлях
|
||||
зарезервовано для внутрішніх RPC площини керування, і він не дає застарілим
|
||||
базовим даним спарювання CLI/пристрою блокувати локальну backend-роботу, як-от
|
||||
оновлення сеансів під агентів. Віддалені клієнти, клієнти з браузерним origin,
|
||||
клієнти-вузли та явні клієнти з токеном пристрою/ідентичністю пристрою й надалі
|
||||
використовують звичайні перевірки спарювання та підвищення областей дії.
|
||||
|
||||
Коли токен пристрою видається, `hello-ok` також містить:
|
||||
Коли токен пристрою видано, `hello-ok` також містить:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -160,14 +162,15 @@ Gateway → Клієнт:
|
||||
}
|
||||
```
|
||||
|
||||
Для вбудованого потоку bootstrap Node/operator основний токен Node залишається
|
||||
`scopes: []`, а будь-який переданий токен оператора залишається обмеженим allowlist
|
||||
оператора bootstrap (`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). Перевірки областей доступу bootstrap залишаються
|
||||
префіксованими роллю: записи оператора задовольняють лише запити оператора, а ролям не-оператора
|
||||
далі потрібні області доступу під власним префіксом ролі.
|
||||
Для вбудованого bootstrap-потоку вузол/оператор основний токен вузла лишається
|
||||
`scopes: []`, а будь-який переданий токен оператора лишається обмеженим
|
||||
bootstrap-списком дозволів оператора (`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). Bootstrap-перевірки областей дії
|
||||
лишаються з префіксом ролі: записи оператора задовольняють лише запити
|
||||
оператора, а неоператорським ролям усе ще потрібні області дії під власним
|
||||
префіксом ролі.
|
||||
|
||||
### Приклад Node
|
||||
### Приклад вузла
|
||||
|
||||
```json
|
||||
{
|
||||
@ -202,7 +205,7 @@ Gateway → Клієнт:
|
||||
}
|
||||
```
|
||||
|
||||
## Обрамлення
|
||||
## Кадрування
|
||||
|
||||
- **Запит**: `{type:"req", id, method, params}`
|
||||
- **Відповідь**: `{type:"res", id, ok, payload|error}`
|
||||
@ -210,16 +213,16 @@ Gateway → Клієнт:
|
||||
|
||||
Методи з побічними ефектами потребують **ключів ідемпотентності** (див. схему).
|
||||
|
||||
## Ролі + області доступу
|
||||
## Ролі + області дії
|
||||
|
||||
### Ролі
|
||||
|
||||
- `operator` = клієнт площини керування (CLI/UI/автоматизація).
|
||||
- `node` = хост можливостей (camera/screen/canvas/system.run).
|
||||
|
||||
### Області доступу (operator)
|
||||
### Області дії (оператор)
|
||||
|
||||
Поширені області доступу:
|
||||
Поширені області дії:
|
||||
|
||||
- `operator.read`
|
||||
- `operator.write`
|
||||
@ -231,45 +234,46 @@ Gateway → Клієнт:
|
||||
`talk.config` з `includeSecrets: true` потребує `operator.talk.secrets`
|
||||
(або `operator.admin`).
|
||||
|
||||
RPC-методи gateway, зареєстровані Plugin, можуть запитувати власну область доступу оператора, але
|
||||
зарезервовані префікси адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) завжди перетворюються на `operator.admin`.
|
||||
Зареєстровані Plugin методи Gateway RPC можуть запитувати власну область дії
|
||||
оператора, але зарезервовані префікси адміністрування ядра (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) завжди зводяться до `operator.admin`.
|
||||
|
||||
Область доступу методу є лише першим бар’єром. Деякі slash-команди, доступні через
|
||||
`chat.send`, застосовують суворіші перевірки рівня команди поверх цього. Наприклад, постійні
|
||||
записи `/config set` і `/config unset` потребують `operator.admin`.
|
||||
Область дії методу є лише першою перевіркою. Деякі slash-команди, доступні через
|
||||
`chat.send`, застосовують суворіші перевірки на рівні команди поверх цього.
|
||||
Наприклад, постійні записи `/config set` і `/config unset` потребують
|
||||
`operator.admin`.
|
||||
|
||||
`node.pair.approve` також має додаткову перевірку області доступу під час схвалення поверх
|
||||
базової області доступу методу:
|
||||
`node.pair.approve` також має додаткову перевірку області дії під час
|
||||
затвердження поверх базової області дії методу:
|
||||
|
||||
- запити без команд: `operator.pairing`
|
||||
- запити з командами Node, що не належать до exec: `operator.pairing` + `operator.write`
|
||||
- запити з не-exec командами вузла: `operator.pairing` + `operator.write`
|
||||
- запити, що містять `system.run`, `system.run.prepare` або `system.which`:
|
||||
`operator.pairing` + `operator.admin`
|
||||
|
||||
### Caps/commands/permissions (node)
|
||||
### Можливості/команди/дозволи (вузол)
|
||||
|
||||
Node оголошують заявлені можливості під час підключення:
|
||||
Вузли оголошують заявлені можливості під час підключення:
|
||||
|
||||
- `caps`: високорівневі категорії можливостей.
|
||||
- `commands`: allowlist команд для invoke.
|
||||
- `commands`: список дозволених команд для invoke.
|
||||
- `permissions`: деталізовані перемикачі (наприклад, `screen.record`, `camera.capture`).
|
||||
|
||||
Gateway трактує їх як **заяви** і застосовує allowlist на серверному боці.
|
||||
Gateway трактує їх як **заявки** та застосовує серверні списки дозволів.
|
||||
|
||||
## Presence
|
||||
## Присутність
|
||||
|
||||
- `system-presence` повертає записи з ключами за ідентичністю пристрою.
|
||||
- Записи presence містять `deviceId`, `roles` і `scopes`, щоб UI міг показувати один рядок на пристрій
|
||||
- Записи присутності містять `deviceId`, `roles` і `scopes`, щоб UI могли показувати один рядок на пристрій
|
||||
навіть коли він підключається і як **operator**, і як **node**.
|
||||
- `node.list` містить необов’язкові поля `lastSeenAtMs` і `lastSeenReason`. Підключені Node повідомляють
|
||||
свій поточний час підключення як `lastSeenAtMs` з причиною `connect`; прив’язані Node також можуть повідомляти
|
||||
тривалу фонову presence, коли довірена подія Node оновлює їхні метадані прив’язки.
|
||||
- `node.list` містить необов’язкові поля `lastSeenAtMs` і `lastSeenReason`. Підключені вузли повідомляють
|
||||
час свого поточного підключення як `lastSeenAtMs` з причиною `connect`; спарені вузли також можуть повідомляти
|
||||
стійку фонову присутність, коли довірена подія вузла оновлює їхні метадані спарювання.
|
||||
|
||||
### Фонова подія alive для Node
|
||||
### Фонова подія активності вузла
|
||||
|
||||
Node можуть викликати `node.event` з `event: "node.presence.alive"`, щоб записати, що прив’язаний Node був
|
||||
живим під час фонового пробудження, не позначаючи його підключеним.
|
||||
Вузли можуть викликати `node.event` з `event: "node.presence.alive"`, щоб записати, що спарений вузол був
|
||||
активний під час фонового пробудження, не позначаючи його як підключений.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -279,9 +283,9 @@ Node можуть викликати `node.event` з `event: "node.presence.aliv
|
||||
```
|
||||
|
||||
`trigger` є закритим enum: `background`, `silent_push`, `bg_app_refresh`,
|
||||
`significant_location`, `manual` або `connect`. Невідомі рядки trigger нормалізуються до
|
||||
`background` gateway перед збереженням. Подія є довговічною лише для автентифікованих сесій пристрою
|
||||
Node; сесії без пристрою або без прив’язки повертають `handled: false`.
|
||||
`significant_location`, `manual` або `connect`. Невідомі рядки trigger gateway нормалізує до
|
||||
`background` перед збереженням. Подія є стійкою лише для автентифікованих
|
||||
сеансів пристроїв-вузлів; сеанси без пристрою або без спарювання повертають `handled: false`.
|
||||
|
||||
Успішні gateway повертають структурований результат:
|
||||
|
||||
@ -294,154 +298,154 @@ Node; сесії без пристрою або без прив’язки по
|
||||
}
|
||||
```
|
||||
|
||||
Старіші gateway можуть далі повертати `{ "ok": true }` для `node.event`; клієнти мають трактувати це як
|
||||
підтверджений RPC, а не як довговічне збереження presence.
|
||||
Старіші gateway усе ще можуть повертати `{ "ok": true }` для `node.event`; клієнти мають трактувати це як
|
||||
підтверджений RPC, а не як стійке збереження присутності.
|
||||
|
||||
## Обмеження області трансляції подій
|
||||
## Області дії широкомовних подій
|
||||
|
||||
Трансляційні події WebSocket, які сервер надсилає клієнтам, обмежуються областями доступу, щоб сесії з областю прив’язки або лише Node не отримували пасивно вміст сесії.
|
||||
Широкомовні події WebSocket, що надсилаються сервером, обмежуються областями дії, щоб сеанси, обмежені спарюванням або лише вузлом, не отримували пасивно вміст сеансу.
|
||||
|
||||
- **Фрейми чату, агента та результатів інструментів** (включно зі streamed подіями `agent` і результатами викликів інструментів) потребують щонайменше `operator.read`. Сесії без `operator.read` повністю пропускають ці фрейми.
|
||||
- **Визначені Plugin трансляції `plugin.*`** обмежуються `operator.write` або `operator.admin`, залежно від того, як Plugin їх зареєстрував.
|
||||
- **Події статусу й транспорту** (`heartbeat`, `presence`, `tick`, життєвий цикл connect/disconnect тощо) залишаються необмеженими, щоб справність транспорту була видимою для кожної автентифікованої сесії.
|
||||
- **Невідомі сімейства трансляційних подій** за замовчуванням обмежуються областями доступу (fail-closed), якщо зареєстрований обробник явно не послаблює їх.
|
||||
- **Кадри чату, агента та результатів інструментів** (зокрема потокові події `agent` і результати викликів інструментів) потребують щонайменше `operator.read`. Сеанси без `operator.read` повністю пропускають ці кадри.
|
||||
- **Визначені Plugin широкомовні події `plugin.*`** обмежуються `operator.write` або `operator.admin` залежно від того, як Plugin їх зареєстрував.
|
||||
- **Події статусу й транспорту** (`heartbeat`, `presence`, `tick`, життєвий цикл підключення/відключення тощо) лишаються необмеженими, щоб справність транспорту була видимою кожному автентифікованому сеансу.
|
||||
- **Невідомі сімейства широкомовних подій** за замовчуванням обмежуються областями дії (fail-closed), якщо зареєстрований обробник явно не послаблює їх.
|
||||
|
||||
Кожне клієнтське підключення зберігає власний порядковий номер на клієнта, тому трансляції зберігають монотонне впорядкування на цьому сокеті, навіть коли різні клієнти бачать різні підмножини потоку подій, відфільтровані за областями доступу.
|
||||
Кожне клієнтське підключення зберігає власний порядковий номер для клієнта, щоб широкомовлення зберігали монотонний порядок на цьому сокеті, навіть коли різні клієнти бачать різні відфільтровані за областями дії підмножини потоку подій.
|
||||
|
||||
## Поширені сімейства RPC-методів
|
||||
## Поширені сімейства методів RPC
|
||||
|
||||
Публічна поверхня WS ширша за наведені вище приклади рукостискання/автентифікації. Це
|
||||
не згенерований дамп — `hello-ok.features.methods` є консервативним
|
||||
списком для виявлення, побудованим із `src/gateway/server-methods-list.ts` плюс завантажених
|
||||
експортів методів Plugin/каналів. Трактуйте його як виявлення функцій, а не повний
|
||||
перелік `src/gateway/server-methods/*.ts`.
|
||||
не згенерований дамп — `hello-ok.features.methods` є консервативним списком
|
||||
виявлення, побудованим із `src/gateway/server-methods-list.ts` плюс експортів
|
||||
методів завантажених Plugin/каналів. Сприймайте його як виявлення можливостей,
|
||||
а не як повний перелік `src/gateway/server-methods/*.ts`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Система та ідентичність">
|
||||
<Accordion title="System and identity">
|
||||
- `health` повертає кешований або щойно перевірений знімок справності gateway.
|
||||
- `diagnostics.stability` повертає нещодавній обмежений реєстратор стабільності діагностики. Він зберігає операційні метадані, як-от назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сесії, назви каналів/Plugin і ідентифікатори сесій. Він не зберігає текст чату, тіла webhook, виводи інструментів, сирі тіла запитів або відповідей, токени, cookies або секретні значення. Потрібна область доступу operator read.
|
||||
- `status` повертає зведення gateway у стилі `/status`; чутливі поля включаються лише для клієнтів-операторів з областю доступу admin.
|
||||
- `gateway.identity.get` повертає ідентичність пристрою gateway, яку використовують потоки relay і прив’язки.
|
||||
- `system-presence` повертає поточний знімок presence для підключених пристроїв operator/node.
|
||||
- `system-event` додає системну подію і може оновлювати/транслювати контекст presence.
|
||||
- `diagnostics.stability` повертає нещодавній обмежений реєстратор діагностичної стабільності. Він зберігає операційні метадані, як-от назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сеансу, назви каналів/Plugin і ідентифікатори сеансів. Він не зберігає текст чату, тіла webhook, виводи інструментів, сирі тіла запитів або відповідей, токени, cookie чи секретні значення. Потрібна область дії читання оператора.
|
||||
- `status` повертає підсумок gateway у стилі `/status`; чутливі поля включаються лише для клієнтів-операторів з admin-областю дії.
|
||||
- `gateway.identity.get` повертає ідентичність пристрою gateway, що використовується потоками relay і спарювання.
|
||||
- `system-presence` повертає поточний знімок присутності для підключених пристроїв operator/node.
|
||||
- `system-event` додає системну подію й може оновити/поширити контекст присутності.
|
||||
- `last-heartbeat` повертає останню збережену подію heartbeat.
|
||||
- `set-heartbeats` вмикає або вимикає обробку heartbeat на gateway.
|
||||
- `set-heartbeats` перемикає обробку heartbeat на gateway.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Моделі та використання">
|
||||
- `models.list` повертає каталог моделей, дозволених під час виконання. Передайте `{ "view": "configured" }` для налаштованих моделей розміру picker (`agents.defaults.models` спочатку, потім `models.providers.*.models`), або `{ "view": "all" }` для повного каталогу.
|
||||
- `usage.status` повертає вікна використання провайдера/зведення залишку квоти.
|
||||
- `usage.cost` повертає агреговані зведення використання витрат за діапазон дат.
|
||||
- `doctor.memory.status` повертає готовність vector-memory / кешованих embeddings для активного робочого простору агента за замовчуванням. Передавайте `{ "probe": true }` або `{ "deep": true }` лише коли викликач явно хоче live ping провайдера embeddings.
|
||||
- `sessions.usage` повертає зведення використання за сесіями.
|
||||
- `sessions.usage.timeseries` повертає timeseries використання для однієї сесії.
|
||||
- `sessions.usage.logs` повертає записи журналу використання для однієї сесії.
|
||||
<Accordion title="Models and usage">
|
||||
- `models.list` повертає дозволений середовищем виконання каталог моделей. Передайте `{ "view": "configured" }` для налаштованих моделей розміру picker (`agents.defaults.models` спершу, потім `models.providers.*.models`), або `{ "view": "all" }` для повного каталогу.
|
||||
- `usage.status` повертає вікна використання провайдерів/підсумки залишку квоти.
|
||||
- `usage.cost` повертає агреговані підсумки вартості використання за діапазон дат.
|
||||
- `doctor.memory.status` повертає готовність vector-memory / кешованих embedding для активного робочого простору агента за замовчуванням. Передавайте `{ "probe": true }` або `{ "deep": true }` лише коли викликач явно хоче живий ping провайдера embedding.
|
||||
- `sessions.usage` повертає підсумки використання за сеансами.
|
||||
- `sessions.usage.timeseries` повертає часовий ряд використання для одного сеансу.
|
||||
- `sessions.usage.logs` повертає записи журналу використання для одного сеансу.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Канали та помічники входу">
|
||||
- `channels.status` повертає зведення стану вбудованих і bundled каналів/plugin.
|
||||
- `channels.status` повертає зведення статусів вбудованих і комплектних каналів/plugin.
|
||||
- `channels.logout` виконує вихід із певного каналу/облікового запису, якщо канал підтримує вихід.
|
||||
- `web.login.start` запускає QR/web-потік входу для поточного web-провайдера каналу з підтримкою QR.
|
||||
- `web.login.wait` очікує завершення цього QR/web-потоку входу та запускає канал у разі успіху.
|
||||
- `push.test` надсилає тестовий APNs push на зареєстрований iOS-вузол.
|
||||
- `web.login.start` запускає потік QR/web-входу для поточного постачальника web-каналу з підтримкою QR.
|
||||
- `web.login.wait` чекає на завершення цього потоку QR/web-входу та запускає канал у разі успіху.
|
||||
- `push.test` надсилає тестовий APNs push на зареєстрований iOS node.
|
||||
- `voicewake.get` повертає збережені тригери wake-word.
|
||||
- `voicewake.set` оновлює тригери wake-word і транслює зміну.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Повідомлення та журнали">
|
||||
- `send` — це прямий outbound-delivery RPC для надсилань, націлених на канал/обліковий запис/тред поза chat runner.
|
||||
<Accordion title="Обмін повідомленнями та журнали">
|
||||
- `send` — це прямий RPC вихідної доставки для надсилань, націлених на канал/обліковий запис/потік, поза chat runner.
|
||||
- `logs.tail` повертає налаштований хвіст файлового журналу gateway з керуванням cursor/limit і max-byte.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Talk і TTS">
|
||||
- `talk.config` повертає ефективний payload конфігурації Talk; `includeSecrets` потребує `operator.talk.secrets` (або `operator.admin`).
|
||||
- `talk.mode` встановлює/транслює поточний стан режиму Talk для клієнтів WebChat/Control UI.
|
||||
- `talk.speak` синтезує мовлення через активного провайдера мовлення Talk.
|
||||
- `tts.status` повертає стан увімкнення TTS, активного провайдера, fallback-провайдерів і стан конфігурації провайдера.
|
||||
- `tts.providers` повертає видимий інвентар провайдерів TTS.
|
||||
- `talk.config` повертає ефективне навантаження конфігурації Talk; `includeSecrets` потребує `operator.talk.secrets` (або `operator.admin`).
|
||||
- `talk.mode` задає/транслює поточний стан режиму Talk для клієнтів WebChat/Control UI.
|
||||
- `talk.speak` синтезує мовлення через активного постачальника мовлення Talk.
|
||||
- `tts.status` повертає стан увімкнення TTS, активного постачальника, резервних постачальників і стан конфігурації постачальника.
|
||||
- `tts.providers` повертає видимий інвентар постачальників TTS.
|
||||
- `tts.enable` і `tts.disable` перемикають стан налаштувань TTS.
|
||||
- `tts.setProvider` оновлює бажаного провайдера TTS.
|
||||
- `tts.setProvider` оновлює бажаного постачальника TTS.
|
||||
- `tts.convert` виконує одноразове перетворення text-to-speech.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Секрети, конфігурація, оновлення та майстер">
|
||||
- `secrets.reload` повторно розв’язує активні SecretRefs і замінює runtime-стан секретів лише за повного успіху.
|
||||
- `secrets.resolve` розв’язує призначення секретів, націлені на команду, для певного набору command/target.
|
||||
- `secrets.reload` повторно вирішує активні SecretRefs і замінює стан runtime-секретів лише за повного успіху.
|
||||
- `secrets.resolve` вирішує призначення секретів для цільових команд для певного набору command/target.
|
||||
- `config.get` повертає поточний знімок конфігурації та hash.
|
||||
- `config.set` записує валідований payload конфігурації.
|
||||
- `config.patch` зливає часткове оновлення конфігурації.
|
||||
- `config.apply` валідує + замінює повний payload конфігурації.
|
||||
- `config.schema` повертає live payload схеми конфігурації, який використовують Control UI і CLI-інструменти: schema, `uiHints`, version і metadata генерації, включно з metadata схеми plugin + channel, коли runtime може її завантажити. Схема містить metadata полів `title` / `description`, похідну від тих самих labels і help text, які використовує UI, включно з вкладеними object, wildcard, array-item і гілками композиції `anyOf` / `oneOf` / `allOf`, коли існує відповідна документація поля.
|
||||
- `config.schema.lookup` повертає path-scoped lookup payload для одного шляху конфігурації: нормалізований path, shallow schema node, matched hint + `hintPath` і immediate child summaries для UI/CLI drill-down. Lookup schema nodes зберігають користувацьку документацію та common validation fields (`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, numeric/string/array/object bounds, а також flags на кшталт `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`). Child summaries відкривають `key`, нормалізований `path`, `type`, `required`, `hasChildren`, а також matched `hint` / `hintPath`.
|
||||
- `update.run` запускає потік оновлення gateway і планує restart лише тоді, коли саме оновлення завершилося успішно.
|
||||
- `update.status` повертає останній кешований update restart sentinel, включно з running version після restart, коли вона доступна.
|
||||
- `wizard.start`, `wizard.next`, `wizard.status` і `wizard.cancel` надають onboarding wizard через WS RPC.
|
||||
- `config.set` записує валідоване навантаження конфігурації.
|
||||
- `config.patch` об’єднує часткове оновлення конфігурації.
|
||||
- `config.apply` валідує та замінює повне навантаження конфігурації.
|
||||
- `config.schema` повертає активне навантаження схеми конфігурації, яке використовують Control UI та інструменти CLI: schema, `uiHints`, version і метадані generation, включно з метаданими схеми plugin + channel, коли runtime може її завантажити. Схема містить метадані полів `title` / `description`, отримані з тих самих міток і довідкового тексту, які використовує UI, включно з вкладеним object, wildcard, array-item і гілками композиції `anyOf` / `oneOf` / `allOf`, коли існує відповідна документація поля.
|
||||
- `config.schema.lookup` повертає навантаження пошуку, обмежене шляхом, для одного шляху конфігурації: нормалізований шлях, поверхневий вузол схеми, відповідну підказку + `hintPath` і безпосередні зведення дочірніх елементів для деталізації в UI/CLI. Вузли схеми пошуку зберігають користувацьку документацію та поширені поля валідації (`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, межі numeric/string/array/object і прапорці на кшталт `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`). Зведення дочірніх елементів відкривають `key`, нормалізований `path`, `type`, `required`, `hasChildren`, а також відповідні `hint` / `hintPath`.
|
||||
- `update.run` запускає потік оновлення gateway і планує перезапуск лише тоді, коли саме оновлення завершилося успішно.
|
||||
- `update.status` повертає найновіший кешований sentinel перезапуску оновлення, включно з версією, що працює після перезапуску, коли вона доступна.
|
||||
- `wizard.start`, `wizard.next`, `wizard.status` і `wizard.cancel` відкривають майстер onboarding через WS RPC.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Помічники агентів і робочого простору">
|
||||
- `agents.list` повертає налаштовані записи агентів, включно з effective model і runtime metadata.
|
||||
- `agents.create`, `agents.update` і `agents.delete` керують записами агентів і під’єднанням workspace.
|
||||
- `agents.files.list`, `agents.files.get` і `agents.files.set` керують bootstrap workspace files, доступними для агента.
|
||||
- `agent.identity.get` повертає effective assistant identity для агента або сесії.
|
||||
- `agent.wait` очікує завершення run і повертає terminal snapshot, коли він доступний.
|
||||
<Accordion title="Помічники агента та робочого простору">
|
||||
- `agents.list` повертає налаштовані записи агентів, включно з ефективною моделлю та runtime-метаданими.
|
||||
- `agents.create`, `agents.update` і `agents.delete` керують записами агентів і прив’язкою робочих просторів.
|
||||
- `agents.files.list`, `agents.files.get` і `agents.files.set` керують початковими файлами робочого простору, відкритими для агента.
|
||||
- `agent.identity.get` повертає ефективну ідентичність assistant для агента або сесії.
|
||||
- `agent.wait` чекає завершення запуску та повертає фінальний знімок, коли він доступний.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Керування сесією">
|
||||
- `sessions.list` повертає поточний session index.
|
||||
- `sessions.subscribe` і `sessions.unsubscribe` перемикають підписки на session change event для поточного WS client.
|
||||
- `sessions.messages.subscribe` і `sessions.messages.unsubscribe` перемикають transcript/message event subscriptions для однієї сесії.
|
||||
- `sessions.preview` повертає bounded transcript previews для певних session keys.
|
||||
- `sessions.resolve` розв’язує або канонікалізує session target.
|
||||
- `sessions.create` створює новий session entry.
|
||||
<Accordion title="Керування сесіями">
|
||||
- `sessions.list` повертає поточний індекс сесій.
|
||||
- `sessions.subscribe` і `sessions.unsubscribe` перемикають підписки на події змін сесій для поточного WS-клієнта.
|
||||
- `sessions.messages.subscribe` і `sessions.messages.unsubscribe` перемикають підписки на події транскрипту/повідомлень для однієї сесії.
|
||||
- `sessions.preview` повертає обмежені попередні перегляди транскриптів для певних ключів сесій.
|
||||
- `sessions.resolve` вирішує або канонізує ціль сесії.
|
||||
- `sessions.create` створює новий запис сесії.
|
||||
- `sessions.send` надсилає повідомлення в наявну сесію.
|
||||
- `sessions.steer` — це interrupt-and-steer variant для активної сесії.
|
||||
- `sessions.steer` — це варіант переривання та скеровування для активної сесії.
|
||||
- `sessions.abort` перериває активну роботу для сесії.
|
||||
- `sessions.patch` оновлює metadata/overrides сесії.
|
||||
- `sessions.reset`, `sessions.delete` і `sessions.compact` виконують обслуговування сесії.
|
||||
- `sessions.get` повертає повний збережений session row.
|
||||
- Виконання чату досі використовує `chat.history`, `chat.send`, `chat.abort` і `chat.inject`. `chat.history` display-normalized для UI clients: inline directive tags видаляються з видимого тексту, plain-text tool-call XML payloads (включно з `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і truncated tool-call blocks) та leaked ASCII/full-width model control tokens видаляються, pure silent-token assistant rows на кшталт точних `NO_REPLY` / `no_reply` опускаються, а oversized rows можуть бути замінені placeholders.
|
||||
- `sessions.patch` оновлює метадані/перевизначення сесії.
|
||||
- `sessions.reset`, `sessions.delete` і `sessions.compact` виконують обслуговування сесій.
|
||||
- `sessions.get` повертає повний збережений рядок сесії.
|
||||
- Виконання чату й далі використовує `chat.history`, `chat.send`, `chat.abort` і `chat.inject`. `chat.history` нормалізовано для відображення клієнтам UI: inline-теги директив вилучаються з видимого тексту, plain-text XML-навантаження викликів інструментів (зокрема `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізані блоки викликів інструментів) та витеклі ASCII/full-width токени керування моделі вилучаються, суто silent-token рядки assistant, як-от точні `NO_REPLY` / `no_reply`, пропускаються, а надмірно великі рядки можуть замінюватися placeholders.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Спарювання пристроїв і токени пристроїв">
|
||||
- `device.pair.list` повертає pending і approved paired devices.
|
||||
- `device.pair.approve`, `device.pair.reject` і `device.pair.remove` керують записами device-pairing.
|
||||
- `device.token.rotate` ротує paired device token у межах його approved role і caller scope bounds.
|
||||
- `device.token.revoke` відкликає paired device token у межах його approved role і caller scope bounds.
|
||||
- `device.pair.list` повертає pending і approved спарені пристрої.
|
||||
- `device.pair.approve`, `device.pair.reject` і `device.pair.remove` керують записами спарювання пристроїв.
|
||||
- `device.token.rotate` ротує токен спареного пристрою в межах його approved role і caller scope.
|
||||
- `device.token.revoke` відкликає токен спареного пристрою в межах його approved role і caller scope.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Спарювання вузлів, invoke і pending work">
|
||||
- `node.pair.request`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.remove` і `node.pair.verify` охоплюють node pairing і bootstrap verification.
|
||||
- `node.list` і `node.describe` повертають known/connected node state.
|
||||
- `node.rename` оновлює мітку paired node.
|
||||
- `node.invoke` пересилає команду до connected node.
|
||||
- `node.invoke.result` повертає результат для invoke request.
|
||||
- `node.event` передає node-originated events назад у gateway.
|
||||
- `node.canvas.capability.refresh` оновлює scoped canvas-capability tokens.
|
||||
- `node.pending.pull` і `node.pending.ack` — це connected-node queue APIs.
|
||||
- `node.pending.enqueue` і `node.pending.drain` керують durable pending work для offline/disconnected nodes.
|
||||
<Accordion title="Спарювання node, виклик і pending work">
|
||||
- `node.pair.request`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.remove` і `node.pair.verify` охоплюють спарювання node і bootstrap verification.
|
||||
- `node.list` і `node.describe` повертають стан відомих/підключених node.
|
||||
- `node.rename` оновлює мітку спареного node.
|
||||
- `node.invoke` пересилає команду до підключеного node.
|
||||
- `node.invoke.result` повертає результат для запиту invoke.
|
||||
- `node.event` переносить події, що походять із node, назад у gateway.
|
||||
- `node.canvas.capability.refresh` оновлює токени scoped canvas-capability.
|
||||
- `node.pending.pull` і `node.pending.ack` — це API черги connected-node.
|
||||
- `node.pending.enqueue` і `node.pending.drain` керують durable pending work для offline/disconnected node.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Сімейства підтверджень">
|
||||
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` і `exec.approval.resolve` охоплюють one-shot exec approval requests, а також pending approval lookup/replay.
|
||||
- `exec.approval.waitDecision` очікує одне pending exec approval і повертає final decision (або `null` у разі timeout).
|
||||
- `exec.approvals.get` і `exec.approvals.set` керують snapshots політики gateway exec approval.
|
||||
- `exec.approvals.node.get` і `exec.approvals.node.set` керують node-local exec approval policy через node relay commands.
|
||||
- `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` і `plugin.approval.resolve` охоплюють plugin-defined approval flows.
|
||||
<Accordion title="Сімейства схвалень">
|
||||
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` і `exec.approval.resolve` охоплюють одноразові запити схвалення exec, а також пошук/відтворення pending approval.
|
||||
- `exec.approval.waitDecision` чекає на одне pending exec approval і повертає остаточне рішення (або `null` у разі timeout).
|
||||
- `exec.approvals.get` і `exec.approvals.set` керують знімками політики gateway exec approval.
|
||||
- `exec.approvals.node.get` і `exec.approvals.node.set` керують node-local політикою exec approval через node relay commands.
|
||||
- `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` і `plugin.approval.resolve` охоплюють plugin-defined потоки схвалення.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Автоматизація, Skills та інструменти">
|
||||
- Автоматизація: `wake` планує immediate або next-heartbeat wake text injection; `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` керують scheduled work.
|
||||
<Accordion title="Автоматизація, skills та інструменти">
|
||||
- Автоматизація: `wake` планує негайну або next-heartbeat ін’єкцію wake text; `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` керують запланованою роботою.
|
||||
- Skills та інструменти: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`.
|
||||
|
||||
</Accordion>
|
||||
@ -449,97 +453,80 @@ Node; сесії без пристрою або без прив’язки по
|
||||
|
||||
### Поширені сімейства подій
|
||||
|
||||
- `chat`: оновлення UI chat, як-от `chat.inject` та інші transcript-only chat
|
||||
events.
|
||||
- `session.message` і `session.tool`: transcript/event-stream updates для
|
||||
subscribed session.
|
||||
- `sessions.changed`: змінено session index або metadata.
|
||||
- `presence`: оновлення system presence snapshot.
|
||||
- `tick`: periodic keepalive / liveness event.
|
||||
- `health`: оновлення gateway health snapshot.
|
||||
- `heartbeat`: оновлення Heartbeat event stream.
|
||||
- `cron`: event зміни cron run/job.
|
||||
- `shutdown`: сповіщення про shutdown gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved`: lifecycle node pairing.
|
||||
- `node.invoke.request`: broadcast node invoke request.
|
||||
- `device.pair.requested` / `device.pair.resolved`: paired-device lifecycle.
|
||||
- `voicewake.changed`: змінено конфігурацію wake-word trigger.
|
||||
- `exec.approval.requested` / `exec.approval.resolved`: lifecycle exec approval.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved`: lifecycle plugin approval.
|
||||
- `chat`: оновлення UI-чату, як-от `chat.inject`, та інші події чату лише для транскрипту.
|
||||
- `session.message` і `session.tool`: оновлення transcript/event-stream для підписаної сесії.
|
||||
- `sessions.changed`: індекс сесій або метадані змінено.
|
||||
- `presence`: оновлення знімка присутності системи.
|
||||
- `tick`: періодична подія keepalive / liveness.
|
||||
- `health`: оновлення знімка стану gateway.
|
||||
- `heartbeat`: оновлення потоку подій heartbeat.
|
||||
- `cron`: подія зміни запуску/завдання cron.
|
||||
- `shutdown`: сповіщення про завершення роботи gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved`: життєвий цикл спарювання node.
|
||||
- `node.invoke.request`: трансляція запиту invoke node.
|
||||
- `device.pair.requested` / `device.pair.resolved`: життєвий цикл спареного пристрою.
|
||||
- `voicewake.changed`: конфігурацію тригера wake-word змінено.
|
||||
- `exec.approval.requested` / `exec.approval.resolved`: життєвий цикл exec approval.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved`: життєвий цикл plugin approval.
|
||||
|
||||
### Допоміжні методи вузлів
|
||||
### Допоміжні методи node
|
||||
|
||||
- Вузли можуть викликати `skills.bins`, щоб отримати поточний список skill executables
|
||||
для auto-allow checks.
|
||||
- Node можуть викликати `skills.bins`, щоб отримати поточний список виконуваних файлів skill для перевірок auto-allow.
|
||||
|
||||
### Допоміжні методи операторів
|
||||
### Допоміжні методи оператора
|
||||
|
||||
- Оператори можуть викликати `commands.list` (`operator.read`), щоб отримати runtime
|
||||
command inventory для агента.
|
||||
- `agentId` необов’язковий; опустіть його, щоб прочитати default agent workspace.
|
||||
- `scope` керує тим, на яку surface націлюється primary `name`:
|
||||
- `text` повертає primary text command token без початкового `/`
|
||||
- `native` і default шлях `both` повертають provider-aware native names,
|
||||
коли доступні
|
||||
- `textAliases` містить exact slash aliases, як-от `/model` і `/m`.
|
||||
- `nativeName` містить provider-aware native command name, коли він існує.
|
||||
- `provider` необов’язковий і впливає лише на native naming, а також native plugin
|
||||
command availability.
|
||||
- `includeArgs=false` опускає serialized argument metadata з відповіді.
|
||||
- Оператори можуть викликати `tools.catalog` (`operator.read`), щоб отримати runtime tool catalog для
|
||||
агента. Відповідь містить grouped tools і provenance metadata:
|
||||
- Оператори можуть викликати `commands.list` (`operator.read`), щоб отримати runtime-інвентар команд для агента.
|
||||
- `agentId` є необов’язковим; пропустіть його, щоб читати робочий простір агента за замовчуванням.
|
||||
- `scope` керує тим, на яку поверхню спрямовано основний `name`:
|
||||
- `text` повертає основний текстовий токен команди без початкового `/`
|
||||
- `native` і стандартний шлях `both` повертають provider-aware native names, коли вони доступні
|
||||
- `textAliases` переносить точні slash aliases, як-от `/model` і `/m`.
|
||||
- `nativeName` переносить provider-aware native command name, коли він існує.
|
||||
- `provider` є необов’язковим і впливає лише на native naming, а також доступність native plugin command.
|
||||
- `includeArgs=false` пропускає серіалізовані метадані аргументів у відповіді.
|
||||
- Оператори можуть викликати `tools.catalog` (`operator.read`), щоб отримати runtime-каталог інструментів для агента. Відповідь містить згруповані інструменти та метадані походження:
|
||||
- `source`: `core` або `plugin`
|
||||
- `pluginId`: власник plugin, коли `source="plugin"`
|
||||
- `optional`: чи є plugin tool optional
|
||||
- Оператори можуть викликати `tools.effective` (`operator.read`), щоб отримати runtime-effective tool
|
||||
inventory для сесії.
|
||||
- `sessionKey` обов’язковий.
|
||||
- Gateway виводить trusted runtime context із сесії на серверному боці замість приймання
|
||||
caller-supplied auth або delivery context.
|
||||
- Відповідь session-scoped і відображає те, що активна розмова може використовувати прямо зараз,
|
||||
включно з core, plugin і channel tools.
|
||||
- Оператори можуть викликати `skills.status` (`operator.read`), щоб отримати visible
|
||||
skill inventory для агента.
|
||||
- `agentId` необов’язковий; опустіть його, щоб прочитати default agent workspace.
|
||||
- Відповідь містить eligibility, missing requirements, config checks і
|
||||
sanitized install options без розкриття raw secret values.
|
||||
- Оператори можуть викликати `skills.search` і `skills.detail` (`operator.read`) для
|
||||
ClawHub discovery metadata.
|
||||
- `optional`: чи є інструмент plugin необов’язковим
|
||||
- Оператори можуть викликати `tools.effective` (`operator.read`), щоб отримати runtime-effective інвентар інструментів для сесії.
|
||||
- `sessionKey` є обов’язковим.
|
||||
- gateway виводить довірений runtime-контекст із сесії на боці сервера замість приймання caller-supplied auth або delivery context.
|
||||
- Відповідь обмежена сесією та відображає те, що активна розмова може використовувати прямо зараз, включно з інструментами core, plugin і channel.
|
||||
- Оператори можуть викликати `skills.status` (`operator.read`), щоб отримати видимий інвентар skill для агента.
|
||||
- `agentId` є необов’язковим; пропустіть його, щоб читати робочий простір агента за замовчуванням.
|
||||
- Відповідь містить eligibility, відсутні requirements, config checks і sanitized install options без розкриття raw secret values.
|
||||
- Оператори можуть викликати `skills.search` і `skills.detail` (`operator.read`) для метаданих виявлення ClawHub.
|
||||
- Оператори можуть викликати `skills.install` (`operator.admin`) у двох режимах:
|
||||
- Режим ClawHub: `{ source: "clawhub", slug, version?, force? }` встановлює
|
||||
skill folder у директорію `skills/` default agent workspace.
|
||||
- Режим інсталятора Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
|
||||
запускає оголошену дію `metadata.openclaw.install` на gateway host.
|
||||
- Режим ClawHub: `{ source: "clawhub", slug, version?, force? }` встановлює папку skill у каталог `skills/` робочого простору агента за замовчуванням.
|
||||
- Режим installer gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` запускає оголошену дію `metadata.openclaw.install` на host gateway.
|
||||
- Оператори можуть викликати `skills.update` (`operator.admin`) у двох режимах:
|
||||
- Режим ClawHub оновлює один tracked slug або всі tracked ClawHub installs у
|
||||
default agent workspace.
|
||||
- Config mode виправляє values `skills.entries.<skillKey>`, як-от `enabled`,
|
||||
`apiKey` і `env`.
|
||||
- Режим ClawHub оновлює один tracked slug або всі tracked встановлення ClawHub у робочому просторі агента за замовчуванням.
|
||||
- Режим конфігурації патчить значення `skills.entries.<skillKey>`, як-от `enabled`, `apiKey` і `env`.
|
||||
|
||||
### Подання `models.list`
|
||||
|
||||
`models.list` приймає необов’язковий параметр `view`:
|
||||
|
||||
- Не вказано або `"default"`: поточна поведінка runtime. Якщо налаштовано `agents.defaults.models`, відповідь є дозволеним каталогом; інакше відповідь є повним каталогом Gateway.
|
||||
- `"configured"`: поведінка розміру пікера. Якщо налаштовано `agents.defaults.models`, вона все одно має пріоритет. Інакше відповідь використовує явні записи `models.providers.*.models`, повертаючись до повного каталогу лише тоді, коли налаштованих рядків моделей немає.
|
||||
- `"all"`: повний каталог Gateway, оминаючи `agents.defaults.models`. Використовуйте це для діагностики та інтерфейсів виявлення, а не для звичайних пікерів моделей.
|
||||
- Пропущено або `"default"`: поточна поведінка під час виконання. Якщо налаштовано `agents.defaults.models`, відповіддю буде дозволений каталог; інакше відповіддю буде повний каталог Gateway.
|
||||
- `"configured"`: поведінка, розрахована на розмір засобу вибору. Якщо налаштовано `agents.defaults.models`, він усе одно має пріоритет. Інакше відповідь використовує явні записи `models.providers.*.models`, повертаючись до повного каталогу лише тоді, коли налаштованих рядків моделей немає.
|
||||
- `"all"`: повний каталог Gateway в обхід `agents.defaults.models`. Використовуйте це для діагностики та інтерфейсів виявлення, а не для звичайних засобів вибору моделей.
|
||||
|
||||
## Схвалення exec
|
||||
## Затвердження exec
|
||||
|
||||
- Коли запит exec потребує схвалення, Gateway транслює `exec.approval.requested`.
|
||||
- Клієнти оператора виконують вирішення, викликаючи `exec.approval.resolve` (потрібна область `operator.approvals`).
|
||||
- Для `host=node` `exec.approval.request` має містити `systemRunPlan` (канонічні метадані `argv`/`cwd`/`rawCommand`/сеансу). Запити без `systemRunPlan` відхиляються.
|
||||
- Після схвалення переадресовані виклики `node.invoke system.run` повторно використовують цей канонічний
|
||||
- Коли запит exec потребує затвердження, gateway транслює `exec.approval.requested`.
|
||||
- Клієнти оператора вирішують його викликом `exec.approval.resolve` (потрібна область `operator.approvals`).
|
||||
- Для `host=node` `exec.approval.request` має містити `systemRunPlan` (канонічні `argv`/`cwd`/`rawCommand`/метадані сеансу). Запити без `systemRunPlan` відхиляються.
|
||||
- Після затвердження переслані виклики `node.invoke system.run` повторно використовують цей канонічний
|
||||
`systemRunPlan` як авторитетний контекст команди/cwd/сеансу.
|
||||
- Якщо викликач змінює `command`, `rawCommand`, `cwd`, `agentId` або
|
||||
`sessionKey` між підготовкою та фінальним схваленим переадресуванням `system.run`, Gateway
|
||||
відхиляє запуск замість того, щоб довіряти зміненому payload.
|
||||
`sessionKey` між підготовкою та остаточним затвердженим пересиланням `system.run`, gateway
|
||||
відхиляє запуск замість довіри зміненому корисному навантаженню.
|
||||
|
||||
## Резервна доставка агента
|
||||
## Резервний варіант доставки агента
|
||||
|
||||
- Запити `agent` можуть містити `deliver=true`, щоб запросити вихідну доставку.
|
||||
- `bestEffortDeliver=false` зберігає сувору поведінку: невирішені або лише внутрішні цілі доставки повертають `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` дозволяє резервний перехід до виконання лише в сеансі, коли неможливо визначити зовнішній маршрут доставки (наприклад, внутрішні/webchat-сеанси або неоднозначні багатоканальні конфігурації).
|
||||
- `bestEffortDeliver=false` зберігає сувору поведінку: нерозв’язані або лише внутрішні цілі доставки повертають `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` дозволяє резервний перехід до виконання лише в сеансі, коли неможливо визначити зовнішній маршрут доставки (наприклад, внутрішні/вебчат-сеанси або неоднозначні багатоканальні конфігурації).
|
||||
|
||||
## Версіонування
|
||||
|
||||
@ -553,29 +540,29 @@ Node; сесії без пристрою або без прив’язки по
|
||||
### Константи клієнта
|
||||
|
||||
Еталонний клієнт у `src/gateway/client.ts` використовує ці типові значення. Значення
|
||||
стабільні в межах protocol v3 і є очікуваною базою для сторонніх клієнтів.
|
||||
стабільні в protocol v3 і є очікуваною базою для сторонніх клієнтів.
|
||||
|
||||
| Константа | Типове значення | Джерело |
|
||||
| ----------------------------------------- | ---------------------------------------------------- | --------------------------------------------------------- |
|
||||
| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
|
||||
| Тайм-аут запиту (на RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |
|
||||
| Тайм-аут preauth / connect-challenge | `15_000` ms | `src/gateway/handshake-timeouts.ts` (clamp `250`–`15_000`) |
|
||||
| Початкова затримка повторного підключення | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
|
||||
| Максимальна затримка повторного підключення | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
|
||||
| Обмеження швидкої повторної спроби після закриття device-token | `250` ms | `src/gateway/client.ts` |
|
||||
| Пільговий період force-stop перед `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
|
||||
| Типовий тайм-аут `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
|
||||
| Типовий інтервал tick (до `hello-ok`) | `30_000` ms | `src/gateway/client.ts` |
|
||||
| Закриття через тайм-аут tick | код `4000`, коли тиша перевищує `tickIntervalMs * 2` | `src/gateway/client.ts` |
|
||||
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` |
|
||||
| Константа | Типове значення | Джерело |
|
||||
| ----------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
|
||||
| Час очікування запиту (на RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |
|
||||
| Час очікування preauth / connect-challenge | `15_000` ms | `src/gateway/handshake-timeouts.ts` (config/env можуть збільшити парний бюджет сервера/клієнта) |
|
||||
| Початкова затримка повторного підключення | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
|
||||
| Максимальна затримка повторного підключення | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
|
||||
| Обмеження швидкої повторної спроби після закриття через токен пристрою | `250` ms | `src/gateway/client.ts` |
|
||||
| Пільговий період force-stop перед `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
|
||||
| Типовий час очікування `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
|
||||
| Типовий інтервал такту (до `hello-ok`) | `30_000` ms | `src/gateway/client.ts` |
|
||||
| Закриття через тайм-аут такту | код `4000`, коли тиша перевищує `tickIntervalMs * 2` | `src/gateway/client.ts` |
|
||||
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` |
|
||||
|
||||
Сервер оголошує ефективні `policy.tickIntervalMs`, `policy.maxPayload`
|
||||
та `policy.maxBufferedBytes` у `hello-ok`; клієнти мають дотримуватися цих значень,
|
||||
і `policy.maxBufferedBytes` у `hello-ok`; клієнти мають дотримуватися цих значень,
|
||||
а не типових значень до handshake.
|
||||
|
||||
## Автентифікація
|
||||
|
||||
- Автентифікація Gateway зі спільним секретом використовує `connect.params.auth.token` або
|
||||
- Автентифікація gateway зі спільним секретом використовує `connect.params.auth.token` або
|
||||
`connect.params.auth.password`, залежно від налаштованого режиму автентифікації.
|
||||
- Режими з ідентичністю, як-от Tailscale Serve
|
||||
(`gateway.auth.allowTailscale: true`) або не-loopback
|
||||
@ -583,78 +570,79 @@ Node; сесії без пристрою або без прив’язки по
|
||||
заголовків запиту замість `connect.params.auth.*`.
|
||||
- Private-ingress `gateway.auth.mode: "none"` повністю пропускає автентифікацію підключення зі спільним секретом;
|
||||
не відкривайте цей режим на публічному/ненадійному ingress.
|
||||
- Після pairing Gateway видає **device token**, обмежений роллю підключення
|
||||
- Після спарювання Gateway видає **токен пристрою**, обмежений роллю з’єднання
|
||||
+ областями. Він повертається в `hello-ok.auth.deviceToken` і має
|
||||
зберігатися клієнтом для майбутніх підключень.
|
||||
- Клієнти мають зберігати основний `hello-ok.auth.deviceToken` після будь-якого
|
||||
успішного підключення.
|
||||
- Повторне підключення з цим **збереженим** device token також має повторно використовувати збережений
|
||||
затверджений набір областей для цього токена. Це зберігає доступ read/probe/status,
|
||||
- Повторне підключення з цим **збереженим** токеном пристрою також має повторно використовувати збережений
|
||||
затверджений набір областей для цього токена. Це зберігає доступ читання/перевірки/статусу,
|
||||
який уже було надано, і запобігає непомітному звуженню повторних підключень до
|
||||
вужчої неявної області лише для адміністратора.
|
||||
- Складання автентифікації підключення на боці клієнта (`selectConnectAuth` у
|
||||
`src/gateway/client.ts`):
|
||||
- `auth.password` є ортогональним і завжди пересилається, коли встановлений.
|
||||
- `auth.token` заповнюється в порядку пріоритету: спершу явний спільний токен,
|
||||
потім явний `deviceToken`, потім збережений токен для пристрою (за ключем
|
||||
- `auth.password` є ортогональним і завжди пересилається, коли заданий.
|
||||
- `auth.token` заповнюється в порядку пріоритету: спочатку явний спільний токен,
|
||||
потім явний `deviceToken`, потім збережений токен для пристрою (з ключем за
|
||||
`deviceId` + `role`).
|
||||
- `auth.bootstrapToken` надсилається лише тоді, коли жоден із наведених вище варіантів не визначив
|
||||
`auth.token`. Спільний токен або будь-який визначений device token пригнічує його.
|
||||
- Автопідвищення збереженого device token під час одноразової
|
||||
повторної спроби `AUTH_TOKEN_MISMATCH` обмежене **лише довіреними endpoints** —
|
||||
`auth.token`. Спільний токен або будь-який визначений токен пристрою його пригнічує.
|
||||
- Автоматичне підвищення збереженого токена пристрою під час одноразової
|
||||
повторної спроби `AUTH_TOKEN_MISMATCH` обмежене **лише довіреними endpoint** —
|
||||
loopback або `wss://` із закріпленим `tlsFingerprint`. Публічний `wss://`
|
||||
без закріплення не підходить.
|
||||
без закріплення не відповідає вимогам.
|
||||
- Додаткові записи `hello-ok.auth.deviceTokens` є токенами передачі bootstrap.
|
||||
Зберігайте їх лише тоді, коли підключення використовувало bootstrap-автентифікацію на довіреному транспорті,
|
||||
як-от `wss://` або loopback/local pairing.
|
||||
- Якщо клієнт надає **явний** `deviceToken` або явні `scopes`, цей
|
||||
запитаний викликачем набір областей залишається авторитетним; кешовані області
|
||||
повторно використовуються лише тоді, коли клієнт повторно використовує збережений токен для пристрою.
|
||||
- Device tokens можна ротувати/відкликати через `device.token.rotate` та
|
||||
запитаний викликачем набір областей лишається авторитетним; кешовані області лише
|
||||
повторно використовуються, коли клієнт повторно використовує збережений токен для пристрою.
|
||||
- Токени пристроїв можна обертати/відкликати через `device.token.rotate` і
|
||||
`device.token.revoke` (потрібна область `operator.pairing`).
|
||||
- `device.token.rotate` повертає метадані ротації. Він віддзеркалює замінний
|
||||
bearer token лише для викликів із того самого пристрою, які вже автентифіковані цим
|
||||
device token, щоб клієнти лише з токеном могли зберегти заміну перед
|
||||
повторним підключенням. Ротації shared/admin не віддзеркалюють bearer token.
|
||||
- Видача, ротація та відкликання токенів залишаються обмеженими затвердженим набором ролей,
|
||||
записаним у pairing-записі цього пристрою; мутація токена не може розширити або
|
||||
націлити роль пристрою, якої pairing approval ніколи не надавало.
|
||||
- Для сеансів токенів paired-device керування пристроєм є self-scoped, якщо
|
||||
викликач також не має `operator.admin`: викликачі без прав адміністратора можуть видаляти/відкликати/ротувати
|
||||
bearer-токен лише для викликів із того самого пристрою, які вже автентифіковані цим
|
||||
токеном пристрою, щоб клієнти лише з токеном могли зберегти заміну перед
|
||||
повторним підключенням. Спільні/адміністративні ротації не віддзеркалюють bearer-токен.
|
||||
- Випуск, ротація та відкликання токенів залишаються обмеженими затвердженим набором ролей,
|
||||
записаним у записі спарювання цього пристрою; зміна токена не може розширити або
|
||||
націлити роль пристрою, яку затвердження спарювання ніколи не надавало.
|
||||
- Для сеансів токенів спарених пристроїв керування пристроями має самостійну область, якщо
|
||||
викликач також не має `operator.admin`: викликачі без прав адміністратора можуть видаляти/відкликати/обертати
|
||||
лише **власний** запис пристрою.
|
||||
- `device.token.rotate` і `device.token.revoke` також перевіряють цільовий набір областей operator
|
||||
- `device.token.rotate` і `device.token.revoke` також перевіряють набір областей цільового operator
|
||||
token щодо поточних областей сеансу викликача. Викликачі без прав адміністратора
|
||||
не можуть ротувати або відкликати ширший operator token, ніж уже мають.
|
||||
- Збої автентифікації містять `error.details.code` плюс підказки відновлення:
|
||||
не можуть обертати або відкликати ширший operator token, ніж уже мають.
|
||||
- Збої автентифікації містять `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`), отриману з
|
||||
відбитка keypair.
|
||||
- Gateway видають токени для пристрою + ролі.
|
||||
- Pairing approvals потрібні для нових ідентифікаторів пристроїв, якщо не ввімкнено локальне автоматичне схвалення.
|
||||
- Автоматичне схвалення pairing зосереджене на прямих підключеннях local loopback.
|
||||
- OpenClaw також має вузький backend/container-local шлях самопідключення для
|
||||
довірених допоміжних потоків зі спільним секретом.
|
||||
- Підключення з того самого хоста через tailnet або LAN усе одно вважаються віддаленими для pairing і
|
||||
потребують схвалення.
|
||||
відбитка пари ключів.
|
||||
- Gateway видають токени на пристрій + роль.
|
||||
- Затвердження спарювання потрібні для нових ідентифікаторів пристроїв, якщо локальне автоматичне затвердження
|
||||
не ввімкнено.
|
||||
- Автоматичне затвердження спарювання зосереджене на прямих підключеннях local loopback.
|
||||
- OpenClaw також має вузький шлях самопідключення всередині backend/container для
|
||||
довірених helper-потоків зі спільним секретом.
|
||||
- Підключення same-host tailnet або LAN усе ще розглядаються як віддалені для спарювання і
|
||||
потребують затвердження.
|
||||
- WS-клієнти зазвичай містять ідентичність `device` під час `connect` (operator +
|
||||
node). Єдині винятки operator без пристрою — явні довірені шляхи:
|
||||
- `gateway.controlUi.allowInsecureAuth=true` для localhost-only insecure HTTP compatibility.
|
||||
- успішна автентифікація operator Control UI `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (break-glass, серйозне зниження безпеки).
|
||||
- direct-loopback backend RPCs `gateway-client`, автентифіковані спільним
|
||||
gateway token/password.
|
||||
- Усі підключення мають підписувати наданий сервером nonce `connect.challenge`.
|
||||
node). Єдині винятки для операторів без пристрою — явні довірчі шляхи:
|
||||
- `gateway.controlUi.allowInsecureAuth=true` для сумісності з небезпечним HTTP лише на localhost.
|
||||
- успішна автентифікація operator Control UI з `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (аварійний режим, серйозне зниження безпеки).
|
||||
- прямі loopback backend RPC `gateway-client`, автентифіковані спільним
|
||||
токеном/паролем gateway.
|
||||
- Усі з’єднання мають підписувати наданий сервером nonce `connect.challenge`.
|
||||
|
||||
### Діагностика міграції автентифікації пристрою
|
||||
### Діагностика міграції автентифікації пристроїв
|
||||
|
||||
Для застарілих клієнтів, які досі використовують поведінку підписування до challenge, `connect` тепер повертає
|
||||
Для застарілих клієнтів, які все ще використовують поведінку підписування до challenge, `connect` тепер повертає
|
||||
коди деталей `DEVICE_AUTH_*` у `error.details.code` зі стабільним `error.details.reason`.
|
||||
|
||||
Поширені збої міграції:
|
||||
@ -662,35 +650,35 @@ Node; сесії без пристрою або без прив’язки по
|
||||
| Повідомлення | 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` | Підписана мітка часу виходить за межі дозволеного skew. |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Клієнт підписав застарілим/неправильним nonce. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Корисне навантаження підпису не відповідає payload v2. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Підписаний timestamp виходить за межі дозволеного skew. |
|
||||
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` не відповідає відбитку публічного ключа. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Формат/канонікалізація публічного ключа не вдалася. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Формат/канонікалізація публічного ключа не вдалися. |
|
||||
|
||||
Ціль міграції:
|
||||
|
||||
- Завжди чекайте на `connect.challenge`.
|
||||
- Підписуйте payload v2, який містить server nonce.
|
||||
- Підписуйте payload v2, який містить nonce сервера.
|
||||
- Надсилайте той самий nonce у `connect.params.device.nonce`.
|
||||
- Бажаний payload підпису — `v3`, який прив’язує `platform` і `deviceFamily`
|
||||
- Бажане корисне навантаження підпису — `v3`, яке прив’язує `platform` і `deviceFamily`
|
||||
на додачу до полів device/client/role/scopes/token/nonce.
|
||||
- Застарілі підписи `v2` залишаються прийнятими для сумісності, але закріплення метаданих paired-device
|
||||
усе одно контролює політику команд під час повторного підключення.
|
||||
- Застарілі підписи `v2` залишаються прийнятими для сумісності, але закріплення metadata
|
||||
спареного пристрою все одно керує політикою команд під час повторного підключення.
|
||||
|
||||
## TLS + закріплення
|
||||
|
||||
- TLS підтримується для WS-з’єднань.
|
||||
- Клієнти можуть необов’язково закріпити відбиток сертифіката Gateway (див. конфігурацію `gateway.tls`
|
||||
плюс `gateway.remote.tlsFingerprint` або CLI `--tls-fingerprint`).
|
||||
- Клієнти можуть за потреби закріпити відбиток сертифіката Gateway (див. конфігурацію `gateway.tls`
|
||||
разом із `gateway.remote.tlsFingerprint` або CLI `--tls-fingerprint`).
|
||||
|
||||
## Область
|
||||
## Обсяг
|
||||
|
||||
Цей протокол відкриває **повний API Gateway** (status, channels, models, chat,
|
||||
agent, sessions, nodes, approvals тощо). Точна поверхня визначена
|
||||
схемами TypeBox у `src/gateway/protocol/schema.ts`.
|
||||
Цей протокол надає **повний API Gateway** (статус, канали, моделі, чат,
|
||||
агент, сесії, вузли, схвалення тощо). Точну поверхню визначено схемами
|
||||
TypeBox у `src/gateway/protocol/schema.ts`.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Протокол мосту](/uk/gateway/bridge-protocol)
|
||||
- [Операційний посібник Gateway](/uk/gateway)
|
||||
- [Протокол Bridge](/uk/gateway/bridge-protocol)
|
||||
- [Runbook Gateway](/uk/gateway)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user