chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
d8b90e79ab
commit
30732dff86
@ -1,56 +1,57 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви створюєте зовнішній застосунок, скрипт, панель моніторингу, завдання CI або розширення IDE, що взаємодіє з OpenClaw
|
||||
- Ви створюєте зовнішній застосунок, скрипт, панель моніторингу, завдання CI або розширення IDE, яке взаємодіє з OpenClaw
|
||||
- Ви обираєте між App SDK і Plugin SDK
|
||||
- Ви інтегруєтеся з виконаннями агентів Gateway, сеансами, подіями, схваленнями, моделями або інструментами
|
||||
- Ви інтегруєтеся із запусками агентів Gateway, сеансами, подіями, схваленнями, моделями або інструментами
|
||||
sidebarTitle: App SDK
|
||||
summary: Публічний OpenClaw App SDK для зовнішніх застосунків, скриптів, панелей моніторингу, завдань CI та розширень IDE
|
||||
summary: Публічний SDK OpenClaw App для зовнішніх застосунків, скриптів, дашбордів, завдань CI та розширень IDE
|
||||
title: SDK застосунку OpenClaw
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T00:39:41Z"
|
||||
generated_at: "2026-05-01T08:21:08Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: e531e985ca82026b230b03f8df5ab908d66e2b608e09c46af2ec060b9def0c24
|
||||
source_hash: a6b22e9f4f809a572cfd19fd22f633a706dd23b8bee2f3c244003a0861a41073
|
||||
source_path: concepts/openclaw-sdk.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
The **OpenClaw App SDK** — це публічний клієнтський API для застосунків поза процесом
|
||||
OpenClaw. Використовуйте `@openclaw/sdk`, коли скрипт, панель керування, завдання CI, розширення IDE
|
||||
або інший зовнішній застосунок хоче підключитися до Gateway, запускати виконання агентів,
|
||||
транслювати події, чекати на результати, скасовувати роботу або перевіряти ресурси Gateway.
|
||||
**OpenClaw App SDK** — це публічний клієнтський API для застосунків поза
|
||||
процесом OpenClaw. Використовуйте `@openclaw/sdk`, коли скрипт, dashboard, завдання CI, IDE
|
||||
extension або інший зовнішній застосунок хоче підключитися до Gateway, запускати
|
||||
запуски агентів, транслювати події, чекати результатів, скасовувати роботу або переглядати
|
||||
ресурси Gateway.
|
||||
|
||||
<Note>
|
||||
App SDK відрізняється від [Plugin SDK](/uk/plugins/sdk-overview).
|
||||
`@openclaw/sdk` взаємодіє з Gateway ззовні OpenClaw.
|
||||
`openclaw/plugin-sdk/*` призначений лише для plugins, які працюють усередині OpenClaw і
|
||||
реєструють провайдери, канали, інструменти, хуки або довірені середовища виконання.
|
||||
`openclaw/plugin-sdk/*` призначений лише для plugins, які виконуються всередині OpenClaw і
|
||||
реєструють провайдерів, канали, інструменти, hooks або довірені runtime.
|
||||
</Note>
|
||||
|
||||
## Що постачається сьогодні
|
||||
|
||||
`@openclaw/sdk` постачається з:
|
||||
|
||||
| Поверхня | Статус | Що вона робить |
|
||||
| ------------------------- | ------- | ---------------------------------------------------------------------------- |
|
||||
| `OpenClaw` | Готово | Головна точка входу клієнта. Керує транспортом, підключенням, запитами та подіями. |
|
||||
| `GatewayClientTransport` | Готово | WebSocket-транспорт на базі клієнта Gateway. |
|
||||
| `oc.agents` | Готово | Перелічує, створює, оновлює, видаляє та отримує дескриптори агентів. |
|
||||
| `Agent.run()` | Готово | Запускає виконання Gateway `agent` і повертає `Run`. |
|
||||
| `oc.runs` | Готово | Створює, отримує, очікує, скасовує та транслює виконання. |
|
||||
| `Run.events()` | Готово | Транслює нормалізовані події окремого виконання з повтором для швидких виконань. |
|
||||
| `Run.wait()` | Готово | Викликає `agent.wait` і повертає стабільний `RunResult`. |
|
||||
| `Run.cancel()` | Готово | Викликає `sessions.abort` за id виконання, із ключем сесії, коли він доступний. |
|
||||
| `oc.sessions` | Готово | Створює, розв’язує, надсилає до, патчить, стискає та отримує дескриптори сесій. |
|
||||
| `Session.send()` | Готово | Викликає `sessions.send` і повертає `Run`. |
|
||||
| `oc.models` | Готово | Викликає `models.list` і поточний статусний RPC `models.authStatus`. |
|
||||
| `oc.tools` | Частково | Перелічує каталог інструментів і ефективні інструменти; прямий виклик інструментів не підключено. |
|
||||
| `oc.artifacts` | Готово | Перелічує, отримує та завантажує артефакти транскриптів Gateway. |
|
||||
| `oc.approvals` | Готово | Перелічує та розв’язує схвалення exec через RPC схвалень Gateway. |
|
||||
| `oc.rawEvents()` | Готово | Надає сирі події Gateway для просунутих споживачів. |
|
||||
| `normalizeGatewayEvent()` | Готово | Перетворює сирі події Gateway на стабільну форму події SDK. |
|
||||
| Поверхня | Статус | Що вона робить |
|
||||
| ------------------------- | ------ | -------------------------------------------------------------------------- |
|
||||
| `OpenClaw` | Готово | Основна точка входу клієнта. Керує transport, з’єднанням, запитами та подіями. |
|
||||
| `GatewayClientTransport` | Готово | WebSocket transport на основі клієнта Gateway. |
|
||||
| `oc.agents` | Готово | Перелічує, створює, оновлює, видаляє та отримує дескриптори агентів. |
|
||||
| `Agent.run()` | Готово | Запускає запуск Gateway `agent` і повертає `Run`. |
|
||||
| `oc.runs` | Готово | Створює, отримує, очікує, скасовує та транслює запуски. |
|
||||
| `Run.events()` | Готово | Транслює нормалізовані події окремого запуску з replay для швидких запусків. |
|
||||
| `Run.wait()` | Готово | Викликає `agent.wait` і повертає стабільний `RunResult`. |
|
||||
| `Run.cancel()` | Готово | Викликає `sessions.abort` за id запуску, із ключем сеансу, коли він доступний. |
|
||||
| `oc.sessions` | Готово | Створює, розв’язує, надсилає в, патчить, стискає та отримує дескриптори сеансів. |
|
||||
| `Session.send()` | Готово | Викликає `sessions.send` і повертає `Run`. |
|
||||
| `oc.models` | Готово | Викликає `models.list` і поточний status RPC `models.authStatus`. |
|
||||
| `oc.tools` | Готово | Перелічує, обмежує scope та викликає інструменти Gateway через policy pipeline. |
|
||||
| `oc.artifacts` | Готово | Перелічує, отримує та завантажує артефакти transcript Gateway. |
|
||||
| `oc.approvals` | Готово | Перелічує та розв’язує exec approvals через approval RPCs Gateway. |
|
||||
| `oc.rawEvents()` | Готово | Надає raw події Gateway для досвідчених споживачів. |
|
||||
| `normalizeGatewayEvent()` | Готово | Перетворює raw події Gateway на стабільну форму подій SDK. |
|
||||
|
||||
SDK також експортує основні типи, які використовують ці поверхні:
|
||||
SDK також експортує базові типи, які використовують ці поверхні:
|
||||
`AgentRunParams`, `RunResult`, `RunStatus`, `OpenClawEvent`,
|
||||
`OpenClawEventType`, `GatewayEvent`, `OpenClawTransport`,
|
||||
`GatewayRequestOptions`, `SessionCreateParams`, `SessionSendParams`,
|
||||
@ -61,8 +62,8 @@ SDK також експортує основні типи, які викорис
|
||||
|
||||
## Підключення до Gateway
|
||||
|
||||
Створіть клієнт із явною URL-адресою Gateway або інжектуйте власний транспорт для
|
||||
тестів і вбудованих середовищ виконання застосунків.
|
||||
Створіть клієнт із явним URL Gateway або інжектуйте власний transport для
|
||||
тестів і runtime вбудованих застосунків.
|
||||
|
||||
```typescript
|
||||
import { OpenClaw } from "@openclaw/sdk";
|
||||
@ -76,8 +77,8 @@ const oc = new OpenClaw({
|
||||
await oc.connect();
|
||||
```
|
||||
|
||||
`new OpenClaw({ gateway: "ws://..." })` еквівалентний `url`. Опцію
|
||||
`gateway: "auto"` приймає конструктор, але автоматичне виявлення Gateway
|
||||
`new OpenClaw({ gateway: "ws://..." })` еквівалентний `url`. Опція
|
||||
`gateway: "auto"` приймається конструктором, але автоматичне виявлення Gateway
|
||||
ще не є окремою функцією SDK; передавайте `url`, коли застосунок ще не знає,
|
||||
як виявити Gateway.
|
||||
|
||||
@ -120,18 +121,18 @@ const result = await run.wait({ timeoutMs: 120_000 });
|
||||
console.log(result.status);
|
||||
```
|
||||
|
||||
Посилання на моделі з кваліфікацією провайдера, як-от `openai/gpt-5.5`, розділяються на Gateway
|
||||
перевизначення `provider` і `model`. `timeoutMs` залишається в мілісекундах у SDK і
|
||||
перетворюється на секунди тайм-ауту Gateway для RPC `agent`.
|
||||
Посилання на моделі з указанням провайдера, як-от `openai/gpt-5.5`, розділяються на Gateway
|
||||
override для `provider` і `model`. `timeoutMs` лишається в SDK у мілісекундах і
|
||||
перетворюється на секунди timeout Gateway для RPC `agent`.
|
||||
|
||||
`run.wait()` використовує RPC Gateway `agent.wait`. Дедлайн очікування, який спливає,
|
||||
поки виконання ще активне, повертає `status: "accepted"` замість того, щоб удавати,
|
||||
ніби саме виконання вичерпало час. Тайм-аути середовища виконання, перервані виконання та скасовані виконання
|
||||
`run.wait()` використовує RPC Gateway `agent.wait`. Deadline очікування, який спливає,
|
||||
поки запуск ще активний, повертає `status: "accepted"` замість того, щоб удавати,
|
||||
ніби сам запуск вичерпав час. Runtime timeouts, перервані запуски та скасовані запуски
|
||||
нормалізуються в `timed_out` або `cancelled`.
|
||||
|
||||
## Створення та повторне використання сесій
|
||||
## Створення та повторне використання сеансів
|
||||
|
||||
Використовуйте сесії, коли застосунку потрібен тривалий стан транскрипту.
|
||||
Використовуйте сеанси, коли застосунку потрібен стійкий стан transcript.
|
||||
|
||||
```typescript
|
||||
const session = await oc.sessions.create({
|
||||
@ -143,7 +144,7 @@ const run = await session.send("Prepare release notes from the current diff.");
|
||||
await run.wait();
|
||||
```
|
||||
|
||||
`Session.send()` викликає `sessions.send` і повертає `Run`. Дескриптори сесій також
|
||||
`Session.send()` викликає `sessions.send` і повертає `Run`. Дескриптори сеансів також
|
||||
підтримують:
|
||||
|
||||
```typescript
|
||||
@ -154,7 +155,7 @@ await session.compact({ maxLines: 200 });
|
||||
|
||||
## Трансляція подій
|
||||
|
||||
SDK нормалізує сирі події Gateway у стабільну оболонку `OpenClawEvent`:
|
||||
SDK нормалізує raw події Gateway у стабільний envelope `OpenClawEvent`:
|
||||
|
||||
```typescript
|
||||
type OpenClawEvent = {
|
||||
@ -174,31 +175,31 @@ type OpenClawEvent = {
|
||||
|
||||
Поширені типи подій включають:
|
||||
|
||||
| Тип події | Вихідна подія Gateway |
|
||||
| Тип події | Подія Gateway-джерела |
|
||||
| --------------------- | ------------------------------------------- |
|
||||
| `run.started` | Початок життєвого циклу `agent` |
|
||||
| `run.completed` | Кінець життєвого циклу `agent` |
|
||||
| `run.failed` | Помилка життєвого циклу `agent` |
|
||||
| `run.cancelled` | Кінець перерваного/скасованого життєвого циклу |
|
||||
| `run.timed_out` | Кінець життєвого циклу через тайм-аут |
|
||||
| `assistant.delta` | Потокова дельта асистента |
|
||||
| `run.started` | Початок lifecycle `agent` |
|
||||
| `run.completed` | Завершення lifecycle `agent` |
|
||||
| `run.failed` | Помилка lifecycle `agent` |
|
||||
| `run.cancelled` | Завершення перерваного/скасованого lifecycle |
|
||||
| `run.timed_out` | Завершення lifecycle через timeout |
|
||||
| `assistant.delta` | Streaming delta асистента |
|
||||
| `assistant.message` | Повідомлення асистента |
|
||||
| `thinking.delta` | Потік міркувань або плану |
|
||||
| `tool.call.started` | Початок інструмента/елемента/команди |
|
||||
| `tool.call.delta` | Оновлення інструмента/елемента/команди |
|
||||
| `tool.call.completed` | Завершення інструмента/елемента/команди |
|
||||
| `tool.call.failed` | Помилка інструмента/елемента/команди або заблокований статус |
|
||||
| `approval.requested` | Запит на схвалення exec або Plugin |
|
||||
| `approval.resolved` | Розв’язання схвалення exec або Plugin |
|
||||
| `thinking.delta` | Потік мислення або плану |
|
||||
| `tool.call.started` | Початок інструмента/item/команди |
|
||||
| `tool.call.delta` | Оновлення інструмента/item/команди |
|
||||
| `tool.call.completed` | Завершення інструмента/item/команди |
|
||||
| `tool.call.failed` | Збій інструмента/item/команди або заблокований статус |
|
||||
| `approval.requested` | Запит exec або plugin approval |
|
||||
| `approval.resolved` | Розв’язання exec або plugin approval |
|
||||
| `session.created` | Створення `sessions.changed` |
|
||||
| `session.updated` | Оновлення `sessions.changed` |
|
||||
| `session.compacted` | Compaction `sessions.changed` |
|
||||
| `task.updated` | Події оновлення завдання |
|
||||
| `artifact.updated` | Події потоку патчів |
|
||||
| `raw` | Будь-яка подія, яка ще не має стабільного зіставлення SDK |
|
||||
| `artifact.updated` | Події patch stream |
|
||||
| `raw` | Будь-яка подія, яка ще не має стабільного SDK mapping |
|
||||
|
||||
`Run.events()` фільтрує події до одного id виконання та повторює вже побачені події для
|
||||
швидких виконань. Це означає, що задокументований потік безпечний:
|
||||
`Run.events()` фільтрує події до одного id запуску та відтворює вже побачені події для
|
||||
швидких запусків. Це означає, що документований потік безпечний:
|
||||
|
||||
```typescript
|
||||
const run = await agent.run("Summarize the latest session.");
|
||||
@ -210,27 +211,35 @@ for await (const event of run.events()) {
|
||||
}
|
||||
```
|
||||
|
||||
Для потоків на рівні всього застосунку використовуйте `oc.events()`. Для сирих кадрів Gateway використовуйте
|
||||
Для потоків усього застосунку використовуйте `oc.events()`. Для raw frames Gateway використовуйте
|
||||
`oc.rawEvents()`.
|
||||
|
||||
## Моделі, інструменти, артефакти та схвалення
|
||||
## Моделі, інструменти, артефакти та approvals
|
||||
|
||||
Допоміжні функції моделей відповідають поточним методам Gateway:
|
||||
Допоміжні функції моделей відображаються на поточні методи Gateway:
|
||||
|
||||
```typescript
|
||||
await oc.models.list();
|
||||
await oc.models.status({ probe: false }); // calls models.authStatus
|
||||
```
|
||||
|
||||
Допоміжні функції інструментів надають каталог Gateway і подання ефективних інструментів:
|
||||
Допоміжні функції інструментів надають каталог Gateway, effective tool view і прямий
|
||||
виклик інструментів Gateway. `oc.tools.invoke()` повертає типізований envelope замість
|
||||
викидання помилки для policy або approval refusals.
|
||||
|
||||
```typescript
|
||||
await oc.tools.list();
|
||||
await oc.tools.effective({ sessionKey: "main" });
|
||||
await oc.tools.invoke("tool-name", {
|
||||
args: { input: "value" },
|
||||
sessionKey: "main",
|
||||
confirm: false,
|
||||
idempotencyKey: "tool-call-1",
|
||||
});
|
||||
```
|
||||
|
||||
Допоміжні функції артефактів надають проєкцію артефактів Gateway для контексту сесії, виконання або
|
||||
завдання. Кожен виклик вимагає одну явну область `sessionKey`, `runId` або
|
||||
Допоміжні функції артефактів надають projection артефактів Gateway для контексту сеансу, запуску або
|
||||
завдання. Кожен виклик вимагає одного явного scope `sessionKey`, `runId` або
|
||||
`taskId`:
|
||||
|
||||
```typescript
|
||||
@ -244,34 +253,33 @@ if (first) {
|
||||
}
|
||||
```
|
||||
|
||||
Допоміжні функції схвалень використовують RPC схвалень exec:
|
||||
Допоміжні функції approvals використовують exec approval RPCs:
|
||||
|
||||
```typescript
|
||||
const approvals = await oc.approvals.list();
|
||||
await oc.approvals.respond("approval-id", { decision: "approve" });
|
||||
```
|
||||
|
||||
## Явно непідтримуване сьогодні
|
||||
## Явно не підтримується сьогодні
|
||||
|
||||
SDK містить назви для продуктової моделі, яку ми хочемо, але він не вдає мовчки,
|
||||
ніби RPC Gateway існують. Зараз ці виклики кидають явні помилки непідтримуваності:
|
||||
SDK включає назви для моделі продукту, якої ми прагнемо, але він не вдає мовчки,
|
||||
що RPCs Gateway існують. Ці виклики наразі викидають явні помилки про
|
||||
непідтримуваність:
|
||||
|
||||
```typescript
|
||||
await oc.tasks.list();
|
||||
await oc.tasks.get("task-id");
|
||||
await oc.tasks.cancel("task-id");
|
||||
|
||||
await oc.tools.invoke("tool-name", {});
|
||||
|
||||
await oc.environments.list();
|
||||
await oc.environments.create({});
|
||||
await oc.environments.status("environment-id");
|
||||
await oc.environments.delete("environment-id");
|
||||
```
|
||||
|
||||
Поля окремого виконання `workspace`, `runtime`, `environment` і `approvals` типізовані
|
||||
як майбутня форма, але поточний Gateway не підтримує ці перевизначення в
|
||||
RPC `agent`. Якщо викликачі передають їх, SDK кидає помилку перед надсиланням виконання,
|
||||
Поля окремого запуску `workspace`, `runtime`, `environment` і `approvals` типізовані
|
||||
як майбутня форма, але поточний Gateway не підтримує ці overrides в
|
||||
RPC `agent`. Якщо викликачі передають їх, SDK викидає помилку до надсилання запуску,
|
||||
щоб робота випадково не виконалася з типовою поведінкою workspace, runtime,
|
||||
environment або approval.
|
||||
|
||||
@ -279,31 +287,31 @@ environment або approval.
|
||||
|
||||
Використовуйте App SDK, коли код живе поза OpenClaw:
|
||||
|
||||
- Node-скрипти, які запускають або спостерігають виконання агентів
|
||||
- завдання CI, які викликають Gateway
|
||||
- панелі керування та адміністративні панелі
|
||||
- розширення IDE
|
||||
- зовнішні мости, яким не потрібно ставати channel plugins
|
||||
- інтеграційні тести з фейковими або реальними транспортами Gateway
|
||||
- Node scripts, які запускають або спостерігають запуски агентів
|
||||
- Завдання CI, які викликають Gateway
|
||||
- dashboards і панелі адміністрування
|
||||
- IDE extensions
|
||||
- зовнішні bridges, яким не потрібно ставати channel plugins
|
||||
- інтеграційні тести з fake або real transports Gateway
|
||||
|
||||
Використовуйте Plugin SDK, коли код працює всередині OpenClaw:
|
||||
Використовуйте Plugin SDK, коли код виконується всередині OpenClaw:
|
||||
|
||||
- provider plugins
|
||||
- channel plugins
|
||||
- хуки інструментів або життєвого циклу
|
||||
- agent harness plugins
|
||||
- довірені допоміжні засоби середовища виконання
|
||||
- hooks інструментів або lifecycle
|
||||
- plugins agent harness
|
||||
- довірені runtime helpers
|
||||
|
||||
Код App SDK має імпортувати з `@openclaw/sdk`. Код Plugin має імпортувати з
|
||||
задокументованих підшляхів `openclaw/plugin-sdk/*`. Не змішуйте ці два контракти.
|
||||
документованих subpaths `openclaw/plugin-sdk/*`. Не змішуйте ці два контракти.
|
||||
|
||||
## Пов’язані документи
|
||||
|
||||
- [Дизайн API OpenClaw App SDK](/uk/reference/openclaw-sdk-api-design)
|
||||
- [Довідник RPC Gateway](/uk/reference/rpc)
|
||||
- [Цикл агента](/uk/concepts/agent-loop)
|
||||
- [Середовища виконання агентів](/uk/concepts/agent-runtimes)
|
||||
- [Сесії](/uk/concepts/session)
|
||||
- [Runtime агентів](/uk/concepts/agent-runtimes)
|
||||
- [Сеанси](/uk/concepts/session)
|
||||
- [Фонові завдання](/uk/automation/tasks)
|
||||
- [Агенти ACP](/uk/tools/acp-agents)
|
||||
- [Огляд Plugin SDK](/uk/plugins/sdk-overview)
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Реалізація або оновлення WS-клієнтів Gateway
|
||||
- Налагодження невідповідностей протоколу або помилок підключення
|
||||
- Налагодження невідповідностей протоколу або збоїв підключення
|
||||
- Повторне генерування схеми/моделей протоколу
|
||||
summary: 'Протокол WebSocket Gateway: рукостискання, фрейми, версіонування'
|
||||
summary: 'Протокол WebSocket Gateway: рукостискання, кадри, версіонування'
|
||||
title: Протокол Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T00:39:39Z"
|
||||
generated_at: "2026-05-01T08:21:03Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: a6da9ce755b941789ae6b9e866247c8bebb86e9a1530fb8cb258fb0650b24b8a
|
||||
source_hash: 1b80ee7d9a36f78b05b8ca83d70baf6ec53fc907ca25e8b4c2ab39350ff95c54
|
||||
source_path: gateway/protocol.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -24,13 +24,13 @@ OpenClaw. Усі клієнти (CLI, вебінтерфейс, застосун
|
||||
- WebSocket, текстові кадри з JSON-навантаженнями.
|
||||
- Перший кадр **має** бути запитом `connect`.
|
||||
- Кадри до підключення обмежені 64 KiB. Після успішного рукостискання клієнти
|
||||
мають дотримуватися лімітів `hello-ok.policy.maxPayload` і
|
||||
мають дотримуватися обмежень `hello-ok.policy.maxPayload` і
|
||||
`hello-ok.policy.maxBufferedBytes`. Коли діагностику ввімкнено,
|
||||
завеликі вхідні кадри та повільні вихідні буфери випускають події
|
||||
завеликі вхідні кадри та повільні вихідні буфери створюють події
|
||||
`payload.large` перед тим, як Gateway закриє або відкине відповідний кадр.
|
||||
Ці події зберігають розміри, ліміти, поверхні та безпечні коди причин. Вони
|
||||
не зберігають тіло повідомлення, вміст вкладень, сире тіло кадру, токени,
|
||||
cookie або секретні значення.
|
||||
Ці події зберігають розміри, обмеження, поверхні та безпечні коди причин.
|
||||
Вони не зберігають тіло повідомлення, вміст вкладень, сире тіло кадру,
|
||||
токени, cookies або секретні значення.
|
||||
|
||||
## Рукостискання (connect)
|
||||
|
||||
@ -105,18 +105,18 @@ Gateway → Клієнт:
|
||||
}
|
||||
```
|
||||
|
||||
Поки Gateway ще завершує запуск sidecar-компонентів, запит `connect` може
|
||||
повернути повторювану помилку `UNAVAILABLE` з `details.reason`, встановленим у
|
||||
`"startup-sidecars"`, і `retryAfterMs`. Клієнти мають повторити таку відповідь
|
||||
Поки Gateway ще завершує запуск побічних процесів, запит `connect` може
|
||||
повернути повторювану помилку `UNAVAILABLE` з `details.reason`, установленим у
|
||||
`"startup-sidecars"`, і `retryAfterMs`. Клієнти мають повторити цю відповідь
|
||||
у межах свого загального бюджету підключення, а не показувати її як остаточний
|
||||
збій рукостискання.
|
||||
|
||||
`server`, `features`, `snapshot` і `policy` усі є обов’язковими за схемою
|
||||
`server`, `features`, `snapshot` і `policy` є обов’язковими за схемою
|
||||
(`src/gateway/protocol/schema/frames.ts`). `auth` також є обов’язковим і
|
||||
повідомляє узгоджену роль/області дії. `canvasHostUrl` є необов’язковим.
|
||||
|
||||
Коли токен пристрою не видано, `hello-ok.auth` повідомляє узгоджені
|
||||
дозволи без полів токена:
|
||||
Коли токен пристрою не видано, `hello-ok.auth` повідомляє узгоджені дозволи
|
||||
без полів токена:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -127,15 +127,15 @@ Gateway → Клієнт:
|
||||
}
|
||||
```
|
||||
|
||||
Довірені серверні клієнти в тому самому процесі (`client.id: "gateway-client"`,
|
||||
`client.mode: "backend"`) можуть опускати `device` для прямих підключень
|
||||
local loopback, коли вони автентифікуються спільним токеном/паролем Gateway. Цей
|
||||
шлях зарезервований для внутрішніх RPC площини керування й не дає застарілим
|
||||
базовим станам спарювання CLI/пристрою блокувати локальну серверну роботу,
|
||||
наприклад оновлення сесій субагентів. Віддалені клієнти, клієнти з браузерним
|
||||
Довірені backend-клієнти в тому самому процесі (`client.id: "gateway-client"`,
|
||||
`client.mode: "backend"`) можуть не передавати `device` для прямих loopback-з’єднань,
|
||||
коли вони автентифікуються спільним токеном/паролем Gateway. Цей шлях
|
||||
зарезервований для внутрішніх RPC площини керування і не дає застарілим
|
||||
базовим станам сполучення CLI/пристрою блокувати локальну backend-роботу,
|
||||
таку як оновлення сеансів субагентів. Віддалені клієнти, клієнти з браузерним
|
||||
походженням, клієнти-вузли та явні клієнти з токеном пристрою/ідентичністю
|
||||
пристрою й надалі використовують звичайні перевірки спарювання та підвищення
|
||||
областей дії.
|
||||
пристрою й далі використовують звичайні перевірки сполучення та підвищення
|
||||
області дії.
|
||||
|
||||
Коли токен пристрою видано, `hello-ok` також містить:
|
||||
|
||||
@ -149,8 +149,8 @@ local loopback, коли вони автентифікуються спільн
|
||||
}
|
||||
```
|
||||
|
||||
Під час довіреної передачі bootstrap `hello-ok.auth` також може містити додаткові
|
||||
обмежені записи ролей у `deviceTokens`:
|
||||
Під час довіреної передачі bootstrap `hello-ok.auth` також може містити
|
||||
додаткові обмежені записи ролей у `deviceTokens`:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -169,13 +169,13 @@ local loopback, коли вони автентифікуються спільн
|
||||
}
|
||||
```
|
||||
|
||||
Для вбудованого bootstrap-потоку вузол/оператор основний токен вузла лишається
|
||||
`scopes: []`, а будь-який переданий токен оператора лишається обмеженим
|
||||
дозволеним списком bootstrap-оператора (`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). Перевірки областей дії bootstrap
|
||||
лишаються префіксованими роллю: записи оператора задовольняють лише запити
|
||||
оператора, а неоператорські ролі все одно потребують областей дії під власним
|
||||
префіксом ролі.
|
||||
Для вбудованого bootstrap-потоку вузол/оператор основний токен вузла
|
||||
залишається з `scopes: []`, а будь-який переданий операторський токен
|
||||
залишається обмеженим allowlist bootstrap-оператора (`operator.approvals`,
|
||||
`operator.read`, `operator.talk.secrets`, `operator.write`). Перевірки областей
|
||||
дії bootstrap залишаються префіксованими роллю: операторські записи
|
||||
задовольняють лише операторські запити, а неоператорські ролі все ще потребують
|
||||
областей дії з префіксом власної ролі.
|
||||
|
||||
### Приклад вузла
|
||||
|
||||
@ -224,7 +224,7 @@ local loopback, коли вони автентифікуються спільн
|
||||
|
||||
### Ролі
|
||||
|
||||
- `operator` = клієнт площини керування (CLI/інтерфейс/автоматизація).
|
||||
- `operator` = клієнт площини керування (CLI/UI/автоматизація).
|
||||
- `node` = хост можливостей (camera/screen/canvas/system.run).
|
||||
|
||||
### Області дії (оператор)
|
||||
@ -241,47 +241,47 @@ local loopback, коли вони автентифікуються спільн
|
||||
`talk.config` з `includeSecrets: true` потребує `operator.talk.secrets`
|
||||
(або `operator.admin`).
|
||||
|
||||
Зареєстровані Plugin методи Gateway RPC можуть запитувати власну область дії
|
||||
оператора, але зарезервовані префікси адміністрування ядра (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) завжди зіставляються з
|
||||
RPC-методи Gateway, зареєстровані Plugin, можуть запитувати власну операторську
|
||||
область дії, але зарезервовані основні префікси адміністратора (`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`
|
||||
- запити з не-exec командами вузла: `operator.pairing` + `operator.write`
|
||||
- запити, що містять `system.run`, `system.run.prepare` або `system.which`:
|
||||
- запити з node-командами не для exec: `operator.pairing` + `operator.write`
|
||||
- запити, які містять `system.run`, `system.run.prepare` або `system.which`:
|
||||
`operator.pairing` + `operator.admin`
|
||||
|
||||
### Можливості/команди/дозволи (вузол)
|
||||
|
||||
Вузли оголошують заявки на можливості під час підключення:
|
||||
|
||||
- `caps`: високорівневі категорії можливостей.
|
||||
- `commands`: дозволений список команд для invoke.
|
||||
- `permissions`: деталізовані перемикачі (наприклад, `screen.record`, `camera.capture`).
|
||||
- `caps`: категорії можливостей високого рівня.
|
||||
- `commands`: allowlist команд для виклику.
|
||||
- `permissions`: детальні перемикачі (наприклад, `screen.record`, `camera.capture`).
|
||||
|
||||
Gateway трактує їх як **заявки** та застосовує серверні дозволені списки.
|
||||
Gateway розглядає їх як **заявки** і забезпечує server-side allowlist.
|
||||
|
||||
## Присутність
|
||||
|
||||
- `system-presence` повертає записи з ключами за ідентичністю пристрою.
|
||||
- Записи присутності містять `deviceId`, `roles` і `scopes`, щоб інтерфейси могли показувати один рядок на пристрій
|
||||
навіть коли він підключається і як **оператор**, і як **вузол**.
|
||||
- `system-presence` повертає записи, ключовані ідентичністю пристрою.
|
||||
- Записи присутності містять `deviceId`, `roles` і `scopes`, щоб UI могли показувати один рядок на пристрій,
|
||||
навіть коли він підключається одночасно як **operator** і **node**.
|
||||
- `node.list` містить необов’язкові поля `lastSeenAtMs` і `lastSeenReason`. Підключені вузли повідомляють
|
||||
свій поточний час підключення як `lastSeenAtMs` з причиною `connect`; спарені вузли також можуть повідомляти
|
||||
тривалу фонову присутність, коли довірена подія вузла оновлює їхні метадані спарювання.
|
||||
свій поточний час підключення як `lastSeenAtMs` із причиною `connect`; сполучені вузли також можуть повідомляти
|
||||
сталу фонову присутність, коли довірена подія вузла оновлює їхні метадані сполучення.
|
||||
|
||||
### Фонова подія активності вузла
|
||||
|
||||
Вузли можуть викликати `node.event` з `event: "node.presence.alive"`, щоб записати, що спарений вузол був
|
||||
активний під час фонового пробудження, не позначаючи його як підключений.
|
||||
Вузли можуть викликати `node.event` з `event: "node.presence.alive"`, щоб записати, що сполучений вузол був
|
||||
активним під час фонового пробудження, не позначаючи його як підключений.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -291,9 +291,9 @@ Gateway трактує їх як **заявки** та застосовує се
|
||||
```
|
||||
|
||||
`trigger` є закритим enum: `background`, `silent_push`, `bg_app_refresh`,
|
||||
`significant_location`, `manual` або `connect`. Невідомі рядки тригерів нормалізуються до
|
||||
`background` Gateway перед збереженням. Подія є тривалою лише для автентифікованих сесій
|
||||
пристроїв-вузлів; сесії без пристрою або без спарювання повертають `handled: false`.
|
||||
`significant_location`, `manual` або `connect`. Невідомі рядки trigger нормалізуються до
|
||||
`background` Gateway перед збереженням. Подія є сталою лише для автентифікованих node-сеансів
|
||||
пристрою; сеанси без пристрою або без сполучення повертають `handled: false`.
|
||||
|
||||
Успішні Gateway повертають структурований результат:
|
||||
|
||||
@ -307,57 +307,57 @@ Gateway трактує їх як **заявки** та застосовує се
|
||||
```
|
||||
|
||||
Старіші Gateway можуть усе ще повертати `{ "ok": true }` для `node.event`; клієнти мають трактувати це як
|
||||
підтверджений RPC, а не як тривале збереження присутності.
|
||||
підтверджений RPC, а не як стале збереження присутності.
|
||||
|
||||
## Обмеження області дії трансляційних подій
|
||||
## Обмеження області дії broadcast-подій
|
||||
|
||||
Трансляційні події WebSocket, які надсилає сервер, обмежуються областями дії, щоб сесії з областю дії спарювання або лише вузлів не отримували пасивно вміст сесій.
|
||||
Broadcast-події WebSocket, які надсилає сервер, обмежуються областями дії, щоб сеанси з областю дії сполучення або лише вузлами не отримували пасивно вміст сеансів.
|
||||
|
||||
- **Кадри чату, агента та результатів інструментів** (зокрема потокові події `agent` і результати викликів інструментів) потребують щонайменше `operator.read`. Сесії без `operator.read` повністю пропускають ці кадри.
|
||||
- **Визначені Plugin трансляції `plugin.*`** обмежуються `operator.write` або `operator.admin`, залежно від того, як Plugin їх зареєстрував.
|
||||
- **Події статусу й транспорту** (`heartbeat`, `presence`, `tick`, життєвий цикл підключення/відключення тощо) лишаються необмеженими, щоб стан транспорту був видимим для кожної автентифікованої сесії.
|
||||
- **Невідомі родини трансляційних подій** за замовчуванням обмежуються областю дії (fail-closed), якщо зареєстрований обробник явно не послаблює їх.
|
||||
- **Кадри чату, агента та результатів інструментів** (включно зі streamed-подіями `agent` і результатами викликів інструментів) потребують щонайменше `operator.read`. Сеанси без `operator.read` повністю пропускають ці кадри.
|
||||
- **Визначені Plugin broadcast-події `plugin.*`** обмежуються `operator.write` або `operator.admin`, залежно від того, як Plugin їх зареєстрував.
|
||||
- **Події стану й транспорту** (`heartbeat`, `presence`, `tick`, життєвий цикл connect/disconnect тощо) залишаються необмеженими, щоб справність транспорту була видимою для кожного автентифікованого сеансу.
|
||||
- **Невідомі сімейства broadcast-подій** за замовчуванням обмежуються областю дії (fail-closed), якщо зареєстрований обробник явно не послаблює їх.
|
||||
|
||||
Кожне клієнтське підключення зберігає власний порядковий номер для кожного клієнта, тож трансляції зберігають монотонне впорядкування на цьому сокеті, навіть коли різні клієнти бачать різні підмножини потоку подій, відфільтровані за областями дії.
|
||||
Кожне клієнтське підключення зберігає власний порядковий номер для кожного клієнта, тому broadcast-події зберігають монотонний порядок у цьому socket навіть тоді, коли різні клієнти бачать різні підмножини потоку подій після фільтрації за областями дії.
|
||||
|
||||
## Поширені родини методів RPC
|
||||
## Поширені сімейства RPC-методів
|
||||
|
||||
Публічна поверхня WS ширша за наведені вище приклади рукостискання/автентифікації. Це
|
||||
Публічна поверхня WS ширша за наведені вище приклади рукостискання/auth. Це
|
||||
не згенерований дамп — `hello-ok.features.methods` є консервативним списком
|
||||
виявлення, побудованим із `src/gateway/server-methods-list.ts` плюс завантажених
|
||||
експортів методів Plugin/каналів. Трактуйте його як виявлення функцій, а не як повний
|
||||
перелік `src/gateway/server-methods/*.ts`.
|
||||
виявлення, побудованим із `src/gateway/server-methods-list.ts` плюс завантажені
|
||||
експорти методів Plugin/каналів. Трактуйте його як виявлення функцій, а не
|
||||
повний перелік `src/gateway/server-methods/*.ts`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="System and identity">
|
||||
- `health` повертає кешований або щойно перевірений знімок стану Gateway.
|
||||
- `diagnostics.stability` повертає нещодавній обмежений діагностичний реєстратор стабільності. Він зберігає операційні метадані, як-от назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сесії, назви каналів/Plugin і ідентифікатори сесій. Він не зберігає текст чату, тіла webhook, виводи інструментів, сирі тіла запитів або відповідей, токени, cookie чи секретні значення. Потрібна область читання оператора.
|
||||
- `status` повертає зведення Gateway у стилі `/status`; чутливі поля включаються лише для клієнтів-операторів з адміністративною областю дії.
|
||||
- `gateway.identity.get` повертає ідентичність пристрою Gateway, яку використовують relay і потоки спарювання.
|
||||
- `system-presence` повертає поточний знімок присутності для підключених пристроїв операторів/вузлів.
|
||||
- `system-event` додає системну подію та може оновити/транслювати контекст присутності.
|
||||
- `diagnostics.stability` повертає нещодавній обмежений реєстратор діагностичної стабільності. Він зберігає операційні метадані, як-от назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сеансу, назви каналів/Plugin і ідентифікатори сеансів. Він не зберігає текст чату, тіла webhook, виводи інструментів, сирі тіла запитів або відповідей, токени, cookies чи секретні значення. Потрібна операторська область дії read.
|
||||
- `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" }` для налаштованих моделей розміру вибірника (`agents.defaults.models` спочатку, потім `models.providers.*.models`) або `{ "view": "all" }` для повного каталогу.
|
||||
- `usage.status` повертає вікна використання провайдера / зведення залишкової квоти.
|
||||
- `usage.cost` повертає агреговані зведення використання вартості за діапазон дат.
|
||||
- `doctor.memory.status` повертає готовність векторної пам’яті / кешованих embedding для активного робочого простору агента за замовчуванням. Передавайте `{ "probe": true }` або `{ "deep": true }` лише коли викликач явно хоче живу перевірку embedding-провайдера.
|
||||
- `doctor.memory.remHarness` повертає обмежений, доступний лише для читання попередній перегляд REM harness для віддалених клієнтів control plane. Він може містити шляхи робочого простору, фрагменти пам’яті, відрендерений grounded markdown і кандидатів на deep promotion, тому викликачам потрібен `operator.read`.
|
||||
- `sessions.usage` повертає зведення використання для кожної сесії.
|
||||
- `sessions.usage.timeseries` повертає використання у вигляді часового ряду для однієї сесії.
|
||||
- `sessions.usage.logs` повертає записи журналу використання для однієї сесії.
|
||||
- `models.list` повертає каталог моделей, дозволених під час виконання. Передайте `{ "view": "configured" }` для стислого для вибірника списку налаштованих моделей (спочатку `agents.defaults.models`, потім `models.providers.*.models`) або `{ "view": "all" }` для повного каталогу.
|
||||
- `usage.status` повертає зведення щодо вікон використання провайдера та залишкової квоти.
|
||||
- `usage.cost` повертає агреговані зведення витрат за діапазон дат.
|
||||
- `doctor.memory.status` повертає готовність векторної памʼяті / кешованих embedding для активного робочого простору типового агента. Передавайте `{ "probe": true }` або `{ "deep": true }` лише коли викликач явно хоче живий ping провайдера embedding.
|
||||
- `doctor.memory.remHarness` повертає обмежений, доступний лише для читання попередній перегляд REM harness для віддалених клієнтів control-plane. Він може містити шляхи робочого простору, фрагменти памʼяті, відрендерений grounded markdown і кандидатів на deep promotion, тому викликачам потрібен `operator.read`.
|
||||
- `sessions.usage` повертає зведення використання за сеансами.
|
||||
- `sessions.usage.timeseries` повертає часовий ряд використання для одного сеансу.
|
||||
- `sessions.usage.logs` повертає записи журналу використання для одного сеансу.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Канали та помічники входу">
|
||||
- `channels.status` повертає зведення статусів вбудованих і комплектних каналів/Plugin.
|
||||
- `channels.logout` виходить із певного каналу/акаунта, якщо канал підтримує вихід.
|
||||
- `web.login.start` запускає потік QR/web-входу для поточного QR-сумісного провайдера вебканалу.
|
||||
- `web.login.wait` чекає завершення цього потоку QR/web-входу й запускає канал у разі успіху.
|
||||
- `channels.status` повертає зведення статусу вбудованих і комплектних каналів/Plugin.
|
||||
- `channels.logout` виконує вихід із певного каналу/облікового запису, якщо канал підтримує вихід.
|
||||
- `web.login.start` запускає QR/web-потік входу для поточного web-провайдера каналу з підтримкою QR.
|
||||
- `web.login.wait` очікує завершення цього QR/web-потоку входу та в разі успіху запускає канал.
|
||||
- `push.test` надсилає тестовий APNs push на зареєстрований iOS-вузол.
|
||||
- `voicewake.get` повертає збережені тригери wake-word.
|
||||
- `voicewake.set` оновлює тригери wake-word і транслює зміну.
|
||||
@ -365,179 +365,207 @@ Gateway трактує їх як **заявки** та застосовує се
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Повідомлення та журнали">
|
||||
- `send` — це прямий RPC вихідної доставки для надсилань, націлених на канал/акаунт/тред поза chat runner.
|
||||
- `logs.tail` повертає налаштований хвіст файлового журналу gateway з курсором/лімітом і керуванням максимальною кількістю байтів.
|
||||
- `send` — це прямий RPC для вихідної доставки, націлений на канал/обліковий запис/тред, для надсилань поза chat runner.
|
||||
- `logs.tail` повертає налаштований хвіст файлового журналу gateway з елементами керування cursor/limit і max-byte.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Talk і TTS">
|
||||
- `talk.config` повертає ефективне корисне навантаження конфігурації Talk; `includeSecrets` потребує `operator.talk.secrets` (або `operator.admin`).
|
||||
- `talk.mode` задає/транслює поточний стан режиму Talk для клієнтів WebChat/Control UI.
|
||||
- `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.convert` запускає одноразове перетворення text-to-speech.
|
||||
- `tts.convert` виконує одноразове перетворення тексту на мовлення.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Секрети, конфігурація, оновлення та майстер">
|
||||
- `secrets.reload` повторно вирішує активні SecretRefs і замінює стан секретів у середовищі виконання лише за повного успіху.
|
||||
- `secrets.resolve` вирішує прив’язки секретів, націлені на команди, для певного набору команда/ціль.
|
||||
- `config.get` повертає поточний знімок конфігурації та хеш.
|
||||
- `config.set` записує валідоване корисне навантаження конфігурації.
|
||||
- `secrets.reload` повторно розвʼязує активні SecretRefs і замінює стан секретів під час виконання лише в разі повного успіху.
|
||||
- `secrets.resolve` розвʼязує призначення секретів для цільових команд для певного набору command/target.
|
||||
- `config.get` повертає поточний знімок конфігурації та hash.
|
||||
- `config.set` записує перевірене корисне навантаження конфігурації.
|
||||
- `config.patch` зливає часткове оновлення конфігурації.
|
||||
- `config.apply` валідує та замінює повне корисне навантаження конфігурації.
|
||||
- `config.schema` повертає живе корисне навантаження схеми конфігурації, яке використовують Control UI та інструменти CLI: схема, `uiHints`, версія та метадані генерації, включно з метаданими схем plugin + каналу, коли середовище виконання може їх завантажити. Схема містить метадані полів `title` / `description`, виведені з тих самих міток і довідкового тексту, які використовує UI, включно з гілками композиції вкладених об’єктів, wildcard, елементів масиву та `anyOf` / `oneOf` / `allOf`, коли існує відповідна документація поля.
|
||||
- `config.schema.lookup` повертає корисне навантаження пошуку, обмежене шляхом, для одного шляху конфігурації: нормалізований шлях, поверхневий вузол схеми, відповідний hint + `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` надають майстер онбордингу через WS RPC.
|
||||
- `config.apply` перевіряє та замінює повне корисне навантаження конфігурації.
|
||||
- `config.schema` повертає живе корисне навантаження схеми конфігурації, яке використовують Control UI та інструменти CLI: schema, `uiHints`, version і метадані generation, зокрема метадані схеми plugin + channel, коли середовище виконання може їх завантажити. Схема містить метадані полів `title` / `description`, отримані з тих самих міток і довідкового тексту, які використовує UI, зокрема вкладені обʼєкти, wildcard, елементи масиву та гілки композиції `anyOf` / `oneOf` / `allOf`, коли існує відповідна документація поля.
|
||||
- `config.schema.lookup` повертає корисне навантаження пошуку, обмежене шляхом, для одного шляху конфігурації: нормалізований шлях, поверхневий вузол схеми, відповідний hint + `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` повертає останній кешований restart sentinel оновлення, зокрема поточну версію після перезапуску, коли вона доступна.
|
||||
- `wizard.start`, `wizard.next`, `wizard.status` і `wizard.cancel` відкривають майстер онбордингу через WS RPC.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Помічники агента та робочого простору">
|
||||
- `agents.list` повертає налаштовані записи агентів, включно з ефективною моделлю та метаданими середовища виконання.
|
||||
- `agents.create`, `agents.update` і `agents.delete` керують записами агентів і зв’язуванням робочих просторів.
|
||||
- `agents.files.list`, `agents.files.get` і `agents.files.set` керують файлами bootstrap-робочого простору, відкритими для агента.
|
||||
- `artifacts.list`, `artifacts.get` і `artifacts.download` надають зведення артефактів, отриманих із транскрипту, і завантаження для явної області `sessionKey`, `runId` або `taskId`. Запити запусків і завдань вирішують сесію-власника на сервері та повертають лише медіа транскрипту з відповідним походженням; небезпечні або локальні URL-джерела повертають непідтримувані завантаження замість отримання на сервері.
|
||||
- `agent.identity.get` повертає ефективну ідентичність асистента для агента або сесії.
|
||||
- `agent.wait` чекає завершення запуску й повертає термінальний знімок, коли він доступний.
|
||||
- `agents.list` повертає налаштовані записи агентів, зокрема ефективну модель і метадані середовища виконання.
|
||||
- `agents.create`, `agents.update` і `agents.delete` керують записами агентів і привʼязкою робочого простору.
|
||||
- `agents.files.list`, `agents.files.get` і `agents.files.set` керують bootstrap-файлами робочого простору, відкритими для агента.
|
||||
- `artifacts.list`, `artifacts.get` і `artifacts.download` відкривають зведення артефактів і завантаження, отримані з транскрипту, для явної області `sessionKey`, `runId` або `taskId`. Запити run і task розвʼязують власний сеанс на боці сервера та повертають лише медіа транскрипту з відповідним походженням; небезпечні або локальні URL-джерела повертають непідтримувані завантаження замість завантаження на боці сервера.
|
||||
- `agent.identity.get` повертає ефективну ідентичність асистента для агента або сеансу.
|
||||
- `agent.wait` очікує завершення run і повертає фінальний знімок, коли він доступний.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Керування сесіями">
|
||||
- `sessions.list` повертає поточний індекс сесій, включно з метаданими `agentRuntime` для кожного рядка, коли налаштовано backend середовища виконання агента.
|
||||
- `sessions.subscribe` і `sessions.unsubscribe` перемикають підписки на події змін сесій для поточного WS-клієнта.
|
||||
- `sessions.messages.subscribe` і `sessions.messages.unsubscribe` перемикають підписки на події транскрипту/повідомлень для однієї сесії.
|
||||
- `sessions.preview` повертає обмежені попередні перегляди транскриптів для конкретних ключів сесій.
|
||||
- `sessions.resolve` вирішує або канонізує ціль сесії.
|
||||
- `sessions.create` створює новий запис сесії.
|
||||
- `sessions.send` надсилає повідомлення в наявну сесію.
|
||||
- `sessions.steer` — це варіант interrupt-and-steer для активної сесії.
|
||||
- `sessions.abort` перериває активну роботу для сесії. Викликач може передати `key` плюс необов’язковий `runId` або передати лише `runId` для активних запусків, які Gateway може зіставити із сесією.
|
||||
- `sessions.patch` оновлює метадані/перевизначення сесії та повідомляє вирішену канонічну модель плюс ефективний `agentRuntime`.
|
||||
- `sessions.reset`, `sessions.delete` і `sessions.compact` виконують обслуговування сесії.
|
||||
- `sessions.get` повертає повний збережений рядок сесії.
|
||||
- Виконання чату й далі використовує `chat.history`, `chat.send`, `chat.abort` і `chat.inject`. `chat.history` нормалізовано для відображення в UI-клієнтах: inline directive tags вилучаються з видимого тексту, XML-корисні навантаження викликів інструментів у plain-text (включно з `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізаними блоками викликів інструментів) і витіклі ASCII/full-width model control tokens вилучаються, рядки асистента лише з silent-token, як-от точні `NO_REPLY` / `no_reply`, пропускаються, а завеликі рядки можуть бути замінені placeholders.
|
||||
<Accordion title="Керування сеансами">
|
||||
- `sessions.list` повертає поточний індекс сеансів, зокрема метадані `agentRuntime` для кожного рядка, коли налаштовано backend середовища виконання агента.
|
||||
- `sessions.subscribe` і `sessions.unsubscribe` перемикають підписки на події зміни сеансів для поточного WS-клієнта.
|
||||
- `sessions.messages.subscribe` і `sessions.messages.unsubscribe` перемикають підписки на події транскрипту/повідомлень для одного сеансу.
|
||||
- `sessions.preview` повертає обмежені попередні перегляди транскриптів для певних ключів сеансів.
|
||||
- `sessions.resolve` розвʼязує або канонізує ціль сеансу.
|
||||
- `sessions.create` створює новий запис сеансу.
|
||||
- `sessions.send` надсилає повідомлення в наявний сеанс.
|
||||
- `sessions.steer` — це варіант interrupt-and-steer для активного сеансу.
|
||||
- `sessions.abort` перериває активну роботу для сеансу. Викликач може передати `key` плюс необовʼязковий `runId` або передати лише `runId` для активних run, які Gateway може розвʼязати до сеансу.
|
||||
- `sessions.patch` оновлює метадані/перевизначення сеансу та повідомляє розвʼязану канонічну модель плюс ефективний `agentRuntime`.
|
||||
- `sessions.reset`, `sessions.delete` і `sessions.compact` виконують обслуговування сеансів.
|
||||
- `sessions.get` повертає повний збережений рядок сеансу.
|
||||
- Виконання чату й надалі використовує `chat.history`, `chat.send`, `chat.abort` і `chat.inject`. `chat.history` нормалізовано для відображення UI-клієнтам: inline directive tags вилучаються з видимого тексту, plain-text XML payloads викликів інструментів (зокрема `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізані блоки викликів інструментів) та leaked ASCII/full-width model control tokens вилучаються, чисті silent-token рядки асистента, як-от точні `NO_REPLY` / `no_reply`, опускаються, а надмірно великі рядки можуть замінюватися placeholder.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Сполучення пристроїв і токени пристроїв">
|
||||
- `device.pair.list` повертає пристрої в очікуванні та схвалені сполучені пристрої.
|
||||
- `device.pair.approve`, `device.pair.reject` і `device.pair.remove` керують записами сполучення пристроїв.
|
||||
- `device.token.rotate` обертає токен сполученого пристрою в межах його схваленої ролі та меж області викликача.
|
||||
- `device.token.revoke` відкликає токен сполученого пристрою в межах його схваленої ролі та меж області викликача.
|
||||
<Accordion title="Спарювання пристроїв і токени пристроїв">
|
||||
- `device.pair.list` повертає очікувані та схвалені спарені пристрої.
|
||||
- `device.pair.approve`, `device.pair.reject` і `device.pair.remove` керують записами спарювання пристроїв.
|
||||
- `device.token.rotate` ротує токен спареного пристрою в межах його схваленої ролі та області викликача.
|
||||
- `device.token.revoke` відкликає токен спареного пристрою в межах його схваленої ролі та області викликача.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Сполучення Node, invoke і робота в очікуванні">
|
||||
- `node.pair.request`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.remove` і `node.pair.verify` охоплюють сполучення вузлів і перевірку bootstrap.
|
||||
<Accordion title="Спарювання Node, invoke і очікувана робота">
|
||||
- `node.pair.request`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.remove` і `node.pair.verify` покривають спарювання вузлів і перевірку bootstrap.
|
||||
- `node.list` і `node.describe` повертають стан відомих/підключених вузлів.
|
||||
- `node.rename` оновлює мітку сполученого вузла.
|
||||
- `node.rename` оновлює мітку спареного вузла.
|
||||
- `node.invoke` пересилає команду підключеному вузлу.
|
||||
- `node.invoke.result` повертає результат для запиту invoke.
|
||||
- `node.event` переносить події, що походять від вузла, назад у gateway.
|
||||
- `node.canvas.capability.refresh` оновлює токени canvas-capability з обмеженою областю.
|
||||
- `node.canvas.capability.refresh` оновлює scoped canvas-capability tokens.
|
||||
- `node.pending.pull` і `node.pending.ack` — це API черги підключеного вузла.
|
||||
- `node.pending.enqueue` і `node.pending.drain` керують durable роботою в очікуванні для offline/disconnected вузлів.
|
||||
- `node.pending.enqueue` і `node.pending.drain` керують надійно збереженою очікуваною роботою для офлайн/відключених вузлів.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Сімейства схвалень">
|
||||
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` і `exec.approval.resolve` охоплюють одноразові запити схвалення exec, а також пошук/повторне відтворення схвалень в очікуванні.
|
||||
- `exec.approval.waitDecision` чекає одне схвалення exec в очікуванні та повертає фінальне рішення (або `null` у разі timeout).
|
||||
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` і `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 через команди ретрансляції вузла.
|
||||
- `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` і `plugin.approval.resolve` охоплюють визначені plugin потоки схвалення.
|
||||
- `exec.approvals.node.get` і `exec.approvals.node.set` керують локальною для вузла політикою схвалення exec через команди relay вузла.
|
||||
- `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` і `plugin.approval.resolve` покривають потоки схвалень, визначені plugin.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Автоматизація, skills та інструменти">
|
||||
- Автоматизація: `wake` планує негайну або під час наступного heartbeat ін’єкцію wake-тексту; `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` керують запланованою роботою.
|
||||
- Skills та інструменти: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`.
|
||||
<Accordion title="Автоматизація, Skills та інструменти">
|
||||
- Автоматизація: `wake` планує негайну або під час наступного heartbeat інʼєкцію тексту wake; `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` керують запланованою роботою.
|
||||
- Skills та інструменти: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`, `tools.invoke`.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Поширені сімейства подій
|
||||
|
||||
- `chat`: оновлення чату UI, як-от `chat.inject`, та інші події чату лише для транскрипту.
|
||||
- `session.message` і `session.tool`: оновлення транскрипту/потоку подій для підписаної сесії.
|
||||
- `sessions.changed`: індекс сесій або метадані змінено.
|
||||
- `chat`: оновлення чату UI, як-от `chat.inject` та інші події чату
|
||||
лише для транскрипту.
|
||||
- `session.message` і `session.tool`: оновлення транскрипту/потоку подій для
|
||||
підписаного сеансу.
|
||||
- `sessions.changed`: індекс сеансів або метадані змінено.
|
||||
- `presence`: оновлення знімка присутності системи.
|
||||
- `tick`: періодична keepalive / liveness подія.
|
||||
- `health`: оновлення знімка справності gateway.
|
||||
- `tick`: періодична подія keepalive / liveness.
|
||||
- `health`: оновлення знімка стану gateway.
|
||||
- `heartbeat`: оновлення потоку подій heartbeat.
|
||||
- `cron`: подія зміни запуску/завдання cron.
|
||||
- `cron`: подія зміни run/job cron.
|
||||
- `shutdown`: сповіщення про вимкнення gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved`: життєвий цикл сполучення вузла.
|
||||
- `node.pair.requested` / `node.pair.resolved`: життєвий цикл спарювання вузлів.
|
||||
- `node.invoke.request`: трансляція запиту invoke вузла.
|
||||
- `device.pair.requested` / `device.pair.resolved`: життєвий цикл сполученого пристрою.
|
||||
- `device.pair.requested` / `device.pair.resolved`: життєвий цикл спареного пристрою.
|
||||
- `voicewake.changed`: конфігурацію тригерів wake-word змінено.
|
||||
- `exec.approval.requested` / `exec.approval.resolved`: життєвий цикл схвалення exec.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved`: життєвий цикл схвалення plugin.
|
||||
|
||||
### Допоміжні методи Node
|
||||
### Методи-помічники Node
|
||||
|
||||
- Вузли можуть викликати `skills.bins`, щоб отримати поточний список виконуваних файлів Skills для перевірок auto-allow.
|
||||
- Вузли можуть викликати `skills.bins`, щоб отримати поточний список виконуваних файлів Skills
|
||||
для перевірок auto-allow.
|
||||
|
||||
### Допоміжні методи оператора
|
||||
### Методи-помічники оператора
|
||||
|
||||
- Оператори можуть викликати `commands.list` (`operator.read`), щоб отримати інвентар команд часу виконання для агента.
|
||||
- `agentId` необов'язковий; не вказуйте його, щоб читати робочий простір агента за замовчуванням.
|
||||
- `scope` керує тим, на яку поверхню націлено основний `name`:
|
||||
- Оператори можуть викликати `commands.list` (`operator.read`), щоб отримати runtime
|
||||
інвентар команд для агента.
|
||||
- `agentId` необов’язковий; пропустіть його, щоб прочитати стандартний робочий простір агента.
|
||||
- `scope` керує тим, на яку поверхню націлюється основний `name`:
|
||||
- `text` повертає основний текстовий токен команди без початкового `/`
|
||||
- `native` і шлях за замовчуванням `both` повертають нативні імена з урахуванням провайдера, коли вони доступні
|
||||
- `textAliases` містить точні slash-псевдоніми, як-от `/model` і `/m`.
|
||||
- `nativeName` містить нативне ім'я команди з урахуванням провайдера, коли воно існує.
|
||||
- `provider` необов'язковий і впливає лише на нативне найменування та доступність нативних команд plugin.
|
||||
- `includeArgs=false` вилучає серіалізовані метадані аргументів із відповіді.
|
||||
- Оператори можуть викликати `tools.catalog` (`operator.read`), щоб отримати каталог інструментів часу виконання для агента. Відповідь містить згруповані інструменти та метадані походження:
|
||||
- `native` і стандартний шлях `both` повертають native-імена з урахуванням провайдера,
|
||||
коли вони доступні
|
||||
- `textAliases` містить точні slash-аліаси, як-от `/model` і `/m`.
|
||||
- `nativeName` містить native-ім’я команди з урахуванням провайдера, коли воно існує.
|
||||
- `provider` необов’язковий і впливає лише на native-іменування та доступність native-команд Plugin.
|
||||
- `includeArgs=false` пропускає серіалізовані метадані аргументів у відповіді.
|
||||
- Оператори можуть викликати `tools.catalog` (`operator.read`), щоб отримати runtime-каталог інструментів для
|
||||
агента. Відповідь містить згруповані інструменти та метадані походження:
|
||||
- `source`: `core` або `plugin`
|
||||
- `pluginId`: власник plugin, коли `source="plugin"`
|
||||
- `optional`: чи є інструмент plugin необов'язковим
|
||||
- Оператори можуть викликати `tools.effective` (`operator.read`), щоб отримати фактично доступний у часі виконання інвентар інструментів для сесії.
|
||||
- `sessionKey` обов'язковий.
|
||||
- Gateway виводить довірений контекст часу виконання із сесії на серверному боці замість приймання наданого викликачем контексту автентифікації або доставки.
|
||||
- Відповідь обмежена сесією та відображає те, що активна розмова може використовувати прямо зараз, включно з core, plugin і каналними інструментами.
|
||||
- Оператори можуть викликати `skills.status` (`operator.read`), щоб отримати видимий інвентар skill для агента.
|
||||
- `agentId` необов'язковий; не вказуйте його, щоб читати робочий простір агента за замовчуванням.
|
||||
- Відповідь містить придатність, відсутні вимоги, перевірки конфігурації та очищені варіанти встановлення без розкриття необроблених секретних значень.
|
||||
- Оператори можуть викликати `skills.search` і `skills.detail` (`operator.read`) для метаданих виявлення ClawHub.
|
||||
- `pluginId`: власник Plugin, коли `source="plugin"`
|
||||
- `optional`: чи є інструмент Plugin необов’язковим
|
||||
- Оператори можуть викликати `tools.effective` (`operator.read`), щоб отримати runtime-ефективний
|
||||
інвентар інструментів для сесії.
|
||||
- `sessionKey` обов’язковий.
|
||||
- Gateway виводить довірений runtime-контекст із сесії на серверному боці замість прийняття
|
||||
auth або контексту доставки, наданого викликачем.
|
||||
- Відповідь обмежена сесією та відображає те, що активна розмова може використовувати прямо зараз,
|
||||
включно з core, Plugin і channel-інструментами.
|
||||
- Оператори можуть викликати `tools.invoke` (`operator.write`), щоб викликати один доступний інструмент через
|
||||
той самий шлях політики Gateway, що й `/tools/invoke`.
|
||||
- `name` обов’язковий. `args`, `sessionKey`, `agentId`, `confirm` і
|
||||
`idempotencyKey` необов’язкові.
|
||||
- Якщо наявні і `sessionKey`, і `agentId`, визначений агент сесії має збігатися з
|
||||
`agentId`.
|
||||
- Відповідь є envelope для SDK з полями `ok`, `toolName`, необов’язковим `output` і типізованими
|
||||
`error`. Відмови через погодження або політику повертають `ok:false` у payload, а не
|
||||
обходять pipeline політики інструментів Gateway.
|
||||
- Оператори можуть викликати `skills.status` (`operator.read`), щоб отримати видимий
|
||||
інвентар Skills для агента.
|
||||
- `agentId` необов’язковий; пропустіть його, щоб прочитати стандартний робочий простір агента.
|
||||
- Відповідь містить eligibility, відсутні вимоги, перевірки конфігурації та
|
||||
очищені параметри встановлення без розкриття необроблених секретних значень.
|
||||
- Оператори можуть викликати `skills.search` і `skills.detail` (`operator.read`) для
|
||||
метаданих discovery у ClawHub.
|
||||
- Оператори можуть викликати `skills.install` (`operator.admin`) у двох режимах:
|
||||
- Режим ClawHub: `{ source: "clawhub", slug, version?, force? }` встановлює папку skill у директорію `skills/` робочого простору агента за замовчуванням.
|
||||
- Режим інсталятора Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` запускає оголошену дію `metadata.openclaw.install` на хості Gateway.
|
||||
- Режим ClawHub: `{ source: "clawhub", slug, version?, force? }` встановлює
|
||||
теку Skills у директорію `skills/` стандартного робочого простору агента.
|
||||
- Режим інсталятора Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
|
||||
запускає оголошену дію `metadata.openclaw.install` на хості Gateway.
|
||||
- Оператори можуть викликати `skills.update` (`operator.admin`) у двох режимах:
|
||||
- Режим ClawHub оновлює один відстежуваний slug або всі відстежувані встановлення ClawHub у робочому просторі агента за замовчуванням.
|
||||
- Режим конфігурації виправляє значення `skills.entries.<skillKey>`, як-от `enabled`, `apiKey` і `env`.
|
||||
- Режим ClawHub оновлює один відстежуваний slug або всі відстежувані встановлення ClawHub у
|
||||
стандартному робочому просторі агента.
|
||||
- Режим конфігурації патчить значення `skills.entries.<skillKey>`, як-от `enabled`,
|
||||
`apiKey` і `env`.
|
||||
|
||||
### Представлення `models.list`
|
||||
### Подання `models.list`
|
||||
|
||||
`models.list` приймає необов'язковий параметр `view`:
|
||||
`models.list` приймає необов’язковий параметр `view`:
|
||||
|
||||
- Не вказано або `"default"`: поточна поведінка часу виконання. Якщо `agents.defaults.models` налаштовано, відповідь є дозволеним каталогом; інакше відповідь є повним каталогом Gateway.
|
||||
- `"configured"`: поведінка розміру picker. Якщо `agents.defaults.models` налаштовано, він усе одно має перевагу. Інакше відповідь використовує явні записи `models.providers.*.models`, повертаючись до повного каталогу лише тоді, коли немає налаштованих рядків моделей.
|
||||
- `"all"`: повний каталог Gateway, в обхід `agents.defaults.models`. Використовуйте це для діагностики та UI виявлення, а не для звичайних picker моделей.
|
||||
- Пропущено або `"default"`: поточна runtime-поведінка. Якщо `agents.defaults.models` налаштовано, відповідь є дозволеним каталогом; інакше відповідь є повним каталогом Gateway.
|
||||
- `"configured"`: поведінка розміру picker. Якщо `agents.defaults.models` налаштовано, він усе одно має пріоритет. Інакше відповідь використовує явні записи `models.providers.*.models`, повертаючись до повного каталогу лише тоді, коли немає жодних налаштованих рядків моделей.
|
||||
- `"all"`: повний каталог Gateway, оминаючи `agents.defaults.models`. Використовуйте це для діагностики та discovery UI, а не для звичайних picker моделей.
|
||||
|
||||
## Схвалення exec
|
||||
## Погодження exec
|
||||
|
||||
- Коли запит exec потребує схвалення, gateway транслює `exec.approval.requested`.
|
||||
- Клієнти операторів вирішують це, викликаючи `exec.approval.resolve` (потребує scope `operator.approvals`).
|
||||
- Коли exec-запит потребує погодження, Gateway транслює `exec.approval.requested`.
|
||||
- Операторські клієнти вирішують це, викликаючи `exec.approval.resolve` (потребує scope `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.
|
||||
- Після погодження переслані виклики `node.invoke system.run` повторно використовують цей канонічний
|
||||
`systemRunPlan` як authoritative контекст команди/cwd/сесії.
|
||||
- Якщо викликач змінює `command`, `rawCommand`, `cwd`, `agentId` або
|
||||
`sessionKey` між підготовкою та фінальним погодженим forward `system.run`, Gateway
|
||||
відхиляє запуск замість того, щоб довіряти зміненому payload.
|
||||
|
||||
## Резервна доставка агента
|
||||
## Fallback доставки агентом
|
||||
|
||||
- Запити `agent` можуть містити `deliver=true`, щоб запросити вихідну доставку.
|
||||
- `bestEffortDeliver=false` зберігає сувору поведінку: нерозв'язані або лише внутрішні цілі доставки повертають `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` дозволяє fallback до виконання лише в сесії, коли неможливо розв'язати зовнішній маршрут доставки (наприклад, внутрішні/webchat-сесії або неоднозначні багатоканальні конфігурації).
|
||||
- `bestEffortDeliver=false` зберігає сувору поведінку: нерозв’язані або лише внутрішні цілі доставки повертають `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` дозволяє fallback до виконання лише в сесії, коли неможливо визначити зовнішній доставний маршрут (наприклад, внутрішні/webchat-сесії або неоднозначні багатоканальні конфігурації).
|
||||
|
||||
## Версіонування
|
||||
|
||||
- `PROTOCOL_VERSION` розташований у `src/gateway/protocol/schema/protocol-schemas.ts`.
|
||||
- `PROTOCOL_VERSION` міститься в `src/gateway/protocol/schema/protocol-schemas.ts`.
|
||||
- Клієнти надсилають `minProtocol` + `maxProtocol`; сервер відхиляє невідповідності.
|
||||
- Схеми + моделі генеруються з визначень TypeBox:
|
||||
- `pnpm protocol:gen`
|
||||
@ -546,70 +574,103 @@ Gateway трактує їх як **заявки** та застосовує се
|
||||
|
||||
### Константи клієнта
|
||||
|
||||
Еталонний клієнт у `src/gateway/client.ts` використовує ці значення за замовчуванням. Значення стабільні в protocol v3 і є очікуваною базовою лінією для сторонніх клієнтів.
|
||||
Референсний клієнт у `src/gateway/client.ts` використовує ці стандартні значення. Значення
|
||||
стабільні в protocol v3 і є очікуваною baseline для сторонніх клієнтів.
|
||||
|
||||
| Константа | За замовчуванням | Джерело |
|
||||
| Константа | Стандартне значення | Джерело |
|
||||
| ----------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| `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 можуть збільшити парний бюджет server/client) |
|
||||
| Тайм-аут preauth / connect-challenge | `15_000` ms | `src/gateway/handshake-timeouts.ts` (config/env може збільшити спільний server/client budget) |
|
||||
| Початковий backoff повторного підключення | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
|
||||
| Максимальний backoff повторного підключення | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
|
||||
| Обмеження fast-retry після закриття 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 | code `4000`, коли тиша перевищує `tickIntervalMs * 2` | `src/gateway/client.ts` |
|
||||
| Fast-retry clamp після закриття device-token | `250` ms | `src/gateway/client.ts` |
|
||||
| Grace 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-timeout | code `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`; клієнти мають дотримуватися цих значень, а не значень за замовчуванням до handshake.
|
||||
Сервер оголошує ефективні `policy.tickIntervalMs`, `policy.maxPayload`
|
||||
і `policy.maxBufferedBytes` у `hello-ok`; клієнти мають дотримуватися цих значень
|
||||
замість стандартних значень до handshake.
|
||||
|
||||
## Автентифікація
|
||||
## Auth
|
||||
|
||||
- Автентифікація gateway зі спільним секретом використовує `connect.params.auth.token` або `connect.params.auth.password`, залежно від налаштованого режиму автентифікації.
|
||||
- Режими з ідентичністю, як-от Tailscale Serve (`gateway.auth.allowTailscale: true`) або non-loopback `gateway.auth.mode: "trusted-proxy"`, задовольняють перевірку connect auth із заголовків запиту замість `connect.params.auth.*`.
|
||||
- Private-ingress `gateway.auth.mode: "none"` повністю пропускає shared-secret connect auth; не виставляйте цей режим на публічний/недовірений ingress.
|
||||
- Після pairing Gateway видає **device token**, обмежений роллю підключення + scopes. Він повертається в `hello-ok.auth.deviceToken` і має зберігатися клієнтом для майбутніх підключень.
|
||||
- Клієнти мають зберігати основний `hello-ok.auth.deviceToken` після будь-якого успішного підключення.
|
||||
- Повторне підключення з цим **збереженим** device token також має повторно використовувати збережений затверджений набір scope для цього token. Це зберігає вже наданий доступ read/probe/status і не дозволяє reconnect непомітно звузитися до неявного admin-only scope.
|
||||
- Збирання connect auth на боці клієнта (`selectConnectAuth` у `src/gateway/client.ts`):
|
||||
- `auth.password` ортогональний і завжди пересилається, коли встановлений.
|
||||
- `auth.token` заповнюється в порядку пріоритету: спершу явний спільний token, потім явний `deviceToken`, потім збережений per-device token (за ключем `deviceId` + `role`).
|
||||
- `auth.bootstrapToken` надсилається лише тоді, коли жодне з наведеного вище не розв'язало `auth.token`. Спільний token або будь-який розв'язаний device token пригнічує його.
|
||||
- Автоматичне підвищення збереженого device token під час одноразової повторної спроби `AUTH_TOKEN_MISMATCH` обмежене **лише довіреними endpoints** — loopback або `wss://` із закріпленим `tlsFingerprint`. Публічний `wss://` без pinning не підходить.
|
||||
- Додаткові записи `hello-ok.auth.deviceTokens` є bootstrap handoff tokens. Зберігайте їх лише тоді, коли connect використовував bootstrap auth на довіреному транспорті, як-от `wss://` або loopback/local pairing.
|
||||
- Якщо клієнт надає **явний** `deviceToken` або явні `scopes`, цей запитаний викликачем набір scope залишається авторитетним; кешовані scopes повторно використовуються лише тоді, коли клієнт повторно використовує збережений per-device token.
|
||||
- Device tokens можна ротувати/відкликати через `device.token.rotate` і `device.token.revoke` (потребує scope `operator.pairing`).
|
||||
- `device.token.rotate` повертає метадані ротації. Він відлунює replacement bearer token лише для викликів із того самого пристрою, які вже автентифіковані цим device token, щоб token-only клієнти могли зберегти свою заміну перед повторним підключенням. Shared/admin rotations не відлунюють bearer token.
|
||||
- Випуск, ротація та відкликання token залишаються обмеженими затвердженим набором ролей, записаним у pairing entry цього пристрою; мутація token не може розширити або націлити роль пристрою, яку pairing approval ніколи не надавало.
|
||||
- Для paired-device token sessions керування пристроями є self-scoped, якщо викликач також не має `operator.admin`: non-admin callers можуть видаляти/відкликати/ротувати лише запис **власного** пристрою.
|
||||
- `device.token.rotate` і `device.token.revoke` також перевіряють набір scope цільового operator token відносно поточних scopes сесії викликача. Non-admin callers не можуть ротувати або відкликати ширший operator token, ніж той, який вони вже мають.
|
||||
- Помилки автентифікації містять `error.details.code` плюс підказки відновлення:
|
||||
- Автентифікація Gateway зі спільним секретом використовує `connect.params.auth.token` або
|
||||
`connect.params.auth.password`, залежно від налаштованого режиму автентифікації.
|
||||
- Режими з ідентичністю, як-от Tailscale Serve
|
||||
(`gateway.auth.allowTailscale: true`) або не-loopback
|
||||
`gateway.auth.mode: "trusted-proxy"`, задовольняють перевірку автентифікації підключення за
|
||||
заголовками запиту замість `connect.params.auth.*`.
|
||||
- Private-ingress `gateway.auth.mode: "none"` повністю пропускає автентифікацію підключення зі спільним секретом; не відкривайте цей режим для публічного/ненадійного ingress.
|
||||
- Після сполучення Gateway видає **токен пристрою**, обмежений роллю підключення
|
||||
+ scopes. Він повертається в `hello-ok.auth.deviceToken` і має бути
|
||||
збережений клієнтом для майбутніх підключень.
|
||||
- Клієнти мають зберігати основний `hello-ok.auth.deviceToken` після будь-якого
|
||||
успішного підключення.
|
||||
- Повторне підключення з цим **збереженим** токеном пристрою також має повторно використовувати збережений
|
||||
набір схвалених scopes для цього токена. Це зберігає доступ read/probe/status,
|
||||
який уже було надано, і запобігає непомітному звуженню повторних підключень до
|
||||
вужчого неявного scope лише для адміністратора.
|
||||
- Клієнтське складання автентифікації підключення (`selectConnectAuth` у
|
||||
`src/gateway/client.ts`):
|
||||
- `auth.password` є ортогональним і завжди пересилається, коли його задано.
|
||||
- `auth.token` заповнюється в порядку пріоритету: спочатку явний спільний токен,
|
||||
потім явний `deviceToken`, потім збережений токен для окремого пристрою (за ключем
|
||||
`deviceId` + `role`).
|
||||
- `auth.bootstrapToken` надсилається лише тоді, коли жоден із наведених вище варіантів не визначив
|
||||
`auth.token`. Спільний токен або будь-який визначений токен пристрою пригнічує його.
|
||||
- Автоматичне підвищення збереженого токена пристрою під час одноразової
|
||||
повторної спроби `AUTH_TOKEN_MISMATCH` дозволене **лише для довірених кінцевих точок** —
|
||||
loopback або `wss://` із закріпленим `tlsFingerprint`. Публічний `wss://`
|
||||
без закріплення не підходить.
|
||||
- Додаткові записи `hello-ok.auth.deviceTokens` є токенами передавання bootstrap.
|
||||
Зберігайте їх лише тоді, коли підключення використовувало bootstrap-автентифікацію на довіреному транспорті,
|
||||
як-от `wss://` або loopback/локальне сполучення.
|
||||
- Якщо клієнт надає **явний** `deviceToken` або явні `scopes`, цей
|
||||
запитаний викликачем набір scopes залишається авторитетним; кешовані scopes використовуються повторно лише
|
||||
тоді, коли клієнт повторно використовує збережений токен для окремого пристрою.
|
||||
- Токени пристроїв можна ротувати/відкликати через `device.token.rotate` і
|
||||
`device.token.revoke` (потрібен scope `operator.pairing`).
|
||||
- `device.token.rotate` повертає метадані ротації. Він віддзеркалює replacement
|
||||
bearer token лише для викликів із того самого пристрою, які вже автентифіковані цим
|
||||
токеном пристрою, щоб клієнти лише з токеном могли зберегти заміну перед
|
||||
повторним підключенням. Ротації shared/admin не віддзеркалюють bearer token.
|
||||
- Видача, ротація та відкликання токенів залишаються обмеженими схваленим набором ролей,
|
||||
записаним у записі сполучення цього пристрою; зміна токена не може розширити або
|
||||
націлитися на роль пристрою, яку ніколи не надавало схвалення сполучення.
|
||||
- Для токен-сесій сполучених пристроїв керування пристроями є self-scoped, якщо
|
||||
викликач також не має `operator.admin`: викликачі без прав адміністратора можуть видаляти/відкликати/ротувати
|
||||
лише запис **власного** пристрою.
|
||||
- `device.token.rotate` і `device.token.revoke` також перевіряють цільовий набір scopes токена
|
||||
оператора щодо поточних scopes сесії викликача. Викликачі без прав адміністратора
|
||||
не можуть ротувати або відкликати ширший токен оператора, ніж той, який вони вже мають.
|
||||
- Помилки автентифікації містять `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`:
|
||||
- Довірені клієнти можуть спробувати одну обмежену повторну спробу з кешованим per-device token.
|
||||
- Якщо ця повторна спроба не вдається, клієнти мають зупинити автоматичні цикли повторного підключення та показати настанови щодо дій оператора.
|
||||
- Довірені клієнти можуть виконати одну обмежену повторну спробу з кешованим токеном для окремого пристрою.
|
||||
- Якщо ця повторна спроба зазнає невдачі, клієнти мають припинити автоматичні цикли повторного підключення та показати оператору вказівки щодо дій.
|
||||
|
||||
## Ідентичність пристрою + pairing
|
||||
## Ідентичність пристрою + сполучення
|
||||
|
||||
- Вузли мають містити стабільну ідентичність пристрою (`device.id`), отриману з
|
||||
- Nodes мають містити стабільну ідентичність пристрою (`device.id`), отриману з
|
||||
відбитка пари ключів.
|
||||
- Gateway видає токени для кожного пристрою + ролі.
|
||||
- Для нових ідентифікаторів пристроїв потрібні схвалення сполучення, якщо не ввімкнено
|
||||
локальне автосхвалення.
|
||||
- Автосхвалення сполучення зосереджене на прямих підключеннях local loopback.
|
||||
- OpenClaw також має вузький шлях самопідключення в межах бекенда/локального контейнера для
|
||||
- Gateways видають токени для кожного пристрою + ролі.
|
||||
- Для нових ідентифікаторів пристроїв потрібні схвалення сполучення, якщо не ввімкнено локальне автоматичне схвалення.
|
||||
- Автоматичне схвалення сполучення зосереджене на прямих підключеннях local loopback.
|
||||
- OpenClaw також має вузький backend/container-local шлях self-connect для
|
||||
довірених допоміжних потоків зі спільним секретом.
|
||||
- Підключення tailnet або LAN на тому самому хості все одно вважаються віддаленими для сполучення й
|
||||
- Підключення з same-host tailnet або LAN все одно розглядаються як віддалені для сполучення та
|
||||
потребують схвалення.
|
||||
- Клієнти WS зазвичай включають ідентичність `device` під час `connect` (оператор +
|
||||
вузол). Єдині винятки для оператора без пристрою — це явні шляхи довіри:
|
||||
- `gateway.controlUi.allowInsecureAuth=true` для сумісності з небезпечним HTTP лише на localhost.
|
||||
- успішна автентифікація оператора Control UI через `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (аварійний режим, суттєве зниження безпеки).
|
||||
- прямі loopback RPC бекенда `gateway-client`, автентифіковані за допомогою спільного
|
||||
токена/пароля Gateway.
|
||||
- WS-клієнти зазвичай додають ідентичність `device` під час `connect` (operator +
|
||||
node). Єдині винятки оператора без пристрою — явні довірені шляхи:
|
||||
- `gateway.controlUi.allowInsecureAuth=true` для localhost-only insecure HTTP-сумісності.
|
||||
- успішна автентифікація operator Control UI з `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (break-glass, серйозне зниження безпеки).
|
||||
- direct-loopback `gateway-client` backend RPCs, автентифіковані спільним
|
||||
токеном/паролем gateway.
|
||||
- Усі підключення мають підписувати наданий сервером nonce `connect.challenge`.
|
||||
|
||||
### Діагностика міграції автентифікації пристрою
|
||||
@ -622,32 +683,32 @@ Gateway трактує їх як **заявки** та застосовує се
|
||||
| Повідомлення | 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` | Позначка часу підпису виходить за межі дозволеного відхилення. |
|
||||
| `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 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` не відповідає відбитку публічного ключа. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Формат/канонікалізація публічного ключа зазнали невдачі. |
|
||||
|
||||
Ціль міграції:
|
||||
|
||||
- Завжди чекайте на `connect.challenge`.
|
||||
- Підписуйте корисне навантаження v2, яке містить server nonce.
|
||||
- Підписуйте payload v2, що містить nonce сервера.
|
||||
- Надсилайте той самий nonce у `connect.params.device.nonce`.
|
||||
- Бажане корисне навантаження підпису — `v3`, яке прив’язує `platform` і `deviceFamily`
|
||||
на додаток до полів пристрою/клієнта/ролі/областей дії/токена/nonce.
|
||||
- Застарілі підписи `v2` залишаються прийнятими для сумісності, але закріплення
|
||||
метаданих сполученого пристрою й надалі керує політикою команд під час повторного підключення.
|
||||
- Бажаний payload підпису — `v3`, який прив’язує `platform` і `deviceFamily`
|
||||
на додачу до полів device/client/role/scopes/token/nonce.
|
||||
- Застарілі підписи `v2` залишаються прийнятими для сумісності, але pinning метаданих
|
||||
сполученого пристрою все ще керує політикою команд під час повторного підключення.
|
||||
|
||||
## TLS + закріплення
|
||||
|
||||
- TLS підтримується для підключень WS.
|
||||
- Клієнти можуть необов’язково закріпити відбиток сертифіката Gateway (див. конфігурацію `gateway.tls`
|
||||
- TLS підтримується для WS-підключень.
|
||||
- Клієнти можуть опційно закріпити відбиток сертифіката gateway (див. конфігурацію `gateway.tls`
|
||||
плюс `gateway.remote.tlsFingerprint` або CLI `--tls-fingerprint`).
|
||||
|
||||
## Область дії
|
||||
## Scope
|
||||
|
||||
Цей протокол надає **повний API Gateway** (статус, канали, моделі, чат,
|
||||
агент, сесії, вузли, схвалення тощо). Точна поверхня визначається
|
||||
Цей протокол відкриває **повний API gateway** (status, channels, models, chat,
|
||||
agent, sessions, nodes, approvals тощо). Точна поверхня визначена
|
||||
схемами TypeBox у `src/gateway/protocol/schema.ts`.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
Loading…
Reference in New Issue
Block a user