chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
dab841265c
commit
694810bc95
@ -1,16 +1,16 @@
|
||||
---
|
||||
read_when:
|
||||
- Перегляд фонової роботи, що триває або нещодавно завершилася
|
||||
- Налагодження збоїв доставки для відокремлених запусків агентів
|
||||
- Перегляд фонової роботи, що виконується або нещодавно завершилася
|
||||
- Налагодження збоїв доставки для від’єднаних запусків агентів
|
||||
- Розуміння того, як фонові запуски пов’язані із сеансами, Cron і Heartbeat
|
||||
sidebarTitle: Background tasks
|
||||
summary: Відстеження фонових завдань для запусків ACP, субагентів, ізольованих завдань Cron і операцій CLI
|
||||
summary: Відстеження фонових завдань для запусків ACP, субагентів, ізольованих завдань Cron та операцій CLI
|
||||
title: Фонові завдання
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T11:04:13Z"
|
||||
generated_at: "2026-04-28T20:11:28Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 54843ab3831dceb3df810a17dbe97e2824d99bae2233291a70f52aca168778b4
|
||||
source_hash: ff4f22f98148b01c1b044a5213a5946eac8c5d763f0d22c992e6a4a2297bc308
|
||||
source_path: automation/tasks.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -19,35 +19,35 @@ x-i18n:
|
||||
Шукаєте планування? Див. [Автоматизація та завдання](/uk/automation), щоб вибрати правильний механізм. Ця сторінка є журналом активності для фонової роботи, а не планувальником.
|
||||
</Note>
|
||||
|
||||
Фонові завдання відстежують роботу, що виконується **поза вашим основним сеансом розмови**: запуски ACP, створення субагентів, ізольовані виконання cron-завдань і операції, ініційовані з CLI.
|
||||
Фонові завдання відстежують роботу, яка виконується **поза основним сеансом розмови**: запуски ACP, створення субагентів, ізольовані виконання завдань cron і операції, ініційовані CLI.
|
||||
|
||||
Завдання **не** замінюють сеанси, cron-завдання чи Heartbeat — вони є **журналом активності**, який записує, яка відокремлена робота відбулася, коли саме та чи завершилася вона успішно.
|
||||
Завдання **не** замінюють сеанси, завдання cron чи heartbeats — вони є **журналом активності**, який записує, яка відокремлена робота відбулася, коли саме та чи була вона успішною.
|
||||
|
||||
<Note>
|
||||
Не кожен запуск агента створює завдання. Ходи Heartbeat і звичайний інтерактивний чат не створюють. Усі виконання cron, створення ACP, створення субагентів і агентні команди CLI створюють.
|
||||
Не кожен запуск агента створює завдання. Heartbeat-ходи та звичайний інтерактивний чат цього не роблять. Усі виконання cron, створення ACP, створення субагентів і команди агента CLI створюють завдання.
|
||||
</Note>
|
||||
|
||||
## TL;DR
|
||||
## Коротко
|
||||
|
||||
- Завдання — це **записи**, а не планувальники — cron і Heartbeat вирішують, _коли_ виконується робота, а завдання відстежують, _що сталося_.
|
||||
- ACP, субагенти, усі cron-завдання й операції CLI створюють завдання. Ходи Heartbeat не створюють.
|
||||
- Завдання — це **записи**, а не планувальники: cron і heartbeat вирішують, _коли_ виконується робота, а завдання відстежують, _що сталося_.
|
||||
- ACP, субагенти, усі завдання cron і операції CLI створюють завдання. Heartbeat-ходи цього не роблять.
|
||||
- Кожне завдання проходить через `queued → running → terminal` (succeeded, failed, timed_out, cancelled або lost).
|
||||
- Cron-завдання залишаються активними, доки середовище виконання cron усе ще володіє завданням; якщо
|
||||
стан середовища виконання в пам’яті зник, супровід завдань спершу перевіряє стійку історію запусків cron,
|
||||
перш ніж позначити завдання як lost.
|
||||
- Завершення керується push-механізмом: відокремлена робота може сповістити напряму або пробудити
|
||||
сеанс запитувача/Heartbeat після завершення, тому цикли опитування статусу
|
||||
- Завдання Cron залишаються активними, доки середовище виконання cron усе ще володіє завданням; якщо
|
||||
стан середовища виконання в пам’яті зник, обслуговування завдань спершу перевіряє збережену історію запусків cron,
|
||||
перш ніж позначити завдання як втрачене.
|
||||
- Завершення працює через push: відокремлена робота може сповіщати напряму або пробуджувати
|
||||
сеанс/heartbeat запитувача після завершення, тому цикли опитування статусу
|
||||
зазвичай мають неправильну форму.
|
||||
- Ізольовані запуски cron і завершення субагентів докладають максимальних зусиль, щоб очистити відстежувані вкладки браузера/процеси для свого дочірнього сеансу перед фінальним службовим очищенням.
|
||||
- Ізольована доставка cron пригнічує застарілі проміжні відповіді батьківського сеансу, доки робота нащадкових субагентів ще завершується, і віддає перевагу фінальному виводу нащадка, якщо він надходить до доставки.
|
||||
- Сповіщення про завершення доставляються напряму в канал або ставляться в чергу для наступного Heartbeat.
|
||||
- Ізольовані запуски cron і завершення субагентів за можливості очищають відстежувані вкладки браузера/процеси для свого дочірнього сеансу перед фінальним службовим очищенням.
|
||||
- Ізольована доставка cron пригнічує застарілі проміжні відповіді батьківського сеансу, поки робота нащадків-субагентів ще завершується, і надає перевагу фінальному виводу нащадка, якщо він надходить до доставки.
|
||||
- Сповіщення про завершення доставляються напряму в канал або ставляться в чергу до наступного heartbeat.
|
||||
- `openclaw tasks list` показує всі завдання; `openclaw tasks audit` виявляє проблеми.
|
||||
- Термінальні записи зберігаються 7 днів, а потім автоматично видаляються.
|
||||
- Термінальні записи зберігаються 7 днів, а потім автоматично очищаються.
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Список і фільтрування">
|
||||
<Tab title="List and filter">
|
||||
```bash
|
||||
# List all tasks (newest first)
|
||||
openclaw tasks list
|
||||
@ -58,13 +58,13 @@ x-i18n:
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab title="Перегляд">
|
||||
<Tab title="Inspect">
|
||||
```bash
|
||||
# Show details for a specific task (by ID, run ID, or session key)
|
||||
openclaw tasks show <lookup>
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Скасування та сповіщення">
|
||||
<Tab title="Cancel and notify">
|
||||
```bash
|
||||
# Cancel a running task (kills the child session)
|
||||
openclaw tasks cancel <lookup>
|
||||
@ -74,7 +74,7 @@ x-i18n:
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab title="Аудит і супровід">
|
||||
<Tab title="Audit and maintenance">
|
||||
```bash
|
||||
# Run a health audit
|
||||
openclaw tasks audit
|
||||
@ -85,7 +85,7 @@ x-i18n:
|
||||
```
|
||||
|
||||
</Tab>
|
||||
<Tab title="Потік завдань">
|
||||
<Tab title="Task flow">
|
||||
```bash
|
||||
# Inspect TaskFlow state
|
||||
openclaw tasks flow list
|
||||
@ -97,26 +97,26 @@ x-i18n:
|
||||
|
||||
## Що створює завдання
|
||||
|
||||
| Джерело | Тип середовища виконання | Коли створюється запис завдання | Типова політика сповіщень |
|
||||
| Джерело | Тип середовища виконання | Коли створюється запис завдання | Типова політика сповіщень |
|
||||
| ---------------------- | ------------ | ------------------------------------------------------ | --------------------- |
|
||||
| Фонові запуски ACP | `acp` | Створення дочірнього сеансу ACP | `done_only` |
|
||||
| Фонові запуски ACP | `acp` | Створення дочірнього сеансу ACP | `done_only` |
|
||||
| Оркестрація субагентів | `subagent` | Створення субагента через `sessions_spawn` | `done_only` |
|
||||
| Cron-завдання (усі типи) | `cron` | Кожне виконання cron (основний сеанс та ізольоване) | `silent` |
|
||||
| Операції CLI | `cli` | Команди `openclaw agent`, що виконуються через gateway | `silent` |
|
||||
| Медіазавдання агента | `cli` | Запуски `video_generate`, підтримані сеансом | `silent` |
|
||||
| Завдання Cron (усі типи) | `cron` | Кожне виконання cron (у головному сеансі та ізольоване) | `silent` |
|
||||
| Операції CLI | `cli` | Команди `openclaw agent`, що виконуються через Gateway | `silent` |
|
||||
| Медіазавдання агента | `cli` | Запуски `video_generate`, прив’язані до сеансу | `silent` |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Типові сповіщення для cron і медіа">
|
||||
Cron-завдання основного сеансу за замовчуванням використовують політику сповіщень `silent` — вони створюють записи для відстеження, але не генерують сповіщень. Ізольовані cron-завдання також за замовчуванням використовують `silent`, але вони помітніші, бо виконуються у власному сеансі.
|
||||
<Accordion title="Notify defaults for cron and media">
|
||||
Завдання cron у головному сеансі типово використовують політику сповіщень `silent` — вони створюють записи для відстеження, але не генерують сповіщень. Ізольовані завдання cron також типово мають `silent`, але є помітнішими, оскільки виконуються у власному сеансі.
|
||||
|
||||
Запуски `video_generate`, підтримані сеансом, також використовують політику сповіщень `silent`. Вони все одно створюють записи завдань, але завершення повертається до початкового сеансу агента як внутрішнє пробудження, щоб агент міг сам написати подальше повідомлення й прикріпити готове відео. Якщо ви вмикаєте `tools.media.asyncCompletion.directSend`, асинхронні завершення `music_generate` і `video_generate` спершу намагаються виконати пряму доставку в канал, перш ніж повернутися до шляху пробудження сеансу запитувача.
|
||||
Запуски `video_generate`, прив’язані до сеансу, також використовують політику сповіщень `silent`. Вони все одно створюють записи завдань, але завершення повертається до початкового сеансу агента як внутрішнє пробудження, щоб агент міг сам написати наступне повідомлення й прикріпити готове відео. Якщо ввімкнути `tools.media.asyncCompletion.directSend`, асинхронні завершення `music_generate` і `video_generate` спершу намагаються доставити результат напряму в канал, перш ніж перейти до шляху пробудження сеансу запитувача.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Запобіжник для одночасних video_generate">
|
||||
Доки завдання `video_generate`, підтримане сеансом, усе ще активне, інструмент також працює як запобіжник: повторні виклики `video_generate` у тому самому сеансі повертають статус активного завдання замість запуску другої паралельної генерації. Використовуйте `action: "status"`, коли потрібен явний запит прогресу/статусу з боку агента.
|
||||
<Accordion title="Concurrent video_generate guardrail">
|
||||
Поки завдання `video_generate`, прив’язане до сеансу, ще активне, інструмент також діє як запобіжник: повторні виклики `video_generate` у тому самому сеансі повертають статус активного завдання замість запуску другої паралельної генерації. Використовуйте `action: "status"`, коли потрібен явний запит прогресу/статусу з боку агента.
|
||||
</Accordion>
|
||||
<Accordion title="Що не створює завдань">
|
||||
- Ходи Heartbeat — основний сеанс; див. [Heartbeat](/uk/gateway/heartbeat)
|
||||
<Accordion title="What does not create tasks">
|
||||
- Heartbeat-ходи — у головному сеансі; див. [Heartbeat](/uk/gateway/heartbeat)
|
||||
- Звичайні інтерактивні ходи чату
|
||||
- Прямі відповіді `/command`
|
||||
|
||||
@ -137,13 +137,13 @@ stateDiagram-v2
|
||||
running --> lost : session gone > 5 min
|
||||
```
|
||||
|
||||
| Статус | Що це означає |
|
||||
| Статус | Що це означає |
|
||||
| ----------- | -------------------------------------------------------------------------- |
|
||||
| `queued` | Створено, очікує запуску агента |
|
||||
| `running` | Хід агента активно виконується |
|
||||
| `succeeded` | Успішно завершено |
|
||||
| `failed` | Завершено з помилкою |
|
||||
| `timed_out` | Перевищено налаштований тайм-аут |
|
||||
| `timed_out` | Перевищено налаштований час очікування |
|
||||
| `cancelled` | Зупинено оператором через `openclaw tasks cancel` |
|
||||
| `lost` | Середовище виконання втратило авторитетний базовий стан після 5-хвилинного пільгового періоду |
|
||||
|
||||
@ -151,32 +151,32 @@ stateDiagram-v2
|
||||
|
||||
Завершення запуску агента є авторитетним для активних записів завдань. Успішний відокремлений запуск фіналізується як `succeeded`, звичайні помилки запуску фіналізуються як `failed`, а результати тайм-ауту або переривання фіналізуються як `timed_out`. Якщо оператор уже скасував завдання або середовище виконання вже записало сильніший термінальний стан, як-от `failed`, `timed_out` чи `lost`, пізніший сигнал успіху не знижує цей термінальний статус.
|
||||
|
||||
`lost` залежить від середовища виконання:
|
||||
`lost` враховує середовище виконання:
|
||||
|
||||
- Завдання ACP: зникли метадані базового дочірнього сеансу ACP.
|
||||
- Завдання субагентів: базовий дочірній сеанс зник зі сховища цільового агента.
|
||||
- Cron-завдання: середовище виконання cron більше не відстежує завдання як активне, а стійка
|
||||
- Завдання Cron: середовище виконання cron більше не відстежує завдання як активне, а збережена
|
||||
історія запусків cron не показує термінального результату для цього запуску. Офлайн-аудит CLI
|
||||
не вважає власний порожній внутрішньопроцесний стан середовища виконання cron авторитетним.
|
||||
- Завдання CLI: ізольовані завдання дочірніх сеансів використовують дочірній сеанс; підтримані чатом
|
||||
завдання CLI натомість використовують живий контекст запуску, тому залишкові
|
||||
рядки сеансів каналу/групи/особистого чату не підтримують їх активними. Запуски
|
||||
`openclaw agent`, підтримані Gateway, також фіналізуються за результатом свого запуску, тому завершені запуски
|
||||
не вважає власний порожній стан cron у процесі авторитетним.
|
||||
- Завдання CLI: ізольовані завдання дочірнього сеансу використовують дочірній сеанс; завдання CLI,
|
||||
прив’язані до чату, натомість використовують живий контекст запуску, тому тривалі рядки
|
||||
сеансів каналу/групи/приватного чату не підтримують їх активними. Запуски
|
||||
`openclaw agent`, прив’язані до Gateway, також фіналізуються за результатом запуску, тому завершені запуски
|
||||
не залишаються активними, доки прибиральник не позначить їх як `lost`.
|
||||
|
||||
## Доставка та сповіщення
|
||||
|
||||
Коли завдання досягає термінального стану, OpenClaw сповіщає вас. Є два шляхи доставки:
|
||||
|
||||
**Пряма доставка** — якщо завдання має цільовий канал (`requesterOrigin`), повідомлення про завершення надсилається прямо в цей канал (Telegram, Discord, Slack тощо). Для завершень субагентів OpenClaw також зберігає прив’язану маршрутизацію гілки/теми, коли вона доступна, і може заповнити відсутні `to` / обліковий запис зі збереженого маршруту сеансу запитувача (`lastChannel` / `lastTo` / `lastAccountId`), перш ніж відмовитися від прямої доставки.
|
||||
**Пряма доставка** — якщо завдання має цільовий канал (`requesterOrigin`), повідомлення про завершення надсилається прямо в цей канал (Telegram, Discord, Slack тощо). Для завершень субагентів OpenClaw також зберігає прив’язану маршрутизацію thread/topic, коли вона доступна, і може заповнити відсутнє `to` / обліковий запис зі збереженого маршруту сеансу запитувача (`lastChannel` / `lastTo` / `lastAccountId`), перш ніж відмовитися від прямої доставки.
|
||||
|
||||
**Доставка через чергу сеансу** — якщо пряма доставка не вдається або джерело не задане, оновлення ставиться в чергу як системна подія в сеансі запитувача й з’являється під час наступного Heartbeat.
|
||||
**Доставка через чергу сеансу** — якщо пряма доставка не вдається або origin не задано, оновлення ставиться в чергу як системна подія в сеансі запитувача й з’являється під час наступного heartbeat.
|
||||
|
||||
<Tip>
|
||||
Завершення завдання запускає негайне пробудження Heartbeat, тож ви швидко бачите результат — вам не потрібно чекати наступного запланованого такту Heartbeat.
|
||||
Завершення завдання запускає негайне пробудження heartbeat, тож ви швидко бачите результат — не потрібно чекати наступного запланованого heartbeat-тику.
|
||||
</Tip>
|
||||
|
||||
Це означає, що звичний робочий процес є push-орієнтованим: запустіть відокремлену роботу один раз, а потім дозвольте середовищу виконання пробудити вас або сповістити після завершення. Опитуйте стан завдання лише тоді, коли потрібні налагодження, втручання або явний аудит.
|
||||
Це означає, що звичний робочий процес є push-орієнтованим: один раз запустіть відокремлену роботу, а потім дозвольте середовищу виконання пробудити вас або сповістити про завершення. Опитуйте стан завдання лише тоді, коли потрібні налагодження, втручання або явний аудит.
|
||||
|
||||
### Політики сповіщень
|
||||
|
||||
@ -184,11 +184,11 @@ stateDiagram-v2
|
||||
|
||||
| Політика | Що доставляється |
|
||||
| --------------------- | ----------------------------------------------------------------------- |
|
||||
| `done_only` (типово) | Лише термінальний стан (succeeded, failed тощо) — **це типове значення** |
|
||||
| `state_changes` | Кожен перехід стану та оновлення прогресу |
|
||||
| `silent` | Нічого |
|
||||
| `done_only` (типово) | Лише термінальний стан (succeeded, failed тощо) — **це типове значення** |
|
||||
| `state_changes` | Кожен перехід стану й оновлення прогресу |
|
||||
| `silent` | Узагалі нічого |
|
||||
|
||||
Змініть політику, доки завдання виконується:
|
||||
Змініть політику, поки завдання виконується:
|
||||
|
||||
```bash
|
||||
openclaw tasks notify <lookup> state_changes
|
||||
@ -202,7 +202,7 @@ openclaw tasks notify <lookup> state_changes
|
||||
openclaw tasks list [--runtime <acp|subagent|cron|cli>] [--status <status>] [--json]
|
||||
```
|
||||
|
||||
Стовпці виводу: ID завдання, вид, статус, доставка, ID запуску, дочірній сеанс, зведення.
|
||||
Стовпці виводу: ID завдання, тип, статус, доставка, ID запуску, дочірній сеанс, підсумок.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="tasks show">
|
||||
@ -210,7 +210,7 @@ openclaw tasks notify <lookup> state_changes
|
||||
openclaw tasks show <lookup>
|
||||
```
|
||||
|
||||
Токен пошуку приймає ID завдання, ID запуску або ключ сеансу. Показує повний запис, зокрема час, стан доставки, помилку та термінальне зведення.
|
||||
Токен lookup приймає ID завдання, ID запуску або ключ сеансу. Показує повний запис, зокрема час, стан доставки, помилку й термінальний підсумок.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="tasks cancel">
|
||||
@ -218,7 +218,7 @@ openclaw tasks notify <lookup> state_changes
|
||||
openclaw tasks cancel <lookup>
|
||||
```
|
||||
|
||||
Для завдань ACP і субагентів це завершує дочірній сеанс. Для завдань, відстежуваних CLI, скасування записується в реєстрі завдань (окремого дескриптора дочірнього середовища виконання немає). Статус переходить у `cancelled`, а сповіщення про доставку надсилається, коли це застосовно.
|
||||
Для завдань ACP і субагентів це завершує дочірній сеанс. Для завдань, відстежуваних CLI, скасування записується в реєстрі завдань (окремого дескриптора дочірнього середовища виконання немає). Статус переходить у `cancelled`, і за потреби надсилається сповіщення про доставку.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="tasks notify">
|
||||
@ -231,64 +231,64 @@ openclaw tasks notify <lookup> state_changes
|
||||
openclaw tasks audit [--json]
|
||||
```
|
||||
|
||||
Виявляє операційні проблеми. Знахідки також з’являються в `openclaw status`, коли виявлено проблеми.
|
||||
Виявляє операційні проблеми. Знахідки також з’являються в `openclaw status`, коли проблеми виявлено.
|
||||
|
||||
| Знахідка | Серйозність | Тригер |
|
||||
| ------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------- |
|
||||
| `stale_queued` | warn | У черзі понад 10 хвилин |
|
||||
| `stale_running` | error | Виконується понад 30 хвилин |
|
||||
| `lost` | warn/error | Власність над задачею, підтримана середовищем виконання, зникла; збережені втрачені задачі попереджають до `cleanupAfter`, потім стають помилками |
|
||||
| `delivery_failed` | warn | Доставка не вдалася, а політика сповіщень не `silent` |
|
||||
| `missing_cleanup` | warn | Завершальна задача без позначки часу очищення |
|
||||
| `inconsistent_timestamps` | warn | Порушення часової шкали (наприклад, завершено до початку) |
|
||||
| Виявлення | Серйозність | Тригер |
|
||||
| ------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- |
|
||||
| `stale_queued` | warn | У черзі понад 10 хвилин |
|
||||
| `stale_running` | error | Виконується понад 30 хвилин |
|
||||
| `lost` | warn/error | Власність над завданням із підтримкою runtime зникла; збережені втрачені завдання попереджають до `cleanupAfter`, потім стають помилками |
|
||||
| `delivery_failed` | warn | Доставка не вдалася, а політика сповіщень не є `silent` |
|
||||
| `missing_cleanup` | warn | Термінальне завдання без часової позначки очищення |
|
||||
| `inconsistent_timestamps` | warn | Порушення часової шкали (наприклад, завершилося до початку) |
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="обслуговування задач">
|
||||
<Accordion title="обслуговування завдань">
|
||||
```bash
|
||||
openclaw tasks maintenance [--json]
|
||||
openclaw tasks maintenance --apply [--json]
|
||||
```
|
||||
|
||||
Використовуйте це, щоб попередньо переглянути або застосувати узгодження, проставлення позначок очищення та скорочення для задач і стану Task Flow.
|
||||
Використовуйте це, щоб переглянути або застосувати звірення, проставлення очищення та обрізання для завдань і стану Task Flow.
|
||||
|
||||
Узгодження враховує середовище виконання:
|
||||
Звірення враховує runtime:
|
||||
|
||||
- Задачі ACP/субагентів перевіряють свій базовий дочірній сеанс.
|
||||
- Задачі Cron перевіряють, чи середовище виконання cron досі володіє завданням, а потім відновлюють завершальний статус зі збережених журналів запусків cron/стану завдання, перш ніж повертатися до `lost`. Лише процес Gateway є авторитетним для набору активних завдань cron у пам’яті; офлайн-аудит CLI використовує довговічну історію, але не позначає задачу cron втраченою лише тому, що цей локальний Set порожній.
|
||||
- Задачі CLI, підтримані чатом, перевіряють живий контекст запуску власника, а не лише рядок сеансу чату.
|
||||
- Завдання ACP/subagent перевіряють свою дочірню сесію, що їх підтримує.
|
||||
- Завдання Cron перевіряють, чи cron runtime досі володіє завданням, потім відновлюють термінальний статус зі збережених журналів запусків cron/стану завдання, перш ніж перейти до `lost`. Лише процес Gateway є авторитетним для набору активних завдань cron у пам’яті; офлайн-аудит CLI використовує довговічну історію, але не позначає завдання cron як втрачене лише тому, що цей локальний Set порожній.
|
||||
- CLI-завдання з підтримкою чату перевіряють власний контекст живого запуску, а не лише рядок сесії чату.
|
||||
|
||||
Очищення після завершення також враховує середовище виконання:
|
||||
Очищення після завершення також враховує runtime:
|
||||
|
||||
- Завершення субагента найкращими зусиллями закриває відстежувані вкладки браузера/процеси для дочірнього сеансу перед продовженням оголошеного очищення.
|
||||
- Завершення ізольованого cron найкращими зусиллями закриває відстежувані вкладки браузера/процеси для сеансу cron перед повним згортанням запуску.
|
||||
- Доставка ізольованого cron за потреби очікує подальшу дію нащадкового субагента та пригнічує застарілий текст підтвердження батьківської задачі замість його оголошення.
|
||||
- Доставка завершення субагента віддає перевагу найновішому видимому тексту асистента; якщо він порожній, вона повертається до очищеного найновішого тексту tool/toolResult, а запуски викликів інструментів лише з тайм-аутом можуть згортатися до короткого підсумку часткового прогресу. Завершальні невдалі запуски оголошують статус помилки без повторного відтворення захопленого тексту відповіді.
|
||||
- Помилки очищення не маскують реальний результат задачі.
|
||||
- Завершення subagent за принципом найкращого зусилля закриває відстежувані вкладки браузера/процеси для дочірньої сесії перед тим, як продовжиться очищення оголошення.
|
||||
- Завершення ізольованого cron за принципом найкращого зусилля закриває відстежувані вкладки браузера/процеси для сесії cron перед повним завершенням запуску.
|
||||
- Доставка ізольованого cron за потреби очікує подальшу дію нащадка subagent і пригнічує застарілий текст підтвердження батьківського елемента замість його оголошення.
|
||||
- Доставка завершення subagent віддає перевагу найновішому видимому тексту асистента; якщо він порожній, вона повертається до очищеного найновішого тексту tool/toolResult, а запуски викликів інструментів лише з тайм-аутом можуть згортатися до короткого підсумку часткового прогресу. Термінальні невдалі запуски оголошують статус помилки без повторного відтворення захопленого тексту відповіді.
|
||||
- Помилки очищення не приховують справжній результат завдання.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="список | показ | скасування flow задач">
|
||||
<Accordion title="список | показ | скасування потоку завдань">
|
||||
```bash
|
||||
openclaw tasks flow list [--status <status>] [--json]
|
||||
openclaw tasks flow show <lookup> [--json]
|
||||
openclaw tasks flow cancel <lookup>
|
||||
```
|
||||
|
||||
Використовуйте їх, коли вас цікавить оркеструвальний Task Flow, а не один окремий запис фонової задачі.
|
||||
Використовуйте ці команди, коли вас цікавить оркеструвальний Task Flow, а не один окремий запис фонового завдання.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Дошка задач чату (`/tasks`)
|
||||
## Дошка завдань у чаті (`/tasks`)
|
||||
|
||||
Використовуйте `/tasks` у будь-якому сеансі чату, щоб побачити фонові задачі, пов’язані з цим сеансом. Дошка показує активні та нещодавно завершені задачі із середовищем виконання, статусом, часом і прогресом або деталями помилки.
|
||||
Використовуйте `/tasks` у будь-якій чат-сесії, щоб побачити фонові завдання, пов’язані з цією сесією. Дошка показує активні й нещодавно завершені завдання з runtime, статусом, часом, а також деталями прогресу або помилки.
|
||||
|
||||
Коли поточний сеанс не має видимих пов’язаних задач, `/tasks` повертається до локальних для агента лічильників задач, тож ви все одно отримуєте огляд без розкриття деталей інших сеансів.
|
||||
Коли поточна сесія не має видимих пов’язаних завдань, `/tasks` повертається до локальних для агента лічильників завдань, щоб ви все одно отримали огляд без витоку деталей інших сесій.
|
||||
|
||||
Для повного операторського журналу використовуйте CLI: `openclaw tasks list`.
|
||||
|
||||
## Інтеграція статусу (навантаження задач)
|
||||
## Інтеграція статусу (навантаження завдань)
|
||||
|
||||
`openclaw status` містить короткий підсумок задач:
|
||||
`openclaw status` містить стислий підсумок завдань:
|
||||
|
||||
```
|
||||
Tasks: 3 queued · 2 running · 1 issues
|
||||
@ -296,79 +296,81 @@ Tasks: 3 queued · 2 running · 1 issues
|
||||
|
||||
Підсумок повідомляє:
|
||||
|
||||
- **active** — кількість `queued` + `running`
|
||||
- **failures** — кількість `failed` + `timed_out` + `lost`
|
||||
- **byRuntime** — розподіл за `acp`, `subagent`, `cron`, `cli`
|
||||
- **активні** — кількість `queued` + `running`
|
||||
- **помилки** — кількість `failed` + `timed_out` + `lost`
|
||||
- **заRuntime** — розбивка за `acp`, `subagent`, `cron`, `cli`
|
||||
|
||||
І `/status`, і інструмент `session_status` використовують знімок задач, що враховує очищення: активні задачі мають пріоритет, застарілі завершені рядки приховуються, а нещодавні помилки показуються лише тоді, коли не залишилося активної роботи. Це утримує картку статусу сфокусованою на тому, що важливо зараз.
|
||||
І `/status`, і інструмент `session_status` використовують знімок завдань із урахуванням очищення: активні завдання мають пріоритет, застарілі завершені рядки приховуються, а нещодавні помилки показуються лише тоді, коли не залишилося активної роботи. Це утримує картку статусу зосередженою на тому, що важливо зараз.
|
||||
|
||||
## Зберігання та обслуговування
|
||||
## Сховище та обслуговування
|
||||
|
||||
### Де зберігаються задачі
|
||||
### Де зберігаються завдання
|
||||
|
||||
Записи задач зберігаються в SQLite за адресою:
|
||||
Записи завдань зберігаються в SQLite за адресою:
|
||||
|
||||
```
|
||||
$OPENCLAW_STATE_DIR/tasks/runs.sqlite
|
||||
```
|
||||
|
||||
Реєстр завантажується в пам’ять під час запуску Gateway і синхронізує записи з SQLite для довговічності між перезапусками.
|
||||
Gateway утримує журнал попереднього запису SQLite обмеженим, використовуючи стандартний поріг
|
||||
autocheckpoint SQLite, а також періодичні контрольні точки `TRUNCATE` і контрольні точки під час завершення роботи.
|
||||
Реєстр завантажується в пам’ять під час запуску gateway і синхронізує записи в SQLite для довговічності між перезапусками.
|
||||
Gateway утримує журнал попереднього запису SQLite в обмежених межах за допомогою стандартного порога autocheckpoint SQLite, а також періодичних і завершальних контрольних точок `TRUNCATE`.
|
||||
|
||||
### Автоматичне обслуговування
|
||||
|
||||
Очищувач запускається кожні **60 секунд** і виконує три речі:
|
||||
Очищувач запускається кожні **60 секунд** і виконує чотири дії:
|
||||
|
||||
<Steps>
|
||||
<Step title="Узгодження">
|
||||
Перевіряє, чи активні задачі досі мають авторитетну підтримку середовища виконання. Задачі ACP/субагентів використовують стан дочірнього сеансу, задачі cron використовують власність активного завдання, а задачі CLI, підтримані чатом, використовують контекст запуску власника. Якщо цей базовий стан відсутній понад 5 хвилин, задачу позначають як `lost`.
|
||||
<Step title="Звірення">
|
||||
Перевіряє, чи активні завдання досі мають авторитетну підтримку runtime. Завдання ACP/subagent використовують стан дочірньої сесії, завдання cron використовують власність активного завдання, а CLI-завдання з підтримкою чату використовують власний контекст запуску. Якщо цей стан підтримки відсутній понад 5 хвилин, завдання позначається як `lost`.
|
||||
</Step>
|
||||
<Step title="Проставлення позначок очищення">
|
||||
Встановлює позначку часу `cleanupAfter` для завершальних задач (endedAt + 7 днів). Під час утримання втрачені задачі все ще відображаються в аудиті як попередження; після завершення строку `cleanupAfter` або коли метадані очищення відсутні, вони є помилками.
|
||||
<Step title="Відновлення сесії ACP">
|
||||
Закриває термінальні одноразові сесії ACP, якими володіє батьківський елемент, і закриває застарілі термінальні постійні сесії ACP лише тоді, коли не залишається активної прив’язки розмови.
|
||||
</Step>
|
||||
<Step title="Скорочення">
|
||||
<Step title="Проставлення очищення">
|
||||
Встановлює часову позначку `cleanupAfter` для термінальних завдань (endedAt + 7 днів). Протягом утримання втрачені завдання все ще з’являються в аудиті як попередження; після завершення строку `cleanupAfter` або коли метадані очищення відсутні, вони є помилками.
|
||||
</Step>
|
||||
<Step title="Обрізання">
|
||||
Видаляє записи після їхньої дати `cleanupAfter`.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
**Утримання:** записи завершальних задач зберігаються **7 днів**, а потім автоматично скорочуються. Налаштування не потрібне.
|
||||
**Утримання:** записи термінальних завдань зберігаються **7 днів**, а потім автоматично обрізаються. Налаштування не потрібне.
|
||||
</Note>
|
||||
|
||||
## Як задачі пов’язані з іншими системами
|
||||
## Як завдання пов’язані з іншими системами
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Задачі та Task Flow">
|
||||
[Task Flow](/uk/automation/taskflow) — це шар оркестрації потоків над фоновими задачами. Один потік може координувати кілька задач протягом свого життєвого циклу, використовуючи керовані або дзеркальні режими синхронізації. Використовуйте `openclaw tasks`, щоб перевіряти окремі записи задач, і `openclaw tasks flow`, щоб перевіряти оркеструвальний потік.
|
||||
<Accordion title="Завдання і Task Flow">
|
||||
[Task Flow](/uk/automation/taskflow) — це шар оркестрації потоків над фоновими завданнями. Один потік може координувати кілька завдань протягом свого життєвого циклу, використовуючи керовані або дзеркальні режими синхронізації. Використовуйте `openclaw tasks`, щоб перевіряти окремі записи завдань, і `openclaw tasks flow`, щоб перевіряти оркеструвальний потік.
|
||||
|
||||
Докладніше див. у [Task Flow](/uk/automation/taskflow).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Задачі та cron">
|
||||
**Визначення** завдання cron зберігається в `~/.openclaw/cron/jobs.json`; стан виконання середовища виконання зберігається поруч у `~/.openclaw/cron/jobs-state.json`. **Кожне** виконання cron створює запис задачі — і основного сеансу, і ізольований. Задачі cron основного сеансу за замовчуванням мають політику сповіщень `silent`, тож вони відстежуються без створення сповіщень.
|
||||
<Accordion title="Завдання і cron">
|
||||
**Визначення** завдання cron зберігається в `~/.openclaw/cron/jobs.json`; стан виконання runtime зберігається поруч у `~/.openclaw/cron/jobs-state.json`. **Кожне** виконання cron створює запис завдання — як основної сесії, так і ізольованої. Завдання cron основної сесії за замовчуванням використовують політику сповіщень `silent`, тому вони відстежуються без створення сповіщень.
|
||||
|
||||
Див. [Завдання Cron](/uk/automation/cron-jobs).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Задачі та heartbeat">
|
||||
Запуски Heartbeat є ходами основного сеансу — вони не створюють записів задач. Коли задача завершується, вона може спричинити пробудження Heartbeat, щоб ви швидко побачили результат.
|
||||
<Accordion title="Завдання і heartbeat">
|
||||
Запуски Heartbeat є ходами основної сесії — вони не створюють записів завдань. Коли завдання завершується, воно може запустити пробудження Heartbeat, щоб ви швидко побачили результат.
|
||||
|
||||
Див. [Heartbeat](/uk/gateway/heartbeat).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Задачі та сеанси">
|
||||
Задача може посилатися на `childSessionKey` (де виконується робота) і `requesterSessionKey` (хто її запустив). Сеанси — це контекст розмови; задачі — це відстеження активності поверх нього.
|
||||
<Accordion title="Завдання і сесії">
|
||||
Завдання може посилатися на `childSessionKey` (де виконується робота) і `requesterSessionKey` (хто його запустив). Сесії є контекстом розмови; завдання — це відстеження активності поверх нього.
|
||||
</Accordion>
|
||||
<Accordion title="Задачі та запуски агентів">
|
||||
`runId` задачі пов’язує її із запуском агента, який виконує роботу. Події життєвого циклу агента (початок, завершення, помилка) автоматично оновлюють статус задачі — вам не потрібно керувати життєвим циклом вручну.
|
||||
<Accordion title="Завдання і запуски агента">
|
||||
`runId` завдання пов’язує його із запуском агента, який виконує роботу. Події життєвого циклу агента (початок, завершення, помилка) автоматично оновлюють статус завдання — вам не потрібно керувати життєвим циклом вручну.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Автоматизація та задачі](/uk/automation) — усі механізми автоматизації одним поглядом
|
||||
- [CLI: Задачі](/uk/cli/tasks) — довідник команд CLI
|
||||
- [Heartbeat](/uk/gateway/heartbeat) — періодичні ходи основного сеансу
|
||||
- [Заплановані задачі](/uk/automation/cron-jobs) — планування фонової роботи
|
||||
- [Task Flow](/uk/automation/taskflow) — оркестрація потоків над задачами
|
||||
- [Автоматизація й завдання](/uk/automation) — усі механізми автоматизації стисло
|
||||
- [CLI: Завдання](/uk/cli/tasks) — довідник команд CLI
|
||||
- [Heartbeat](/uk/gateway/heartbeat) — періодичні ходи основної сесії
|
||||
- [Заплановані завдання](/uk/automation/cron-jobs) — планування фонової роботи
|
||||
- [Task Flow](/uk/automation/taskflow) — оркестрація потоків над завданнями
|
||||
|
||||
@ -1,25 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- Робота над функціями Telegram або Webhook
|
||||
summary: Стан підтримки, можливості та конфігурація бота Telegram
|
||||
summary: Стан підтримки бота Telegram, можливості та конфігурація
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T19:31:37Z"
|
||||
generated_at: "2026-04-28T20:11:05Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: dadd8d0a735b8d8ee75eb44ad0ce018f81c6774aee3bd69f0804e9e731352546
|
||||
source_hash: 663fd2eecc7f2ff02622f5fde1a6ae3c97427f7aeda26f89a230529f3284df8b
|
||||
source_path: channels/telegram.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Готово для продакшну для особистих повідомлень бота та груп через grammY. Довге опитування є режимом за замовчуванням; режим Webhook є необов’язковим.
|
||||
Готовий до production для DM бота та груп через grammY. Довге опитування є режимом за замовчуванням; режим Webhook необов’язковий.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
|
||||
Стандартна політика особистих повідомлень для Telegram — сполучення.
|
||||
Політика DM за замовчуванням для Telegram — сполучення.
|
||||
</Card>
|
||||
<Card title="Усунення несправностей каналів" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика та сценарії відновлення.
|
||||
<Card title="Усунення проблем каналів" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика та інструкції з відновлення.
|
||||
</Card>
|
||||
<Card title="Конфігурація Gateway" icon="settings" href="/uk/gateway/configuration">
|
||||
Повні шаблони та приклади конфігурації каналів.
|
||||
@ -30,13 +30,13 @@ x-i18n:
|
||||
|
||||
<Steps>
|
||||
<Step title="Створіть токен бота в BotFather">
|
||||
Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що ім’я точно `@BotFather`).
|
||||
Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що handle саме `@BotFather`).
|
||||
|
||||
Виконайте `/newbot`, дотримуйтесь підказок і збережіть токен.
|
||||
Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Налаштуйте токен і політику особистих повідомлень">
|
||||
<Step title="Налаштуйте токен і політику DM">
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -51,12 +51,12 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Резервний варіант через змінну середовища: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням).
|
||||
Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у конфігурації або змінній середовища, потім запустіть gateway.
|
||||
Резервний варіант через env: `TELEGRAM_BOT_TOKEN=...` (лише обліковий запис за замовчуванням).
|
||||
Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть gateway.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Запустіть gateway і схваліть перше особисте повідомлення">
|
||||
<Step title="Запустіть gateway і схваліть перший DM">
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
@ -64,77 +64,79 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
Коди сполучення спливають через 1 годину.
|
||||
Коди сполучення діють 1 годину.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте бота до групи">
|
||||
Додайте бота до своєї групи, потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу.
|
||||
Додайте бота до своєї групи, а потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення з конфігурації мають пріоритет над резервною змінною середовища, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням.
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення config мають пріоритет над резервним env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням.
|
||||
</Note>
|
||||
|
||||
## Налаштування на боці Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Режим приватності та видимість груп">
|
||||
Боти Telegram за замовчуванням використовують **режим приватності**, який обмежує те, які групові повідомлення вони отримують.
|
||||
<Accordion title="Режим приватності та видимість у групах">
|
||||
Боти Telegram за замовчуванням використовують **Privacy Mode**, який обмежує, які групові повідомлення вони отримують.
|
||||
|
||||
Якщо бот має бачити всі повідомлення групи, зробіть одне з такого:
|
||||
Якщо бот має бачити всі групові повідомлення, або:
|
||||
|
||||
- вимкніть режим приватності через `/setprivacy`, або
|
||||
- зробіть бота адміністратором групи.
|
||||
|
||||
Після перемикання режиму приватності видаліть і повторно додайте бота в кожну групу, щоб Telegram застосував зміну.
|
||||
Після перемикання режиму приватності видаліть і повторно додайте бота в кожній групі, щоб Telegram застосував зміну.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Дозволи групи">
|
||||
Статус адміністратора керується в налаштуваннях групи Telegram.
|
||||
Статус адміністратора контролюється в налаштуваннях групи Telegram.
|
||||
|
||||
Боти-адміністратори отримують усі повідомлення групи, що корисно для постійно активної поведінки в групі.
|
||||
Боти-адміністратори отримують усі групові повідомлення, що корисно для постійно активної поведінки в групі.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Корисні перемикачі BotFather">
|
||||
|
||||
- `/setjoingroups` для дозволу або заборони додавання до груп
|
||||
- `/setjoingroups`, щоб дозволити/заборонити додавання до груп
|
||||
- `/setprivacy` для поведінки видимості в групах
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Керування доступом і активація
|
||||
## Контроль доступу та активація
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Політика особистих повідомлень">
|
||||
`channels.telegram.dmPolicy` керує доступом до особистих повідомлень:
|
||||
<Tab title="Політика DM">
|
||||
`channels.telegram.dmPolicy` керує доступом до прямих повідомлень:
|
||||
|
||||
- `pairing` (за замовчуванням)
|
||||
- `allowlist` (потрібен принаймні один ID відправника в `allowFrom`)
|
||||
- `open` (потрібно, щоб `allowFrom` містив `"*"`)
|
||||
- `allowlist` (потребує щонайменше одного ID відправника в `allowFrom`)
|
||||
- `open` (потребує, щоб `allowFrom` містив `"*"`)
|
||||
- `disabled`
|
||||
|
||||
`dmPolicy: "open"` з `allowFrom: ["*"]` дозволяє будь-якому обліковому запису Telegram, який знайде або вгадає ім’я користувача бота, керувати ботом. Використовуйте це лише для навмисно публічних ботів із жорстко обмеженими інструментами; боти з одним власником мають використовувати `allowlist` із числовими ID користувачів.
|
||||
|
||||
`channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються та нормалізуються.
|
||||
`dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі особисті повідомлення та відхиляється валідацією конфігурації.
|
||||
`dmPolicy: "allowlist"` із порожнім `allowFrom` блокує всі DM і відхиляється валідацією конфігурації.
|
||||
Налаштування запитує лише числові ID користувачів.
|
||||
Якщо ви оновилися і ваша конфігурація містить записи allowlist виду `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (наскільки можливо; потрібен токен бота Telegram).
|
||||
Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у потоках allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
|
||||
Якщо ви оновилися і ваша конфігурація містить записи allowlist з `@username`, виконайте `openclaw doctor --fix`, щоб їх розв’язати (best-effort; потрібен токен бота Telegram).
|
||||
Якщо раніше ви покладалися на файли allowlist зі сховища сполучень, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` у сценаріях allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
|
||||
|
||||
Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була стабільно збережена в конфігурації (а не залежала від попередніх схвалень сполучення).
|
||||
Для ботів з одним власником надавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID `allowFrom`, щоб політика доступу була сталою в конфігурації (замість залежності від попередніх схвалень сполучення).
|
||||
|
||||
Поширена плутанина: схвалення сполучення для особистих повідомлень не означає «цей відправник авторизований всюди».
|
||||
Сполучення надає доступ лише до особистих повідомлень. Авторизація відправників у групах усе ще береться з явних allowlist у конфігурації.
|
||||
Якщо вам потрібно «мене авторизовано один раз, і працюють як особисті повідомлення, так і групові команди», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`.
|
||||
Поширене непорозуміння: схвалення сполучення DM не означає «цей відправник авторизований усюди».
|
||||
Сполучення надає доступ лише до DM. Авторизація відправника в групі все одно береться з явних allowlist у конфігурації.
|
||||
Якщо ви хочете «я авторизований один раз, і працюють як DM, так і групові команди», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`.
|
||||
|
||||
### Як знайти свій ID користувача Telegram
|
||||
|
||||
Безпечніше (без стороннього бота):
|
||||
|
||||
1. Напишіть своєму боту в особисті повідомлення.
|
||||
1. Напишіть своєму боту в DM.
|
||||
2. Виконайте `openclaw logs --follow`.
|
||||
3. Прочитайте `from.id`.
|
||||
|
||||
@ -149,10 +151,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Tab>
|
||||
|
||||
<Tab title="Політика груп і allowlist">
|
||||
Разом застосовуються два елементи керування:
|
||||
Два механізми застосовуються разом:
|
||||
|
||||
1. **Які групи дозволені** (`channels.telegram.groups`)
|
||||
- конфігурації `groups` немає:
|
||||
- немає конфігурації `groups`:
|
||||
- з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи
|
||||
- з `groupPolicy: "allowlist"` (за замовчуванням): групи заблоковані, доки ви не додасте записи `groups` (або `"*"`)
|
||||
- `groups` налаштовано: працює як allowlist (явні ID або `"*"`)
|
||||
@ -162,15 +164,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `allowlist` (за замовчуванням)
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` використовується для фільтрації відправників у групах. Якщо його не задано, Telegram повертається до `allowFrom`.
|
||||
`groupAllowFrom` використовується для фільтрації відправників у групах. Якщо не задано, Telegram повертається до `allowFrom`.
|
||||
Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (префікси `telegram:` / `tg:` нормалізуються).
|
||||
Не додавайте ID чатів груп або супергруп Telegram у `groupAllowFrom`. Негативні ID чатів належать до `channels.telegram.groups`.
|
||||
Нечислові записи ігноруються для авторизації відправників.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправників у групах **не** успадковує схвалення зі сховища сполучень для особистих повідомлень.
|
||||
Сполучення залишається лише для особистих повідомлень. Для груп задайте `groupAllowFrom` або `allowFrom` для окремої групи чи теми.
|
||||
Якщо `groupAllowFrom` не задано, Telegram повертається до конфігураційного `allowFrom`, а не до сховища сполучень.
|
||||
Нечислові записи ігноруються для авторизації відправника.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправника в групі **не** успадковує схвалення зі сховища сполучень DM.
|
||||
Сполучення лишається тільки для DM. Для груп задайте `groupAllowFrom` або `allowFrom` на рівні групи/теми.
|
||||
Якщо `groupAllowFrom` не задано, Telegram повертається до `allowFrom` у конфігурації, а не до сховища сполучень.
|
||||
Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`.
|
||||
Примітка щодо середовища виконання: якщо `channels.telegram` повністю відсутній, середовище виконання за замовчуванням відмовляє безпечно через `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно.
|
||||
Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням fail-closed із `groupPolicy="allowlist"`, якщо `channels.defaults.groupPolicy` не задано явно.
|
||||
|
||||
Приклад: дозволити будь-якого учасника в одній конкретній групі:
|
||||
|
||||
@ -189,7 +191,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Приклад: дозволити лише конкретних користувачів в одній конкретній групі:
|
||||
Приклад: дозволити лише конкретних користувачів усередині однієї конкретної групи:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -209,8 +211,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Warning>
|
||||
Поширена помилка: `groupAllowFrom` не є allowlist груп Telegram.
|
||||
|
||||
- Розміщуйте негативні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`.
|
||||
- Розміщуйте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота.
|
||||
- Додавайте негативні ID чатів груп або супергруп Telegram, як-от `-1001234567890`, у `channels.telegram.groups`.
|
||||
- Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, які люди всередині дозволеної групи можуть запускати бота.
|
||||
- Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом.
|
||||
|
||||
</Warning>
|
||||
@ -227,12 +229,12 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `agents.list[].groupChat.mentionPatterns`
|
||||
- `messages.groupChat.mentionPatterns`
|
||||
|
||||
Перемикачі команд рівня сесії:
|
||||
Перемикачі команд на рівні сесії:
|
||||
|
||||
- `/activation always`
|
||||
- `/activation mention`
|
||||
|
||||
Вони оновлюють лише стан сесії. Для сталості використовуйте конфігурацію.
|
||||
Вони оновлюють лише стан сесії. Для збереження використовуйте конфігурацію.
|
||||
|
||||
Приклад сталої конфігурації:
|
||||
|
||||
@ -250,29 +252,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Отримання ID групового чату:
|
||||
|
||||
- перешліть повідомлення групи до `@userinfobot` / `@getidsbot`
|
||||
- або прочитайте `chat.id` з `openclaw logs --follow`
|
||||
- або перегляньте `getUpdates` у Bot API
|
||||
- переслати групове повідомлення до `@userinfobot` / `@getidsbot`
|
||||
- або прочитати `chat.id` з `openclaw logs --follow`
|
||||
- або перевірити `getUpdates` Bot API
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Поведінка середовища виконання
|
||||
## Поведінка runtime
|
||||
|
||||
- Telegram належить процесу Gateway.
|
||||
- Маршрутизація детермінована: вхідні повідомлення Telegram отримують відповідь у Telegram (модель не вибирає канали).
|
||||
- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та заповнювачами медіа.
|
||||
- Групові сесії ізольовані за ID групи. Теми форуму додають `:topic:<threadId>`, щоб ізолювати теми.
|
||||
- Особисті повідомлення можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесій, що враховують тему, і зберігає ID теми для відповідей.
|
||||
- Довге опитування використовує runner grammY з послідовністю за чатом і темою. Загальна конкурентність sink runner використовує `agents.defaults.maxConcurrent`.
|
||||
- Довге опитування захищене всередині кожного процесу Gateway, тож лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший Gateway OpenClaw, скрипт або зовнішній poller.
|
||||
- Перезапуски сторожового механізму довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеної перевірки живості `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через зупинку опитування під час довготривалої роботи. Значення задається в мілісекундах і дозволене в діапазоні від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів.
|
||||
- Telegram Bot API не підтримує підтвердження прочитання (`sendReadReceipts` не застосовується).
|
||||
- Telegram належить процесу gateway.
|
||||
- Маршрутизація детермінована: вхідні повідомлення Telegram відповідають назад у Telegram (модель не вибирає канали).
|
||||
- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та плейсхолдерами медіа.
|
||||
- Групові сесії ізольовані за ID групи. Теми форумів додають `:topic:<threadId>`, щоб ізолювати теми.
|
||||
- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесій, що враховують thread, і зберігає ID thread для відповідей.
|
||||
- Довге опитування використовує grammY runner із послідовністю на рівні чату/thread. Загальна конкурентність runner sink використовує `agents.defaults.maxConcurrent`.
|
||||
- Довге опитування захищене всередині кожного процесу gateway, тож лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, інший gateway OpenClaw, скрипт або зовнішній poller використовує той самий токен.
|
||||
- Перезапуски watchdog довгого опитування за замовчуванням спрацьовують після 120 секунд без завершеної liveness `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо ваше розгортання все ще бачить хибні перезапуски через зупинку опитування під час тривалої роботи. Значення вказується в мілісекундах і дозволене від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів.
|
||||
- Telegram Bot API не підтримує сповіщення про прочитання (`sendReadReceipts` не застосовується).
|
||||
|
||||
## Довідник функцій
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Попередній перегляд живого потоку (редагування повідомлень)">
|
||||
<Accordion title="Попередній перегляд live stream (редагування повідомлень)">
|
||||
OpenClaw може транслювати часткові відповіді в реальному часі:
|
||||
|
||||
- прямі чати: повідомлення попереднього перегляду + `editMessageText`
|
||||
@ -282,10 +284,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`)
|
||||
- `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним іменуванням)
|
||||
- `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли потоковий попередній перегляд активний)
|
||||
- застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх до `channels.telegram.streaming.mode`
|
||||
- `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме редаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активний streaming попереднього перегляду)
|
||||
- застарілі значення `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб мігрувати їх до `channels.telegram.streaming.mode`
|
||||
|
||||
Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Працюємо...», які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлень планування або підсумків патчів. Telegram залишає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw від `v2026.4.22` і пізніше. Щоб залишити редагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте:
|
||||
Оновлення попереднього перегляду прогресу інструментів — це короткі рядки "Working...", які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення планування або підсумки patch. Telegram тримає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw від `v2026.4.22` і пізніше. Щоб зберегти редагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -302,39 +304,39 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте `streaming.mode: "off"` лише тоді, коли хочете доставляти тільки фінальну відповідь: редагування попереднього перегляду Telegram вимикаються, а загальні повідомлення інструментів/прогресу пригнічуються замість надсилання як окремі повідомлення «Працюємо...». Запити схвалення, медіавміст і помилки все ще маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете лише зберегти редагування попереднього перегляду відповіді, приховавши рядки статусу прогресу інструментів.
|
||||
Використовуйте `streaming.mode: "off"` лише тоді, коли хочете доставку лише фінальної відповіді: редагування попереднього перегляду Telegram вимкнені, а загальний шум інструментів/прогресу пригнічується замість надсилання як окремі повідомлення "Working...". Запити схвалення, медіа payloads і помилки все одно маршрутизуються через звичайну фінальну доставку. Використовуйте `streaming.preview.toolProgress: false`, коли хочете зберегти лише редагування попереднього перегляду відповіді, приховавши рядки статусу прогресу інструментів.
|
||||
|
||||
Для відповідей лише з текстом:
|
||||
|
||||
- короткі попередні перегляди в особистих повідомленнях/групах/темах: OpenClaw зберігає те саме повідомлення попереднього перегляду та виконує фінальне редагування на місці
|
||||
- попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, щоб видима мітка часу Telegram відображала час завершення, а не час створення попереднього перегляду
|
||||
- короткі попередні перегляди DM/груп/тем: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці
|
||||
- попередні перегляди, старші приблизно за одну хвилину: OpenClaw надсилає завершену відповідь як нове фінальне повідомлення, а потім очищає попередній перегляд, тож видима мітка часу Telegram відображає час завершення, а не час створення попереднього перегляду
|
||||
|
||||
Для складних відповідей (наприклад, медіавмісту) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду.
|
||||
Для складних відповідей (наприклад, media payloads) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду.
|
||||
|
||||
Потоковий попередній перегляд відокремлений від блокового потокового передавання. Коли блокове потокове передавання явно ввімкнене для Telegram, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійної потокової передачі.
|
||||
Попередній streaming окремий від блокового streaming. Коли блоковий streaming явно ввімкнено для Telegram, OpenClaw пропускає попередній stream, щоб уникнути подвійного streaming.
|
||||
|
||||
Якщо нативний транспорт чернеток недоступний або відхилений, OpenClaw автоматично повертається до `sendMessage` + `editMessageText`.
|
||||
|
||||
Потік міркувань лише для Telegram:
|
||||
Stream reasoning лише для Telegram:
|
||||
|
||||
- `/reasoning stream` надсилає міркування до живого попереднього перегляду під час генерування
|
||||
- фінальна відповідь надсилається без тексту міркувань
|
||||
- `/reasoning stream` надсилає reasoning у живий попередній перегляд під час генерування
|
||||
- фінальна відповідь надсилається без тексту reasoning
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Форматування та резервний HTML">
|
||||
<Accordion title="Formatting and HTML fallback">
|
||||
Вихідний текст використовує Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- Текст у стилі Markdown відтворюється як безпечний для Telegram HTML.
|
||||
- Markdown-подібний текст рендериться у безпечний для Telegram HTML.
|
||||
- Сирий HTML від моделі екранується, щоб зменшити кількість помилок парсингу Telegram.
|
||||
- Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює надсилання як звичайний текст.
|
||||
- Якщо Telegram відхиляє розпарсений HTML, OpenClaw повторює надсилання як звичайний текст.
|
||||
|
||||
Попередні перегляди посилань увімкнені за замовчуванням і можуть бути вимкнені через `channels.telegram.linkPreview: false`.
|
||||
Попередні перегляди посилань увімкнено за замовчуванням, і їх можна вимкнути за допомогою `channels.telegram.linkPreview: false`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нативні команди та власні команди">
|
||||
Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`.
|
||||
<Accordion title="Native commands and custom commands">
|
||||
Реєстрація меню команд Telegram обробляється під час запуску через `setMyCommands`.
|
||||
|
||||
Типові значення нативних команд:
|
||||
|
||||
@ -360,44 +362,44 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- імена нормалізуються (видаляється початковий `/`, переводяться в нижній регістр)
|
||||
- допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32`
|
||||
- власні команди не можуть перевизначати нативні команди
|
||||
- конфлікти/дублікати пропускаються і записуються в журнал
|
||||
- конфлікти/дублікати пропускаються й логуються
|
||||
|
||||
Примітки:
|
||||
|
||||
- власні команди є лише записами меню; вони не реалізують поведінку автоматично
|
||||
- команди plugin/skill можуть працювати під час введення, навіть якщо їх не показано в меню Telegram
|
||||
- команди plugin/skill усе ще можуть працювати, якщо їх ввести, навіть якщо вони не показані в меню Telegram
|
||||
|
||||
Якщо нативні команди вимкнені, вбудовані команди видаляються. Власні команди або команди Plugin можуть усе ще реєструватися, якщо це налаштовано.
|
||||
Якщо нативні команди вимкнено, вбудовані команди видаляються. Власні команди/команди Plugin усе ще можуть реєструватися, якщо налаштовані.
|
||||
|
||||
Поширені помилки налаштування:
|
||||
Типові помилки налаштування:
|
||||
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після обрізання; зменште кількість команд Plugin/skill/власних команд або вимкніть `channels.telegram.commands.native`.
|
||||
- Помилка `deleteWebhook`, `deleteMyCommands` або `setMyCommands` з `404: Not Found`, коли прямі команди curl до Bot API працюють, може означати, що `channels.telegram.apiRoot` було задано як повний endpoint `/bot<TOKEN>`. `apiRoot` має бути лише коренем Bot API, а `openclaw doctor --fix` видаляє випадковий кінцевий `/bot<TOKEN>`.
|
||||
- `getMe returned 401` означає, що Telegram відхилив налаштований токен бота. Оновіть `botToken`, `tokenFile` або `TELEGRAM_BOT_TOKEN` поточним токеном BotFather; OpenClaw зупиняється до polling, тому це не повідомляється як помилка очищення Webhook.
|
||||
- `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідні DNS/HTTPS-з’єднання до `api.telegram.org` заблоковані.
|
||||
- `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблоковано.
|
||||
|
||||
### Команди сполучення пристрою (`device-pair` plugin)
|
||||
### Команди сполучення пристрою (Plugin `device-pair`)
|
||||
|
||||
Коли встановлено `device-pair` plugin:
|
||||
Коли Plugin `device-pair` встановлено:
|
||||
|
||||
1. `/pair` генерує код налаштування
|
||||
2. вставте код у застосунок iOS
|
||||
3. `/pair pending` показує список очікуваних запитів (включно з роллю/областями дії)
|
||||
3. `/pair pending` перелічує запити, що очікують (зокрема role/scopes)
|
||||
4. схваліть запит:
|
||||
- `/pair approve <requestId>` для явного схвалення
|
||||
- `/pair approve`, коли є лише один очікуваний запит
|
||||
- `/pair approve`, коли є лише один запит, що очікує
|
||||
- `/pair approve latest` для найновішого
|
||||
|
||||
Код налаштування містить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен основного вузла на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки областей дії bootstrap мають префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; неоператорським ролям усе ще потрібні області дії під власним префіксом ролі.
|
||||
Код налаштування містить короткочасний bootstrap-токен. Вбудована передача bootstrap зберігає токен primary node на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap scope мають префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; ролям, що не є операторськими, все ще потрібні scopes під власним префіксом ролі.
|
||||
|
||||
Якщо пристрій повторює спробу зі зміненими даними автентифікації (наприклад, роль/області дії/публічний ключ), попередній очікуваний запит замінюється, а новий запит використовує інший `requestId`. Повторно виконайте `/pair pending` перед схваленням.
|
||||
Якщо пристрій повторює спробу зі зміненими деталями автентифікації (наприклад, role/scopes/public key), попередній запит, що очікує, замінюється, а новий запит використовує інший `requestId`. Перед схваленням повторно запустіть `/pair pending`.
|
||||
|
||||
Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Вбудовані кнопки">
|
||||
Налаштуйте область дії вбудованої клавіатури:
|
||||
<Accordion title="Inline buttons">
|
||||
Налаштуйте scope inline-клавіатури:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -429,7 +431,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Області дії:
|
||||
Scopes:
|
||||
|
||||
- `off`
|
||||
- `dm`
|
||||
@ -437,7 +439,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `all`
|
||||
- `allowlist` (за замовчуванням)
|
||||
|
||||
Застаріле `capabilities: ["inlineButtons"]` відображається на `inlineButtons: "all"`.
|
||||
Застаріле `capabilities: ["inlineButtons"]` мапиться на `inlineButtons: "all"`.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -462,14 +464,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Дії повідомлень Telegram для агентів і автоматизації">
|
||||
Дії інструмента Telegram включають:
|
||||
<Accordion title="Telegram message actions for agents and automation">
|
||||
Дії інструментів Telegram включають:
|
||||
|
||||
- `sendMessage` (`to`, `content`, необов’язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `sendMessage` (`to`, `content`, необов’язково `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
- `react` (`chatId`, `messageId`, `emoji`)
|
||||
- `deleteMessage` (`chatId`, `messageId`)
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, необов’язкові `iconColor`, `iconCustomEmojiId`)
|
||||
- `createForumTopic` (`chatId`, `name`, необов’язково `iconColor`, `iconCustomEmojiId`)
|
||||
|
||||
Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
@ -480,17 +482,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.actions.reactions`
|
||||
- `channels.telegram.actions.sticker` (за замовчуванням: вимкнено)
|
||||
|
||||
Примітка: `edit` і `topic-create` наразі ввімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`.
|
||||
Надсилання під час виконання використовують активний знімок конфігурації/секретів (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання SecretRef для кожного надсилання.
|
||||
Примітка: `edit` і `topic-create` зараз увімкнено за замовчуванням, і вони не мають окремих перемикачів `channels.telegram.actions.*`.
|
||||
Надсилання під час виконання використовують активний знімок config/secrets (запуск/перезавантаження), тому шляхи дій не виконують ad-hoc повторне розв’язання SecretRef для кожного надсилання.
|
||||
|
||||
Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Теги гілкування відповідей">
|
||||
Telegram підтримує явні теги гілкування відповідей у згенерованому виводі:
|
||||
<Accordion title="Reply threading tags">
|
||||
Telegram підтримує явні теги reply threading у згенерованому виводі:
|
||||
|
||||
- `[[reply_to_current]]` відповідає на повідомлення, що запустило дію
|
||||
- `[[reply_to_current]]` відповідає на повідомлення, що спричинило запуск
|
||||
- `[[reply_to:<id>]]` відповідає на конкретний ID повідомлення Telegram
|
||||
|
||||
`channels.telegram.replyToMode` керує обробкою:
|
||||
@ -499,29 +501,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
Коли гілкування відповідей увімкнене і вихідний текст або підпис Telegram доступний, OpenClaw автоматично додає нативний уривок цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються з початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату.
|
||||
Коли reply threading увімкнено й доступний початковий текст або підпис Telegram, OpenClaw автоматично включає нативний фрагмент цитати Telegram. Telegram обмежує нативний текст цитати 1024 кодовими одиницями UTF-16, тому довші повідомлення цитуються з початку й повертаються до звичайної відповіді, якщо Telegram відхиляє цитату.
|
||||
|
||||
Примітка: `off` вимикає неявні ланцюжки відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються.
|
||||
Примітка: `off` вимикає неявний reply threading. Явні теги `[[reply_to_*]]` усе ще враховуються.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Теми форуму та поведінка гілок">
|
||||
<Accordion title="Forum topics and thread behavior">
|
||||
Форумні супергрупи:
|
||||
|
||||
- ключі сесій тем додають `:topic:<threadId>`
|
||||
- відповіді та індикатор набору спрямовуються в гілку теми
|
||||
- відповіді й індикація набору тексту спрямовуються в thread теми
|
||||
- шлях конфігурації теми:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Спеціальний випадок загальної теми (`threadId=1`):
|
||||
|
||||
- під час надсилання повідомлень `message_thread_id` не додається (Telegram відхиляє `sendMessage(...thread_id=1)`)
|
||||
- дії набору тексту все одно містять `message_thread_id`
|
||||
- надсилання повідомлень не включають `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`)
|
||||
- дії набору тексту все одно включають `message_thread_id`
|
||||
|
||||
Успадкування тем: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` належить лише темі й не успадковується з типових налаштувань групи.
|
||||
Наслідування тем: записи тем наслідують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` застосовується лише до теми й не наслідується з типових значень групи.
|
||||
|
||||
**Маршрутизація агента за темами**: Кожну тему можна спрямувати до іншого агента, задавши `agentId` у конфігурації теми. Це дає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад:
|
||||
**Маршрутизація агентів за темами**: кожна тема може спрямовуватися до іншого агента через встановлення `agentId` у конфігурації теми. Це дає кожній темі власний ізольований workspace, пам’ять і сесію. Приклад:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -541,26 +543,26 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Після цього кожна тема має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
Кожна тема потім має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
|
||||
**Постійна прив’язка тем ACP**: Форумні теми можуть закріплювати сесії ACP harness через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором із темою, наприклад `-1001234567890:topic:42`). Наразі обмежено форумними темами в групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents).
|
||||
**Постійне прив’язування тем ACP**: форумні теми можуть закріплювати сесії ACP harness через типізовані ACP bindings верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та id з уточненням теми, як-от `-1001234567890:topic:42`). Наразі scoped до форумних тем у групах/супергрупах. Див. [Агенти ACP](/uk/tools/acp-agents).
|
||||
|
||||
**Створення ACP, прив’язане до гілки, із чату**: `/acp spawn <agent> --thread here|auto` прив’язує поточну тему до нової сесії ACP; наступні повідомлення спрямовуються туди напряму. OpenClaw закріплює підтвердження створення в темі. Потрібно `channels.telegram.threadBindings.spawnAcpSessions=true`.
|
||||
**Створення thread-bound ACP із чату**: `/acp spawn <agent> --thread here|auto` прив’язує поточну тему до нової ACP-сесії; подальші повідомлення спрямовуються туди напряму. OpenClaw закріплює підтвердження створення в темі. Потрібно `channels.telegram.threadBindings.spawnAcpSessions=true`.
|
||||
|
||||
Контекст шаблону надає `MessageThreadId` і `IsForum`. Чати DM з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сесій з урахуванням гілок.
|
||||
Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають DM-маршрутизацію, але використовують ключі сесій, що враховують thread.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Аудіо, відео та стікери">
|
||||
<Accordion title="Audio, video, and stickers">
|
||||
### Аудіоповідомлення
|
||||
|
||||
Telegram розрізняє голосові нотатки й аудіофайли.
|
||||
Telegram розрізняє голосові нотатки та аудіофайли.
|
||||
|
||||
- типово: поведінка аудіофайлу
|
||||
- за замовчуванням: поведінка аудіофайла
|
||||
- тег `[[audio_as_voice]]` у відповіді агента примусово надсилає голосову нотатку
|
||||
- транскрипти вхідних голосових нотаток оформлюються в контексті агента як машинно згенерований,
|
||||
ненадійний текст; виявлення згадок усе одно використовує сирий
|
||||
транскрипт, тому голосові повідомлення з обмеженням за згадкою продовжують працювати.
|
||||
- транскрипти вхідних голосових нотаток оформлюються як машинно згенерований,
|
||||
недовірений текст у контексті агента; виявлення згадок усе ще використовує сирий
|
||||
транскрипт, тому voice-повідомлення з gate за згадкою продовжують працювати.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -576,7 +578,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
### Відеоповідомлення
|
||||
|
||||
Telegram розрізняє відеофайли й відеонотатки.
|
||||
Telegram розрізняє відеофайли та відеонотатки.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -596,9 +598,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Обробка вхідних стікерів:
|
||||
|
||||
- статичні WEBP: завантажуються й обробляються (заповнювач `<media:sticker>`)
|
||||
- анімовані TGS: пропускаються
|
||||
- відео WEBM: пропускаються
|
||||
- статичний WEBP: завантажується й обробляється (placeholder `<media:sticker>`)
|
||||
- анімований TGS: пропускається
|
||||
- відео WEBM: пропускається
|
||||
|
||||
Поля контексту стікера:
|
||||
|
||||
@ -612,9 +614,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити повторні виклики vision.
|
||||
Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити кількість повторних vision-викликів.
|
||||
|
||||
Увімкнути дії зі стікерами:
|
||||
Увімкніть дії зі стікерами:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -652,8 +654,8 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Сповіщення про реакції">
|
||||
Реакції Telegram надходять як оновлення `message_reaction` (окремо від вмісту повідомлень).
|
||||
<Accordion title="Reaction notifications">
|
||||
Реакції Telegram надходять як оновлення `message_reaction` (окремо від payload повідомлень).
|
||||
|
||||
Коли ввімкнено, OpenClaw ставить у чергу системні події на кшталт:
|
||||
|
||||
@ -661,35 +663,35 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Конфігурація:
|
||||
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all` (типово: `own`)
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (типово: `minimal`)
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all` (за замовчуванням: `own`)
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (за замовчуванням: `minimal`)
|
||||
|
||||
Примітки:
|
||||
|
||||
- `own` означає лише реакції користувачів на повідомлення, надіслані ботом (наскільки можливо, через кеш надісланих повідомлень).
|
||||
- Події реакцій усе одно дотримуються засобів контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Telegram не надає ідентифікатори гілок в оновленнях реакцій.
|
||||
- нефорумні групи спрямовуються до сесії групового чату
|
||||
- форумні групи спрямовуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми
|
||||
- `own` означає лише реакції користувачів на повідомлення, надіслані ботом (за найкращих зусиль через кеш надісланих повідомлень).
|
||||
- Події реакцій усе ще поважають засоби контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Telegram не надає ідентифікатори тем у оновленнях реакцій.
|
||||
- групи без форуму маршрутизуються до сеансу групового чату
|
||||
- групи-форуми маршрутизуються до сеансу загальної теми групи (`:topic:1`), а не до точної початкової теми
|
||||
|
||||
`allowed_updates` для polling/webhook автоматично містить `message_reaction`.
|
||||
`allowed_updates` для polling/webhook автоматично включає `message_reaction`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ack-реакції">
|
||||
`ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення.
|
||||
<Accordion title="Підтверджувальні реакції">
|
||||
`ackReaction` надсилає emoji підтвердження, поки OpenClaw обробляє вхідне повідомлення.
|
||||
|
||||
Порядок визначення:
|
||||
|
||||
- `channels.telegram.accounts.<accountId>.ackReaction`
|
||||
- `channels.telegram.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- запасний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀")
|
||||
- резервний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀")
|
||||
|
||||
Примітки:
|
||||
|
||||
- Telegram очікує unicode emoji (наприклад "👀").
|
||||
- Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису.
|
||||
- Telegram очікує unicode emoji (наприклад, "👀").
|
||||
- Використайте `""`, щоб вимкнути реакцію для каналу або облікового запису.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -699,7 +701,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Записи, ініційовані Telegram, включають:
|
||||
|
||||
- події міграції групи (`migrate_to_chat_id`) для оновлення `channels.telegram.groups`
|
||||
- `/config set` і `/config unset` (потребує ввімкнення команд)
|
||||
- `/config set` і `/config unset` (потрібне ввімкнення команд)
|
||||
|
||||
Вимкнення:
|
||||
|
||||
@ -715,29 +717,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Довге опитування проти webhook">
|
||||
За замовчуванням використовується довге опитування. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов'язкові `webhookPath`, `webhookHost`, `webhookPort` (за замовчуванням `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
<Accordion title="Long polling проти webhook">
|
||||
За замовчуванням використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язкові `webhookPath`, `webhookHost`, `webhookPort` (за замовчуванням `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
|
||||
Локальний слухач прив'язується до `127.0.0.1:8787`. Для публічного входу або розмістіть reverse proxy перед локальним портом, або свідомо задайте `webhookHost: "0.0.0.0"`.
|
||||
Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного входу або розмістіть reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`.
|
||||
|
||||
Режим webhook перевіряє захисти запиту, секретний токен Telegram і JSON-тіло, перш ніж повернути `200` до Telegram.
|
||||
Потім OpenClaw обробляє оновлення асинхронно через ті самі смуги бота для кожного чату/теми, що й довге опитування, тому повільні ходи агента не затримують ACK доставки Telegram.
|
||||
Режим Webhook перевіряє захист запитів, секретний токен Telegram і тіло JSON перед поверненням `200` до Telegram.
|
||||
Потім OpenClaw обробляє оновлення асинхронно через ті самі смуги бота для кожного чату/кожної теми, що й у long polling, тож повільні ходи агента не утримують delivery ACK Telegram.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Обмеження, повторні спроби та цілі CLI">
|
||||
- `channels.telegram.textChunkLimit` за замовчуванням дорівнює 4000.
|
||||
- `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною.
|
||||
- `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною.
|
||||
- `channels.telegram.mediaMaxMb` (за замовчуванням 100) обмежує розмір вхідних і вихідних медіа Telegram.
|
||||
- `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується значення grammY за замовчуванням).
|
||||
- `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте між `30000` і `600000` лише для хибнопозитивних перезапусків через зависання опитування.
|
||||
- `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується стандартне значення grammY).
|
||||
- `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте між `30000` і `600000` лише для хибнопозитивних перезапусків через зависання polling.
|
||||
- історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає.
|
||||
- додатковий контекст відповіді/цитати/пересилання наразі передається так, як отримано.
|
||||
- allowlist Telegram насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту.
|
||||
- Елементи керування історією DM:
|
||||
- додатковий контекст відповіді/цитати/пересилання наразі передається як отриманий.
|
||||
- allowlist Telegram передусім обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту.
|
||||
- Керування історією DM:
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- конфігурація `channels.telegram.retry` застосовується до допоміжних засобів надсилання Telegram (CLI/інструменти/дії) для відновлюваних вихідних помилок API.
|
||||
- конфігурація `channels.telegram.retry` застосовується до допоміжних функцій надсилання Telegram (CLI/інструменти/дії) для відновлюваних вихідних помилок API.
|
||||
|
||||
Ціль надсилання CLI може бути числовим ID чату або іменем користувача:
|
||||
|
||||
@ -756,55 +758,55 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
--poll-duration-seconds 300 --poll-public
|
||||
```
|
||||
|
||||
Прапорці опитування лише для Telegram:
|
||||
Прапорці опитувань лише для Telegram:
|
||||
|
||||
- `--poll-duration-seconds` (5-600)
|
||||
- `--poll-anonymous`
|
||||
- `--poll-public`
|
||||
- `--thread-id` для тем форуму (або використовуйте ціль `:topic:`)
|
||||
- `--thread-id` для тем форуму (або використайте ціль `:topic:`)
|
||||
|
||||
Надсилання Telegram також підтримує:
|
||||
|
||||
- `--presentation` з блоками `buttons` для inline-клавіатур, коли `channels.telegram.capabilities.inlineButtons` це дозволяє
|
||||
- `--pin` або `--delivery '{"pin":true}'`, щоб запросити закріплену доставку, коли бот може закріплювати в цьому чаті
|
||||
- `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень animated-media
|
||||
- `--pin` або `--delivery '{"pin":true}'`, щоб запитати закріплену доставку, коли бот може закріплювати в цьому чаті
|
||||
- `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених завантажень фото або animated-media
|
||||
|
||||
Обмеження дій:
|
||||
|
||||
- `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, зокрема опитування
|
||||
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайні надсилання ввімкненими
|
||||
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання ввімкненим
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Затвердження exec у Telegram">
|
||||
Telegram підтримує затвердження exec у DM затверджувачів і може додатково публікувати запити у вихідному чаті або темі. Затверджувачі мають бути числовими ID користувачів Telegram.
|
||||
<Accordion title="Підтвердження exec у Telegram">
|
||||
Telegram підтримує підтвердження exec у DM затверджувачів і може додатково публікувати запити в початковому чаті або темі. Затверджувачі мають бути числовими ID користувачів Telegram.
|
||||
|
||||
Шлях конфігурації:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли можна визначити принаймні одного затверджувача)
|
||||
- `channels.telegram.execApprovals.approvers` (відступає до числових ID власників з `allowFrom` / `defaultTo`)
|
||||
- `channels.telegram.execApprovals.approvers` (резервно використовує числові ID власників із `allowFrom` / `defaultTo`)
|
||||
- `channels.telegram.execApprovals.target`: `dm` (за замовчуванням) | `channel` | `both`
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему для запиту затвердження та подальшого повідомлення. Затвердження exec за замовчуванням спливають через 30 хвилин.
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему для запиту підтвердження та наступного повідомлення. Підтвердження exec за замовчуванням спливають через 30 хвилин.
|
||||
|
||||
Inline-кнопки затвердження також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID затверджень із префіксом `plugin:` вирішуються через затвердження plugin; інші спершу вирішуються через затвердження exec.
|
||||
Кнопки inline-підтвердження також потребують, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID підтверджень із префіксом `plugin:` визначаються через підтвердження plugin; інші спочатку визначаються через підтвердження exec.
|
||||
|
||||
Див. [Затвердження exec](/uk/tools/exec-approvals).
|
||||
Див. [Підтвердження exec](/uk/tools/exec-approvals).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Елементи керування відповідями про помилки
|
||||
## Керування відповідями про помилки
|
||||
|
||||
Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або придушити її. Цю поведінку контролюють два ключі конфігурації:
|
||||
Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або придушити його. Цю поведінку контролюють два ключі конфігурації:
|
||||
|
||||
| Ключ | Значення | За замовчуванням | Опис |
|
||||
| ----------------------------------- | ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю придушує відповіді про помилки. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями про помилки в той самий чат. Запобігає спаму помилками під час збоїв. |
|
||||
|
||||
Підтримуються перевизначення для облікового запису, групи та теми (те саме успадкування, що й для інших ключів конфігурації Telegram).
|
||||
Підтримуються перевизначення для облікового запису, групи та теми (таке саме успадкування, як і для інших ключів конфігурації Telegram).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -829,31 +831,31 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
|
||||
- Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість.
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- потім видаліть і знову додайте бота до групи
|
||||
- потім видаліть і повторно додайте бота до групи
|
||||
- `openclaw channels status` попереджає, коли конфігурація очікує групові повідомлення без згадки.
|
||||
- `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` не можна перевірити на членство.
|
||||
- швидкий тест сесії: `/activation always`.
|
||||
- швидкий тест сеансу: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Бот взагалі не бачить групові повідомлення">
|
||||
<Accordion title="Бот узагалі не бачить групові повідомлення">
|
||||
|
||||
- коли існує `channels.telegram.groups`, група має бути в списку (або містити `"*"`)
|
||||
- коли існує `channels.telegram.groups`, група має бути в списку (або включати `"*"`)
|
||||
- перевірте членство бота в групі
|
||||
- перегляньте журнали: `openclaw logs --follow` для причин пропуску
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Команди працюють частково або не працюють взагалі">
|
||||
<Accordion title="Команди працюють частково або не працюють узагалі">
|
||||
|
||||
- авторизуйте ідентичність відправника (pairing та/або числовий `allowFrom`)
|
||||
- авторизація команд усе одно застосовується, навіть коли політика групи має значення `open`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що native menu має забагато записів; зменште кількість plugin/skill/custom команд або вимкніть native menu
|
||||
- `setMyCommands failed` з помилками network/fetch зазвичай вказує на проблеми DNS/HTTPS-доступності до `api.telegram.org`
|
||||
- авторизуйте свою ідентичність відправника (сполучення та/або числовий `allowFrom`)
|
||||
- авторизація команд усе ще застосовується, навіть коли політика групи — `open`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато пунктів; зменште кількість команд plugin/skill/користувацьких команд або вимкніть нативні меню
|
||||
- `setMyCommands failed` із помилками network/fetch зазвичай вказує на проблеми доступності DNS/HTTPS до `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Під час запуску повідомляється про неавторизований токен">
|
||||
<Accordion title="Під час запуску повідомляється про неавторизований token">
|
||||
|
||||
- `getMe returned 401` — це збій автентифікації Telegram для налаштованого токена бота.
|
||||
- Повторно скопіюйте або згенеруйте токен бота в BotFather, потім оновіть `channels.telegram.botToken`, `channels.telegram.tokenFile`, `channels.telegram.accounts.<id>.botToken` або `TELEGRAM_BOT_TOKEN` для облікового запису за замовчуванням.
|
||||
@ -861,13 +863,13 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нестабільність опитування або мережі">
|
||||
<Accordion title="Нестабільність polling або мережі">
|
||||
|
||||
- Node 22+ + власний fetch/proxy може спричиняти негайну поведінку abort, якщо типи AbortSignal не збігаються.
|
||||
- Деякі хости спершу вирішують `api.telegram.org` в IPv6; несправний вихід IPv6 може спричиняти періодичні збої Telegram API.
|
||||
- Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці операції як відновлювані мережеві помилки.
|
||||
- Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає опитування та перебудовує транспорт Telegram після 120 секунд без завершеної long-poll liveness за замовчуванням.
|
||||
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе одно повідомляє про хибні перезапуски через зависання опитування. Постійні зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або TLS-виходу між хостом і `api.telegram.org`.
|
||||
- Node 22+ + користувацький fetch/proxy може спричинити негайну поведінку abort, якщо типи AbortSignal не збігаються.
|
||||
- Деякі хости спершу резолвлять `api.telegram.org` в IPv6; зламаний вихід IPv6 може спричиняти переривчасті збої Telegram API.
|
||||
- Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює ці помилки як відновлювані мережеві помилки.
|
||||
- Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll за замовчуванням.
|
||||
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` справні, але ваш хост усе одно повідомляє про хибні перезапуски через зависання polling. Постійні зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або виходу TLS між хостом і `api.telegram.org`.
|
||||
- На VPS-хостах із нестабільним прямим виходом/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`:
|
||||
|
||||
```yaml
|
||||
@ -888,9 +890,9 @@ channels:
|
||||
|
||||
- Відповіді benchmark-діапазону RFC 2544 (`198.18.0.0/15`) уже дозволені
|
||||
для завантажень медіа Telegram за замовчуванням. Якщо довірений fake-IP або
|
||||
прозорий proxy переписує `api.telegram.org` на якусь іншу
|
||||
приватну/внутрішню/спеціального призначення адресу під час завантажень медіа, ви можете явно
|
||||
ввімкнути обхід лише для Telegram:
|
||||
прозорий proxy переписує `api.telegram.org` на іншу
|
||||
приватну/внутрішню/спеціального призначення адресу під час завантажень медіа, ви можете увімкнути
|
||||
обхід лише для Telegram:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -899,18 +901,18 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- Таке саме явне ввімкнення доступне для кожного облікового запису за адресою
|
||||
- Такий самий opt-in доступний для кожного облікового запису за адресою
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Якщо ваш proxy вирішує хости медіа Telegram у `198.18.x.x`, спершу залиште
|
||||
небезпечний прапорець вимкненим. Медіа Telegram уже за замовчуванням дозволяє
|
||||
benchmark-діапазон RFC 2544.
|
||||
- Якщо ваш proxy резолвить хости медіа Telegram у `198.18.x.x`, спочатку залиште
|
||||
небезпечний прапорець вимкненим. Медіа Telegram уже дозволяє benchmark-діапазон
|
||||
RFC 2544 за замовчуванням.
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист Telegram
|
||||
media SSRF. Використовуйте це лише для довірених proxy-середовищ під контролем оператора,
|
||||
таких як Clash, Mihomo або Surge fake-IP routing, коли вони
|
||||
синтезують приватні або спеціального призначення відповіді поза benchmark-
|
||||
діапазоном RFC 2544. Залишайте вимкненим для звичайного публічного доступу Telegram через інтернет.
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист медіа Telegram
|
||||
від SSRF. Використовуйте це лише для довірених, контрольованих оператором proxy
|
||||
середовищ, як-от маршрутизація fake-IP Clash, Mihomo або Surge, коли вони
|
||||
синтезують приватні або спеціального призначення відповіді поза benchmark-діапазоном
|
||||
RFC 2544. Залишайте вимкненим для звичайного публічного інтернет-доступу до Telegram.
|
||||
</Warning>
|
||||
|
||||
- Перевизначення середовища (тимчасові):
|
||||
@ -927,23 +929,23 @@ dig +short api.telegram.org AAAA
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Додаткова довідка: [Усунення несправностей каналів](/uk/channels/troubleshooting).
|
||||
Додаткова допомога: [Усунення проблем із каналами](/uk/channels/troubleshooting).
|
||||
|
||||
## Довідник конфігурації
|
||||
|
||||
Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram).
|
||||
|
||||
<Accordion title="Високосигнальні поля Telegram">
|
||||
<Accordion title="Ключові поля Telegram">
|
||||
|
||||
- запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються)
|
||||
- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневий `bindings[]` (`type: "acp"`)
|
||||
- запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символьні посилання відхиляються)
|
||||
- контроль доступу: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, `bindings[]` верхнього рівня (`type: "acp"`)
|
||||
- підтвердження виконання: `execApprovals`, `accounts.*.execApprovals`
|
||||
- команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- потоки/відповіді: `replyToMode`
|
||||
- потокова передача: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- гілки/відповіді: `replyToMode`
|
||||
- потокове передавання: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- користувацький корінь API: `apiRoot` (лише корінь Bot API; не включайте `/bot<TOKEN>`)
|
||||
- користувацький корінь API: `apiRoot` (лише корінь Bot API; не додавайте `/bot<TOKEN>`)
|
||||
- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- реакції: `reactionNotifications`, `reactionLevel`
|
||||
@ -953,7 +955,7 @@ dig +short api.telegram.org AAAA
|
||||
</Accordion>
|
||||
|
||||
<Note>
|
||||
Пріоритетність кількох облікових записів: коли налаштовано два або більше ідентифікаторів облікових записів, установіть `channels.telegram.defaultAccount` (або додайте `channels.telegram.accounts.default`), щоб зробити маршрутизацію за замовчуванням явною. Інакше OpenClaw повертається до першого нормалізованого ідентифікатора облікового запису, а `openclaw doctor` попереджає. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`.
|
||||
Пріоритет кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або додайте `channels.telegram.accounts.default`), щоб явно визначити маршрутизацію за замовчуванням. Інакше OpenClaw повертається до першого нормалізованого ID облікового запису, а `openclaw doctor` попереджає про це. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`.
|
||||
</Note>
|
||||
|
||||
## Пов’язане
|
||||
@ -969,12 +971,12 @@ dig +short api.telegram.org AAAA
|
||||
Маршрутизуйте вхідні повідомлення до агентів.
|
||||
</Card>
|
||||
<Card title="Безпека" icon="shield" href="/uk/gateway/security">
|
||||
Модель загроз і зміцнення захисту.
|
||||
Модель загроз і посилення захисту.
|
||||
</Card>
|
||||
<Card title="Маршрутизація кількох агентів" icon="sitemap" href="/uk/concepts/multi-agent">
|
||||
Зіставляйте групи й теми з агентами.
|
||||
</Card>
|
||||
<Card title="Усунення несправностей" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
<Card title="Усунення проблем" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
399
docs/uk/ci.md
399
docs/uk/ci.md
File diff suppressed because one or more lines are too long
@ -1,39 +1,39 @@
|
||||
---
|
||||
read_when:
|
||||
- Додавання або змінення `openclaw infer` команд
|
||||
- Проєктування стабільної автоматизації можливостей без інтерфейсу
|
||||
summary: CLI, орієнтований насамперед на інференс, для робочих процесів із моделями, зображеннями, аудіо, TTS, відео, вебом та ембедингами на базі провайдерів
|
||||
- Додавання або змінення команд `openclaw infer`
|
||||
- Проєктування стабільної безінтерфейсної автоматизації можливостей
|
||||
summary: CLI з підходом infer-first для робочих процесів із моделями, зображеннями, аудіо, TTS, відео, вебом та ембедингами, що підтримуються провайдерами
|
||||
title: CLI для інференсу
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T17:56:08Z"
|
||||
generated_at: "2026-04-28T20:11:19Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: b284a884605ee7c0095652bf1b947dbc2ce78ef70532a161d97553379f348f6b
|
||||
source_hash: 8a154cf11a09f6c60117740f42937da3a0e6942931dde6eee6d902fb6e0ba461
|
||||
source_path: cli/infer.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
`openclaw infer` — це канонічна headless-поверхня для робочих процесів інференсу на базі провайдерів.
|
||||
`openclaw infer` є канонічною безголовою поверхнею для робочих процесів інференсу на основі провайдерів.
|
||||
|
||||
Вона навмисно надає сімейства можливостей, а не сирі назви RPC Gateway і не сирі ідентифікатори інструментів агента.
|
||||
Вона навмисно відкриває сімейства можливостей, а не сирі назви Gateway RPC і не сирі ідентифікатори інструментів агента.
|
||||
|
||||
## Перетворіть infer на навичку
|
||||
## Перетворіть infer на skill
|
||||
|
||||
Скопіюйте та вставте це в агента:
|
||||
Скопіюйте й вставте це в агент:
|
||||
|
||||
```text
|
||||
Read https://docs.openclaw.ai/cli/infer, then create a skill that routes my common workflows to `openclaw infer`.
|
||||
Focus on model runs, image generation, video generation, audio transcription, TTS, web search, and embeddings.
|
||||
```
|
||||
|
||||
Добра навичка на основі infer має:
|
||||
Якісний skill на основі infer має:
|
||||
|
||||
- зіставляти типові наміри користувача з правильной підкомандою infer
|
||||
- містити кілька канонічних прикладів infer для робочих процесів, які вона охоплює
|
||||
- зіставляти поширені наміри користувача з правильним підкомандним рядком infer
|
||||
- містити кілька канонічних прикладів infer для робочих процесів, які він охоплює
|
||||
- надавати перевагу `openclaw infer ...` у прикладах і пропозиціях
|
||||
- уникати повторного документування всієї поверхні infer в тілі навички
|
||||
- уникати повторного документування всієї поверхні infer у тілі skill
|
||||
|
||||
Типове покриття навички, зосередженої на infer:
|
||||
Типове покриття skill, зосередженого на infer:
|
||||
|
||||
- `openclaw infer model run`
|
||||
- `openclaw infer image generate`
|
||||
@ -44,19 +44,19 @@ Focus on model runs, image generation, video generation, audio transcription, TT
|
||||
|
||||
## Навіщо використовувати infer
|
||||
|
||||
`openclaw infer` надає один узгоджений CLI для завдань інференсу на базі провайдерів усередині OpenClaw.
|
||||
`openclaw infer` надає єдиний узгоджений CLI для завдань інференсу на основі провайдерів усередині OpenClaw.
|
||||
|
||||
Переваги:
|
||||
|
||||
- Використовуйте провайдерів і моделі, уже налаштовані в OpenClaw, замість створення одноразових обгорток для кожного бекенда.
|
||||
- Тримайте робочі процеси для моделей, зображень, транскрибування аудіо, TTS, відео, вебу та embeddings в одному дереві команд.
|
||||
- Використовуйте стабільну форму виводу `--json` для скриптів, автоматизації та робочих процесів, керованих агентом.
|
||||
- Надавайте перевагу першосторонній поверхні OpenClaw, коли завдання по суті є «запустити інференс».
|
||||
- Для більшості команд infer використовуйте звичайний локальний шлях без вимоги Gateway.
|
||||
- Використовуйте провайдери й моделі, уже налаштовані в OpenClaw, замість створення одноразових обгорток для кожного бекенда.
|
||||
- Тримайте робочі процеси для моделей, зображень, транскрипції аудіо, TTS, відео, вебу та embeddings в одному дереві команд.
|
||||
- Використовуйте стабільну форму виводу `--json` для скриптів, автоматизації та робочих процесів, керованих агентами.
|
||||
- Надавайте перевагу першосторонній поверхні OpenClaw, коли завдання по суті полягає в «запуску інференсу».
|
||||
- Для більшості команд infer використовуйте звичайний локальний шлях без потреби в Gateway.
|
||||
|
||||
Для наскрізних перевірок провайдерів надавайте перевагу `openclaw infer ...`, коли нижчорівневі
|
||||
тести провайдера вже зелені. Це перевіряє поставлений CLI, завантаження конфігурації,
|
||||
розв’язання агента за замовчуванням, активацію вбудованого Plugin, відновлення runtime-залежностей
|
||||
тести провайдерів уже зелені. Це перевіряє відвантажений CLI, завантаження конфігурації,
|
||||
розв’язання агента за замовчуванням, активацію вбудованого Plugin, відновлення залежностей виконання
|
||||
і спільний runtime можливостей до виконання запиту до провайдера.
|
||||
|
||||
## Дерево команд
|
||||
@ -110,42 +110,43 @@ Focus on model runs, image generation, video generation, audio transcription, TT
|
||||
providers
|
||||
```
|
||||
|
||||
## Типові завдання
|
||||
## Поширені завдання
|
||||
|
||||
Ця таблиця зіставляє типові завдання інференсу з відповідною командою infer.
|
||||
Ця таблиця зіставляє поширені завдання інференсу з відповідною командою infer.
|
||||
|
||||
| Завдання | Команда | Примітки |
|
||||
| ---------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
|
||||
| Запустити текстовий/модельний prompt | `openclaw infer model run --prompt "..." --json` | За замовчуванням використовує звичайний локальний шлях |
|
||||
| Запустити модельний prompt із зображеннями | `openclaw infer model run --prompt "Describe this" --file ./image.png --model provider/model` | Повторіть `--file` для кількох вхідних зображень |
|
||||
| Згенерувати зображення | `openclaw infer image generate --prompt "..." --json` | Використовуйте `image edit`, коли починаєте з наявного файла |
|
||||
| Описати файл зображення | `openclaw infer image describe --file ./image.png --prompt "..." --json` | `--model` має бути моделлю з підтримкою зображень у формі `<provider/model>` |
|
||||
| Транскрибувати аудіо | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` має бути `<provider/model>` |
|
||||
| Синтезувати мовлення | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` орієнтовано на Gateway |
|
||||
| Запустити модельний prompt для зображень | `openclaw infer model run --prompt "Describe this" --file ./image.png --model provider/model` | Повторіть `--file` для кількох вхідних зображень |
|
||||
| Згенерувати зображення | `openclaw infer image generate --prompt "..." --json` | Використовуйте `image edit`, коли починаєте з наявного файлу |
|
||||
| Описати файл зображення | `openclaw infer image describe --file ./image.png --prompt "..." --json` | `--model` має бути моделлю з підтримкою зображень у форматі `<provider/model>` |
|
||||
| Транскрибувати аудіо | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` має бути `<provider/model>` |
|
||||
| Синтезувати мовлення | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` орієнтовано на Gateway |
|
||||
| Згенерувати відео | `openclaw infer video generate --prompt "..." --json` | Підтримує підказки провайдера, як-от `--resolution` |
|
||||
| Описати відеофайл | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` має бути `<provider/model>` |
|
||||
| Описати відеофайл | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` має бути `<provider/model>` |
|
||||
| Шукати в інтернеті | `openclaw infer web search --query "..." --json` | |
|
||||
| Отримати вебсторінку | `openclaw infer web fetch --url https://example.com --json` | |
|
||||
| Створити embeddings | `openclaw infer embedding create --text "..." --json` | |
|
||||
|
||||
## Поведінка
|
||||
|
||||
- `openclaw infer ...` — основна поверхня CLI для цих робочих процесів.
|
||||
- `openclaw infer ...` є основною CLI-поверхнею для цих робочих процесів.
|
||||
- Використовуйте `--json`, коли вивід споживатиме інша команда або скрипт.
|
||||
- Використовуйте `--provider` або `--model provider/model`, коли потрібен конкретний бекенд.
|
||||
- Для `image describe`, `audio transcribe` і `video describe` `--model` має використовувати форму `<provider/model>`.
|
||||
- Для `image describe` явний `--model` запускає цей provider/model напряму. Модель має підтримувати зображення в каталозі моделей або конфігурації провайдера. `codex/<model>` запускає обмежений хід Codex app-server для розуміння зображень; `openai-codex/<model>` використовує шлях OpenAI Codex OAuth provider.
|
||||
- Команди виконання без стану за замовчуванням локальні.
|
||||
- Для `image describe` явний `--model` запускає цей provider/model напряму. Модель має підтримувати зображення в каталозі моделей або конфігурації провайдера. `codex/<model>` запускає обмежений крок розуміння зображення через Codex app-server; `openai-codex/<model>` використовує шлях провайдера OpenAI Codex OAuth.
|
||||
- Команди виконання без стану за замовчуванням використовують локальний режим.
|
||||
- Команди стану, керованого Gateway, за замовчуванням використовують Gateway.
|
||||
- Звичайний локальний шлях не потребує запущеного Gateway.
|
||||
- Локальний `model run` — це компактне одноразове завершення провайдера. Він розв’язує налаштовану модель агента й автентифікацію, але не запускає хід chat-agent, не завантажує інструменти й не відкриває вбудовані MCP-сервери.
|
||||
- Локальний `model run` — це легке одноразове завершення через провайдера. Він розв’язує налаштовану модель агента й авторизацію, але не запускає крок чат-агента, не завантажує інструменти й не відкриває вбудовані MCP-сервери.
|
||||
- `model run --file` приймає файли зображень, визначає їхній MIME-тип і надсилає їх із наданим prompt до вибраної моделі. Повторіть `--file` для кількох зображень.
|
||||
- `model run --file` відхиляє вхідні дані, що не є зображеннями. Використовуйте `infer audio transcribe` для аудіофайлів і `infer video describe` для відеофайлів.
|
||||
- `model run --gateway` перевіряє маршрутизацію Gateway, збережену автентифікацію, вибір провайдера та вбудований runtime, але все одно працює як сирий модельний probe: він надсилає наданий prompt і будь-які вкладення зображень без попереднього transcript сеансу, bootstrap/AGENTS context, складання context-engine, інструментів або вбудованих MCP-серверів.
|
||||
- `model run --gateway` перевіряє маршрутизацію Gateway, збережену авторизацію, вибір провайдера й вбудований runtime, але все одно працює як сирий модельний пробник: він надсилає наданий prompt і будь-які вкладення зображень без попереднього transcript сесії, bootstrap/AGENTS-контексту, збирання context-engine, інструментів або вбудованих MCP-серверів.
|
||||
- `model run --gateway --model <provider/model>` потребує довіреного операторського облікового запису Gateway, оскільки запит просить Gateway виконати одноразове перевизначення provider/model.
|
||||
|
||||
## Модель
|
||||
|
||||
Використовуйте `model` для текстового інференсу на базі провайдерів і перевірки моделей/провайдерів.
|
||||
Використовуйте `model` для текстового інференсу на основі провайдерів і перевірки моделей/провайдерів.
|
||||
|
||||
```bash
|
||||
openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json
|
||||
@ -155,7 +156,7 @@ openclaw infer model providers --json
|
||||
openclaw infer model inspect --name gpt-5.5 --json
|
||||
```
|
||||
|
||||
Використовуйте повні посилання `<provider/model>`, щоб виконати smoke-test конкретного провайдера без
|
||||
Використовуйте повні посилання `<provider/model>`, щоб smoke-тестувати конкретного провайдера без
|
||||
запуску Gateway або завантаження повної поверхні інструментів агента:
|
||||
|
||||
```bash
|
||||
@ -170,18 +171,18 @@ openclaw infer model run --local --model ollama/qwen2.5vl:7b --prompt "Describe
|
||||
|
||||
Примітки:
|
||||
|
||||
- Локальний `model run` — це найвужчий CLI smoke для перевірки стану provider/model/auth, бо він надсилає лише наданий prompt до вибраної моделі.
|
||||
- Локальний `model run --file` зберігає цей компактний шлях і додає вміст зображення безпосередньо до одного повідомлення користувача. Поширені файли зображень, як-от PNG, JPEG і WebP, працюють, коли їхній MIME-тип визначено як `image/*`; непідтримувані або нерозпізнані файли завершуються помилкою до виклику провайдера.
|
||||
- `model run --file` найкраще підходить, коли ви хочете напряму протестувати вибрану мультимодальну текстову модель. Використовуйте `infer image describe`, коли вам потрібні вибір провайдера розуміння зображень OpenClaw і маршрутизація image-model за замовчуванням.
|
||||
- Вибрана модель має підтримувати вхідні зображення; моделі лише для тексту можуть відхилити запит на рівні провайдера.
|
||||
- `model run --prompt` має містити текст не лише з пробілів; порожні prompts відхиляються до виклику локальних провайдерів або Gateway.
|
||||
- Локальний `model run` завершується з ненульовим кодом, коли провайдер не повертає текстового виводу, тож недосяжні локальні провайдери й порожні завершення не виглядають як успішні probes.
|
||||
- Використовуйте `model run --gateway`, коли потрібно протестувати маршрутизацію Gateway, налаштування agent-runtime або стан провайдера, керований Gateway, зберігаючи вхідні дані моделі сирими. Використовуйте `openclaw agent` або chat-поверхні, коли потрібні повний контекст агента, інструменти, пам’ять і transcript сеансу.
|
||||
- `model auth login`, `model auth logout` і `model auth status` керують збереженим станом автентифікації провайдера.
|
||||
- Локальний `model run` є найвужчим CLI-smoke для справності provider/model/auth, оскільки він надсилає вибраній моделі лише наданий prompt.
|
||||
- Локальний `model run --file` зберігає цей легкий шлях і прикріплює вміст зображення напряму до єдиного повідомлення користувача. Поширені файли зображень, як-от PNG, JPEG і WebP, працюють, коли їхній MIME-тип визначено як `image/*`; непідтримувані або нерозпізнані файли зазнають помилки до виклику провайдера.
|
||||
- `model run --file` найкраще підходить, коли потрібно напряму протестувати вибрану мультимодальну текстову модель. Використовуйте `infer image describe`, коли потрібні вибір провайдера розуміння зображень OpenClaw і маршрутизація до моделі зображень за замовчуванням.
|
||||
- Вибрана модель має підтримувати вхідні зображення; текстові-only моделі можуть відхилити запит на рівні провайдера.
|
||||
- `model run --prompt` має містити текст не лише з пробільних символів; порожні prompts відхиляються до виклику локальних провайдерів або Gateway.
|
||||
- Локальний `model run` завершується з ненульовим кодом, коли провайдер не повертає текстового виводу, тому недосяжні локальні провайдери й порожні completions не виглядають як успішні проби.
|
||||
- Використовуйте `model run --gateway`, коли потрібно протестувати маршрутизацію Gateway, налаштування agent-runtime або стан провайдера, керований Gateway, зберігаючи модельний вхід сирим. Використовуйте `openclaw agent` або чат-поверхні, коли потрібні повний контекст агента, інструменти, пам’ять і transcript сесії.
|
||||
- `model auth login`, `model auth logout` і `model auth status` керують збереженим станом авторизації провайдера.
|
||||
|
||||
## Зображення
|
||||
|
||||
Використовуйте `image` для генерації, редагування та опису.
|
||||
Використовуйте `image` для генерації, редагування й опису.
|
||||
|
||||
```bash
|
||||
openclaw infer image generate --prompt "friendly lobster illustration" --json
|
||||
@ -201,16 +202,16 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --p
|
||||
|
||||
- Використовуйте `image edit`, коли починаєте з наявних вхідних файлів.
|
||||
- Використовуйте `--size`, `--aspect-ratio` або `--resolution` з `image edit` для
|
||||
провайдерів/моделей, що підтримують геометричні підказки під час редагування reference-image.
|
||||
провайдерів/моделей, які підтримують підказки геометрії під час редагування референсних зображень.
|
||||
- Використовуйте `--output-format png --background transparent` з
|
||||
`--model openai/gpt-image-1.5` для PNG-виводу OpenAI з прозорим фоном;
|
||||
`--openai-background` залишається доступним як специфічний для OpenAI псевдонім. Провайдери,
|
||||
які не оголошують підтримку фону, повідомляють підказку як проігнороване перевизначення.
|
||||
`--openai-background` залишається доступним як специфічний для OpenAI alias. Провайдери,
|
||||
які не оголошують підтримку фону, повідомляють цю підказку як проігнороване перевизначення.
|
||||
- Використовуйте `image providers --json`, щоб перевірити, які вбудовані провайдери зображень
|
||||
можна виявити, налаштовано, вибрано, і які можливості генерації/редагування
|
||||
виявляються, налаштовані, вибрані та які можливості генерації/редагування
|
||||
надає кожен провайдер.
|
||||
- Використовуйте `image generate --model <provider/model> --json` як найвужчий live
|
||||
CLI smoke для змін генерації зображень. Приклад:
|
||||
CLI-smoke для змін генерації зображень. Приклад:
|
||||
|
||||
```bash
|
||||
openclaw infer image providers --json
|
||||
@ -221,14 +222,14 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --p
|
||||
--json
|
||||
```
|
||||
|
||||
Відповідь JSON повідомляє `ok`, `provider`, `model`, `attempts` і записані
|
||||
шляхи виводу. Коли задано `--output`, кінцеве розширення може відповідати
|
||||
MIME-типу, поверненому постачальником.
|
||||
JSON-відповідь повідомляє `ok`, `provider`, `model`, `attempts` і шляхи
|
||||
записаних вихідних файлів. Коли задано `--output`, кінцеве розширення може відповідати
|
||||
MIME-типу, який повернув провайдер.
|
||||
|
||||
- Для `image describe` і `image describe-many` використовуйте `--prompt`, щоб надати візійній моделі інструкцію для конкретного завдання, наприклад OCR, порівняння, перевірку UI або стислий підпис.
|
||||
- Використовуйте `--timeout-ms` із повільними локальними візійними моделями або холодними запусками Ollama.
|
||||
- Для `image describe` та `image describe-many` використовуйте `--prompt`, щоб надати моделі комп’ютерного зору інструкцію для конкретного завдання, як-от OCR, порівняння, перевірка UI або стислий підпис.
|
||||
- Використовуйте `--timeout-ms` з повільними локальними моделями комп’ютерного зору або холодними запусками Ollama.
|
||||
- Для `image describe` `--model` має бути моделлю `<provider/model>` із підтримкою зображень.
|
||||
- Для локальних візійних моделей Ollama спершу завантажте модель і задайте для `OLLAMA_API_KEY` будь-яке значення-заповнювач, наприклад `ollama-local`. Див. [Ollama](/uk/providers/ollama#vision-and-image-description).
|
||||
- Для локальних моделей комп’ютерного зору Ollama спочатку завантажте модель і задайте для `OLLAMA_API_KEY` будь-яке значення-заповнювач, наприклад `ollama-local`. Див. [Ollama](/uk/providers/ollama#vision-and-image-description).
|
||||
|
||||
## Аудіо
|
||||
|
||||
@ -247,7 +248,7 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso
|
||||
|
||||
## TTS
|
||||
|
||||
Використовуйте `tts` для синтезу мовлення та стану постачальника TTS.
|
||||
Використовуйте `tts` для синтезу мовлення та стану TTS-провайдера.
|
||||
|
||||
```bash
|
||||
openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json
|
||||
@ -258,12 +259,12 @@ openclaw infer tts status --json
|
||||
|
||||
Примітки:
|
||||
|
||||
- `tts status` за замовчуванням використовує gateway, оскільки відображає стан TTS, керований gateway.
|
||||
- Використовуйте `tts providers`, `tts voices` і `tts set-provider`, щоб переглядати й налаштовувати поведінку TTS.
|
||||
- `tts status` за замовчуванням використовує Gateway, оскільки відображає стан TTS, керований Gateway.
|
||||
- Використовуйте `tts providers`, `tts voices` і `tts set-provider`, щоб переглядати та налаштовувати поведінку TTS.
|
||||
|
||||
## Відео
|
||||
|
||||
Використовуйте `video` для генерації та опису.
|
||||
Використовуйте `video` для генерування й опису.
|
||||
|
||||
```bash
|
||||
openclaw infer video generate --prompt "cinematic sunset over the ocean" --json
|
||||
@ -274,7 +275,7 @@ openclaw infer video describe --file ./clip.mp4 --model openai/gpt-4.1-mini --js
|
||||
|
||||
Примітки:
|
||||
|
||||
- `video generate` приймає `--size`, `--aspect-ratio`, `--resolution`, `--duration`, `--audio`, `--watermark` і `--timeout-ms` та передає їх у середовище виконання генерації відео.
|
||||
- `video generate` приймає `--size`, `--aspect-ratio`, `--resolution`, `--duration`, `--audio`, `--watermark` і `--timeout-ms` та передає їх до середовища виконання генерування відео.
|
||||
- `--model` має бути `<provider/model>` для `video describe`.
|
||||
|
||||
## Веб
|
||||
@ -290,11 +291,11 @@ openclaw infer web providers --json
|
||||
|
||||
Примітки:
|
||||
|
||||
- Використовуйте `web providers`, щоб переглядати доступних, налаштованих і вибраних постачальників.
|
||||
- Використовуйте `web providers`, щоб переглянути доступних, налаштованих і вибраних провайдерів.
|
||||
|
||||
## Embedding
|
||||
## Вбудовування
|
||||
|
||||
Використовуйте `embedding` для створення векторів і перегляду постачальника embeddings.
|
||||
Використовуйте `embedding` для створення векторів і перевірки провайдера вбудовувань.
|
||||
|
||||
```bash
|
||||
openclaw infer embedding create --text "friendly lobster" --json
|
||||
@ -304,7 +305,7 @@ openclaw infer embedding providers --json
|
||||
|
||||
## Вивід JSON
|
||||
|
||||
Команди infer нормалізують вивід JSON у спільній обгортці:
|
||||
Команди infer нормалізують вивід JSON у спільній оболонці:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -329,9 +330,9 @@ openclaw infer embedding providers --json
|
||||
- `outputs`
|
||||
- `error`
|
||||
|
||||
Для команд генерації медіа `outputs` містить файли, записані OpenClaw. Використовуйте
|
||||
`path`, `mimeType`, `size` і будь-які специфічні для медіа розміри в цьому масиві
|
||||
для автоматизації замість аналізу stdout, призначеного для читання людиною.
|
||||
Для команд генерування медіа `outputs` містить файли, записані OpenClaw. Використовуйте
|
||||
`path`, `mimeType`, `size` і будь-які медіаспецифічні розміри в цьому масиві
|
||||
для автоматизації замість розбору зрозумілого для людини stdout.
|
||||
|
||||
## Поширені помилки
|
||||
|
||||
|
||||
@ -1,24 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібен точний покроковий опис циклу агента або подій життєвого циклу
|
||||
- Ви змінюєте постановку сесій у чергу, записування транскрипту або поведінку блокування запису сесії
|
||||
- Ви змінюєте постановку сеансів у чергу, запис транскриптів або поведінку блокування запису сеансу
|
||||
summary: Життєвий цикл циклу агента, потоки та семантика очікування
|
||||
title: Цикл агента
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T09:29:56Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-04-28T20:11:20Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 7b7cb32238489e213680553d0c5ea13f32fecb6ee748a514b69dbe2d223661b0
|
||||
source_hash: 3f870abbd9ce724e04b32dfe6296ef0df10ebd5cc6d37492457dc77dfb868b8f
|
||||
source_path: concepts/agent-loop.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Агентний цикл — це повний «реальний» запуск агента: прийом → збирання контексту → інференс моделі →
|
||||
виконання інструментів → потокове надсилання відповідей → збереження. Це авторитетний шлях, який перетворює повідомлення
|
||||
на дії та фінальну відповідь, зберігаючи узгодженість стану сесії.
|
||||
Агентний цикл — це повний “реальний” запуск агента: приймання → збирання контексту → інференс моделі →
|
||||
виконання інструментів → потокові відповіді → збереження. Це авторитетний шлях, який перетворює повідомлення
|
||||
на дії та фінальну відповідь, водночас підтримуючи узгоджений стан сеансу.
|
||||
|
||||
В OpenClaw цикл — це один серіалізований запуск на сесію, який генерує події життєвого циклу та потокові події,
|
||||
поки модель думає, викликає інструменти та потоково виводить результат. У цьому документі пояснюється, як цей справжній цикл
|
||||
В OpenClaw цикл — це один серіалізований запуск на сеанс, який генерує події життєвого циклу та потоку,
|
||||
поки модель міркує, викликає інструменти й потоково видає результат. У цьому документі пояснено, як цей автентичний цикл
|
||||
з’єднаний наскрізно.
|
||||
|
||||
## Точки входу
|
||||
@ -26,151 +26,152 @@ x-i18n:
|
||||
- Gateway RPC: `agent` і `agent.wait`.
|
||||
- CLI: команда `agent`.
|
||||
|
||||
## Як це працює (на високому рівні)
|
||||
## Як це працює (загальний огляд)
|
||||
|
||||
1. RPC `agent` валідує параметри, визначає сесію (sessionKey/sessionId), зберігає метадані сесії та одразу повертає `{ runId, acceptedAt }`.
|
||||
1. RPC `agent` перевіряє параметри, визначає сеанс (sessionKey/sessionId), зберігає метадані сеансу, одразу повертає `{ runId, acceptedAt }`.
|
||||
2. `agentCommand` запускає агента:
|
||||
- визначає модель + типові значення thinking/verbose/trace
|
||||
- визначає модель + стандартні значення thinking/verbose/trace
|
||||
- завантажує знімок Skills
|
||||
- викликає `runEmbeddedPiAgent` (середовище виконання pi-agent-core)
|
||||
- генерує **lifecycle end/error**, якщо вбудований цикл сам цього не згенерував
|
||||
- генерує **завершення/помилку життєвого циклу**, якщо вбудований цикл не згенерує їх сам
|
||||
3. `runEmbeddedPiAgent`:
|
||||
- серіалізує запуски через черги на рівні сесії та глобальні черги
|
||||
- визначає модель + профіль автентифікації та будує pi session
|
||||
- підписується на події pi і потоково передає дельти асистента/інструментів
|
||||
- застосовує timeout -> перериває запуск, якщо його перевищено
|
||||
- повертає payload-и та метадані використання
|
||||
4. `subscribeEmbeddedPiSession` з’єднує події pi-agent-core з потоком OpenClaw `agent`:
|
||||
- серіалізує запуски через посеансові + глобальні черги
|
||||
- визначає модель + профіль автентифікації та створює сеанс pi
|
||||
- підписується на події pi й потоково передає дельти асистента/інструментів
|
||||
- застосовує тайм-аут -> перериває запуск у разі перевищення
|
||||
- повертає payload-и + метадані використання
|
||||
4. `subscribeEmbeddedPiSession` мостить події pi-agent-core до потоку OpenClaw `agent`:
|
||||
- події інструментів => `stream: "tool"`
|
||||
- дельти асистента => `stream: "assistant"`
|
||||
- події життєвого циклу => `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
|
||||
5. `agent.wait` використовує `waitForAgentRun`:
|
||||
- очікує на **lifecycle end/error** для `runId`
|
||||
- чекає **завершення/помилки життєвого циклу** для `runId`
|
||||
- повертає `{ status: ok|error|timeout, startedAt, endedAt, error? }`
|
||||
|
||||
## Постановка в чергу + конкурентність
|
||||
## Черги + паралельність
|
||||
|
||||
- Запуски серіалізуються для кожного ключа сесії (доріжка сесії) і, за потреби, також через глобальну доріжку.
|
||||
- Це запобігає змаганням інструментів/сесій і зберігає узгоджену історію сесії.
|
||||
- Канали обміну повідомленнями можуть вибирати режими черги (collect/steer/followup), які подаються в цю систему доріжок.
|
||||
Див. [Command Queue](/uk/concepts/queue).
|
||||
- Записи транскрипту також захищені блокуванням запису сесії на файлі сесії. Це блокування
|
||||
враховує процеси та базується на файлі, тому виявляє записувачів, які обходять внутрішньопроцесну чергу або походять
|
||||
- Запуски серіалізуються за ключем сеансу (лінія сеансу) й опціонально через глобальну лінію.
|
||||
- Це запобігає перегонам інструментів/сеансів і підтримує узгоджену історію сеансу.
|
||||
- Канали повідомлень можуть вибирати режими черги (collect/steer/followup), які передаються до цієї системи ліній.
|
||||
Див. [Черга команд](/uk/concepts/queue).
|
||||
- Записи транскрипту також захищені блокуванням запису сеансу на файлі сеансу. Блокування
|
||||
враховує процеси та базується на файлі, тому воно ловить записувачів, які обходять внутрішньопроцесну чергу або приходять
|
||||
з іншого процесу.
|
||||
- Блокування запису сесії за замовчуванням не є реентерабельними. Якщо допоміжний код навмисно вкладає отримання
|
||||
- Блокування запису сеансу за замовчуванням нерекурсивні. Якщо helper навмисно вкладає отримання
|
||||
того самого блокування, зберігаючи одного логічного записувача, він має явно ввімкнути це через
|
||||
`allowReentrant: true`.
|
||||
|
||||
## Підготовка сесії + робочого простору
|
||||
## Підготовка сеансу + робочого простору
|
||||
|
||||
- Робочий простір визначається та створюється; sandboxed-запуски можуть перенаправлятися до кореня робочого простору sandbox.
|
||||
- Skills завантажуються (або повторно використовуються зі знімка) та впроваджуються в env і prompt.
|
||||
- Bootstrap/context файли визначаються та впроваджуються у звіт системного prompt.
|
||||
- Отримується блокування запису сесії; `SessionManager` відкривається та готується перед початком потокової передачі. Будь-який
|
||||
подальший шлях перезапису, Compaction або усічення транскрипту повинен брати те саме блокування перед відкриттям або
|
||||
- Робочий простір визначається й створюється; sandbox-запуски можуть перенаправлятися до кореня sandbox-робочого простору.
|
||||
- Skills завантажуються (або повторно використовуються зі знімка) та інжектяться в env і prompt.
|
||||
- Bootstrap/context-файли визначаються й інжектяться у звіт системного prompt-а.
|
||||
- Отримується блокування запису сеансу; `SessionManager` відкривається й готується до потокової передачі. Будь-який
|
||||
подальший шлях переписування транскрипту, Compaction або скорочення має взяти те саме блокування перед відкриттям або
|
||||
зміною файлу транскрипту.
|
||||
|
||||
## Збирання prompt + системний prompt
|
||||
## Збирання prompt-а + системний prompt
|
||||
|
||||
- Системний prompt будується з базового prompt OpenClaw, prompt для Skills, bootstrap-контексту та перевизначень для конкретного запуску.
|
||||
- Застосовуються специфічні для моделі обмеження та резерв токенів для Compaction.
|
||||
- Див. [System prompt](/uk/concepts/system-prompt), щоб зрозуміти, що бачить модель.
|
||||
- Системний prompt будується з базового prompt-а OpenClaw, prompt-а Skills, bootstrap-контексту та перевизначень для запуску.
|
||||
- Застосовуються модельно-специфічні ліміти та резерв токенів для Compaction.
|
||||
- Див. [Системний prompt](/uk/concepts/system-prompt), щоб зрозуміти, що бачить модель.
|
||||
|
||||
## Точки перехоплення (де можна втрутитися)
|
||||
## Точки hook-ів (де можна перехоплювати)
|
||||
|
||||
OpenClaw має дві системи хуків:
|
||||
OpenClaw має дві системи hook-ів:
|
||||
|
||||
- **Внутрішні хуки** (хуки Gateway): скрипти, що реагують на події команд і події життєвого циклу.
|
||||
- **Plugin hooks**: точки розширення всередині життєвого циклу агента/інструментів і конвеєра gateway.
|
||||
- **Внутрішні hook-и** (hook-и Gateway): подієві скрипти для команд і подій життєвого циклу.
|
||||
- **Hook-и Plugin**: точки розширення всередині життєвого циклу агента/інструментів і конвеєра gateway.
|
||||
|
||||
### Внутрішні хуки (хуки Gateway)
|
||||
### Внутрішні hook-и (hook-и Gateway)
|
||||
|
||||
- **`agent:bootstrap`**: запускається під час побудови bootstrap-файлів до фіналізації системного prompt.
|
||||
- **`agent:bootstrap`**: запускається під час побудови bootstrap-файлів до фіналізації системного prompt-а.
|
||||
Використовуйте це, щоб додавати/видаляти файли bootstrap-контексту.
|
||||
- **Хуки команд**: `/new`, `/reset`, `/stop` та інші події команд (див. документацію Hooks).
|
||||
- **Hook-и команд**: `/new`, `/reset`, `/stop` та інші події команд (див. документацію про hook-и).
|
||||
|
||||
Див. [Hooks](/uk/automation/hooks), щоб переглянути налаштування та приклади.
|
||||
Див. [Hook-и](/uk/automation/hooks) для налаштування та прикладів.
|
||||
|
||||
### Plugin hooks (життєвий цикл агента + gateway)
|
||||
### Hook-и Plugin (життєвий цикл агента + gateway)
|
||||
|
||||
Вони запускаються всередині циклу агента або конвеєра gateway:
|
||||
Вони виконуються всередині циклу агента або конвеєра gateway:
|
||||
|
||||
- **`before_model_resolve`**: виконується до сесії (без `messages`), щоб детерміновано перевизначити provider/model до визначення моделі.
|
||||
- **`before_prompt_build`**: виконується після завантаження сесії (з `messages`), щоб впровадити `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext` перед надсиланням prompt. Використовуйте `prependContext` для динамічного тексту на поточний хід, а поля системного контексту — для стабільних вказівок, які мають залишатися в просторі системного prompt.
|
||||
- **`before_agent_start`**: застарілий хук сумісності, який може виконуватися в будь-якій фазі; надавайте перевагу явним хукам вище.
|
||||
- **`before_agent_reply`**: виконується після вбудованих дій і перед викликом LLM, дозволяючи плагіну перехопити хід і повернути синтетичну відповідь або повністю приглушити хід.
|
||||
- **`agent_end`**: дає змогу перевірити фінальний список повідомлень і метадані запуску після завершення.
|
||||
- **`before_compaction` / `after_compaction`**: дають змогу спостерігати або анотувати цикли Compaction.
|
||||
- **`before_model_resolve`**: виконується до сеансу (без `messages`), щоб детерміновано перевизначити provider/model перед визначенням моделі.
|
||||
- **`before_prompt_build`**: виконується після завантаження сеансу (з `messages`), щоб інжектити `prependContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext` перед надсиланням prompt-а. Використовуйте `prependContext` для динамічного тексту на хід і поля системного контексту для стабільних настанов, які мають бути в просторі системного prompt-а.
|
||||
- **`before_agent_start`**: застарілий hook сумісності, який може виконуватися в будь-якій фазі; віддавайте перевагу явним hook-ам вище.
|
||||
- **`before_agent_reply`**: виконується після inline-дій і перед викликом LLM, дозволяючи Plugin забрати хід і повернути синтетичну відповідь або повністю приглушити хід.
|
||||
- **`agent_end`**: перевіряє фінальний список повідомлень і метадані запуску після завершення.
|
||||
- **`before_compaction` / `after_compaction`**: спостерігають або анотують цикли Compaction.
|
||||
- **`before_tool_call` / `after_tool_call`**: перехоплюють параметри/результати інструментів.
|
||||
- **`before_install`**: дає змогу перевірити вбудовані результати сканування та за потреби заблокувати встановлення skill або plugin.
|
||||
- **`tool_result_persist`**: синхронно трансформує результати інструментів перед тим, як вони будуть записані в транскрипт сесії, що належить OpenClaw.
|
||||
- **`message_received` / `message_sending` / `message_sent`**: хуки вхідних і вихідних повідомлень.
|
||||
- **`session_start` / `session_end`**: межі життєвого циклу сесії.
|
||||
- **`before_install`**: перевіряє вбудовані результати сканування та опціонально блокує встановлення skill або Plugin.
|
||||
- **`tool_result_persist`**: синхронно трансформує результати інструментів перед записом у транскрипт сеансу, який належить OpenClaw.
|
||||
- **`message_received` / `message_sending` / `message_sent`**: hook-и вхідних + вихідних повідомлень.
|
||||
- **`session_start` / `session_end`**: межі життєвого циклу сеансу.
|
||||
- **`gateway_start` / `gateway_stop`**: події життєвого циклу gateway.
|
||||
|
||||
Правила прийняття рішень хуками для захисту вихідних повідомлень/інструментів:
|
||||
Правила ухвалення рішень hook-ами для outbound/tool-запобіжників:
|
||||
|
||||
- `before_tool_call`: `{ block: true }` є кінцевим і зупиняє обробники з нижчим пріоритетом.
|
||||
- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує попереднє блокування.
|
||||
- `before_install`: `{ block: true }` є кінцевим і зупиняє обробники з нижчим пріоритетом.
|
||||
- `before_install`: `{ block: false }` нічого не робить і не скасовує попереднє блокування.
|
||||
- `message_sending`: `{ cancel: true }` є кінцевим і зупиняє обробники з нижчим пріоритетом.
|
||||
- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує попереднє скасування.
|
||||
- `before_tool_call`: `{ block: true }` є термінальним і зупиняє handler-и з нижчим пріоритетом.
|
||||
- `before_tool_call`: `{ block: false }` нічого не робить і не знімає попереднє блокування.
|
||||
- `before_install`: `{ block: true }` є термінальним і зупиняє handler-и з нижчим пріоритетом.
|
||||
- `before_install`: `{ block: false }` нічого не робить і не знімає попереднє блокування.
|
||||
- `message_sending`: `{ cancel: true }` є термінальним і зупиняє handler-и з нижчим пріоритетом.
|
||||
- `message_sending`: `{ cancel: false }` нічого не робить і не знімає попереднє скасування.
|
||||
|
||||
Див. [Plugin hooks](/uk/plugins/hooks), щоб переглянути API хуків і подробиці реєстрації.
|
||||
Див. [Hook-и Plugin](/uk/plugins/hooks) для API hook-ів і деталей реєстрації.
|
||||
|
||||
Harness-оточення можуть адаптувати ці хуки по-різному. Harness app-server у Codex зберігає
|
||||
Plugin hooks OpenClaw як контракт сумісності для документованих дзеркальних
|
||||
поверхонь, тоді як нативні хуки Codex залишаються окремим низькорівневим механізмом Codex.
|
||||
Harness-и можуть адаптувати ці hook-и по-різному. Harness app-server Codex зберігає
|
||||
hook-и Plugin OpenClaw як контракт сумісності для задокументованих дзеркальних
|
||||
поверхонь, тоді як нативні hook-и Codex залишаються окремим нижчорівневим механізмом Codex.
|
||||
|
||||
## Потокова передача + часткові відповіді
|
||||
|
||||
- Дельти асистента потоково передаються з pi-agent-core та генеруються як події `assistant`.
|
||||
- Потокова передача блоків може видавати часткові відповіді або на `text_end`, або на `message_end`.
|
||||
- Потокову передачу міркувань можна видавати як окремий потік або як відповіді блоками.
|
||||
- Див. [Streaming](/uk/concepts/streaming), щоб дізнатися про нарізання на фрагменти та поведінку відповідей блоками.
|
||||
- Дельти асистента потоково надходять із pi-agent-core і генеруються як події `assistant`.
|
||||
- Блокова потокова передача може генерувати часткові відповіді або на `text_end`, або на `message_end`.
|
||||
- Потокове міркування може генеруватися як окремий потік або як блокові відповіді.
|
||||
- Див. [Потокова передача](/uk/concepts/streaming) щодо поведінки chunking і блокових відповідей.
|
||||
|
||||
## Виконання інструментів + інструменти обміну повідомленнями
|
||||
## Виконання інструментів + інструменти повідомлень
|
||||
|
||||
- Події початку/оновлення/завершення інструмента генеруються в потоці `tool`.
|
||||
- Результати інструментів очищуються з урахуванням розміру та зображень перед логуванням/генерацією подій.
|
||||
- Надсилання інструментами обміну повідомленнями відстежуються, щоб уникати дубльованих підтверджень від асистента.
|
||||
- Події старту/оновлення/завершення інструменту генеруються в потоці `tool`.
|
||||
- Результати інструментів очищаються за розміром і payload-ами зображень перед логуванням/генеруванням.
|
||||
- Надсилання інструментів повідомлень відстежуються, щоб пригнічувати дублікати підтверджень асистента.
|
||||
|
||||
## Формування відповіді + приглушення
|
||||
## Формування відповіді + пригнічення
|
||||
|
||||
- Фінальні payload-и збираються з:
|
||||
- тексту асистента (і, за потреби, міркувань)
|
||||
- вбудованих зведень інструментів (коли verbose увімкнено й дозволено)
|
||||
- тексту помилки асистента, якщо модель повернула помилку
|
||||
- Точний маркер тиші `NO_REPLY` / `no_reply` відфільтровується з вихідних
|
||||
- тексту асистента (та опціонального міркування)
|
||||
- inline-підсумків інструментів (коли verbose + дозволено)
|
||||
- тексту помилки асистента, коли модель помиляється
|
||||
- Точний мовчазний токен `NO_REPLY` / `no_reply` фільтрується з вихідних
|
||||
payload-ів.
|
||||
- Дублікати інструментів обміну повідомленнями видаляються з фінального списку payload-ів.
|
||||
- Якщо не залишилося жодних payload-ів, які можна відобразити, і інструмент повернув помилку, генерується
|
||||
резервна відповідь про помилку інструмента (якщо тільки інструмент обміну повідомленнями вже не надіслав видиму для користувача відповідь).
|
||||
- Дублікати інструментів повідомлень видаляються з фінального списку payload-ів.
|
||||
- Якщо не лишається придатних до рендерингу payload-ів і інструмент завершився з помилкою, генерується fallback-відповідь про помилку інструменту
|
||||
(якщо інструмент повідомлень уже не надіслав видиму для користувача відповідь).
|
||||
|
||||
## Compaction + повторні спроби
|
||||
|
||||
- Автоматичний Compaction генерує події потоку `compaction` і може спричинити повторну спробу.
|
||||
- Під час повторної спроби буфери в пам’яті та зведення інструментів скидаються, щоб уникнути дубльованого виводу.
|
||||
- Див. [Compaction](/uk/concepts/compaction), щоб переглянути конвеєр Compaction.
|
||||
- Автоматичний Compaction генерує події потоку `compaction` і може запускати повторну спробу.
|
||||
- Під час повторної спроби буфери в пам’яті та підсумки інструментів скидаються, щоб уникнути дублювання виводу.
|
||||
- Див. [Compaction](/uk/concepts/compaction) щодо конвеєра Compaction.
|
||||
|
||||
## Потоки подій (сьогодні)
|
||||
|
||||
- `lifecycle`: генерується `subscribeEmbeddedPiSession` (і як резервний варіант — `agentCommand`)
|
||||
- `lifecycle`: генерується `subscribeEmbeddedPiSession` (і як fallback через `agentCommand`)
|
||||
- `assistant`: потокові дельти з pi-agent-core
|
||||
- `tool`: потокові події інструментів з pi-agent-core
|
||||
- `tool`: потокові події інструментів із pi-agent-core
|
||||
|
||||
## Обробка chat-каналу
|
||||
## Обробка чат-каналу
|
||||
|
||||
- Дельти асистента буферизуються в chat-повідомлення `delta`.
|
||||
- Chat `final` генерується на **lifecycle end/error**.
|
||||
- Дельти асистента буферизуються в чат-повідомлення `delta`.
|
||||
- Чат `final` генерується на **завершення/помилку життєвого циклу**.
|
||||
|
||||
## Тайм-аути
|
||||
|
||||
- Типове значення `agent.wait`: 30s (лише очікування). Його перевизначає параметр `timeoutMs`.
|
||||
- Час виконання агента: типове значення `agents.defaults.timeoutSeconds` — 172800s (48 годин); застосовується в таймері переривання `runEmbeddedPiAgent`.
|
||||
- Тайм-аут бездіяльності моделі: OpenClaw перериває запит моделі, якщо до завершення вікна бездіяльності не надходять фрагменти відповіді. `models.providers.<id>.timeoutSeconds` подовжує цей сторож бездіяльності для повільних локальних/self-hosted provider-ів; інакше OpenClaw використовує `agents.defaults.timeoutSeconds`, якщо його налаштовано, з обмеженням 120s за замовчуванням. Запуски, ініційовані Cron, без явного тайм-ауту моделі чи агента вимикають сторож бездіяльності й покладаються на зовнішній тайм-аут Cron.
|
||||
- Тайм-аут HTTP-запиту provider-а: `models.providers.<id>.timeoutSeconds` застосовується до HTTP fetch-запитів моделі цього provider-а, зокрема до з’єднання, заголовків, тіла, тайм-ауту запиту SDK, обробки переривання guarded-fetch за загальним тайм-аутом і сторожа бездіяльності потоку моделі. Використовуйте це для повільних локальних/self-hosted provider-ів, таких як Ollama, перш ніж збільшувати тайм-аут усього часу виконання агента.
|
||||
- Стандартно для `agent.wait`: 30 с (лише очікування). Параметр `timeoutMs` перевизначає.
|
||||
- Середовище виконання агента: `agents.defaults.timeoutSeconds` за замовчуванням 172800 с (48 годин); застосовується таймером переривання в `runEmbeddedPiAgent`.
|
||||
- Відновлення завислого сеансу: коли діагностику ввімкнено, `diagnostics.stuckSessionWarnMs` виявляє довгі сеанси `processing`. Активні вбудовані запуски, активні операції відповіді та активні задачі лінії сеансу за замовчуванням залишаються лише попередженнями; якщо діагностика не показує активної роботи для сеансу, watchdog звільняє відповідну лінію сеансу, щоб запланована стартова робота могла завершитися.
|
||||
- Тайм-аут простою моделі: OpenClaw перериває запит до моделі, коли до завершення вікна простою не надходять chunks відповіді. `models.providers.<id>.timeoutSeconds` розширює цей idle watchdog для повільних локальних/self-hosted provider-ів; інакше OpenClaw використовує `agents.defaults.timeoutSeconds`, коли налаштовано, з верхньою межею 120 с за замовчуванням. Запуски, ініційовані Cron, без явного тайм-ауту моделі або агента вимикають idle watchdog і покладаються на зовнішній тайм-аут cron.
|
||||
- Тайм-аут HTTP-запиту provider-а: `models.providers.<id>.timeoutSeconds` застосовується до HTTP-fetch-ів моделі цього provider-а, включно з connect, headers, body, тайм-аутом запиту SDK, загальною обробкою guarded-fetch abort і idle watchdog потоку моделі. Використовуйте це для повільних локальних/self-hosted provider-ів, як-от Ollama, перед підвищенням тайм-ауту всього середовища виконання агента.
|
||||
|
||||
## Де все може завершитися раніше
|
||||
|
||||
@ -181,8 +182,8 @@ Plugin hooks OpenClaw як контракт сумісності для доку
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Tools](/uk/tools) — доступні інструменти агента
|
||||
- [Hooks](/uk/automation/hooks) — скрипти, що реагують на події, які запускаються подіями життєвого циклу агента
|
||||
- [Інструменти](/uk/tools) — доступні інструменти агента
|
||||
- [Hook-и](/uk/automation/hooks) — подієві скрипти, що запускаються подіями життєвого циклу агента
|
||||
- [Compaction](/uk/concepts/compaction) — як підсумовуються довгі розмови
|
||||
- [Exec Approvals](/uk/tools/exec-approvals) — етапи схвалення для shell-команд
|
||||
- [Thinking](/uk/tools/thinking) — конфігурація рівня thinking/міркувань
|
||||
- [Схвалення Exec](/uk/tools/exec-approvals) — ворота схвалення для shell-команд
|
||||
- [Thinking](/uk/tools/thinking) — налаштування рівня thinking/reasoning
|
||||
|
||||
@ -1,48 +1,49 @@
|
||||
---
|
||||
read_when:
|
||||
- Зміна виконання або паралелізму автовідповіді
|
||||
summary: Проєктування черги команд, яка серіалізує вхідні запуски автовідповіді
|
||||
title: черга команд
|
||||
- Зміна виконання автоматичних відповідей або паралельності
|
||||
summary: Проєктування черги команд, що послідовно виконує вхідні запуски автовідповіді
|
||||
title: Черга команд
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T08:45:01Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-04-28T20:11:10Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 8fa2d4953ba8a3d9be7080599e550c796ccedf622a9467bf77e50454b6ea4c4a
|
||||
source_hash: 8ed2bd9fad7f35f124b99c570703ddd075c742391061a977323c28feaf3ab508
|
||||
source_path: concepts/queue.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Ми серіалізуємо вхідні запуски автовідповіді (усі канали) через невелику внутрішньопроцесну чергу, щоб запобігти конфліктам між кількома запусками агента, водночас зберігаючи безпечний паралелізм між сесіями.
|
||||
Ми серіалізуємо вхідні запуски автовідповідей (усі канали) через невелику внутрішньопроцесну чергу, щоб запобігти конфліктам між кількома запусками агента, водночас зберігаючи безпечний паралелізм між сесіями.
|
||||
|
||||
## Чому
|
||||
|
||||
- Запуски автовідповіді можуть бути дорогими (виклики LLM) і можуть конфліктувати, коли кілька вхідних повідомлень надходять майже одночасно.
|
||||
- Серіалізація дозволяє уникнути конкуренції за спільні ресурси (файли сесії, журнали, CLI stdin) і зменшує ймовірність лімітів з боку зовнішніх сервісів.
|
||||
- Запуски автовідповідей можуть бути дорогими (виклики LLM) і можуть конфліктувати, коли кілька вхідних повідомлень надходять майже одночасно.
|
||||
- Серіалізація дає змогу уникнути конкуренції за спільні ресурси (файли сесій, журнали, CLI stdin) і зменшує ймовірність лімітів частоти від upstream-сервісів.
|
||||
|
||||
## Як це працює
|
||||
|
||||
- FIFO-черга з урахуванням смуг обробляє кожну смугу з налаштовуваним обмеженням паралелізму (типово 1 для неналаштованих смуг; для main типово 4, для subagent — 8).
|
||||
- `runEmbeddedPiAgent` ставить у чергу за **ключем сесії** (смуга `session:<key>`), щоб гарантувати лише один активний запуск на сесію.
|
||||
- Потім кожен запуск сесії ставиться в **глобальну смугу** (`main` типово), щоб загальний паралелізм обмежувався через `agents.defaults.maxConcurrent`.
|
||||
- Коли увімкнено докладне журналювання, запуски в черзі виводять коротке повідомлення, якщо вони чекали понад ~2 с перед стартом.
|
||||
- Індикатори набору тексту все одно спрацьовують одразу під час додавання в чергу (коли це підтримується каналом), тому користувацький досвід не змінюється, поки ми чекаємо своєї черги.
|
||||
- FIFO-черга з урахуванням lane обробляє кожну lane з настроюваним лімітом паралельності (типово 1 для неналаштованих lane; main типово 4, subagent — 8).
|
||||
- `runEmbeddedPiAgent` ставить у чергу за **ключем сесії** (lane `session:<key>`), щоб гарантувати лише один активний запуск на сесію.
|
||||
- Потім кожен запуск сесії ставиться в **глобальну lane** (`main` типово), тож загальний паралелізм обмежується `agents.defaults.maxConcurrent`.
|
||||
- Коли ввімкнено докладне журналювання, запуски в черзі виводять коротке повідомлення, якщо чекали понад ~2 с перед стартом.
|
||||
- Індикатори набору все одно спрацьовують одразу під час додавання в чергу (коли канал це підтримує), тож користувацький досвід не змінюється, поки ми чекаємо своєї черги.
|
||||
|
||||
## Режими черги (для кожного каналу)
|
||||
|
||||
Вхідні повідомлення можуть керувати поточним запуском, чекати наступного ходу або робити обидва варіанти:
|
||||
Вхідні повідомлення можуть спрямовувати поточний запуск, чекати на наступний хід або робити і те, й інше:
|
||||
|
||||
- `steer`: негайно інʼєктується в поточний запуск (скасовує відкладені виклики інструментів після наступної межі інструмента). Якщо потокова передача не активна, використовується резервний перехід до followup.
|
||||
- `followup`: ставиться в чергу на наступний хід агента після завершення поточного запуску.
|
||||
- `collect`: обʼєднує всі повідомлення в черзі в **один** наступний хід (типово). Якщо повідомлення націлені на різні канали/гілки, вони обробляються окремо, щоб зберегти маршрутизацію.
|
||||
- `steer-backlog` (також `steer+backlog`): спрямовує зараз **і** зберігає повідомлення для наступного ходу.
|
||||
- `interrupt` (застаріле): перериває активний запуск для цієї сесії, а потім запускає найновіше повідомлення.
|
||||
- `steer`: негайно вставити в поточний запуск (скасовує очікувані виклики інструментів після наступної межі інструмента). Якщо streaming не використовується, повертається до followup.
|
||||
- `followup`: поставити в чергу для наступного ходу агента після завершення поточного запуску.
|
||||
- `collect`: об’єднати всі повідомлення в черзі в **один** наступний хід (типово). Якщо повідомлення спрямовані в різні канали/гілки, вони обробляються окремо, щоб зберегти маршрутизацію.
|
||||
- `steer-backlog` (також `steer+backlog`): спрямувати зараз **і** зберегти повідомлення для наступного ходу.
|
||||
- `interrupt` (застарілий): перервати активний запуск для цієї сесії, потім запустити найновіше повідомлення.
|
||||
- `queue` (застарілий псевдонім): те саме, що `steer`.
|
||||
|
||||
Steer-backlog означає, що ви можете отримати наступну відповідь після спрямованого запуску, тому на поверхнях зі стримінгом це може виглядати як дублікати. Віддавайте перевагу `collect`/`steer`, якщо хочете
|
||||
одну відповідь на одне вхідне повідомлення.
|
||||
Надішліть `/queue collect` як окрему команду (для конкретної сесії) або встановіть `messages.queue.byChannel.discord: "collect"`.
|
||||
Steer-backlog означає, що ви можете отримати наступну відповідь після спрямованого запуску, тому
|
||||
поверхні streaming можуть виглядати як дублікати. Надавайте перевагу `collect`/`steer`, якщо хочете
|
||||
одну відповідь на кожне вхідне повідомлення.
|
||||
Надішліть `/queue collect` як окрему команду (для сесії) або задайте `messages.queue.byChannel.discord: "collect"`.
|
||||
|
||||
Типові значення (якщо не задані в конфігурації):
|
||||
Типові значення (коли не задано в конфігурації):
|
||||
|
||||
- Усі поверхні → `collect`
|
||||
|
||||
@ -64,33 +65,34 @@ Steer-backlog означає, що ви можете отримати насту
|
||||
|
||||
## Параметри черги
|
||||
|
||||
Параметри застосовуються до `followup`, `collect` і `steer-backlog` (а також до `steer`, коли він резервно переходить до followup):
|
||||
Параметри застосовуються до `followup`, `collect` і `steer-backlog` (а також до `steer`, коли він повертається до followup):
|
||||
|
||||
- `debounceMs`: очікувати тиші перед початком наступного ходу (запобігає “continue, continue”).
|
||||
- `debounceMs`: чекати тиші перед запуском наступного ходу (запобігає “continue, continue”).
|
||||
- `cap`: максимальна кількість повідомлень у черзі на сесію.
|
||||
- `drop`: політика переповнення (`old`, `new`, `summarize`).
|
||||
|
||||
Summarize зберігає короткий маркований список відкинутих повідомлень і інʼєктує його як синтетичний followup-промпт.
|
||||
Summarize зберігає короткий маркований список відкинутих повідомлень і вставляє його як синтетичний followup prompt.
|
||||
Типові значення: `debounceMs: 1000`, `cap: 20`, `drop: summarize`.
|
||||
|
||||
## Перевизначення для сесії
|
||||
|
||||
- Надішліть `/queue <mode>` як окрему команду, щоб зберегти режим для поточної сесії.
|
||||
- Параметри можна комбінувати: `/queue collect debounce:2s cap:25 drop:summarize`
|
||||
- `/queue default` або `/queue reset` очищає перевизначення для сесії.
|
||||
- `/queue default` або `/queue reset` очищає перевизначення сесії.
|
||||
|
||||
## Область дії та гарантії
|
||||
|
||||
- Застосовується до запусків агента автовідповіді в усіх вхідних каналах, які використовують конвеєр відповіді Gateway (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat тощо).
|
||||
- Типова смуга (`main`) є загальнопроцесною для вхідних подій і основних Heartbeat; установіть `agents.defaults.maxConcurrent`, щоб дозволити паралельну обробку кількох сесій.
|
||||
- Можуть існувати додаткові смуги (наприклад, `cron`, `cron-nested`, `nested`, `subagent`), щоб фонові завдання могли виконуватися паралельно без блокування вхідних відповідей. Ізольовані ходи Cron-агента утримують слот `cron`, тоді як їхнє внутрішнє виконання агента використовує `cron-nested`; обидва використовують `cron.maxConcurrentRuns`. Спільні не-Cron-потоки `nested` зберігають власну поведінку смуг. Ці відокремлені запуски відстежуються як [фонові завдання](/uk/automation/tasks).
|
||||
- Смуги на рівні сесії гарантують, що лише один запуск агента одночасно працює з певною сесією.
|
||||
- Жодних зовнішніх залежностей або фонових worker-потоків; лише TypeScript + promises.
|
||||
- Застосовується до запусків агентів автовідповідей у всіх вхідних каналах, які використовують пайплайн відповідей Gateway (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat тощо).
|
||||
- Типова lane (`main`) є процесною для вхідних повідомлень і main Heartbeat; задайте `agents.defaults.maxConcurrent`, щоб дозволити кілька сесій паралельно.
|
||||
- Можуть існувати додаткові lane (наприклад, `cron`, `cron-nested`, `nested`, `subagent`), щоб фонові завдання могли виконуватися паралельно, не блокуючи вхідні відповіді. Ізольовані ходи агента cron утримують слот `cron`, поки їхнє внутрішнє виконання агента використовує `cron-nested`; обидва використовують `cron.maxConcurrentRuns`. Спільні не-cron потоки `nested` зберігають власну поведінку lane. Ці відокремлені запуски відстежуються як [фонові завдання](/uk/automation/tasks).
|
||||
- Lane для сесій гарантують, що лише один запуск агента одночасно працює з певною сесією.
|
||||
- Без зовнішніх залежностей або фонових робочих потоків; чистий TypeScript + promises.
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
- Якщо здається, що команди зависли, увімкніть докладні журнали та шукайте рядки “queued for …ms”, щоб підтвердити, що черга обробляється.
|
||||
- Якщо вам потрібна глибина черги, увімкніть докладні журнали та відстежуйте рядки з таймінгами черги.
|
||||
- Якщо команди здаються завислими, увімкніть докладні журнали й шукайте рядки “queued for …ms”, щоб підтвердити, що черга обробляється.
|
||||
- Якщо вам потрібна глибина черги, увімкніть докладні журнали й стежте за рядками часу черги.
|
||||
- Коли діагностику ввімкнено, сесії, що залишаються в `processing` довше за `diagnostics.stuckSessionWarnMs`, записують попередження про завислу сесію. Активні вбудовані запуски, активні операції відповіді та активні завдання lane типово залишаються лише попередженнями; застарілий стартовий облік без активної роботи сесії може звільнити відповідну lane сесії, щоб робота в черзі продовжилася.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
|
||||
@ -1,36 +1,35 @@
|
||||
---
|
||||
read_when:
|
||||
- Впровадження або оновлення WS-клієнтів Gateway
|
||||
- Реалізація або оновлення WS-клієнтів Gateway
|
||||
- Налагодження невідповідностей протоколу або збоїв підключення
|
||||
- Повторне генерування схеми/моделей протоколу
|
||||
summary: 'Протокол WebSocket для Gateway: рукостискання, фрейми, версіонування'
|
||||
summary: 'WebSocket-протокол Gateway: рукостискання, кадри, версіонування'
|
||||
title: Протокол Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T11:13:37Z"
|
||||
generated_at: "2026-04-28T20:11:25Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: ab961f1ec245e93f5f88a641f558124c36c4c828ba66ff3a2ccd41ba1f12b646
|
||||
source_hash: 95845fc2aa56b0a53cf8c62c517b70d2624b15e707d84503c791af572360aff2
|
||||
source_path: gateway/protocol.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Протокол Gateway WS є **єдиною площиною керування + транспортом вузлів** для
|
||||
OpenClaw. Усі клієнти (CLI, вебінтерфейс, застосунок macOS, вузли iOS/Android,
|
||||
безголові вузли) підключаються через WebSocket і оголошують свою **роль** +
|
||||
**область дії** під час рукостискання.
|
||||
OpenClaw. Усі клієнти (CLI, вебінтерфейс, застосунок macOS, вузли iOS/Android, безголові
|
||||
вузли) підключаються через WebSocket і оголошують свою **роль** + **область дії** під час
|
||||
рукостискання.
|
||||
|
||||
## Транспорт
|
||||
|
||||
- WebSocket, текстові кадри з JSON-навантаженнями.
|
||||
- Перший кадр **має** бути запитом `connect`.
|
||||
- Кадри до підключення обмежені 64 КіБ. Після успішного рукостискання клієнтам
|
||||
слід дотримуватися обмежень `hello-ok.policy.maxPayload` і
|
||||
- Кадри до підключення обмежені 64 KiB. Після успішного рукостискання клієнти
|
||||
мають дотримуватися лімітів `hello-ok.policy.maxPayload` і
|
||||
`hello-ok.policy.maxBufferedBytes`. Коли діагностику ввімкнено,
|
||||
надмірно великі вхідні кадри та повільні вихідні буфери генерують події
|
||||
`payload.large` перед тим, як Gateway закриє або відкине відповідний кадр.
|
||||
Ці події зберігають розміри, обмеження, поверхні та безпечні коди причин.
|
||||
Вони не зберігають тіло повідомлення, вміст вкладень, необроблене тіло кадру,
|
||||
токени, cookie або секретні значення.
|
||||
завеликі вхідні кадри та повільні вихідні буфери створюють події `payload.large`
|
||||
до того, як Gateway закриє або відкине відповідний кадр. Ці події зберігають
|
||||
розміри, ліміти, поверхні та безпечні коди причин. Вони не зберігають тіло
|
||||
повідомлення, вміст вкладень, сире тіло кадру, токени, cookies або секретні значення.
|
||||
|
||||
## Рукостискання (connect)
|
||||
|
||||
@ -105,8 +104,8 @@ Gateway → Клієнт:
|
||||
}
|
||||
```
|
||||
|
||||
`server`, `features`, `snapshot` і `policy` є обов’язковими за схемою
|
||||
(`src/gateway/protocol/schema/frames.ts`). `auth` також є обов’язковим і повідомляє
|
||||
`server`, `features`, `snapshot` і `policy` усі є обов’язковими за схемою
|
||||
(`src/gateway/protocol/schema/frames.ts`). `auth` також обов’язковий і повідомляє
|
||||
узгоджену роль/області дії. `canvasHostUrl` є необов’язковим.
|
||||
|
||||
Коли токен пристрою не видано, `hello-ok.auth` повідомляє узгоджені
|
||||
@ -121,14 +120,13 @@ Gateway → Клієнт:
|
||||
}
|
||||
```
|
||||
|
||||
Довірені клієнти бекенду в тому самому процесі (`client.id: "gateway-client"`,
|
||||
`client.mode: "backend"`) можуть опускати `device` для прямих loopback-підключень,
|
||||
коли автентифікуються спільним токеном/паролем Gateway. Цей шлях зарезервовано
|
||||
для внутрішніх RPC площини керування, і він запобігає тому, щоб застарілі базові
|
||||
дані сполучення CLI/пристрою блокували локальну роботу бекенду, як-от оновлення
|
||||
сеансів субагентів. Віддалені клієнти, клієнти з браузерним origin, клієнти-вузли
|
||||
та явні клієнти з токеном пристрою/ідентичністю пристрою все ще використовують
|
||||
звичайні перевірки сполучення й підвищення областей дії.
|
||||
Довірені клієнти бекенда в тому самому процесі (`client.id: "gateway-client"`,
|
||||
`client.mode: "backend"`) можуть не вказувати `device` на прямих підключеннях local loopback, коли
|
||||
вони автентифікуються спільним токеном/паролем Gateway. Цей шлях зарезервований
|
||||
для внутрішніх RPC площини керування і не дає застарілим базовим станам спарювання CLI/пристрою
|
||||
блокувати локальну роботу бекенда, як-от оновлення сесій субагентів. Віддалені клієнти,
|
||||
клієнти з браузерним походженням, вузлові клієнти та явні клієнти токена пристрою/ідентичності пристрою
|
||||
й надалі використовують звичайні перевірки спарювання та підвищення області дії.
|
||||
|
||||
Коли токен пристрою видано, `hello-ok` також містить:
|
||||
|
||||
@ -163,12 +161,11 @@ Gateway → Клієнт:
|
||||
```
|
||||
|
||||
Для вбудованого потоку bootstrap вузла/оператора основний токен вузла залишається
|
||||
`scopes: []`, а будь-який переданий токен оператора залишається обмеженим списком
|
||||
дозволів оператора bootstrap (`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). Перевірки областей дії bootstrap
|
||||
залишаються префіксованими роллю: записи оператора задовольняють лише запити
|
||||
оператора, а неоператорським ролям і далі потрібні області дії з власним
|
||||
префіксом ролі.
|
||||
`scopes: []`, а будь-який переданий токен оператора залишається обмеженим allowlist оператора
|
||||
bootstrap (`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). Перевірки області дії bootstrap залишаються
|
||||
префіксованими за роллю: записи оператора задовольняють лише запити оператора, а ролі, що не є операторами,
|
||||
й надалі потребують областей дії під власним префіксом ролі.
|
||||
|
||||
### Приклад вузла
|
||||
|
||||
@ -205,7 +202,7 @@ Gateway → Клієнт:
|
||||
}
|
||||
```
|
||||
|
||||
## Фреймінг
|
||||
## Обрамлення
|
||||
|
||||
- **Запит**: `{type:"req", id, method, params}`
|
||||
- **Відповідь**: `{type:"res", id, ok, payload|error}`
|
||||
@ -220,7 +217,7 @@ Gateway → Клієнт:
|
||||
- `operator` = клієнт площини керування (CLI/UI/автоматизація).
|
||||
- `node` = хост можливостей (camera/screen/canvas/system.run).
|
||||
|
||||
### Області дії (operator)
|
||||
### Області дії (оператор)
|
||||
|
||||
Поширені області дії:
|
||||
|
||||
@ -234,46 +231,45 @@ Gateway → Клієнт:
|
||||
`talk.config` з `includeSecrets: true` потребує `operator.talk.secrets`
|
||||
(або `operator.admin`).
|
||||
|
||||
Зареєстровані Plugin методи Gateway RPC можуть запитувати власну область дії
|
||||
оператора, але зарезервовані префікси адміністрування ядра (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) завжди розв’язуються до
|
||||
`operator.admin`.
|
||||
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`:
|
||||
`operator.pairing` + `operator.admin`
|
||||
|
||||
### Можливості/команди/дозволи (node)
|
||||
### Можливості/команди/дозволи (вузол)
|
||||
|
||||
Вузли оголошують претензії на можливості під час підключення:
|
||||
|
||||
- `caps`: високорівневі категорії можливостей.
|
||||
- `commands`: список дозволених команд для invoke.
|
||||
- `permissions`: деталізовані перемикачі (наприклад, `screen.record`, `camera.capture`).
|
||||
- `caps`: категорії можливостей високого рівня.
|
||||
- `commands`: allowlist команд для виклику.
|
||||
- `permissions`: детальні перемикачі (наприклад, `screen.record`, `camera.capture`).
|
||||
|
||||
Gateway трактує їх як **претензії** та застосовує серверні списки дозволів.
|
||||
Gateway розглядає їх як **претензії** і застосовує серверні 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
|
||||
{
|
||||
@ -283,9 +279,9 @@ Gateway трактує їх як **претензії** та застосову
|
||||
```
|
||||
|
||||
`trigger` є закритим enum: `background`, `silent_push`, `bg_app_refresh`,
|
||||
`significant_location`, `manual` або `connect`. Невідомі рядки тригерів Gateway нормалізує до
|
||||
`background` перед збереженням. Подія є тривкою лише для автентифікованих сеансів пристроїв-вузлів;
|
||||
сеанси без пристрою або без сполучення повертають `handled: false`.
|
||||
`significant_location`, `manual` або `connect`. Невідомі рядки trigger нормалізуються до
|
||||
`background` Gateway перед збереженням. Подія є стійкою лише для автентифікованих сесій
|
||||
пристроїв вузлів; сесії без пристрою або без спарювання повертають `handled: false`.
|
||||
|
||||
Успішні Gateway повертають структурований результат:
|
||||
|
||||
@ -298,71 +294,71 @@ Gateway трактує їх як **претензії** та застосову
|
||||
}
|
||||
```
|
||||
|
||||
Старіші Gateway можуть усе ще повертати `{ "ok": true }` для `node.event`; клієнтам слід трактувати це як
|
||||
підтверджений RPC, а не як тривке збереження присутності.
|
||||
Старіші Gateway можуть усе ще повертати `{ "ok": true }` для `node.event`; клієнти мають трактувати це як
|
||||
підтверджений RPC, а не як стійке збереження присутності.
|
||||
|
||||
## Обмеження областей дії широкомовних подій
|
||||
## Обмеження області дії широкомовних подій
|
||||
|
||||
Широкомовні WebSocket-події, які сервер надсилає клієнтам, обмежуються областями дії, щоб сеанси з областю дії сполучення або лише вузлові сеанси пасивно не отримували вміст сеансів.
|
||||
Серверні широкомовні події WebSocket обмежуються областями дії, щоб сесії, обмежені спарюванням або лише вузлами, пасивно не отримували вміст сесій.
|
||||
|
||||
- **Кадри чату, агента та результатів інструментів** (включно зі стримованими подіями `agent` і результатами викликів інструментів) потребують щонайменше `operator.read`. Сеанси без `operator.read` повністю пропускають ці кадри.
|
||||
- **Визначені Plugin широкомовлення `plugin.*`** обмежуються `operator.write` або `operator.admin`, залежно від того, як Plugin їх зареєстрував.
|
||||
- **Події стану й транспорту** (`heartbeat`, `presence`, `tick`, життєвий цикл підключення/відключення тощо) залишаються необмеженими, щоб стан транспорту був видимим для кожного автентифікованого сеансу.
|
||||
- **Невідомі сімейства широкомовних подій** за замовчуванням обмежуються областями дії (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/каналів. Трактуйте його як виявлення функцій, а не як повний
|
||||
не згенерований дамп — `hello-ok.features.methods` є консервативним
|
||||
списком виявлення, побудованим із `src/gateway/server-methods-list.ts` плюс завантажені
|
||||
експорти методів plugin/channel. Сприймайте його як виявлення можливостей, а не повний
|
||||
перелік `src/gateway/server-methods/*.ts`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Система та ідентичність">
|
||||
- `health` повертає кешований або щойно перевірений знімок стану Gateway.
|
||||
- `diagnostics.stability` повертає нещодавній обмежений реєстратор діагностичної стабільності. Він зберігає операційні метадані, як-от назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сеансу, назви каналів/Plugin і ідентифікатори сеансів. Він не зберігає текст чату, тіла webhook, виводи інструментів, необроблені тіла запитів або відповідей, токени, cookie чи секретні значення. Потрібна область дії читання оператора.
|
||||
- `status` повертає зведення Gateway у стилі `/status`; чутливі поля включаються лише для клієнтів-операторів з областю дії admin.
|
||||
- `gateway.identity.get` повертає ідентичність пристрою Gateway, що використовується потоками relay і сполучення.
|
||||
- `system-presence` повертає поточний знімок присутності для підключених пристроїв оператора/вузла.
|
||||
- `system-event` додає системну подію та може оновлювати/широкомовно передавати контекст присутності.
|
||||
- `last-heartbeat` повертає останню збережену подію heartbeat.
|
||||
- `set-heartbeats` перемикає обробку heartbeat на Gateway.
|
||||
- `diagnostics.stability` повертає нещодавній обмежений реєстратор діагностичної стабільності. Він зберігає операційні метадані, як-от назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сесії, назви каналів/plugin і ідентифікатори сесій. Він не зберігає текст чату, тіла webhook, виводи інструментів, сирі тіла запитів або відповідей, токени, cookies або секретні значення. Потрібна область дії читання оператора.
|
||||
- `status` повертає зведення Gateway у стилі `/status`; чутливі поля включаються лише для клієнтів-операторів з адміністративною областю дії.
|
||||
- `gateway.identity.get` повертає ідентичність пристрою Gateway, яку використовують потоки relay і спарювання.
|
||||
- `system-presence` повертає поточний знімок присутності для підключених пристроїв operator/node.
|
||||
- `system-event` додає системну подію і може оновлювати/транслювати контекст присутності.
|
||||
- `last-heartbeat` повертає останню збережену подію Heartbeat.
|
||||
- `set-heartbeats` перемикає обробку Heartbeat на Gateway.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Моделі та використання">
|
||||
- `models.list` повертає дозволений під час виконання каталог моделей. Передайте `{ "view": "configured" }` для налаштованих моделей розміру picker (`agents.defaults.models` спочатку, потім `models.providers.*.models`) або `{ "view": "all" }` для повного каталогу.
|
||||
- `usage.status` повертає зведення вікон використання провайдера/залишкової квоти.
|
||||
- `models.list` повертає каталог моделей, дозволених у runtime. Передайте `{ "view": "configured" }` для налаштованих моделей розміру picker (`agents.defaults.models` спочатку, потім `models.providers.*.models`), або `{ "view": "all" }` для повного каталогу.
|
||||
- `usage.status` повертає вікна використання провайдера/зведення залишкової квоти.
|
||||
- `usage.cost` повертає агреговані зведення вартості використання за діапазон дат.
|
||||
- `doctor.memory.status` повертає готовність векторної пам’яті / кешованих embedding для активного стандартного робочого простору агента. Передавайте `{ "probe": true }` або `{ "deep": true }` лише коли викликач явно хоче live ping провайдера embedding.
|
||||
- `sessions.usage` повертає зведення використання за сеансами.
|
||||
- `sessions.usage.timeseries` повертає часовий ряд використання для одного сеансу.
|
||||
- `sessions.usage.logs` повертає записи журналу використання для одного сеансу.
|
||||
- `doctor.memory.status` повертає готовність векторної пам’яті / кешованих embedding для активного робочого простору агента за замовчуванням. Передавайте `{ "probe": true }` або `{ "deep": true }` лише коли викликач явно хоче живий ping embedding-провайдера.
|
||||
- `sessions.usage` повертає зведення використання за сесіями.
|
||||
- `sessions.usage.timeseries` повертає часовий ряд використання для однієї сесії.
|
||||
- `sessions.usage.logs` повертає записи журналу використання для однієї сесії.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Канали та помічники входу">
|
||||
- `channels.status` повертає зведення стану вбудованих + комплектних каналів/Plugin.
|
||||
- `channels.logout` виходить із певного каналу/облікового запису, якщо канал підтримує вихід.
|
||||
- `web.login.start` запускає QR/web-потік входу для поточного web-провайдера каналу з підтримкою QR.
|
||||
- `web.login.wait` очікує завершення цього QR/web-потоку входу та в разі успіху запускає канал.
|
||||
- `push.test` надсилає тестовий APNs push на зареєстрований вузол iOS.
|
||||
- `channels.status` повертає зведення стану вбудованих + bundled каналів/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 і транслює зміну.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Повідомлення та журнали">
|
||||
- `send` є прямим outbound-delivery RPC для надсилань, націлених на канал/обліковий запис/тред, поза chat runner.
|
||||
- `logs.tail` повертає налаштований фрагмент файлу журналу Gateway з керуванням cursor/limit і max-byte.
|
||||
- `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`).
|
||||
<Accordion title="Розмова та TTS">
|
||||
- `talk.config` повертає ефективне навантаження конфігурації Talk; `includeSecrets` потребує `operator.talk.secrets` (або `operator.admin`).
|
||||
- `talk.mode` встановлює/транслює поточний стан режиму Talk для клієнтів WebChat/Control UI.
|
||||
- `talk.speak` синтезує мовлення через активного провайдера мовлення Talk.
|
||||
- `tts.status` повертає стан увімкнення TTS, активного провайдера, резервних провайдерів і стан конфігурації провайдера.
|
||||
@ -374,78 +370,78 @@ Gateway трактує їх як **претензії** та застосову
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Секрети, конфігурація, оновлення та майстер">
|
||||
- `secrets.reload` повторно розв'язує активні SecretRefs і замінює runtime-стан секретів лише за повного успіху.
|
||||
- `secrets.resolve` розв'язує призначення секретів для цільових команд для певного набору команд/цілей.
|
||||
- `config.get` повертає поточний знімок конфігурації та hash.
|
||||
- `config.set` записує перевірене корисне навантаження конфігурації.
|
||||
- `config.patch` зливає часткове оновлення конфігурації.
|
||||
- `config.apply` перевіряє + замінює повне корисне навантаження конфігурації.
|
||||
- `config.schema` повертає живе корисне навантаження схеми конфігурації, яке використовують інструменти Control UI та CLI: schema, `uiHints`, version і метадані generation, включно з метаданими схеми plugin + каналу, коли runtime може їх завантажити. Схема містить метадані полів `title` / `description`, отримані з тих самих міток і довідкового тексту, які використовує UI, включно з вкладеними object, wildcard, array-item і гілками композиції `anyOf` / `oneOf` / `allOf`, коли існує відповідна документація полів.
|
||||
- `config.schema.lookup` повертає корисне навантаження пошуку, обмежене шляхом, для одного шляху конфігурації: нормалізований path, неглибокий вузол schema, matched hint + `hintPath` і зведення безпосередніх дочірніх елементів для деталізації в UI/CLI. Вузли схеми пошуку зберігають користувацьку документацію та поширені поля перевірки (`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, numeric/string/array/object bounds і прапорці на кшталт `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`). Зведення дочірніх елементів надають `key`, нормалізований `path`, `type`, `required`, `hasChildren`, а також matched `hint` / `hintPath`.
|
||||
- `update.run` запускає потік оновлення Gateway і планує перезапуск лише тоді, коли саме оновлення завершилося успішно.
|
||||
- `update.status` повертає останній кешований sentinel перезапуску оновлення, включно з версією, що працює після перезапуску, коли вона доступна.
|
||||
- `wizard.start`, `wizard.next`, `wizard.status` і `wizard.cancel` відкривають майстер onboarding через WS RPC.
|
||||
- `secrets.reload` повторно розв’язує активні SecretRefs і замінює стан секретів runtime лише в разі повного успіху.
|
||||
- `secrets.resolve` розв’язує призначення секретів, націлені на команду, для певного набору command/target.
|
||||
- `config.get` повертає поточний знімок конфігурації та хеш.
|
||||
- `config.set` записує перевірене навантаження конфігурації.
|
||||
- `config.patch` об’єднує часткове оновлення конфігурації.
|
||||
- `config.apply` перевіряє + замінює повне навантаження конфігурації.
|
||||
- `config.schema` повертає живе навантаження схеми конфігурації, яке використовують Control UI та інструменти CLI: schema, `uiHints`, version і метадані генерації, зокрема метадані схем Plugin + каналів, коли runtime може їх завантажити. Схема містить метадані полів `title` / `description`, виведені з тих самих міток і довідкового тексту, які використовує UI, зокрема для вкладених об’єктів, 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 wizard через WS RPC.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Помічники агента та робочої області">
|
||||
- `agents.list` повертає налаштовані записи агентів.
|
||||
- `agents.create`, `agents.update` і `agents.delete` керують записами агентів і прив'язкою робочої області.
|
||||
- `agents.files.list`, `agents.files.get` і `agents.files.set` керують файлами bootstrap робочої області, відкритими для агента.
|
||||
- `agent.identity.get` повертає ефективну ідентичність асистента для агента або сеансу.
|
||||
- `agent.wait` очікує завершення запуску та повертає кінцевий знімок, коли він доступний.
|
||||
- `agents.create`, `agents.update` і `agents.delete` керують записами агентів і прив’язкою робочої області.
|
||||
- `agents.files.list`, `agents.files.get` і `agents.files.set` керують bootstrap-файлами робочої області, доступними для агента.
|
||||
- `agent.identity.get` повертає ефективну ідентичність асистента для агента або сесії.
|
||||
- `agent.wait` очікує завершення запуску та повертає фінальний знімок, коли він доступний.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<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 для активного сеансу.
|
||||
- `sessions.abort` перериває активну роботу для сеансу.
|
||||
- `sessions.patch` оновлює метадані/перевизначення сеансу.
|
||||
- `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-корисні навантаження tool-call (включно з `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізаними блоками tool-call) та витеклі ASCII/full-width токени керування моделі вилучаються, рядки асистента лише з silent-token, як-от точні `NO_REPLY` / `no_reply`, пропускаються, а надмірно великі рядки можуть замінюватися placeholders.
|
||||
<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 для активної сесії.
|
||||
- `sessions.abort` перериває активну роботу для сесії.
|
||||
- `sessions.patch` оновлює метадані/перевизначення сесії.
|
||||
- `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-навантаження викликів інструментів (зокрема `<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`, пропускаються, а надмірно великі рядки можуть замінюватися placeholders.
|
||||
|
||||
</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.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.invoke` пересилає команду підключеному вузлу.
|
||||
- `node.rename` оновлює мітку сполученого вузла.
|
||||
- `node.invoke` пересилає команду до підключеного вузла.
|
||||
- `node.invoke.result` повертає результат для запиту invoke.
|
||||
- `node.event` переносить події, що походять від вузла, назад у Gateway.
|
||||
- `node.event` переносить події, що походять від вузла, назад у gateway.
|
||||
- `node.canvas.capability.refresh` оновлює токени scoped canvas-capability.
|
||||
- `node.pending.pull` і `node.pending.ack` є API черги підключеного вузла.
|
||||
- `node.pending.enqueue` і `node.pending.drain` керують довговічною очікуваною роботою для offline/disconnected вузлів.
|
||||
- `node.pending.pull` і `node.pending.ack` — це API черги підключеного вузла.
|
||||
- `node.pending.enqueue` і `node.pending.drain` керують надійною відкладеною роботою для offline/disconnected вузлів.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Сімейства схвалень">
|
||||
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` і `exec.approval.resolve` охоплюють одноразові запити схвалення exec, а також пошук/повтор очікуваних схвалень.
|
||||
- `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.get` і `exec.approvals.set` керують знімками політики схвалень exec для gateway.
|
||||
- `exec.approvals.node.get` і `exec.approvals.node.set` керують node-local політикою схвалень exec через relay-команди вузла.
|
||||
- `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` і `plugin.approval.resolve` охоплюють визначені plugin потоки схвалення.
|
||||
- `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` і `plugin.approval.resolve` охоплюють потоки схвалень, визначені Plugin.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Автоматизація, Skills та інструменти">
|
||||
- Автоматизація: `wake` планує негайну або next-heartbeat ін'єкцію wake-тексту; `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` керують запланованою роботою.
|
||||
- Автоматизація: `wake` планує негайну або next-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>
|
||||
@ -453,98 +449,84 @@ Gateway трактує їх як **претензії** та застосову
|
||||
|
||||
### Поширені сімейства подій
|
||||
|
||||
- `chat`: оновлення чату UI, як-от `chat.inject` та інші події чату лише для транскрипту.
|
||||
- `session.message` і `session.tool`: оновлення транскрипту/event-stream для підписаного сеансу.
|
||||
- `sessions.changed`: індекс сеансів або метадані змінилися.
|
||||
- `chat`: оновлення UI-чату, як-от `chat.inject`, та інші chat-події лише для транскрипту.
|
||||
- `session.message` і `session.tool`: оновлення транскрипту/потоку подій для підписаної сесії.
|
||||
- `sessions.changed`: індекс сесій або метадані змінилися.
|
||||
- `presence`: оновлення знімка присутності системи.
|
||||
- `tick`: періодична keepalive / liveness подія.
|
||||
- `health`: оновлення знімка стану Gateway.
|
||||
- `heartbeat`: оновлення потоку подій Heartbeat.
|
||||
- `cron`: подія зміни запуску/job Cron.
|
||||
- `shutdown`: сповіщення про вимкнення Gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved`: життєвий цикл спарювання вузла.
|
||||
- `tick`: періодична подія keepalive / liveness.
|
||||
- `health`: оновлення знімка стану gateway.
|
||||
- `heartbeat`: оновлення потоку подій heartbeat.
|
||||
- `cron`: подія зміни запуску/завдання cron.
|
||||
- `shutdown`: сповіщення про вимкнення gateway.
|
||||
- `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.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved`: життєвий цикл схвалення Plugin.
|
||||
|
||||
### Допоміжні методи вузлів
|
||||
### Допоміжні методи Node
|
||||
|
||||
- Вузли можуть викликати `skills.bins`, щоб отримати поточний список виконуваних файлів skill
|
||||
для перевірок auto-allow.
|
||||
- Вузли можуть викликати `skills.bins`, щоб отримати поточний список виконуваних файлів Skills для перевірок auto-allow.
|
||||
|
||||
### Допоміжні методи операторів
|
||||
### Допоміжні методи оператора
|
||||
|
||||
- Оператори можуть викликати `commands.list` (`operator.read`), щоб отримати runtime
|
||||
інвентар команд для агента.
|
||||
- `agentId` є необов'язковим; опустіть його, щоб читати робочу область агента за замовчуванням.
|
||||
- `scope` керує тим, на яку поверхню націлюється основний `name`:
|
||||
- `text` повертає основний токен текстової команди без початкового `/`
|
||||
- `native` і шлях за замовчуванням `both` повертають provider-aware native назви
|
||||
коли доступні
|
||||
- Оператори можуть викликати `commands.list` (`operator.read`), щоб отримати інвентар runtime-команд для агента.
|
||||
- `agentId` необов’язковий; пропустіть його, щоб прочитати робочу область агента за замовчуванням.
|
||||
- `scope` керує тим, на яку поверхню націлюється основне `name`:
|
||||
- `text` повертає основний текстовий токен команди без початкового `/`
|
||||
- `native` і типовий шлях `both` повертають provider-aware native names, коли вони доступні
|
||||
- `textAliases` містить точні slash aliases, як-от `/model` і `/m`.
|
||||
- `nativeName` містить provider-aware native назву команди, коли така існує.
|
||||
- `provider` є необов'язковим і впливає лише на native naming та доступність native plugin
|
||||
команд.
|
||||
- `includeArgs=false` опускає серіалізовані метадані аргументів із відповіді.
|
||||
- Оператори можуть викликати `tools.catalog` (`operator.read`), щоб отримати runtime catalog інструментів для
|
||||
агента. Відповідь містить згруповані інструменти та метадані походження:
|
||||
- `nativeName` містить provider-aware native command name, коли він існує.
|
||||
- `provider` необов’язковий і впливає лише на native naming плюс доступність native Plugin-команд.
|
||||
- `includeArgs=false` пропускає серіалізовані метадані аргументів у відповіді.
|
||||
- Оператори можуть викликати `tools.catalog` (`operator.read`), щоб отримати runtime-каталог інструментів для агента. Відповідь містить згруповані інструменти та метадані походження:
|
||||
- `source`: `core` або `plugin`
|
||||
- `pluginId`: власник plugin, коли `source="plugin"`
|
||||
- `optional`: чи є інструмент plugin необов'язковим
|
||||
- Оператори можуть викликати `tools.effective` (`operator.read`), щоб отримати runtime-effective
|
||||
інвентар інструментів для сеансу.
|
||||
- `sessionKey` є обов'язковим.
|
||||
- Gateway виводить довірений runtime-контекст із сеансу на боці сервера замість приймати
|
||||
auth або delivery context, надані викликачем.
|
||||
- Відповідь обмежена сеансом і відображає те, що активна розмова може використовувати зараз,
|
||||
включно з core, plugin і channel tools.
|
||||
- Оператори можуть викликати `skills.status` (`operator.read`), щоб отримати видимий
|
||||
інвентар skill для агента.
|
||||
- `agentId` є необов'язковим; опустіть його, щоб читати робочу область агента за замовчуванням.
|
||||
- Відповідь містить eligibility, відсутні вимоги, перевірки конфігурації та
|
||||
sanitized install options без розкриття raw secret values.
|
||||
- Оператори можуть викликати `skills.search` і `skills.detail` (`operator.read`) для
|
||||
метаданих discovery ClawHub.
|
||||
- `pluginId`: власник Plugin, коли `source="plugin"`
|
||||
- `optional`: чи є інструмент Plugin необов’язковим
|
||||
- Оператори можуть викликати `tools.effective` (`operator.read`), щоб отримати runtime-effective інвентар інструментів для сесії.
|
||||
- `sessionKey` обов’язковий.
|
||||
- Gateway виводить довірений runtime-контекст із сесії на серверному боці, замість приймати auth або delivery context, наданий викликачем.
|
||||
- Відповідь обмежена сесією та відображає те, що активна розмова може використовувати просто зараз, зокрема інструменти ядра, Plugin і каналів.
|
||||
- Оператори можуть викликати `skills.status` (`operator.read`), щоб отримати видимий інвентар Skills для агента.
|
||||
- `agentId` необов’язковий; пропустіть його, щоб прочитати робочу область агента за замовчуванням.
|
||||
- Відповідь містить придатність, відсутні вимоги, перевірки конфігурації та санітизовані варіанти встановлення без розкриття raw secret values.
|
||||
- Оператори можуть викликати `skills.search` і `skills.detail` (`operator.read`) для метаданих виявлення 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 host.
|
||||
- Оператори можуть викликати `skills.update` (`operator.admin`) у двох режимах:
|
||||
- Режим ClawHub оновлює один відстежуваний slug або всі відстежувані встановлення ClawHub у
|
||||
робочій області агента за замовчуванням.
|
||||
- Режим конфігурації виправляє значення `skills.entries.<skillKey>`, як-от `enabled`,
|
||||
`apiKey` і `env`.
|
||||
- Режим ClawHub оновлює один tracked slug або всі tracked ClawHub installs у робочій області агента за замовчуванням.
|
||||
- Режим конфігурації патчить значення `skills.entries.<skillKey>`, як-от `enabled`, `apiKey` і `env`.
|
||||
|
||||
### Представлення `models.list`
|
||||
|
||||
`models.list` приймає необов'язковий параметр `view`:
|
||||
`models.list` приймає необов’язковий параметр `view`:
|
||||
|
||||
- Не вказано або `"default"`: поточна поведінка runtime. Якщо налаштовано `agents.defaults.models`, відповіддю є дозволений каталог; інакше відповіддю є повний каталог Gateway.
|
||||
- `"configured"`: поведінка розміру picker. Якщо налаштовано `agents.defaults.models`, він усе одно має пріоритет. Інакше відповідь використовує явні записи `models.providers.*.models`, повертаючись до повного каталогу лише тоді, коли немає налаштованих рядків моделей.
|
||||
- `"all"`: повний каталог Gateway, в обхід `agents.defaults.models`. Використовуйте це для діагностики та інтерфейсів виявлення, а не для звичайних picker моделей.
|
||||
- Пропущено або `"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` (потрібен scope `operator.approvals`).
|
||||
- Для `host=node` `exec.approval.request` має містити `systemRunPlan` (канонічні `argv`/`cwd`/`rawCommand`/метадані сесії). Запити без `systemRunPlan` відхиляються.
|
||||
- Після затвердження переадресовані виклики `node.invoke system.run` повторно використовують цей канонічний
|
||||
`systemRunPlan` як авторитетний контекст команди/cwd/сесії.
|
||||
- Коли запит 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
|
||||
відхиляє запуск замість того, щоб довіряти зміненому корисному навантаженню.
|
||||
|
||||
## Fallback доставки агента
|
||||
## Резервний варіант доставлення агентом
|
||||
|
||||
- Запити `agent` можуть містити `deliver=true`, щоб запросити вихідну доставку.
|
||||
- `bestEffortDeliver=false` зберігає сувору поведінку: нерозв'язані або лише внутрішні цілі доставки повертають `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` дозволяє fallback до виконання лише в сесії, коли не вдається розв'язати жодний зовнішній маршрут доставки (наприклад, внутрішні/webchat-сесії або неоднозначні багатоканальні конфігурації).
|
||||
- Запити `agent` можуть містити `deliver=true`, щоб запросити вихідне доставлення.
|
||||
- `bestEffortDeliver=false` зберігає сувору поведінку: нерозв’язані або лише внутрішні цілі доставлення повертають `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` дозволяє резервний перехід до виконання лише в межах сеансу, коли неможливо визначити зовнішній маршрут доставлення (наприклад, внутрішні/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`
|
||||
@ -553,145 +535,145 @@ Gateway трактує їх як **претензії** та застосову
|
||||
|
||||
### Константи клієнта
|
||||
|
||||
Еталонний клієнт у `src/gateway/client.ts` використовує ці значення за замовчуванням. Значення є
|
||||
стабільними в межах protocol v3 і є очікуваною базовою лінією для сторонніх клієнтів.
|
||||
Еталонний клієнт у `src/gateway/client.ts` використовує ці типові значення. Значення
|
||||
стабільні в межах protocol v3 і є очікуваною базовою лінією для сторонніх клієнтів.
|
||||
|
||||
| Константа | За замовчуванням | Джерело |
|
||||
| Константа | Типово | Джерело |
|
||||
| ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- |
|
||||
| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
|
||||
| Тайм-аут запиту (на RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |
|
||||
| Тайм-аут preauth / connect-challenge | `10_000` ms | `src/gateway/handshake-timeouts.ts` (clamp `250`–`10_000`) |
|
||||
| Початковий backoff повторного підключення | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
|
||||
| Максимальний backoff повторного підключення | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
|
||||
| Clamp швидкого повтору після закриття device-token | `250` ms | `src/gateway/client.ts` |
|
||||
| Grace force-stop перед `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
|
||||
| Тайм-аут 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 | 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.maxBufferedBytes` у `hello-ok`; клієнти мають дотримуватися цих значень,
|
||||
а не типових значень до рукостискання.
|
||||
|
||||
## Автентифікація
|
||||
|
||||
- Автентифікація gateway зі спільним секретом використовує `connect.params.auth.token` або
|
||||
- Автентифікація Gateway зі спільним секретом використовує `connect.params.auth.token` або
|
||||
`connect.params.auth.password`, залежно від налаштованого режиму автентифікації.
|
||||
- Режими з ідентичністю, такі як Tailscale Serve
|
||||
- Режими, що несуть ідентичність, як-от Tailscale Serve
|
||||
(`gateway.auth.allowTailscale: true`) або не-loopback
|
||||
`gateway.auth.mode: "trusted-proxy"`, задовольняють перевірку автентифікації connect з
|
||||
`gateway.auth.mode: "trusted-proxy"` задовольняють перевірку автентифікації підключення з
|
||||
заголовків запиту замість `connect.params.auth.*`.
|
||||
- Private-ingress `gateway.auth.mode: "none"` повністю пропускає автентифікацію connect зі спільним секретом;
|
||||
не відкривайте цей режим у публічному/недовіреному ingress.
|
||||
- Після pairing Gateway видає **device token** із прив'язкою до ролі підключення
|
||||
+ scopes. Він повертається в `hello-ok.auth.deviceToken`, і клієнт має
|
||||
зберігати його для майбутніх підключень.
|
||||
- Private-ingress `gateway.auth.mode: "none"` повністю пропускає автентифікацію підключення зі спільним секретом;
|
||||
не відкривайте цей режим для публічного/ненадійного ingress.
|
||||
- Після сполучення Gateway видає **токен пристрою**, обмежений роллю +
|
||||
областями підключення. Він повертається в `hello-ok.auth.deviceToken` і має
|
||||
зберігатися клієнтом для майбутніх підключень.
|
||||
- Клієнти мають зберігати основний `hello-ok.auth.deviceToken` після будь-якого
|
||||
успішного підключення.
|
||||
- Повторне підключення з цим **збереженим** device token також має повторно використовувати збережений
|
||||
затверджений набір scopes для цього token. Це зберігає вже наданий доступ
|
||||
read/probe/status і уникає тихого звуження повторних підключень до
|
||||
вужчого неявного scope лише адміністратора.
|
||||
- Складання автентифікації connect на боці клієнта (`selectConnectAuth` у
|
||||
- Повторне підключення з цим **збереженим** токеном пристрою також має повторно використовувати збережений
|
||||
затверджений набір областей для цього токена. Це зберігає доступ для читання/перевірки/статусу,
|
||||
який уже було надано, і запобігає непомітному звуженню повторних підключень до
|
||||
вужчої неявної області лише адміністратора.
|
||||
- Збирання автентифікації підключення на боці клієнта (`selectConnectAuth` у
|
||||
`src/gateway/client.ts`):
|
||||
- `auth.password` є ортогональним і завжди пересилається, коли заданий.
|
||||
- `auth.token` заповнюється за пріоритетом: спочатку явний спільний token,
|
||||
потім явний `deviceToken`, потім збережений token для пристрою (ключований за
|
||||
- `auth.token` заповнюється в порядку пріоритету: спочатку явний спільний токен,
|
||||
потім явний `deviceToken`, потім збережений токен для пристрою (за ключем
|
||||
`deviceId` + `role`).
|
||||
- `auth.bootstrapToken` надсилається лише тоді, коли жоден із наведених вище варіантів не розв'язав
|
||||
`auth.token`. Спільний token або будь-який розв'язаний device token пригнічує його.
|
||||
- Автоматичне підвищення збереженого device token під час одноразового
|
||||
повтору `AUTH_TOKEN_MISMATCH` обмежене **лише довіреними endpoint** —
|
||||
- `auth.bootstrapToken` надсилається лише тоді, коли жоден із наведених вище варіантів не визначив
|
||||
`auth.token`. Спільний токен або будь-який визначений токен пристрою його пригнічує.
|
||||
- Автоматичне підвищення збереженого токена пристрою під час одноразової
|
||||
повторної спроби `AUTH_TOKEN_MISMATCH` дозволене **лише для довірених кінцевих точок** —
|
||||
loopback або `wss://` із закріпленим `tlsFingerprint`. Публічний `wss://`
|
||||
без pinning не підходить.
|
||||
- Додаткові записи `hello-ok.auth.deviceTokens` є bootstrap handoff token.
|
||||
Зберігайте їх лише тоді, коли connect використовував bootstrap-автентифікацію через довірений transport,
|
||||
такий як `wss://` або loopback/local pairing.
|
||||
без закріплення не підходить.
|
||||
- Додаткові записи `hello-ok.auth.deviceTokens` є токенами передавання bootstrap.
|
||||
Зберігайте їх лише тоді, коли підключення використовувало bootstrap-автентифікацію на довіреному транспорті,
|
||||
такому як `wss://` або loopback/локальне сполучення.
|
||||
- Якщо клієнт надає **явний** `deviceToken` або явні `scopes`, цей
|
||||
запитаний викликачем набір scopes залишається авторитетним; кешовані scopes лише
|
||||
повторно використовуються, коли клієнт повторно використовує збережений token для пристрою.
|
||||
- Device tokens можна ротувати/відкликати через `device.token.rotate` і
|
||||
`device.token.revoke` (потрібен scope `operator.pairing`).
|
||||
запитаний викликачем набір областей залишається авторитетним; кешовані області лише
|
||||
повторно використовуються, коли клієнт повторно використовує збережений токен для пристрою.
|
||||
- Токени пристроїв можна ротувати/відкликати через `device.token.rotate` і
|
||||
`device.token.revoke` (потрібна область `operator.pairing`).
|
||||
- `device.token.rotate` повертає метадані ротації. Він віддзеркалює замінний
|
||||
bearer token лише для викликів із того самого пристрою, які вже автентифіковані цим
|
||||
device token, щоб клієнти лише з token могли зберегти заміну перед
|
||||
повторним підключенням. Ротації shared/admin не віддзеркалюють bearer token.
|
||||
- Видача, ротація та відкликання token залишаються обмеженими затвердженим набором ролей,
|
||||
записаним у pairing-записі цього пристрою; мутація token не може розширити або
|
||||
націлити роль пристрою, яку pairing approval ніколи не надавав.
|
||||
- Для сесій paired-device token керування пристроями є self-scoped, якщо
|
||||
викликач також не має `operator.admin`: не-admin викликачі можуть видаляти/відкликати/ротувати
|
||||
bearer-токен лише для викликів з того самого пристрою, які вже автентифіковані цим
|
||||
токеном пристрою, щоб клієнти лише з токеном могли зберегти свою заміну перед
|
||||
повторним підключенням. Ротації спільного/адміністративного доступу не віддзеркалюють bearer-токен.
|
||||
- Видача, ротація та відкликання токенів залишаються обмеженими затвердженим набором ролей,
|
||||
записаним у записі сполучення цього пристрою; зміна токена не може розширити або
|
||||
націлитися на роль пристрою, яку затвердження сполучення ніколи не надавало.
|
||||
- Для сеансів токенів сполученого пристрою керування пристроями є самообмеженим, якщо
|
||||
викликач також не має `operator.admin`: викликачі без прав адміністратора можуть видаляти/відкликати/ротувати
|
||||
лише **власний** запис пристрою.
|
||||
- `device.token.rotate` і `device.token.revoke` також перевіряють цільовий набір scopes operator
|
||||
token проти поточних scopes сесії викликача. Не-admin викликачі
|
||||
не можуть ротувати або відкликати ширший operator token, ніж уже мають.
|
||||
- Помилки автентифікації містять `error.details.code` плюс підказки для відновлення:
|
||||
- `device.token.rotate` і `device.token.revoke` також перевіряють набір областей цільового операторського
|
||||
токена відносно поточних областей сеансу викликача. Викликачі без прав адміністратора
|
||||
не можуть ротувати або відкликати ширший операторський токен, ніж той, який вони вже мають.
|
||||
- Збої автентифікації містять `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`:
|
||||
- Довірені клієнти можуть спробувати один обмежений повтор із кешованим token для пристрою.
|
||||
- Якщо цей повтор не вдається, клієнти мають зупинити автоматичні цикли повторного підключення та показати оператору настанови щодо дії.
|
||||
- Довірені клієнти можуть виконати одну обмежену повторну спробу з кешованим токеном для пристрою.
|
||||
- Якщо ця повторна спроба завершується невдало, клієнти мають зупинити автоматичні цикли повторного підключення та показати оператору вказівки щодо дій.
|
||||
|
||||
## Ідентичність пристрою + pairing
|
||||
## Ідентичність пристрою + сполучення
|
||||
|
||||
- Nodes мають містити стабільну ідентичність пристрою (`device.id`), отриману з
|
||||
відбитка keypair.
|
||||
- Gateways видають tokens на пристрій + роль.
|
||||
- Pairing approvals потрібні для нових device IDs, якщо не ввімкнено локальне auto-approval.
|
||||
- Pairing auto-approval зосереджено на прямих підключеннях local loopback.
|
||||
- OpenClaw також має вузький backend/container-local self-connect шлях для
|
||||
довірених helper-потоків зі спільним секретом.
|
||||
- Підключення same-host tailnet або LAN усе ще вважаються віддаленими для pairing і
|
||||
потребують approval.
|
||||
відбитка пари ключів.
|
||||
- Gateways видають токени на пристрій + роль.
|
||||
- Затвердження сполучення потрібні для нових ідентифікаторів пристроїв, якщо не ввімкнено локальне автоматичне затвердження.
|
||||
- Автоматичне затвердження сполучення зосереджене на прямих підключеннях local loopback.
|
||||
- OpenClaw також має вузький backend/container-local шлях самопідключення для
|
||||
довірених допоміжних потоків зі спільним секретом.
|
||||
- Підключення з того самого хоста через tailnet або LAN усе одно розглядаються як віддалені для сполучення та
|
||||
потребують затвердження.
|
||||
- WS-клієнти зазвичай включають ідентичність `device` під час `connect` (operator +
|
||||
node). Єдині винятки operator без device — явні trust paths:
|
||||
- `gateway.controlUi.allowInsecureAuth=true` для localhost-only сумісності з insecure HTTP.
|
||||
- успішна автентифікація operator Control UI через `gateway.auth.mode: "trusted-proxy"`.
|
||||
node). Єдині винятки операторів без пристрою — явні довірчі шляхи:
|
||||
- `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 RPC `gateway-client`, автентифіковані спільним
|
||||
gateway token/password.
|
||||
- direct-loopback backend RPCs `gateway-client`, автентифіковані спільним
|
||||
токеном/паролем Gateway.
|
||||
- Усі підключення мають підписувати наданий сервером nonce `connect.challenge`.
|
||||
|
||||
### Діагностика міграції автентифікації пристрою
|
||||
|
||||
Для legacy-клієнтів, які все ще використовують поведінку підписування до challenge, `connect` тепер повертає
|
||||
detail-коди `DEVICE_AUTH_*` у `error.details.code` зі стабільним `error.details.reason`.
|
||||
Для застарілих клієнтів, які все ще використовують поведінку підписування до challenge, `connect` тепер повертає
|
||||
коди подробиць `DEVICE_AUTH_*` у `error.details.code` зі стабільним `error.details.reason`.
|
||||
|
||||
Поширені помилки міграції:
|
||||
Поширені збої міграції:
|
||||
|
||||
| Повідомлення | details.code | details.reason | Значення |
|
||||
| Повідомлення | details.code | details.reason | Значення |
|
||||
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
|
||||
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Клієнт пропустив `device.nonce` (або надіслав порожній). |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Клієнт підписав зі stale/неправильним nonce. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Payload підпису не відповідає v2 payload. |
|
||||
| `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` не відповідає відбитку public key. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Не вдалося форматування/канонікалізація public key. |
|
||||
| `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` | Не вдалося перевірити формат/канонікалізацію відкритого ключа. |
|
||||
|
||||
Ціль міграції:
|
||||
|
||||
- Завжди очікуйте `connect.challenge`.
|
||||
- Підписуйте payload v2, який містить server nonce.
|
||||
- Завжди чекайте на `connect.challenge`.
|
||||
- Підписуйте корисне навантаження v2, яке містить серверний nonce.
|
||||
- Надсилайте той самий nonce у `connect.params.device.nonce`.
|
||||
- Бажаний payload підпису — `v3`, який прив'язує `platform` і `deviceFamily`
|
||||
- Бажане корисне навантаження підпису — `v3`, яке прив’язує `platform` і `deviceFamily`
|
||||
на додачу до полів device/client/role/scopes/token/nonce.
|
||||
- Legacy-підписи `v2` залишаються прийнятими для сумісності, але pinning metadata paired-device
|
||||
усе ще керує command policy під час повторного підключення.
|
||||
- Застарілі підписи `v2` залишаються прийнятими для сумісності, але закріплення
|
||||
метаданих сполученого пристрою все одно керує політикою команд під час повторного підключення.
|
||||
|
||||
## TLS + pinning
|
||||
## TLS + закріплення
|
||||
|
||||
- TLS підтримується для WS-підключень.
|
||||
- Клієнти можуть необов'язково закріпити відбиток сертифіката gateway (див. конфігурацію `gateway.tls`
|
||||
- Клієнти можуть необов’язково закріпити відбиток сертифіката Gateway (див. конфігурацію `gateway.tls`
|
||||
плюс `gateway.remote.tlsFingerprint` або CLI `--tls-fingerprint`).
|
||||
|
||||
## Scope
|
||||
## Область
|
||||
|
||||
Цей protocol відкриває **повний gateway API** (status, channels, models, chat,
|
||||
agent, sessions, nodes, approvals тощо). Точну поверхню визначають
|
||||
схеми TypeBox у `src/gateway/protocol/schema.ts`.
|
||||
Цей протокол відкриває **повний API Gateway** (status, channels, models, chat,
|
||||
agent, sessions, nodes, approvals тощо). Точна поверхня визначена
|
||||
схемами TypeBox у `src/gateway/protocol/schema.ts`.
|
||||
|
||||
## Пов'язане
|
||||
## Пов’язане
|
||||
|
||||
- [Протокол моста](/uk/gateway/bridge-protocol)
|
||||
- [Операційний довідник Gateway](/uk/gateway)
|
||||
- [Протокол мосту](/uk/gateway/bridge-protocol)
|
||||
- [Операційний посібник Gateway](/uk/gateway)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -4,19 +4,19 @@ read_when:
|
||||
- Вам потрібен довідник усіх методів реєстрації в OpenClawPluginApi
|
||||
- Ви шукаєте конкретний експорт SDK
|
||||
sidebarTitle: SDK overview
|
||||
summary: Карта імпортів, довідник API реєстрації та архітектура SDK
|
||||
summary: Карта імпорту, довідник API реєстрації та архітектура SDK
|
||||
title: Огляд Plugin SDK
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T12:00:02Z"
|
||||
generated_at: "2026-04-28T20:12:31Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 0c3bd7ae2ca2fbf351442bfd073450b72368e1ab833dbbdccfbe569db5346ce9
|
||||
source_hash: 83f554cf3653cdae5027eac2048280a9200828c5ed256d975cd745a77ba1e796
|
||||
source_path: plugins/sdk-overview.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
SDK плагінів є типізованим контрактом між плагінами та ядром. Ця сторінка є
|
||||
довідником про **що імпортувати** та **що можна реєструвати**.
|
||||
SDK плагінів — це типізований контракт між плагінами та ядром. Ця сторінка є
|
||||
довідником щодо **того, що імпортувати** і **що можна реєструвати**.
|
||||
|
||||
<Tip>
|
||||
Шукаєте натомість практичний посібник? Почніть із [Створення плагінів](/uk/plugins/building-plugins), використовуйте [Плагіни каналів](/uk/plugins/sdk-channel-plugins) для плагінів каналів, [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) для плагінів провайдерів і [Хуки Plugin](/uk/plugins/hooks) для плагінів інструментів або хуків життєвого циклу.
|
||||
@ -31,134 +31,137 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
```
|
||||
|
||||
Кожен підшлях є невеликим самодостатнім модулем. Це зберігає швидкий запуск і
|
||||
Кожен підшлях — це невеликий самодостатній модуль. Це забезпечує швидкий запуск і
|
||||
запобігає проблемам із циклічними залежностями. Для специфічних для каналу помічників входу/збирання
|
||||
віддавайте перевагу `openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для
|
||||
ширшої загальної поверхні та спільних помічників, як-от
|
||||
ширшої поверхні-парасольки та спільних помічників, таких як
|
||||
`buildChannelConfigSchema`.
|
||||
|
||||
Для конфігурації каналу публікуйте JSON Schema, якою володіє канал, через
|
||||
`openclaw.plugin.json#channelConfigs`. Підшлях `plugin-sdk/channel-config-schema`
|
||||
призначений для спільних примітивів схем і універсального збирача. Вбудовані
|
||||
призначений для спільних примітивів схеми та універсального конструктора. Вбудовані
|
||||
плагіни OpenClaw використовують `plugin-sdk/bundled-channel-config-schema` для збережених
|
||||
схем вбудованих каналів. Застарілі експорти сумісності залишаються в
|
||||
`plugin-sdk/channel-config-schema-legacy`; жоден із підшляхів вбудованих схем не є
|
||||
шаблоном для нових плагінів.
|
||||
`plugin-sdk/channel-config-schema-legacy`; жоден підшлях вбудованих схем не є
|
||||
зразком для нових плагінів.
|
||||
|
||||
<Warning>
|
||||
Не імпортуйте провайдеро- або канально-брендовані зручні шви (наприклад
|
||||
Не імпортуйте зручні шви з брендуванням провайдера або каналу (наприклад
|
||||
`openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`).
|
||||
Вбудовані плагіни компонують універсальні підшляхи SDK усередині власних барелів `api.ts` /
|
||||
`runtime-api.ts`; споживачі ядра мають або використовувати ці локальні для плагіна
|
||||
барели, або додати вузький універсальний контракт SDK, коли потреба справді є
|
||||
міжканальною.
|
||||
Вбудовані плагіни компонують універсальні підшляхи SDK у власних барелях `api.ts` /
|
||||
`runtime-api.ts`; споживачам ядра слід або використовувати ці локальні для плагіна
|
||||
барелі, або додати вузький універсальний контракт SDK, коли потреба справді
|
||||
є міжканальною.
|
||||
|
||||
Невеликий набір допоміжних швів для вбудованих плагінів усе ще з’являється в згенерованій мапі експортів,
|
||||
коли для них відстежено використання власником. Вони існують лише для супроводу вбудованих плагінів
|
||||
і не рекомендовані як шляхи імпорту для нових сторонніх
|
||||
Невеликий набір допоміжних швів вбудованих плагінів досі з’являється у згенерованій карті експортів,
|
||||
коли для них відстежується використання власником. Вони існують лише для супроводу
|
||||
вбудованих плагінів і не рекомендовані як шляхи імпорту для нових сторонніх
|
||||
плагінів.
|
||||
|
||||
`openclaw/plugin-sdk/discord` також збережено як застарілий фасад сумісності
|
||||
для опублікованого пакета `@openclaw/discord@2026.3.13`. Не копіюйте цей шлях імпорту
|
||||
в нові плагіни; натомість використовуйте універсальні підшляхи SDK каналів.
|
||||
</Warning>
|
||||
|
||||
## Довідник підшляхів
|
||||
|
||||
SDK плагінів експонується як набір вузьких підшляхів, згрупованих за областями (вхід
|
||||
плагіна, канал, провайдер, автентифікація, runtime, можливість, пам’ять і зарезервовані
|
||||
SDK плагінів надається як набір вузьких підшляхів, згрупованих за областями (вхід
|
||||
плагіна, канал, провайдер, автентифікація, runtime, можливості, пам’ять і зарезервовані
|
||||
помічники вбудованих плагінів). Повний каталог — згрупований і з посиланнями — див.
|
||||
[Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths).
|
||||
у [Підшляхи SDK Plugin](/uk/plugins/sdk-subpaths).
|
||||
|
||||
Згенерований список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
## API реєстрації
|
||||
|
||||
Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` з такими
|
||||
Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими
|
||||
методами:
|
||||
|
||||
### Реєстрація можливостей
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| Метод | Що він реєструє |
|
||||
| ------------------------------------------------ | ------------------------------------- |
|
||||
| `api.registerProvider(...)` | Текстове виведення (LLM) |
|
||||
| `api.registerProvider(...)` | Текстове виведення (LLM) |
|
||||
| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента |
|
||||
| `api.registerCliBackend(...)` | Локальний CLI-бекенд виведення |
|
||||
| `api.registerChannel(...)` | Канал обміну повідомленнями |
|
||||
| `api.registerSpeechProvider(...)` | Text-to-speech / STT-синтез |
|
||||
| `api.registerCliBackend(...)` | Локальний бекенд виведення CLI |
|
||||
| `api.registerChannel(...)` | Канал обміну повідомленнями |
|
||||
| `api.registerSpeechProvider(...)` | Text-to-speech / STT синтез |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сесії в реальному часі |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео |
|
||||
| `api.registerImageGenerationProvider(...)` | Генерація зображень |
|
||||
| `api.registerMusicGenerationProvider(...)` | Генерація музики |
|
||||
| `api.registerVideoGenerationProvider(...)` | Генерація відео |
|
||||
| `api.registerWebFetchProvider(...)` | Провайдер веб-отримання / скрейпінгу |
|
||||
| `api.registerWebSearchProvider(...)` | Вебпошук |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео |
|
||||
| `api.registerImageGenerationProvider(...)` | Генерація зображень |
|
||||
| `api.registerMusicGenerationProvider(...)` | Генерація музики |
|
||||
| `api.registerVideoGenerationProvider(...)` | Генерація відео |
|
||||
| `api.registerWebFetchProvider(...)` | Провайдер веботримання / скрейпінгу |
|
||||
| `api.registerWebSearchProvider(...)` | Вебпошук |
|
||||
|
||||
### Інструменти та команди
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ------------------------------- | --------------------------------------------- |
|
||||
| Метод | Що він реєструє |
|
||||
| ----------------------------- | -------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | Користувацька команда (оминає LLM) |
|
||||
| `api.registerCommand(def)` | Користувацька команда (оминає LLM) |
|
||||
|
||||
Команди плагінів можуть задавати `agentPromptGuidance`, коли агенту потрібна коротка,
|
||||
керована командою підказка маршрутизації. Тримайте цей текст про саму команду; не додавайте
|
||||
політику, специфічну для провайдера або плагіна, до збирачів промптів ядра.
|
||||
Команди плагіна можуть задавати `agentPromptGuidance`, коли агенту потрібна коротка
|
||||
підказка маршрутизації, якою володіє команда. Тримайте цей текст про саму команду; не додавайте
|
||||
політику, специфічну для провайдера або плагіна, до побудовників промптів ядра.
|
||||
|
||||
### Інфраструктура
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ---------------------------------------------- | --------------------------------------- |
|
||||
| ---------------------------------------------- | -------------------------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Хук події |
|
||||
| `api.registerHttpRoute(params)` | HTTP-ендпойнт Gateway |
|
||||
| `api.registerHttpRoute(params)` | HTTP endpoint Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway |
|
||||
| `api.registerGatewayDiscoveryService(service)` | Локальний рекламодавець виявлення Gateway |
|
||||
| `api.registerCli(registrar, opts?)` | Підкоманда CLI |
|
||||
| `api.registerService(service)` | Фоновий сервіс |
|
||||
| `api.registerService(service)` | Фонова служба |
|
||||
| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник |
|
||||
| `api.registerAgentToolResultMiddleware(...)` | Runtime middleware результатів інструментів |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Додатковий суміжний із пам’яттю розділ промпта |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Додатковий розділ промпта, суміжний із пам’яттю |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Додатковий корпус пошуку/читання пам’яті |
|
||||
|
||||
### Хостові хуки для плагінів workflow
|
||||
### Хост-хуки для плагінів робочих процесів
|
||||
|
||||
Хостові хуки — це шви SDK для плагінів, яким потрібно брати участь у життєвому циклі хоста,
|
||||
Хост-хуки — це шви SDK для плагінів, яким потрібно брати участь у життєвому циклі хоста,
|
||||
а не лише додавати провайдера, канал або інструмент. Це
|
||||
універсальні контракти; Plan Mode може їх використовувати, але так само можуть workflow затвердження,
|
||||
гейти політик робочого простору, фонові монітори, майстри налаштування та супровідні UI-плагіни.
|
||||
універсальні контракти; їх може використовувати Plan Mode, але також можуть процеси схвалення,
|
||||
шлюзи політик робочої області, фонові монітори, майстри налаштування та супровідні UI-плагіни.
|
||||
|
||||
| Метод | Контракт, яким він володіє |
|
||||
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
|
||||
| Метод | Контракт, яким він володіє |
|
||||
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
|
||||
| `api.registerSessionExtension(...)` | Стан сесії, яким володіє плагін і який сумісний із JSON, проєктований через сесії Gateway |
|
||||
| `api.enqueueNextTurnInjection(...)` | Стійкий контекст exactly-once, вставлений у наступний хід агента для однієї сесії |
|
||||
| `api.registerTrustedToolPolicy(...)` | Вбудована/довірена політика інструментів до плагінів, що може блокувати або переписувати параметри інструмента |
|
||||
| `api.registerToolMetadata(...)` | Метадані відображення каталогу інструментів без зміни реалізації інструмента |
|
||||
| `api.registerCommand(...)` | Обмежені за областю команди плагіна; результати команди можуть задавати `continueAgent: true` |
|
||||
| `api.registerControlUiDescriptor(...)` | Дескриптори внесків Control UI для поверхонь сесії, інструмента, запуску або налаштувань |
|
||||
| `api.registerRuntimeLifecycle(...)` | Колбеки очищення для runtime-ресурсів, якими володіє плагін, на шляхах reset/delete/reload |
|
||||
| `api.registerAgentEventSubscription(...)` | Санітизовані підписки на події для стану workflow і моніторів |
|
||||
| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Чернетковий стан плагіна на один запуск, очищений у кінцевому життєвому циклі запуску |
|
||||
| `api.enqueueNextTurnInjection(...)` | Стійкий контекст рівно один раз, інжектований у наступний хід агента для однієї сесії |
|
||||
| `api.registerTrustedToolPolicy(...)` | Політика інструментів довіреного передплагінного етапу, яка може блокувати або переписувати параметри інструментів |
|
||||
| `api.registerToolMetadata(...)` | Метадані відображення каталогу інструментів без зміни реалізації інструмента |
|
||||
| `api.registerCommand(...)` | Обмежені за областю команди плагіна; результати команд можуть задавати `continueAgent: true` |
|
||||
| `api.registerControlUiDescriptor(...)` | Дескриптори внеску Control UI для поверхонь сесії, інструмента, запуску або налаштувань |
|
||||
| `api.registerRuntimeLifecycle(...)` | Зворотні виклики очищення для runtime-ресурсів, якими володіє плагін, на шляхах reset/delete/reload |
|
||||
| `api.registerAgentEventSubscription(...)` | Очищені підписки на події для стану робочого процесу та моніторів |
|
||||
| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Чернетковий стан плагіна для окремого запуску, очищений під час завершального життєвого циклу запуску |
|
||||
| `api.registerSessionSchedulerJob(...)` | Записи завдань планувальника сесій, якими володіє плагін, із детермінованим очищенням |
|
||||
|
||||
Контракти навмисно розділяють повноваження:
|
||||
|
||||
- Зовнішні плагіни можуть володіти розширеннями сесій, UI-дескрипторами, командами, метаданими інструментів, ін’єкціями наступного ходу та звичайними хуками.
|
||||
- Довірені політики інструментів виконуються перед звичайними хуками `before_tool_call` і є лише вбудованими, бо беруть участь у політиці безпеки хоста.
|
||||
- Зарезервоване володіння командами є лише вбудованим. Зовнішні плагіни мають використовувати
|
||||
власні назви команд або псевдоніми.
|
||||
- Зовнішні плагіни можуть володіти розширеннями сесій, UI-дескрипторами, командами, метаданими інструментів, інжекціями в наступний хід і звичайними хуками.
|
||||
- Довірені політики інструментів виконуються перед звичайними хуками `before_tool_call` і доступні лише вбудованим плагінам, бо вони беруть участь у політиці безпеки хоста.
|
||||
- Зарезервоване володіння командами доступне лише вбудованим плагінам. Зовнішні плагіни мають використовувати власні імена команд або псевдоніми.
|
||||
- `allowPromptInjection=false` вимикає хуки, що змінюють промпт, зокрема
|
||||
`agent_turn_prepare`, `before_prompt_build`, `heartbeat_prompt_contribution`,
|
||||
поля промпта зі спадкового `before_agent_start` і
|
||||
поля промпта зі спадкового `before_agent_start` та
|
||||
`enqueueNextTurnInjection`.
|
||||
|
||||
Приклади споживачів, що не належать до Plan:
|
||||
Приклади споживачів не з Plan:
|
||||
|
||||
| Архетип плагіна | Використані хуки |
|
||||
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Workflow затвердження | Розширення сесії, продовження команди, ін’єкція наступного ходу, UI-дескриптор |
|
||||
| Гейт політики бюджету/робочого простору | Довірена політика інструментів, метадані інструментів, проєкція сесії |
|
||||
| Фоновий монітор життєвого циклу | Очищення життєвого циклу runtime, підписка на події агента, володіння/очищення планувальника сесій, внесок до промпта Heartbeat, UI-дескриптор |
|
||||
| Майстер налаштування або онбордингу | Розширення сесії, обмежені за областю команди, дескриптор Control UI |
|
||||
| Архетип плагіна | Використані хуки |
|
||||
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Процес схвалення | Розширення сесії, продовження команди, інжекція в наступний хід, UI-дескриптор |
|
||||
| Шлюз політик бюджету/робочої області | Довірена політика інструментів, метадані інструментів, проєкція сесії |
|
||||
| Фоновий монітор життєвого циклу | Очищення життєвого циклу runtime, підписка на події агента, володіння/очищення планувальника сесій, внесок промпта Heartbeat, UI-дескриптор |
|
||||
| Майстер налаштування або onboarding | Розширення сесії, команди з областю дії, дескриптор Control UI |
|
||||
|
||||
<Note>
|
||||
Зарезервовані простори імен адміністратора ядра (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
Зарезервовані адміністративні простори імен ядра (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити
|
||||
вужчу область методу gateway. Віддавайте перевагу специфічним для плагіна префіксам для
|
||||
методів, якими володіє плагін.
|
||||
@ -166,24 +169,24 @@ SDK плагінів експонується як набір вузьких п
|
||||
|
||||
<Accordion title="Коли використовувати middleware результатів інструментів">
|
||||
Вбудовані плагіни можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли
|
||||
їм потрібно переписати результат інструмента після виконання й до того, як runtime
|
||||
передасть цей результат назад у модель. Це довірений runtime-нейтральний
|
||||
їм потрібно переписати результат інструмента після виконання і до того, як runtime
|
||||
передасть цей результат назад у модель. Це довірений нейтральний до runtime
|
||||
шов для асинхронних редукторів виводу, таких як tokenjuice.
|
||||
|
||||
Вбудовані плагіни мають оголошувати `contracts.agentToolResultMiddleware` для кожного
|
||||
цільового runtime, наприклад `["pi", "codex"]`. Зовнішні плагіни
|
||||
не можуть реєструвати це middleware; залишайте звичайні хуки плагінів OpenClaw для роботи,
|
||||
яка не потребує таймінгу результатів інструментів перед моделлю. Старий лише Pi-вбудований
|
||||
шлях реєстрації фабрики розширення було видалено.
|
||||
яка не потребує таймінгу результату інструмента перед моделлю. Старий вбудований
|
||||
шлях реєстрації фабрики розширення лише для Pi було видалено.
|
||||
</Accordion>
|
||||
|
||||
### Реєстрація виявлення Gateway
|
||||
|
||||
`api.registerGatewayDiscoveryService(...)` дає змогу плагіну рекламувати активний
|
||||
`api.registerGatewayDiscoveryService(...)` дає плагіну змогу рекламувати активний
|
||||
Gateway у локальному транспорті виявлення, такому як mDNS/Bonjour. OpenClaw викликає
|
||||
сервіс під час запуску Gateway, коли локальне виявлення ввімкнено, передає
|
||||
поточні порти Gateway і несекретні дані підказок TXT, а також викликає повернений
|
||||
обробник `stop` під час вимкнення Gateway.
|
||||
службу під час запуску Gateway, коли локальне виявлення ввімкнено, передає
|
||||
поточні порти Gateway і несекретні TXT-підказки, а також викликає повернений
|
||||
обробник `stop` під час завершення роботи Gateway.
|
||||
|
||||
```typescript
|
||||
api.registerGatewayDiscoveryService({
|
||||
@ -200,20 +203,19 @@ api.registerGatewayDiscoveryService({
|
||||
```
|
||||
|
||||
Плагіни виявлення Gateway не повинні трактувати рекламовані значення TXT як секрети або
|
||||
автентифікацію. Виявлення є підказкою маршрутизації; довірою все ще володіють
|
||||
автентифікація Gateway і TLS pinning.
|
||||
автентифікацію. Виявлення — це підказка маршрутизації; довірою все ще керують автентифікація Gateway і TLS-пінінг.
|
||||
|
||||
### Метадані реєстрації CLI
|
||||
|
||||
`api.registerCli(registrar, opts?)` приймає два види метаданих верхнього рівня:
|
||||
`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня:
|
||||
|
||||
- `commands`: явні корені команд, якими володіє registrar
|
||||
- `descriptors`: дескриптори команд часу парсингу, що використовуються для кореневої довідки CLI,
|
||||
маршрутизації та лінивої реєстрації CLI плагіна
|
||||
- `commands`: явні корені команд, якими володіє реєстратор
|
||||
- `descriptors`: дескриптори команд часу розбору, які використовуються для довідки кореневого CLI,
|
||||
маршрутизації та лінивої реєстрації CLI Plugin
|
||||
|
||||
Якщо ви хочете, щоб команда Plugin залишалася lazy-loaded у звичайному кореневому шляху CLI,
|
||||
надайте `descriptors`, які охоплюють кожен кореневий top-level command, що його відкриває цей
|
||||
реєстратор.
|
||||
Якщо ви хочете, щоб команда Plugin залишалася ліниво завантажуваною у звичайному шляху кореневого CLI,
|
||||
надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що надається цим
|
||||
реєстратором.
|
||||
|
||||
```typescript
|
||||
api.registerCli(
|
||||
@ -233,97 +235,97 @@ api.registerCli(
|
||||
);
|
||||
```
|
||||
|
||||
Використовуйте лише `commands` тільки тоді, коли вам не потрібна lazy root CLI registration.
|
||||
Цей eager compatibility path залишається підтримуваним, але він не встановлює
|
||||
descriptor-backed placeholders для lazy loading під час parsing.
|
||||
Використовуйте `commands` самостійно лише тоді, коли вам не потрібна лінива реєстрація кореневого CLI.
|
||||
Цей енергійний шлях сумісності залишається підтримуваним, але він не встановлює
|
||||
заповнювачі на основі дескрипторів для лінивого завантаження під час розбору.
|
||||
|
||||
### Реєстрація бекенду CLI
|
||||
### Реєстрація бекенда CLI
|
||||
|
||||
`api.registerCliBackend(...)` дає змогу Plugin володіти типовою конфігурацією для локального
|
||||
AI CLI backend, такого як `codex-cli`.
|
||||
`api.registerCliBackend(...)` дає Plugin змогу володіти типовою конфігурацією для локального
|
||||
AI CLI бекенда, такого як `codex-cli`.
|
||||
|
||||
- Backend `id` стає provider prefix у model refs на кшталт `codex-cli/gpt-5`.
|
||||
- Backend `id` стає префіксом постачальника в посиланнях на модель, як-от `codex-cli/gpt-5`.
|
||||
- Backend `config` використовує ту саму форму, що й `agents.defaults.cliBackends.<id>`.
|
||||
- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.<id>` поверх
|
||||
- Конфігурація користувача все одно має пріоритет. OpenClaw об'єднує `agents.defaults.cliBackends.<id>` поверх
|
||||
типового значення Plugin перед запуском CLI.
|
||||
- Використовуйте `normalizeConfig`, коли backend потребує compatibility rewrites після merge
|
||||
- Використовуйте `normalizeConfig`, коли backend потребує переписувань сумісності після об'єднання
|
||||
(наприклад, нормалізації старих форм прапорців).
|
||||
|
||||
### Ексклюзивні слоти
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | Context engine (один активний одночасно). Callback `assemble()` отримує `availableTools` і `citationsMode`, щоб engine міг адаптувати доповнення до prompt. |
|
||||
| `api.registerMemoryCapability(capability)` | Уніфікована можливість пам’яті |
|
||||
| `api.registerMemoryPromptSection(builder)` | Builder секції prompt пам’яті |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush пам’яті |
|
||||
| `api.registerMemoryRuntime(runtime)` | Runtime adapter пам’яті |
|
||||
| Метод | Що він реєструє |
|
||||
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | Рушій контексту (одночасно активний лише один). Callback `assemble()` отримує `availableTools` і `citationsMode`, щоб рушій міг адаптувати доповнення до prompt. |
|
||||
| `api.registerMemoryCapability(capability)` | Уніфікована можливість пам'яті |
|
||||
| `api.registerMemoryPromptSection(builder)` | Побудовник секції prompt пам'яті |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану очищення пам'яті |
|
||||
| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам'яті |
|
||||
|
||||
### Адаптери embedding пам’яті
|
||||
### Адаптери embedding пам'яті
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ---------------------------------------------- | ------------------------------------------------ |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного Plugin |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам'яті для активного Plugin |
|
||||
|
||||
- `registerMemoryCapability` є пріоритетним ексклюзивним API для memory-plugin.
|
||||
- `registerMemoryCapability` також може відкривати `publicArtifacts.listArtifacts(...)`,
|
||||
щоб супровідні plugins могли споживати експортовані artifacts пам’яті через
|
||||
`openclaw/plugin-sdk/memory-host-core` замість доступу до приватної структури конкретного
|
||||
memory plugin.
|
||||
- `registerMemoryCapability` є рекомендованим ексклюзивним API Plugin пам'яті.
|
||||
- `registerMemoryCapability` також може надавати `publicArtifacts.listArtifacts(...)`,
|
||||
щоб супутні plugins могли споживати експортовані артефакти пам'яті через
|
||||
`openclaw/plugin-sdk/memory-host-core`, а не звертатися до приватної структури конкретного
|
||||
Plugin пам'яті.
|
||||
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` і
|
||||
`registerMemoryRuntime` є legacy-compatible ексклюзивними API для memory-plugin.
|
||||
- `MemoryFlushPlan.model` може прив’язати flush turn до точного посилання `provider/model`,
|
||||
такого як `ollama/qwen3:8b`, без успадкування активного fallback chain.
|
||||
- `registerMemoryEmbeddingProvider` дає активному memory plugin змогу зареєструвати один
|
||||
або більше id адаптерів embedding (наприклад, `openai`, `gemini` або custom
|
||||
plugin-defined id).
|
||||
- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і
|
||||
`agents.defaults.memorySearch.fallback`, resolve проти цих зареєстрованих
|
||||
`registerMemoryRuntime` є застаріло-сумісними ексклюзивними API Plugin пам'яті.
|
||||
- `MemoryFlushPlan.model` може прив'язати turn очищення до точного посилання `provider/model`,
|
||||
наприклад `ollama/qwen3:8b`, без успадкування активного ланцюжка fallback.
|
||||
- `registerMemoryEmbeddingProvider` дає активному Plugin пам'яті змогу зареєструвати один
|
||||
або більше id адаптерів embedding (наприклад `openai`, `gemini` або власний
|
||||
id, визначений Plugin).
|
||||
- Конфігурація користувача, як-от `agents.defaults.memorySearch.provider` і
|
||||
`agents.defaults.memorySearch.fallback`, розв'язується відносно цих зареєстрованих
|
||||
id адаптерів.
|
||||
|
||||
### Події та життєвий цикл
|
||||
|
||||
| Метод | Що він робить |
|
||||
| -------------------------------------------- | -------------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Типізований lifecycle hook |
|
||||
| `api.onConversationBindingResolved(handler)` | Callback прив’язки розмови |
|
||||
| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу |
|
||||
| `api.onConversationBindingResolved(handler)` | Callback прив'язки розмови |
|
||||
|
||||
Див. [хуки Plugin](/uk/plugins/hooks) для прикладів, поширених назв hook і семантики guard.
|
||||
Див. [Хуки Plugin](/uk/plugins/hooks) для прикладів, поширених назв хуків і семантики guard.
|
||||
|
||||
### Семантика рішень hook
|
||||
### Семантика рішень хуків
|
||||
|
||||
- `before_tool_call`: повернення `{ block: true }` є terminal. Щойно будь-який handler встановлює його, handlers із нижчим пріоритетом пропускаються.
|
||||
- `before_tool_call`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як omission `block`), а не як override.
|
||||
- `before_install`: повернення `{ block: true }` є terminal. Щойно будь-який handler встановлює його, handlers із нижчим пріоритетом пропускаються.
|
||||
- `before_install`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як omission `block`), а не як override.
|
||||
- `reply_dispatch`: повернення `{ handled: true, ... }` є terminal. Щойно будь-який handler claims dispatch, handlers із нижчим пріоритетом і default model dispatch path пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: true }` є terminal. Щойно будь-який handler встановлює його, handlers із нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: false }` розглядається як відсутність рішення (так само, як omission `cancel`), а не як override.
|
||||
- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна маршрутизація вхідного thread/topic. Залишайте `metadata` для channel-specific extras.
|
||||
- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId` перед fallback до channel-specific `metadata`.
|
||||
- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для startup state, яким володіє Gateway, замість покладання на внутрішні hooks `gateway:startup`.
|
||||
- `cron_changed`: спостерігайте за змінами життєвого циклу cron, яким володіє Gateway. Використовуйте `event.job?.state?.nextRunAtMs` і `ctx.getCron?.()` під час синхронізації зовнішніх wake schedulers, і залишайте OpenClaw джерелом істини для due checks та виконання.
|
||||
- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює його, handlers із нижчим пріоритетом пропускаються.
|
||||
- `before_tool_call`: повернення `{ block: false }` трактується як відсутність рішення (так само, як пропуск `block`), а не як перевизначення.
|
||||
- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює його, handlers із нижчим пріоритетом пропускаються.
|
||||
- `before_install`: повернення `{ block: false }` трактується як відсутність рішення (так само, як пропуск `block`), а не як перевизначення.
|
||||
- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який handler бере dispatch на себе, handlers із нижчим пріоритетом і типовий шлях dispatch моделі пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який handler встановлює його, handlers із нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: false }` трактується як відсутність рішення (так само, як пропуск `cancel`), а не як перевизначення.
|
||||
- `message_received`: використовуйте типізоване поле `threadId`, коли потрібна маршрутизація вхідного thread/topic. Залишайте `metadata` для специфічних для каналу додаткових даних.
|
||||
- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до специфічних для каналу `metadata`.
|
||||
- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, яким володіє gateway, замість покладання на внутрішні хуки `gateway:startup`.
|
||||
- `cron_changed`: спостерігайте за змінами життєвого циклу Cron, яким володіє gateway. Використовуйте `event.job?.state?.nextRunAtMs` і `ctx.getCron?.()` під час синхронізації зовнішніх планувальників пробудження, і зберігайте OpenClaw джерелом істини для перевірок строків і виконання.
|
||||
|
||||
### Поля об’єкта API
|
||||
### Поля об'єкта API
|
||||
|
||||
| Поле | Тип | Опис |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | Id Plugin |
|
||||
| `api.name` | `string` | Відображувана назва |
|
||||
| `api.version` | `string?` | Версія Plugin (опційно) |
|
||||
| `api.description` | `string?` | Опис Plugin (опційно) |
|
||||
| `api.source` | `string` | Шлях джерела Plugin |
|
||||
| `api.rootDir` | `string?` | Кореневий каталог Plugin (опційно) |
|
||||
| `api.config` | `OpenClawConfig` | Поточний snapshot конфігурації (активний in-memory runtime snapshot, коли доступний) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Конфігурація, специфічна для Plugin, з `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [Runtime helpers](/uk/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | Scoped logger (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` є lightweight pre-full-entry startup/setup window |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Resolve path відносно кореня Plugin |
|
||||
| Поле | Тип | Опис |
|
||||
| ------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | id Plugin |
|
||||
| `api.name` | `string` | Відображувана назва |
|
||||
| `api.version` | `string?` | Версія Plugin (необов'язково) |
|
||||
| `api.description` | `string?` | Опис Plugin (необов'язково) |
|
||||
| `api.source` | `string` | Шлях до джерела Plugin |
|
||||
| `api.rootDir` | `string?` | Коренева директорія Plugin (необов'язково) |
|
||||
| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний runtime-знімок у пам'яті, коли доступний) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Специфічна для Plugin конфігурація з `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [Runtime-помічники](/uk/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | Обмежений logger (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — легке вікно startup/setup перед повним entry |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Розв'язати шлях відносно кореня Plugin |
|
||||
|
||||
## Внутрішня домовленість щодо модулів
|
||||
## Угода щодо внутрішніх модулів
|
||||
|
||||
У межах вашого Plugin використовуйте local barrel files для внутрішніх imports:
|
||||
Усередині вашого Plugin використовуйте локальні barrel-файли для внутрішніх імпортів:
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
@ -335,55 +337,55 @@ my-plugin/
|
||||
|
||||
<Warning>
|
||||
Ніколи не імпортуйте власний Plugin через `openclaw/plugin-sdk/<your-plugin>`
|
||||
з production code. Спрямовуйте внутрішні imports через `./api.ts` або
|
||||
`./runtime-api.ts`. Шлях SDK є лише зовнішнім contract.
|
||||
з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або
|
||||
`./runtime-api.ts`. Шлях SDK є лише зовнішнім контрактом.
|
||||
</Warning>
|
||||
|
||||
Facade-loaded bundled plugin public surfaces (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` та подібні public entry files) надають перевагу
|
||||
активному runtime config snapshot, коли OpenClaw уже запущений. Якщо runtime
|
||||
snapshot ще не існує, вони fallback до resolved config file на диску.
|
||||
Packaged bundled plugin facades слід завантажувати через facade loaders OpenClaw SDK;
|
||||
прямі imports з `dist/extensions/...` обходять staged runtime dependency mirrors,
|
||||
які packaged installs використовують для plugin-owned dependencies.
|
||||
Публічні поверхні bundled Plugin, завантажені через facade (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` і подібні публічні entry-файли), віддають перевагу
|
||||
активному runtime-знімку конфігурації, коли OpenClaw уже працює. Якщо runtime-знімка
|
||||
ще немає, вони повертаються до розв'язаної конфігурації з файлу на диску.
|
||||
Упаковані bundled facade Plugin слід завантажувати через facade loaders OpenClaw SDK;
|
||||
прямі імпорти з `dist/extensions/...` обходять staged runtime mirrors залежностей,
|
||||
які packaged installs використовують для залежностей, що належать Plugin.
|
||||
|
||||
Provider plugins можуть відкривати вузький plugin-local contract barrel, коли
|
||||
helper навмисно provider-specific і ще не належить до generic SDK
|
||||
subpath. Bundled examples:
|
||||
Provider plugins можуть надавати вузький локальний barrel контракту Plugin, коли
|
||||
helper навмисно специфічний для provider і ще не належить до generic SDK
|
||||
subpath. Bundled приклади:
|
||||
|
||||
- **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для Claude
|
||||
beta-header і stream helpers `service_tier`.
|
||||
- **`@openclaw/openai-provider`**: `api.ts` експортує provider builders,
|
||||
default-model helpers і realtime provider builders.
|
||||
helpers типової моделі та realtime provider builders.
|
||||
- **`@openclaw/openrouter-provider`**: `api.ts` експортує provider builder
|
||||
плюс onboarding/config helpers.
|
||||
плюс helpers onboarding/config.
|
||||
|
||||
<Warning>
|
||||
Production code розширення також має уникати imports `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Якщо helper справді спільний, підвищте його до нейтрального SDK subpath,
|
||||
такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої
|
||||
capability-oriented surface замість coupling двох plugins разом.
|
||||
Production-код extension також має уникати імпортів `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Якщо helper справді спільний, підніміть його до нейтрального SDK subpath,
|
||||
такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або інша
|
||||
поверхня, орієнтована на можливості, замість того щоб зв'язувати два plugins між собою.
|
||||
</Warning>
|
||||
|
||||
## Пов’язане
|
||||
## Пов'язане
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Точки входу" icon="door-open" href="/uk/plugins/sdk-entrypoints">
|
||||
Параметри `definePluginEntry` і `defineChannelPluginEntry`.
|
||||
</Card>
|
||||
<Card title="Runtime helpers" icon="gears" href="/uk/plugins/sdk-runtime">
|
||||
Повний довідник namespace `api.runtime`.
|
||||
<Card title="Runtime-помічники" icon="gears" href="/uk/plugins/sdk-runtime">
|
||||
Повна довідка простору імен `api.runtime`.
|
||||
</Card>
|
||||
<Card title="Налаштування та конфігурація" icon="sliders" href="/uk/plugins/sdk-setup">
|
||||
Packaging, manifests і config schemas.
|
||||
<Card title="Setup і конфігурація" icon="sliders" href="/uk/plugins/sdk-setup">
|
||||
Пакування, manifests і config schemas.
|
||||
</Card>
|
||||
<Card title="Тестування" icon="vial" href="/uk/plugins/sdk-testing">
|
||||
Test utilities і lint rules.
|
||||
Тестові утиліти та правила lint.
|
||||
</Card>
|
||||
<Card title="Міграція SDK" icon="arrows-turn-right" href="/uk/plugins/sdk-migration">
|
||||
Міграція з deprecated surfaces.
|
||||
Міграція із застарілих поверхонь.
|
||||
</Card>
|
||||
<Card title="Внутрішня архітектура Plugin" icon="diagram-project" href="/uk/plugins/architecture">
|
||||
Глибока архітектура та capability model.
|
||||
Поглиблена архітектура та модель можливостей.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -5,26 +5,26 @@ read_when:
|
||||
summary: 'Каталог підшляхів Plugin SDK: які імпорти де розташовані, згруповано за областями'
|
||||
title: Підшляхи Plugin SDK
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T11:21:35Z"
|
||||
generated_at: "2026-04-28T20:12:45Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 8f9939a84decc6d5ff34662044af97b8c9da838b0d2791b2cd0cfa15d181fdd7
|
||||
source_hash: f66fa1c9f9398ae2124dc4b92d3b11a07800616f452409d12e851a6fb0bcd675
|
||||
source_path: plugins/sdk-subpaths.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
SDK Plugin доступний як набір вузьких підшляхів у `openclaw/plugin-sdk/`.
|
||||
На цій сторінці наведено часто використовувані підшляхи, згруповані за призначенням. Згенерований
|
||||
SDK Plugin надається як набір вузьких підшляхів у `openclaw/plugin-sdk/`.
|
||||
На цій сторінці наведено поширені підшляхи, згруповані за призначенням. Згенерований
|
||||
повний список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`;
|
||||
зарезервовані допоміжні підшляхи bundled-plugin також є там, але вони є деталлю
|
||||
реалізації, якщо сторінка документації явно не просуває їх. Супровідники можуть перевіряти активні
|
||||
реалізації, якщо сторінка документації явно не виносить їх на рівень публічного API. Супровідники можуть перевіряти активні
|
||||
зарезервовані допоміжні підшляхи за допомогою `pnpm plugins:boundary-report:summary`; невикористані
|
||||
зарезервовані допоміжні експорти провалюють звіт CI, а не залишаються в публічному SDK
|
||||
зарезервовані допоміжні експорти призводять до помилки у звіті CI, а не залишаються в публічному SDK
|
||||
як неактивний борг сумісності.
|
||||
|
||||
Посібник з авторства Plugin див. у [Огляд SDK Plugin](/uk/plugins/sdk-overview).
|
||||
Посібник з розробки Plugin див. у [огляді SDK Plugin](/uk/plugins/sdk-overview).
|
||||
|
||||
## Вхідна точка Plugin
|
||||
## Точка входу Plugin
|
||||
|
||||
| Підшлях | Ключові експорти |
|
||||
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
@ -32,297 +32,298 @@ x-i18n:
|
||||
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
|
||||
| `plugin-sdk/config-schema` | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/testing` | Широкий barrel сумісності для застарілих тестів Plugin; для нових тестів розширень віддавайте перевагу сфокусованим тестовим підшляхам |
|
||||
| `plugin-sdk/plugin-test-api` | Мінімальний побудовник mock `OpenClawPluginApi` для прямих unit-тестів реєстрації Plugin |
|
||||
| `plugin-sdk/agent-runtime-test-contracts` | Фікстури контрактів адаптера нативного agent-runtime для профілів автентифікації, приглушення доставки, класифікації fallback, хуків інструментів, накладок prompt, схем і відновлення transcript |
|
||||
| `plugin-sdk/channel-test-helpers` | Допоміжні засоби для тестування життєвого циклу облікового запису каналу, каталогу, send-config, mock runtime, хуків, вхідної точки bundled каналу, timestamp конверта, відповіді pairing та загального контракту каналу |
|
||||
| `plugin-sdk/channel-target-testing` | Спільний набір тестів випадків помилок розв’язання цілі каналу |
|
||||
| `plugin-sdk/plugin-test-contracts` | Допоміжні засоби контрактів реєстрації Plugin, маніфесту пакета, публічного artifact, API runtime, побічних ефектів імпорту та прямого імпорту |
|
||||
| `plugin-sdk/plugin-test-runtime` | Фікстури runtime Plugin, registry, реєстрації provider, setup-wizard і runtime task-flow для тестів |
|
||||
| `plugin-sdk/provider-test-contracts` | Допоміжні засоби контрактів runtime provider, автентифікації, discovery, onboard, catalog, media capability, replay policy, realtime STT live-audio, web-search/fetch і wizard |
|
||||
| `plugin-sdk/provider-http-test-mocks` | Opt-in Vitest HTTP/auth mocks для тестів provider, що перевіряють `plugin-sdk/provider-http` |
|
||||
| `plugin-sdk/test-env` | Фікстури тестового середовища, fetch/network, одноразового HTTP-сервера, вхідного запиту, live-test, тимчасової файлової системи та керування часом |
|
||||
| `plugin-sdk/test-fixtures` | Загальні фікстури тестів CLI, sandbox, skill, agent-message, system-event, перезавантаження модуля, шляху bundled Plugin, terminal, chunking, auth-token і typed-case |
|
||||
| `plugin-sdk/test-node-mocks` | Сфокусовані допоміжні засоби mock для вбудованих модулів Node для використання всередині фабрик Vitest `vi.mock("node:*")` |
|
||||
| `plugin-sdk/migration` | Допоміжні засоби елементів provider міграції, як-от `createMigrationItem`, константи причин, маркери стану елементів, допоміжні засоби редагування та `summarizeMigrationItems` |
|
||||
| `plugin-sdk/migration-runtime` | Допоміжні засоби міграції runtime, як-от `copyMigrationFileItem` і `writeMigrationReport` |
|
||||
| `plugin-sdk/testing` | Широкий barrel сумісності для застарілих тестів Plugin; для нових тестів розширень надавайте перевагу сфокусованим тестовим підшляхам |
|
||||
| `plugin-sdk/plugin-test-api` | Мінімальний builder моків `OpenClawPluginApi` для модульних тестів прямої реєстрації Plugin |
|
||||
| `plugin-sdk/agent-runtime-test-contracts` | Нативні fixtures контрактів адаптера agent-runtime для профілів автентифікації, пригнічення доставки, класифікації fallback, хуків інструментів, накладень промптів, схем і відновлення transcript |
|
||||
| `plugin-sdk/channel-test-helpers` | Помічники тестів життєвого циклу облікового запису каналу, каталогу, send-config, runtime-мока, хуків, точки входу bundled channel, timestamp envelope, pairing reply і generic channel contract |
|
||||
| `plugin-sdk/channel-target-testing` | Спільний набір тестів випадків помилок target-resolution каналу |
|
||||
| `plugin-sdk/plugin-test-contracts` | Помічники контрактів реєстрації Plugin, маніфесту пакета, публічного артефакту, runtime API, side-effect імпорту та прямого імпорту |
|
||||
| `plugin-sdk/plugin-test-runtime` | Fixtures для тестів runtime Plugin, registry, provider-registration, setup-wizard і runtime task-flow |
|
||||
| `plugin-sdk/provider-test-contracts` | Помічники контрактів provider runtime, auth, discovery, onboard, catalog, media capability, replay policy, realtime STT live-audio, web-search/fetch і wizard |
|
||||
| `plugin-sdk/provider-http-test-mocks` | Opt-in HTTP/auth моки Vitest для тестів провайдера, що перевіряють `plugin-sdk/provider-http` |
|
||||
| `plugin-sdk/test-env` | Fixtures тестового середовища, fetch/network, disposable HTTP server, incoming request, live-test, temporary filesystem і time-control |
|
||||
| `plugin-sdk/test-fixtures` | Generic fixtures для CLI, sandbox, skill, agent-message, system-event, module reload, bundled plugin path, terminal, chunking, auth-token і typed-case |
|
||||
| `plugin-sdk/test-node-mocks` | Сфокусовані помічники моків вбудованих модулів Node для використання у factory Vitest `vi.mock("node:*")` |
|
||||
| `plugin-sdk/migration` | Помічники елементів migration provider, як-от `createMigrationItem`, константи причин, маркери стану елементів, помічники редагування та `summarizeMigrationItems` |
|
||||
| `plugin-sdk/migration-runtime` | Runtime-помічники міграції, як-от `copyMigrationFileItem` і `writeMigrationReport` |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Підшляхи каналів">
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/config-schema` | Експорт схеми Zod кореневого `openclaw.json` (`OpenClawSchema`) |
|
||||
| `plugin-sdk/config-schema` | Експорт Zod-схеми кореневого `openclaw.json` (`OpenClawSchema`) |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/setup` | Спільні допоміжні засоби setup wizard, prompt allowlist, побудовники стану setup |
|
||||
| `plugin-sdk/setup` | Спільні помічники setup wizard, allowlist prompts, builder-и стану setup |
|
||||
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | Допоміжні засоби multi-account config/action-gate, допоміжні засоби default-account fallback |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації account-id |
|
||||
| `plugin-sdk/account-resolution` | Допоміжні засоби lookup облікового запису та default-fallback |
|
||||
| `plugin-sdk/account-helpers` | Вузькі допоміжні засоби account-list/account-action |
|
||||
| `plugin-sdk/account-core` | Помічники multi-account config/action-gate, помічники fallback облікового запису за замовчуванням |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, помічники нормалізації account-id |
|
||||
| `plugin-sdk/account-resolution` | Помічники пошуку облікового запису та default-fallback |
|
||||
| `plugin-sdk/account-helpers` | Вузькі помічники account-list/account-action |
|
||||
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline`, `resolveChannelSourceReplyDeliveryMode` |
|
||||
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігурації каналу та загальний побудовник |
|
||||
| `plugin-sdk/bundled-channel-config-schema` | Схеми конфігурації bundled каналів OpenClaw лише для підтримуваних bundled Plugin |
|
||||
| `plugin-sdk/channel-config-schema-legacy` | Застарілий alias сумісності для схем конфігурації bundled-channel |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із fallback bundled-contract |
|
||||
| `plugin-sdk/command-gating` | Вузькі допоміжні засоби gate авторизації команд |
|
||||
| `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігурації каналу та generic builder |
|
||||
| `plugin-sdk/bundled-channel-config-schema` | Bundled схеми конфігурації каналів OpenClaw лише для підтримуваних bundled plugins |
|
||||
| `plugin-sdk/channel-config-schema-legacy` | Застарілий псевдонім сумісності для bundled-channel config schemas |
|
||||
| `plugin-sdk/telegram-command-config` | Помічники нормалізації/валідації користувацьких команд Telegram із bundled-contract fallback |
|
||||
| `plugin-sdk/command-gating` | Вузькі помічники gate авторизації команд |
|
||||
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/фіналізації draft stream |
|
||||
| `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби inbound route та побудовника envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису й dispatch inbound |
|
||||
| `plugin-sdk/messaging-targets` | Допоміжні засоби parsing/matching цілей |
|
||||
| `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження outbound media |
|
||||
| `plugin-sdk/outbound-send-deps` | Легкий lookup залежностей outbound send для адаптерів каналів |
|
||||
| `plugin-sdk/outbound-runtime` | Допоміжні засоби outbound delivery, identity, send delegate, session, formatting і payload planning |
|
||||
| `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації poll |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу thread-binding та адаптера |
|
||||
| `plugin-sdk/agent-media-payload` | Застарілий побудовник agent media payload |
|
||||
| `plugin-sdk/conversation-runtime` | Допоміжні засоби conversation/thread binding, pairing і configured-binding |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб snapshot конфігурації runtime |
|
||||
| `plugin-sdk/runtime-group-policy` | Допоміжні засоби розв’язання group-policy runtime |
|
||||
| `plugin-sdk/channel-status` | Спільні допоміжні засоби snapshot/summary стану каналу |
|
||||
| `plugin-sdk/channel-config-primitives` | Вузькі примітиви config-schema каналу |
|
||||
| `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації config-write каналу |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільні експорти prelude Plugin каналу |
|
||||
| `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання config allowlist |
|
||||
| `plugin-sdk/group-access` | Спільні допоміжні засоби рішень group-access |
|
||||
| `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard direct-DM |
|
||||
| `plugin-sdk/interactive-runtime` | Допоміжні засоби семантичного представлення повідомлень, доставки та застарілих інтерактивних відповідей. Див. [Представлення повідомлень](/uk/plugins/message-presentation) |
|
||||
| `plugin-sdk/channel-inbound` | Barrel сумісності для inbound debounce, matching mention, допоміжних засобів mention-policy та envelope |
|
||||
| `plugin-sdk/channel-inbound-debounce` | Вузькі допоміжні засоби inbound debounce |
|
||||
| `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби mention-policy, маркерів mention і тексту mention без ширшої поверхні inbound runtime |
|
||||
| `plugin-sdk/channel-envelope` | Вузькі допоміжні засоби форматування inbound envelope |
|
||||
| `plugin-sdk/channel-location` | Контекст розташування каналу та допоміжні засоби форматування |
|
||||
| `plugin-sdk/channel-logging` | Допоміжні засоби логування каналу для inbound drops і помилок typing/ack |
|
||||
| `plugin-sdk/channel-send-result` | Типи результатів відповіді |
|
||||
| `plugin-sdk/channel-actions` | Допоміжні засоби message-action каналу, а також застарілі допоміжні засоби нативної схеми, збережені для сумісності Plugin |
|
||||
| `plugin-sdk/channel-route` | Спільні допоміжні засоби нормалізації route, розв’язання цілі на основі parser, перетворення thread-id у рядок, дедуплікації/компактизації ключів route, типи parsed-target і порівняння route/target |
|
||||
| `plugin-sdk/channel-targets` | Допоміжні засоби parsing цілей; викликачі порівняння route мають використовувати `plugin-sdk/channel-route` |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, помічники життєвого циклу/finalization draft stream |
|
||||
| `plugin-sdk/inbound-envelope` | Спільні помічники inbound route та builder envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Спільні помічники record-and-dispatch для inbound |
|
||||
| `plugin-sdk/messaging-targets` | Помічники parsing/matching цілей |
|
||||
| `plugin-sdk/outbound-media` | Спільні помічники завантаження outbound media |
|
||||
| `plugin-sdk/outbound-send-deps` | Легкий пошук залежностей outbound send для адаптерів каналів |
|
||||
| `plugin-sdk/outbound-runtime` | Помічники outbound delivery, identity, send delegate, session, formatting і payload planning |
|
||||
| `plugin-sdk/poll-runtime` | Вузькі помічники нормалізації poll |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Помічники життєвого циклу thread-binding і адаптера |
|
||||
| `plugin-sdk/agent-media-payload` | Застарілий builder agent media payload |
|
||||
| `plugin-sdk/conversation-runtime` | Помічники conversation/thread binding, pairing і configured-binding |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Помічник snapshot runtime-конфігурації |
|
||||
| `plugin-sdk/runtime-group-policy` | Помічники вирішення runtime group-policy |
|
||||
| `plugin-sdk/channel-status` | Спільні помічники snapshot/summary стану каналу |
|
||||
| `plugin-sdk/channel-config-primitives` | Вузькі примітиви channel config-schema |
|
||||
| `plugin-sdk/channel-config-writes` | Помічники авторизації channel config-write |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільні експорти прелюдії channel plugin |
|
||||
| `plugin-sdk/allowlist-config-edit` | Помічники редагування/читання allowlist config |
|
||||
| `plugin-sdk/group-access` | Спільні помічники рішень group-access |
|
||||
| `plugin-sdk/direct-dm` | Спільні помічники direct-DM auth/guard |
|
||||
| `plugin-sdk/discord` | Застарілий фасад сумісності Discord для опублікованого `@openclaw/discord@2026.3.13`; нові plugins мають використовувати generic підшляхи SDK каналу |
|
||||
| `plugin-sdk/interactive-runtime` | Помічники semantic message presentation, delivery і застарілих interactive reply. Див. [подання повідомлень](/uk/plugins/message-presentation) |
|
||||
| `plugin-sdk/channel-inbound` | Barrel сумісності для inbound debounce, mention matching, помічників mention-policy і envelope helpers |
|
||||
| `plugin-sdk/channel-inbound-debounce` | Вузькі помічники inbound debounce |
|
||||
| `plugin-sdk/channel-mention-gating` | Вузькі помічники mention-policy, mention marker і mention text без ширшої поверхні inbound runtime |
|
||||
| `plugin-sdk/channel-envelope` | Вузькі помічники форматування inbound envelope |
|
||||
| `plugin-sdk/channel-location` | Контекст місця каналу та помічники форматування |
|
||||
| `plugin-sdk/channel-logging` | Помічники логування каналу для inbound drops і typing/ack failures |
|
||||
| `plugin-sdk/channel-send-result` | Типи результатів reply |
|
||||
| `plugin-sdk/channel-actions` | Помічники channel message-action, а також застарілі помічники native schema, збережені для сумісності Plugin |
|
||||
| `plugin-sdk/channel-route` | Спільна нормалізація маршрутів, parser-driven target resolution, stringification thread-id, dedupe/compact route keys, типи parsed-target і помічники порівняння route/target |
|
||||
| `plugin-sdk/channel-targets` | Помічники parsing цілей; виклики порівняння маршрутів мають використовувати `plugin-sdk/channel-route` |
|
||||
| `plugin-sdk/channel-contract` | Типи контрактів каналу |
|
||||
| `plugin-sdk/channel-feedback` | Підключення feedback/reaction |
|
||||
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби secret-contract, як-от `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи secret target |
|
||||
| `plugin-sdk/channel-secret-runtime` | Вузькі помічники secret-contract, як-от `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи secret target |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Provider subpaths">
|
||||
<Accordion title="Підшляхи провайдерів">
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/lmstudio` | Підтримуваний фасад постачальника LM Studio для налаштування, виявлення каталогу та підготовки моделі під час виконання |
|
||||
| `plugin-sdk/lmstudio-runtime` | Підтримуваний runtime-фасад LM Studio для типових параметрів локального сервера, виявлення моделей, заголовків запитів і допоміжних засобів завантажених моделей |
|
||||
| `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/самостійно розміщених постачальників |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування самостійно розміщених постачальників, сумісних з OpenAI |
|
||||
| `plugin-sdk/cli-backend` | Типові параметри backend CLI + константи watchdog |
|
||||
| `plugin-sdk/provider-auth-runtime` | Runtime-допоміжні засоби розв’язання API-ключів для Plugin постачальників |
|
||||
| `plugin-sdk/provider-auth-api-key` | Допоміжні засоби onboarding/запису профілю API-ключа, як-от `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | Стандартний збирач результату автентифікації OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для Plugin постачальників |
|
||||
| `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env-var автентифікації постачальника |
|
||||
| `plugin-sdk/lmstudio` | Підтримуваний фасад провайдера LM Studio для налаштування, виявлення каталогу та підготовки моделей під час виконання |
|
||||
| `plugin-sdk/lmstudio-runtime` | Підтримуваний фасад середовища виконання LM Studio для локальних стандартних параметрів сервера, виявлення моделей, заголовків запитів і допоміжних функцій для завантажених моделей |
|
||||
| `plugin-sdk/provider-setup` | Добірні допоміжні функції налаштування локальних/самостійно розгорнутих провайдерів |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Спеціалізовані допоміжні функції налаштування самостійно розгорнутих OpenAI-сумісних провайдерів |
|
||||
| `plugin-sdk/cli-backend` | Стандартні параметри бекенда CLI + константи watchdog |
|
||||
| `plugin-sdk/provider-auth-runtime` | Допоміжні функції розв’язання API-ключів під час виконання для Plugin провайдерів |
|
||||
| `plugin-sdk/provider-auth-api-key` | Допоміжні функції онбордингу API-ключів/запису профілю, як-от `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | Стандартний конструктор результату автентифікації OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | Спільні допоміжні функції інтерактивного входу для Plugin провайдерів |
|
||||
| `plugin-sdk/provider-env-vars` | Допоміжні функції пошуку змінних середовища автентифікації провайдера |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні збирачі replay-policy, допоміжні засоби provider-endpoint і допоміжні засоби нормалізації model-id, як-от `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-catalog-runtime` | Runtime-хук доповнення каталогу постачальника та seams реєстру plugin-provider для контрактних тестів |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори політик відтворення, допоміжні функції кінцевих точок провайдерів і допоміжні функції нормалізації ID моделей, як-от `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-catalog-runtime` | Хук середовища виконання для доповнення каталогу провайдера та шви реєстру Plugin-провайдерів для контрактних тестів |
|
||||
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `buildManifestModelProviderConfig`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-http` | Універсальні допоміжні засоби можливостей HTTP/endpoint постачальника, HTTP-помилки постачальника та допоміжні засоби multipart-форми для аудіотранскрипції |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту config/selection для web-fetch, як-от `enablePluginInConfig` і `WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешу постачальника web-fetch |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби config/credential для web-search для постачальників, яким не потрібне підключення plugin-enable |
|
||||
| `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту config/credential для web-search, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setters/getters облікових даних |
|
||||
| `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешу/runtime постачальника web-search |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика, а також допоміжні засоби сумісності xAI, як-от `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібне |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні допоміжні засоби wrapper для Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-transport-runtime` | Допоміжні засоби нативного транспорту постачальника, як-от guarded fetch, перетворення транспортних повідомлень і writable transport event streams |
|
||||
| `plugin-sdk/provider-onboard` | Допоміжні засоби патчів onboarding-конфігурації |
|
||||
| `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache |
|
||||
| `plugin-sdk/group-activation` | Вузькі допоміжні засоби режиму активації групи та розбору команд |
|
||||
| `plugin-sdk/provider-http` | Загальні допоміжні функції можливостей HTTP/кінцевих точок провайдерів, HTTP-помилки провайдерів і допоміжні функції multipart-форм для транскрипції аудіо |
|
||||
| `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні функції контракту конфігурації/вибору web-fetch, як-от `enablePluginInConfig` і `WebFetchProviderPlugin` |
|
||||
| `plugin-sdk/provider-web-fetch` | Допоміжні функції реєстрації/кешування провайдера web-fetch |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні функції конфігурації/облікових даних web-search для провайдерів, яким не потрібне підключення увімкнення Plugin |
|
||||
| `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні функції контракту конфігурації/облікових даних web-search, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, а також обмежені за областю сетери/гетери облікових даних |
|
||||
| `plugin-sdk/provider-web-search` | Допоміжні функції реєстрації/кешування/середовища виконання провайдера web-search |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика та допоміжні функції сумісності xAI, як-от `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні |
|
||||
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоків і спільні допоміжні функції обгорток Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-transport-runtime` | Допоміжні функції нативного транспорту провайдерів, як-от захищений fetch, перетворення транспортних повідомлень і записувані потоки транспортних подій |
|
||||
| `plugin-sdk/provider-onboard` | Допоміжні функції патчів конфігурації онбордингу |
|
||||
| `plugin-sdk/global-singleton` | Допоміжні функції локальних для процесу singleton/map/cache |
|
||||
| `plugin-sdk/group-activation` | Вузькі допоміжні функції режиму активації груп і парсингу команд |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Auth and security subpaths">
|
||||
<Accordion title="Підшляхи автентифікації та безпеки">
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, зокрема форматування меню динамічних аргументів, допоміжні засоби авторизації відправника |
|
||||
| `plugin-sdk/command-status` | Збирачі повідомлень команд/довідки, як-от `buildCommandsMessagePaginated` і `buildHelpMessage` |
|
||||
| `plugin-sdk/approval-auth-runtime` | Допоміжні засоби розв’язання approver і action-auth у тому самому чаті |
|
||||
| `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра нативного підтвердження exec |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Адаптери нативних можливостей/доставки підтверджень |
|
||||
| `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб розв’язання approval Gateway |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | Легкі допоміжні засоби завантаження нативного approval adapter для гарячих entrypoint каналів |
|
||||
| `plugin-sdk/approval-handler-runtime` | Ширші runtime-допоміжні засоби approval handler; віддавайте перевагу вужчим adapter/gateway seams, коли їх достатньо |
|
||||
| `plugin-sdk/approval-native-runtime` | Допоміжні засоби нативної цілі підтвердження + прив’язки облікового запису |
|
||||
| `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді на підтвердження exec/plugin |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні засоби payload підтвердження exec/plugin, допоміжні засоби маршрутизації/runtime нативного підтвердження та допоміжні засоби структурованого відображення підтвердження, як-от `formatApprovalDisplayPath` |
|
||||
| `plugin-sdk/reply-dedupe` | Вузькі допоміжні засоби скидання дедуплікації вхідних відповідей |
|
||||
| `plugin-sdk/channel-contract-testing` | Вузькі допоміжні засоби тестування контракту каналу без широкого testing barrel |
|
||||
| `plugin-sdk/command-auth-native` | Нативна автентифікація команд, форматування меню динамічних аргументів і допоміжні засоби нативної цілі сеансу |
|
||||
| `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд |
|
||||
| `plugin-sdk/command-primitives-runtime` | Легкі предикати тексту команд для гарячих шляхів каналів |
|
||||
| `plugin-sdk/command-surface` | Нормалізація command-body і допоміжні засоби command-surface |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні функції реєстру команд, зокрема форматування меню динамічних аргументів, допоміжні функції авторизації відправника |
|
||||
| `plugin-sdk/command-status` | Конструктори повідомлень команд/довідки, як-от `buildCommandsMessagePaginated` і `buildHelpMessage` |
|
||||
| `plugin-sdk/approval-auth-runtime` | Допоміжні функції розв’язання затверджувача та автентифікації дій у тому самому чаті |
|
||||
| `plugin-sdk/approval-client-runtime` | Допоміжні функції профілю/фільтра нативного затвердження exec |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Нативні адаптери можливостей/доставки затверджень |
|
||||
| `plugin-sdk/approval-gateway-runtime` | Спільна допоміжна функція розв’язання Gateway для затверджень |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | Легковагові допоміжні функції завантаження нативного адаптера затверджень для гарячих точок входу каналів |
|
||||
| `plugin-sdk/approval-handler-runtime` | Ширші допоміжні функції середовища виконання обробника затверджень; надавайте перевагу вужчим швам адаптера/Gateway, коли їх достатньо |
|
||||
| `plugin-sdk/approval-native-runtime` | Допоміжні функції нативної цілі затвердження + прив’язки облікового запису |
|
||||
| `plugin-sdk/approval-reply-runtime` | Допоміжні функції payload відповіді затвердження exec/Plugin |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні функції payload затвердження exec/Plugin, допоміжні функції маршрутизації/середовища виконання нативних затверджень і допоміжні функції структурованого відображення затверджень, як-от `formatApprovalDisplayPath` |
|
||||
| `plugin-sdk/reply-dedupe` | Вузькі допоміжні функції скидання дедуплікації вхідних відповідей |
|
||||
| `plugin-sdk/channel-contract-testing` | Вузькі допоміжні функції тестування контрактів каналів без широкого barrel для тестування |
|
||||
| `plugin-sdk/command-auth-native` | Нативна автентифікація команд, форматування меню динамічних аргументів і допоміжні функції нативної цілі сеансу |
|
||||
| `plugin-sdk/command-detection` | Спільні допоміжні функції виявлення команд |
|
||||
| `plugin-sdk/command-primitives-runtime` | Легковагові предикати тексту команд для гарячих шляхів каналів |
|
||||
| `plugin-sdk/command-surface` | Нормалізація тіла команд і допоміжні функції поверхні команд |
|
||||
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-contract для поверхонь секретів каналу/Plugin |
|
||||
| `plugin-sdk/secret-ref-runtime` | Вузькі `coerceSecretRef` і допоміжні засоби типізації SecretRef для розбору secret-contract/config |
|
||||
| `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, DM gating, external-content, редагування чутливого тексту, порівняння секретів за сталий час і збирання секретів |
|
||||
| `plugin-sdk/ssrf-policy` | Допоміжні засоби allowlist хостів і політики SSRF для приватної мережі |
|
||||
| `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої runtime-поверхні infra |
|
||||
| `plugin-sdk/ssrf-runtime` | Pinned-dispatcher, SSRF-guarded fetch, SSRF-помилка та допоміжні засоби політики SSRF |
|
||||
| `plugin-sdk/secret-input` | Допоміжні засоби розбору введення секретів |
|
||||
| `plugin-sdk/webhook-ingress` | Допоміжні засоби Webhook-запиту/цілі та приведення raw websocket/body |
|
||||
| `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру/таймауту тіла запиту |
|
||||
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні функції збирання контрактів секретів для поверхонь секретів каналів/Plugin |
|
||||
| `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні функції `coerceSecretRef` і типізації SecretRef для парсингу контрактів секретів/конфігурації |
|
||||
| `plugin-sdk/security-runtime` | Спільні допоміжні функції довіри, обмеження DM, зовнішнього вмісту, редагування чутливого тексту, порівняння секретів за сталий час і збирання секретів |
|
||||
| `plugin-sdk/ssrf-policy` | Допоміжні функції списку дозволених хостів і політики SSRF для приватної мережі |
|
||||
| `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні функції закріпленого диспетчера без широкої інфраструктурної поверхні середовища виконання |
|
||||
| `plugin-sdk/ssrf-runtime` | Допоміжні функції закріпленого диспетчера, захищеного від SSRF fetch, помилок SSRF і політик SSRF |
|
||||
| `plugin-sdk/secret-input` | Допоміжні функції парсингу введення секретів |
|
||||
| `plugin-sdk/webhook-ingress` | Допоміжні функції запиту/цілі Webhook і приведення сирого websocket/body |
|
||||
| `plugin-sdk/webhook-request-guards` | Допоміжні функції розміру/тайм-ауту тіла запиту |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи середовища виконання та сховища">
|
||||
| Підшлях | Основні експорти |
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/runtime` | Широкі помічники для середовища виконання, журналювання, резервного копіювання та встановлення Plugin |
|
||||
| `plugin-sdk/runtime-env` | Вузькі помічники для середовища виконання env, logger, timeout, retry та backoff |
|
||||
| `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових значень, розбору CDP URL і помічників автентифікації керування браузером |
|
||||
| `plugin-sdk/channel-runtime-context` | Загальні помічники реєстрації та пошуку контексту середовища виконання каналу |
|
||||
| `plugin-sdk/runtime` | Широкі допоміжні засоби для середовища виконання, журналювання, резервного копіювання та встановлення Plugin |
|
||||
| `plugin-sdk/runtime-env` | Вузькі допоміжні засоби для env середовища виконання, logger, timeout, retry і backoff |
|
||||
| `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових значень, розбору URL CDP і допоміжних засобів автентифікації керування браузером |
|
||||
| `plugin-sdk/channel-runtime-context` | Допоміжні засоби реєстрації та пошуку generic контексту середовища виконання каналу |
|
||||
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні помічники команд, хуків, HTTP та інтерактивної роботи Plugin |
|
||||
| `plugin-sdk/hook-runtime` | Спільні помічники конвеєра Webhook/внутрішніх хуків |
|
||||
| `plugin-sdk/lazy-runtime` | Помічники лінивого імпорту/прив’язки середовища виконання, як-от `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Помічники виконання процесів |
|
||||
| `plugin-sdk/cli-runtime` | Помічники форматування CLI, очікування, версії, виклику аргументів і лінивих груп команд |
|
||||
| `plugin-sdk/gateway-runtime` | Клієнт Gateway, RPC CLI Gateway, помилки протоколу Gateway та помічники патчів статусу каналу |
|
||||
| `plugin-sdk/config-types` | Поверхня конфігурації лише на рівні типів для форм конфігурації Plugin, як-от `OpenClawConfig`, і типів конфігурації каналів/провайдерів |
|
||||
| `plugin-sdk/plugin-config-runtime` | Помічники пошуку конфігурації Plugin у середовищі виконання, як-от `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` |
|
||||
| `plugin-sdk/config-mutation` | Помічники транзакційної зміни конфігурації, як-от `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Помічники знімка конфігурації поточного процесу, як-от `getRuntimeConfig`, `getRuntimeConfigSnapshot`, і сетери тестових знімків |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд Plugin, hook, http та інтерактивної взаємодії |
|
||||
| `plugin-sdk/hook-runtime` | Спільні допоміжні засоби конвеєра Webhook/внутрішніх hook |
|
||||
| `plugin-sdk/lazy-runtime` | Допоміжні засоби лінивого імпорту/прив’язування середовища виконання, як-от `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Допоміжні засоби виконання процесів |
|
||||
| `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування, версії, виклику аргументів і лінивих груп команд |
|
||||
| `plugin-sdk/gateway-runtime` | Клієнт Gateway, RPC CLI Gateway, помилки протоколу Gateway і допоміжні засоби patch статусу каналу |
|
||||
| `plugin-sdk/config-types` | Поверхня конфігурації лише для типів для форм конфігурації Plugin, як-от `OpenClawConfig`, і типів конфігурації каналів/провайдерів |
|
||||
| `plugin-sdk/plugin-config-runtime` | Допоміжні засоби пошуку конфігурації Plugin у середовищі виконання, як-от `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` |
|
||||
| `plugin-sdk/config-mutation` | Допоміжні засоби транзакційної зміни конфігурації, як-от `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Допоміжні засоби знімка конфігурації поточного процесу, як-от `getRuntimeConfig`, `getRuntimeConfigSnapshot`, і тестові setter знімків |
|
||||
| `plugin-sdk/telegram-command-config` | Нормалізація назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли вбудована контрактна поверхня Telegram недоступна |
|
||||
| `plugin-sdk/text-autolink-runtime` | Виявлення автопосилань на файлові посилання без широкого barrel text-runtime |
|
||||
| `plugin-sdk/approval-runtime` | Помічники затвердження exec/Plugin, конструктори можливостей затвердження, помічники auth/profile, помічники нативної маршрутизації/середовища виконання та форматування структурованого шляху відображення затвердження |
|
||||
| `plugin-sdk/reply-runtime` | Спільні помічники середовища виконання для вхідних повідомлень/відповідей, поділу на фрагменти, диспетчеризації, Heartbeat, планувальника відповідей |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі помічники диспетчеризації/фіналізації відповідей і міток розмов |
|
||||
| `plugin-sdk/reply-history` | Спільні помічники коротковіконної історії відповідей і маркери, як-от `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/text-autolink-runtime` | Виявлення autolink для посилань на файли без широкого barrel text-runtime |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні засоби схвалення exec/Plugin, побудовники можливостей схвалення, допоміжні засоби auth/profile, native routing/runtime і форматування структурованого шляху відображення схвалення |
|
||||
| `plugin-sdk/reply-runtime` | Спільні допоміжні засоби середовища виконання inbound/reply, chunking, dispatch, Heartbeat, планувальник відповідей |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповіді та міток розмов |
|
||||
| `plugin-sdk/reply-history` | Спільні допоміжні засоби коротковіконної історії відповідей і маркери, як-от `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Вузькі помічники поділу тексту/markdown на фрагменти |
|
||||
| `plugin-sdk/session-store-runtime` | Помічники шляху сховища сесій, ключа сесії, updated-at і зміни сховища |
|
||||
| `plugin-sdk/cron-store-runtime` | Помічники шляху/завантаження/збереження сховища Cron |
|
||||
| `plugin-sdk/state-paths` | Помічники шляхів каталогів стану/OAuth |
|
||||
| `plugin-sdk/routing` | Помічники маршруту/ключа сесії/прив’язки акаунта, як-от `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Спільні помічники зведення статусу каналу/акаунта, типові значення стану середовища виконання та помічники метаданих проблем |
|
||||
| `plugin-sdk/target-resolver-runtime` | Спільні помічники розв’язувача цілей |
|
||||
| `plugin-sdk/string-normalization-runtime` | Помічники нормалізації slug/рядків |
|
||||
| `plugin-sdk/request-url` | Видобування рядкових URL з inputs, подібних до fetch/request |
|
||||
| `plugin-sdk/run-command` | Запускач команд із таймером і нормалізованими результатами stdout/stderr |
|
||||
| `plugin-sdk/param-readers` | Спільні зчитувачі параметрів інструментів/CLI |
|
||||
| `plugin-sdk/tool-payload` | Видобування нормалізованих payload з об’єктів результату інструмента |
|
||||
| `plugin-sdk/tool-send` | Видобування канонічних полів цілі надсилання з аргументів інструмента |
|
||||
| `plugin-sdk/temp-path` | Спільні помічники шляхів тимчасових завантажень |
|
||||
| `plugin-sdk/logging-core` | Помічники logger підсистем і редагування чутливих даних |
|
||||
| `plugin-sdk/markdown-table-runtime` | Помічники режиму таблиць Markdown і перетворення |
|
||||
| `plugin-sdk/model-session-runtime` | Помічники перевизначення моделі/сесії, як-от `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` |
|
||||
| `plugin-sdk/talk-config-runtime` | Помічники розв’язання конфігурації провайдера talk |
|
||||
| `plugin-sdk/json-store` | Невеликі помічники читання/запису стану JSON |
|
||||
| `plugin-sdk/file-lock` | Помічники повторно вхідного блокування файлів |
|
||||
| `plugin-sdk/persistent-dedupe` | Помічники кешу дедуплікації з дисковою підтримкою |
|
||||
| `plugin-sdk/acp-runtime` | Помічники середовища виконання/сесії ACP і диспетчеризації відповідей |
|
||||
| `plugin-sdk/acp-runtime-backend` | Легкі помічники реєстрації бекенда ACP і диспетчеризації відповідей для Plugin, завантажених під час запуску |
|
||||
| `plugin-sdk/acp-binding-resolve-runtime` | Розв’язання прив’язок ACP лише для читання без імпортів запуску життєвого циклу |
|
||||
| `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/Markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій, ключа сесії, updated-at і зміни сховища |
|
||||
| `plugin-sdk/cron-store-runtime` | Допоміжні засоби шляху/завантаження/збереження сховища Cron |
|
||||
| `plugin-sdk/state-paths` | Допоміжні засоби шляхів директорій стану/OAuth |
|
||||
| `plugin-sdk/routing` | Допоміжні засоби route/session-key/account binding, як-от `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку статусу каналу/облікового запису, типові значення стану середовища виконання та допоміжні засоби метаданих issue |
|
||||
| `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби розв’язувача цілей |
|
||||
| `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків |
|
||||
| `plugin-sdk/request-url` | Витягує рядкові URL з fetch/request-подібних входів |
|
||||
| `plugin-sdk/run-command` | Виконавець команд із тайм-аутом і нормалізованими результатами stdout/stderr |
|
||||
| `plugin-sdk/param-readers` | Спільні reader параметрів інструментів/CLI |
|
||||
| `plugin-sdk/tool-payload` | Витягує нормалізовані payload з об’єктів результату інструмента |
|
||||
| `plugin-sdk/tool-send` | Витягує канонічні поля цілі надсилання з аргументів інструмента |
|
||||
| `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів тимчасового завантаження |
|
||||
| `plugin-sdk/logging-core` | Допоміжні засоби logger підсистем і редагування секретних даних |
|
||||
| `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму й перетворення Markdown-таблиць |
|
||||
| `plugin-sdk/model-session-runtime` | Допоміжні засоби перевизначення моделі/сесії, як-от `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` |
|
||||
| `plugin-sdk/talk-config-runtime` | Допоміжні засоби розв’язання конфігурації talk-провайдера |
|
||||
| `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису JSON-стану |
|
||||
| `plugin-sdk/file-lock` | Допоміжні засоби реентерабельного file-lock |
|
||||
| `plugin-sdk/persistent-dedupe` | Допоміжні засоби дискового dedupe-кешу |
|
||||
| `plugin-sdk/acp-runtime` | Допоміжні засоби середовища виконання/сесії ACP і dispatch відповідей |
|
||||
| `plugin-sdk/acp-runtime-backend` | Легкі допоміжні засоби реєстрації бекенду ACP і dispatch відповідей для Plugin, завантажених під час запуску |
|
||||
| `plugin-sdk/acp-binding-resolve-runtime` | Розв’язання ACP binding лише для читання без імпортів запуску lifecycle |
|
||||
| `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації середовища виконання агента |
|
||||
| `plugin-sdk/boolean-param` | Нестрогий зчитувач булевих параметрів |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Помічники розв’язання зіставлення небезпечних імен |
|
||||
| `plugin-sdk/device-bootstrap` | Помічники bootstrap пристрою і токенів сполучення |
|
||||
| `plugin-sdk/extension-shared` | Спільні примітиви помічників пасивного каналу, статусу та ambient proxy |
|
||||
| `plugin-sdk/models-provider-runtime` | Помічники відповідей команди/провайдера `/models` |
|
||||
| `plugin-sdk/skill-commands-runtime` | Помічники переліку команд Skills |
|
||||
| `plugin-sdk/native-command-registry` | Помічники реєстру/побудови/серіалізації нативних команд |
|
||||
| `plugin-sdk/agent-harness` | Експериментальна поверхня довірених Plugin для низькорівневих harness агентів: типи harness, помічники керування/скасування активного запуску, помічники мосту інструментів OpenClaw, помічники політик інструментів плану середовища виконання, класифікація результатів термінала, помічники форматування/деталізації прогресу інструментів і утиліти результатів спроб |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Помічники виявлення endpoint Z.AI |
|
||||
| `plugin-sdk/async-lock-runtime` | Помічник локального для процесу async lock для малих файлів стану середовища виконання |
|
||||
| `plugin-sdk/channel-activity-runtime` | Помічник телеметрії активності каналу |
|
||||
| `plugin-sdk/concurrency-runtime` | Помічник обмеженої конкурентності асинхронних завдань |
|
||||
| `plugin-sdk/dedupe-runtime` | Помічники кешу дедуплікації в пам’яті |
|
||||
| `plugin-sdk/delivery-queue-runtime` | Помічник drain очікуваних вихідних доставок |
|
||||
| `plugin-sdk/file-access-runtime` | Помічники безпечних шляхів до локальних файлів і джерел медіа |
|
||||
| `plugin-sdk/heartbeat-runtime` | Помічники подій і видимості Heartbeat |
|
||||
| `plugin-sdk/number-runtime` | Помічник числового приведення |
|
||||
| `plugin-sdk/secure-random-runtime` | Помічники безпечних токенів/UUID |
|
||||
| `plugin-sdk/system-event-runtime` | Помічники черги системних подій |
|
||||
| `plugin-sdk/transport-ready-runtime` | Помічник очікування готовності транспорту |
|
||||
| `plugin-sdk/infra-runtime` | Застарілий shim сумісності; використовуйте наведені вище сфокусовані підшляхи середовища виконання |
|
||||
| `plugin-sdk/collection-runtime` | Невеликі помічники обмеженого кешу |
|
||||
| `plugin-sdk/diagnostic-runtime` | Помічники діагностичних прапорців, подій і контексту трасування |
|
||||
| `plugin-sdk/error-runtime` | Граф помилок, форматування, спільні помічники класифікації помилок, `isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | Обгорнутий fetch, proxy і помічники pinned lookup |
|
||||
| `plugin-sdk/boolean-param` | Нестрогий reader булевого параметра |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби розв’язання зіставлення небезпечних імен |
|
||||
| `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токенів pairing |
|
||||
| `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів пасивного каналу, статусу й ambient proxy |
|
||||
| `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді команди/провайдера `/models` |
|
||||
| `plugin-sdk/skill-commands-runtime` | Допоміжні засоби перелічення команд Skills |
|
||||
| `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/побудови/серіалізації native команд |
|
||||
| `plugin-sdk/agent-harness` | Експериментальна поверхня довірених Plugin для низькорівневих harness агентів: типи harness, допоміжні засоби steer/abort active-run, допоміжні засоби мосту інструментів OpenClaw, допоміжні засоби політики інструментів runtime-plan, класифікація результатів термінала, допоміжні засоби форматування/деталізації перебігу інструментів і утиліти результатів спроб |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI |
|
||||
| `plugin-sdk/async-lock-runtime` | Допоміжний засіб локального для процесу async lock для невеликих файлів стану середовища виконання |
|
||||
| `plugin-sdk/channel-activity-runtime` | Допоміжний засіб телеметрії активності каналу |
|
||||
| `plugin-sdk/concurrency-runtime` | Допоміжний засіб обмеженої concurrency async-завдань |
|
||||
| `plugin-sdk/dedupe-runtime` | Допоміжні засоби in-memory dedupe-кешу |
|
||||
| `plugin-sdk/delivery-queue-runtime` | Допоміжний засіб drain для outbound pending-delivery |
|
||||
| `plugin-sdk/file-access-runtime` | Допоміжні засоби безпечних шляхів local-file і media-source |
|
||||
| `plugin-sdk/heartbeat-runtime` | Допоміжні засоби подій і видимості Heartbeat |
|
||||
| `plugin-sdk/number-runtime` | Допоміжний засіб числового приведення |
|
||||
| `plugin-sdk/secure-random-runtime` | Допоміжні засоби безпечних токенів/UUID |
|
||||
| `plugin-sdk/system-event-runtime` | Допоміжні засоби черги системних подій |
|
||||
| `plugin-sdk/transport-ready-runtime` | Допоміжний засіб очікування готовності транспорту |
|
||||
| `plugin-sdk/infra-runtime` | Застарілий compatibility shim; використовуйте наведені вище спеціалізовані підшляхи середовища виконання |
|
||||
| `plugin-sdk/collection-runtime` | Допоміжні засоби невеликого обмеженого кешу |
|
||||
| `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних flag, event і trace-context |
|
||||
| `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | Допоміжні засоби wrapped fetch, proxy і pinned lookup |
|
||||
| `plugin-sdk/runtime-fetch` | Runtime fetch з урахуванням dispatcher без імпортів proxy/guarded-fetch |
|
||||
| `plugin-sdk/response-limit-runtime` | Обмежений зчитувач тіла відповіді без широкої поверхні середовища виконання медіа |
|
||||
| `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки розмови без налаштованої маршрутизації прив’язок або сховищ сполучення |
|
||||
| `plugin-sdk/session-store-runtime` | Помічники сховища сесій без широких імпортів запису/обслуговування конфігурації |
|
||||
| `plugin-sdk/context-visibility-runtime` | Розв’язання видимості контексту і фільтрування додаткового контексту без широких імпортів конфігурації/безпеки |
|
||||
| `plugin-sdk/string-coerce-runtime` | Вузькі помічники приведення й нормалізації примітивних записів/рядків без імпортів markdown/logging |
|
||||
| `plugin-sdk/host-runtime` | Помічники нормалізації hostname і SCP host |
|
||||
| `plugin-sdk/retry-runtime` | Помічники конфігурації retry і запуску retry |
|
||||
| `plugin-sdk/agent-runtime` | Помічники каталогу агента/ідентичності/робочого простору |
|
||||
| `plugin-sdk/directory-runtime` | Запит/дедуплікація каталогів на основі конфігурації |
|
||||
| `plugin-sdk/response-limit-runtime` | Обмежений reader response-body без широкої media runtime surface |
|
||||
| `plugin-sdk/session-binding-runtime` | Поточний стан binding розмови без налаштованого binding routing або pairing stores |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні засоби session-store без широких імпортів запису/обслуговування конфігурації |
|
||||
| `plugin-sdk/context-visibility-runtime` | Розв’язання видимості контексту та фільтрація додаткового контексту без широких імпортів конфігурації/безпеки |
|
||||
| `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення й нормалізації примітивних записів/рядків без імпортів markdown/logging |
|
||||
| `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і SCP host |
|
||||
| `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry та виконавця retry |
|
||||
| `plugin-sdk/agent-runtime` | Допоміжні засоби директорії/ідентичності/робочого простору агента |
|
||||
| `plugin-sdk/directory-runtime` | Запит/дедуп директорії на основі конфігурації |
|
||||
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Capability and testing subpaths">
|
||||
| Підшлях | Ключові експорти |
|
||||
<Accordion title="Підшляхи можливостей і тестування">
|
||||
| Підшлях | Основні експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/media-runtime` | Спільні допоміжні засоби отримання, перетворення й збереження медіа, а також побудовники медіа-навантажень |
|
||||
| `plugin-sdk/media-store` | Вузькі допоміжні засоби сховища медіа, як-от `saveMediaBuffer` |
|
||||
| `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби резервного перемикання для генерації медіа, вибору кандидатів і повідомлень про відсутню модель |
|
||||
| `plugin-sdk/media-understanding` | Типи провайдера розуміння медіа, а також експорти допоміжних засобів зображень і аудіо для провайдерів |
|
||||
| `plugin-sdk/text-runtime` | Спільні допоміжні засоби для тексту, markdown і журналювання, як-от вилучення тексту, видимого асистенту, допоміжні засоби рендерингу, поділу на фрагменти й таблиць markdown, допоміжні засоби редагування, допоміжні засоби тегів директив і утиліти безпечного тексту |
|
||||
| `plugin-sdk/text-chunking` | Допоміжний засіб поділу вихідного тексту на фрагменти |
|
||||
| `plugin-sdk/speech` | Типи мовленнєвого провайдера, а також експорти директив, реєстру, валідації, побудовника TTS, сумісного з OpenAI, і допоміжних засобів мовлення для провайдерів |
|
||||
| `plugin-sdk/speech-core` | Спільні типи мовленнєвого провайдера, реєстр, директива, нормалізація й експорти допоміжних засобів мовлення |
|
||||
| `plugin-sdk/realtime-transcription` | Типи провайдера транскрипції в реальному часі, допоміжні засоби реєстру й спільний допоміжний засіб сесії WebSocket |
|
||||
| `plugin-sdk/realtime-voice` | Типи провайдера голосу в реальному часі й допоміжні засоби реєстру |
|
||||
| `plugin-sdk/image-generation` | Типи провайдера генерації зображень, а також допоміжні засоби URL зображувальних ресурсів/даних і побудовник провайдера зображень, сумісний з OpenAI |
|
||||
| `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, резервне перемикання, автентифікація й допоміжні засоби реєстру |
|
||||
| `plugin-sdk/music-generation` | Типи провайдера/запиту/результату генерації музики |
|
||||
| `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби резервного перемикання, пошук провайдера й розбір посилань на модель |
|
||||
| `plugin-sdk/video-generation` | Типи провайдера/запиту/результату генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби резервного перемикання, пошук провайдера й розбір посилань на модель |
|
||||
| `plugin-sdk/webhook-targets` | Реєстр цілей Webhook і допоміжні засоби встановлення маршрутів |
|
||||
| `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху Webhook |
|
||||
| `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа |
|
||||
| `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK |
|
||||
| `plugin-sdk/testing` | Широкий barrel сумісності для застарілих тестів Plugin. Нові тести розширень мають натомість імпортувати сфокусовані підшляхи SDK, як-от `plugin-sdk/agent-runtime-test-contracts`, `plugin-sdk/plugin-test-runtime`, `plugin-sdk/channel-test-helpers`, `plugin-sdk/test-env` або `plugin-sdk/test-fixtures` |
|
||||
| `plugin-sdk/plugin-test-api` | Мінімальний допоміжний засіб `createTestPluginApi` для прямих модульних тестів реєстрації Plugin без імпорту мостів тестових допоміжних засобів репозиторію |
|
||||
| `plugin-sdk/agent-runtime-test-contracts` | Нативні фікстури контрактів адаптера середовища виконання агента для тестів автентифікації, доставки, fallback, hook інструментів, prompt overlay, схеми й проєкції транскрипту |
|
||||
| `plugin-sdk/channel-test-helpers` | Орієнтовані на канали тестові допоміжні засоби для загальних контрактів дій/налаштування/статусу, перевірок каталогів, життєвого циклу запуску облікового запису, потоків send-config, моків середовища виконання, проблем статусу, вихідної доставки й реєстрації hook |
|
||||
| `plugin-sdk/channel-target-testing` | Спільний набір випадків помилок розв’язання цілей для тестів каналів |
|
||||
| `plugin-sdk/plugin-test-contracts` | Допоміжні засоби контрактів пакета Plugin, реєстрації, публічного артефакту, прямого імпорту, API середовища виконання й побічних ефектів імпорту |
|
||||
| `plugin-sdk/provider-test-contracts` | Допоміжні засоби контрактів середовища виконання провайдера, автентифікації, виявлення, onboard, каталогу, майстра, медіаможливостей, політики відтворення, живого аудіо realtime STT, вебпошуку/отримання й потоку |
|
||||
| `plugin-sdk/provider-http-test-mocks` | Опціональні HTTP/auth моки Vitest для тестів провайдерів, які перевіряють `plugin-sdk/provider-http` |
|
||||
| `plugin-sdk/test-fixtures` | Загальні фікстури захоплення середовища виконання CLI, контексту пісочниці, записувача skill, повідомлення агента, системної події, перезавантаження модуля, шляху до bundled Plugin, термінального тексту, поділу на фрагменти, auth-токена й типізованих cases |
|
||||
| `plugin-sdk/test-node-mocks` | Сфокусовані допоміжні засоби моків вбудованих модулів Node для використання всередині фабрик Vitest `vi.mock("node:*")` |
|
||||
| `plugin-sdk/media-runtime` | Спільні помічники отримання/перетворення/зберігання медіа, а також конструктори медіа-навантажень |
|
||||
| `plugin-sdk/media-store` | Вузькі помічники сховища медіа, як-от `saveMediaBuffer` |
|
||||
| `plugin-sdk/media-generation-runtime` | Спільні помічники резервного перемикання для генерації медіа, вибір кандидатів і повідомлення про відсутню модель |
|
||||
| `plugin-sdk/media-understanding` | Типи провайдерів розуміння медіа, а також експорти помічників для зображень/аудіо, орієнтовані на провайдерів |
|
||||
| `plugin-sdk/text-runtime` | Спільні помічники для тексту/markdown/журналювання, як-от вилучення видимого для асистента тексту, помічники рендерингу/розбиття/таблиць markdown, помічники редагування, помічники тегів директив і утиліти безпечного тексту |
|
||||
| `plugin-sdk/text-chunking` | Помічник розбиття вихідного тексту |
|
||||
| `plugin-sdk/speech` | Типи мовних провайдерів, а також орієнтовані на провайдерів експорти директив, реєстру, валідації, OpenAI-сумісного конструктора TTS і мовних помічників |
|
||||
| `plugin-sdk/speech-core` | Спільні типи мовних провайдерів, експорти реєстру, директив, нормалізації та мовних помічників |
|
||||
| `plugin-sdk/realtime-transcription` | Типи провайдерів транскрипції в реальному часі, помічники реєстру та спільний помічник WebSocket-сеансу |
|
||||
| `plugin-sdk/realtime-voice` | Типи провайдерів голосу в реальному часі та помічники реєстру |
|
||||
| `plugin-sdk/image-generation` | Типи провайдерів генерації зображень, а також помічники ресурсів зображень/data URL і OpenAI-сумісний конструктор провайдера зображень |
|
||||
| `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, резервне перемикання, автентифікація та помічники реєстру |
|
||||
| `plugin-sdk/music-generation` | Типи провайдерів/запитів/результатів генерації музики |
|
||||
| `plugin-sdk/music-generation-core` | Спільні типи генерації музики, помічники резервного перемикання, пошук провайдера та розбір посилань на модель |
|
||||
| `plugin-sdk/video-generation` | Типи провайдерів/запитів/результатів генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільні типи генерації відео, помічники резервного перемикання, пошук провайдера та розбір посилань на модель |
|
||||
| `plugin-sdk/webhook-targets` | Реєстр цілей Webhook і помічники встановлення маршрутів |
|
||||
| `plugin-sdk/webhook-path` | Помічники нормалізації шляху Webhook |
|
||||
| `plugin-sdk/web-media` | Спільні помічники завантаження віддалених/локальних медіа |
|
||||
| `plugin-sdk/zod` | Повторно експортований `zod` для споживачів plugin SDK |
|
||||
| `plugin-sdk/testing` | Широкий compatibility barrel для застарілих тестів plugin. Нові тести розширень натомість мають імпортувати сфокусовані підшляхи SDK, як-от `plugin-sdk/agent-runtime-test-contracts`, `plugin-sdk/plugin-test-runtime`, `plugin-sdk/channel-test-helpers`, `plugin-sdk/test-env` або `plugin-sdk/test-fixtures` |
|
||||
| `plugin-sdk/plugin-test-api` | Мінімальний помічник `createTestPluginApi` для unit-тестів прямої реєстрації plugin без імпорту мостів тестових помічників репозиторію |
|
||||
| `plugin-sdk/agent-runtime-test-contracts` | Нативні фікстури контрактів адаптера agent-runtime для тестів автентифікації, доставки, fallback, tool-hook, prompt-overlay, схеми та проєкції транскрипту |
|
||||
| `plugin-sdk/channel-test-helpers` | Орієнтовані на канал тестові помічники для загальних контрактів дій/налаштування/статусу, перевірок каталогів, життєвого циклу запуску облікового запису, потоків send-config, runtime-моків, проблем статусу, вихідної доставки та реєстрації хуків |
|
||||
| `plugin-sdk/channel-target-testing` | Спільний набір випадків помилок визначення цілі для тестів каналів |
|
||||
| `plugin-sdk/plugin-test-contracts` | Помічники контрактів пакета plugin, реєстрації, публічного артефакту, прямого імпорту, runtime API та побічних ефектів імпорту |
|
||||
| `plugin-sdk/provider-test-contracts` | Помічники контрактів runtime провайдера, автентифікації, виявлення, onboard, каталогу, майстра, медіа-можливостей, політики replay, live-audio realtime STT, web-search/fetch і потоків |
|
||||
| `plugin-sdk/provider-http-test-mocks` | Opt-in HTTP/auth моки Vitest для тестів провайдерів, які перевіряють `plugin-sdk/provider-http` |
|
||||
| `plugin-sdk/test-fixtures` | Загальні фікстури захоплення CLI runtime, контексту sandbox, записувача skill, agent-message, system-event, перезавантаження модуля, шляху bundled plugin, terminal-text, розбиття, auth-token і типізованих випадків |
|
||||
| `plugin-sdk/test-node-mocks` | Сфокусовані помічники моків вбудованих модулів Node для використання всередині фабрик Vitest `vi.mock("node:*")` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Memory subpaths">
|
||||
| Підшлях | Ключові експорти |
|
||||
<Accordion title="Підшляхи пам’яті">
|
||||
| Підшлях | Основні експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/memory-core` | Поверхня bundled допоміжних засобів memory-core для допоміжних засобів менеджера/конфігурації/файлів/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Фасад середовища виконання індексу/пошуку пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation-рушія хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embeddings хоста пам’яті, доступ до реєстру, локальний провайдер і загальні пакетні/віддалені допоміжні засоби |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD-рушія хоста пам’яті |
|
||||
| `plugin-sdk/memory-core` | Поверхня bundled memory-core помічників для помічників manager/config/file/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Runtime-фасад індексу/пошуку пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Експорти рушія foundation хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста пам’яті, доступ до реєстру, локальний провайдер і загальні batch/remote помічники |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Експорти рушія QMD хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Експорти рушія сховища хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби середовища виконання CLI хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core середовища виконання хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/середовища виконання хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-core` | Нейтральний щодо постачальника псевдонім для допоміжних засобів core середовища виконання хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-events` | Нейтральний щодо постачальника псевдонім для допоміжних засобів журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-files` | Нейтральний щодо постачальника псевдонім для допоміжних засобів файлів/середовища виконання хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби managed-markdown для Plugin, суміжних із пам’яттю |
|
||||
| `plugin-sdk/memory-host-search` | Фасад середовища виконання активної пам’яті для доступу до search-manager |
|
||||
| `plugin-sdk/memory-host-status` | Нейтральний щодо постачальника псевдонім для допоміжних засобів статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Мультимодальні помічники хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-query` | Помічники запитів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-secret` | Помічники секретів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-events` | Помічники журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-status` | Помічники статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Помічники CLI runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Помічники core runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Помічники файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-core` | Нейтральний щодо постачальника псевдонім для core runtime помічників хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-events` | Нейтральний щодо постачальника псевдонім для помічників журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-files` | Нейтральний щодо постачальника псевдонім для помічників файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-markdown` | Спільні помічники managed-markdown для plugins, суміжних із пам’яттю |
|
||||
| `plugin-sdk/memory-host-search` | Runtime-фасад Active Memory для доступу до search-manager |
|
||||
| `plugin-sdk/memory-host-status` | Нейтральний щодо постачальника псевдонім для помічників статусу хоста пам’яті |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Reserved bundled-helper subpaths">
|
||||
Наразі немає зарезервованих підшляхів SDK для bundled допоміжних засобів. Допоміжні засоби, специфічні для власника,
|
||||
розташовані всередині пакета Plugin-власника, а багаторазові контракти хоста
|
||||
<Accordion title="Зарезервовані підшляхи bundled-helper">
|
||||
Наразі немає зарезервованих підшляхів SDK bundled-helper. Власницькі
|
||||
помічники живуть у пакеті plugin власника, а повторно використовувані контракти хоста
|
||||
використовують загальні підшляхи SDK, як-от `plugin-sdk/gateway-runtime`,
|
||||
`plugin-sdk/security-runtime` і `plugin-sdk/plugin-config-runtime`.
|
||||
</Accordion>
|
||||
@ -332,4 +333,4 @@ x-i18n:
|
||||
|
||||
- [Огляд Plugin SDK](/uk/plugins/sdk-overview)
|
||||
- [Налаштування Plugin SDK](/uk/plugins/sdk-setup)
|
||||
- [Створення Plugin](/uk/plugins/building-plugins)
|
||||
- [Створення plugins](/uk/plugins/building-plugins)
|
||||
|
||||
@ -1,51 +1,52 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви налагоджуєте відхилення запитів провайдером, пов’язані зі структурою транскрипту
|
||||
- Ви змінюєте логіку санітизації транскрипту або виправлення викликів інструментів
|
||||
- Ви досліджуєте невідповідності ідентифікаторів викликів інструментів між провайдерами
|
||||
summary: 'Довідка: правила очищення та відновлення транскриптів, специфічні для провайдера'
|
||||
title: Гігієна транскрипту
|
||||
- Ви діагностуєте відхилення запитів провайдера, пов’язані зі структурою транскрипту.
|
||||
- Ви змінюєте логіку санітизації транскриптів або виправлення викликів інструментів
|
||||
- Ви досліджуєте невідповідності ідентифікаторів викликів інструментів у різних провайдерів
|
||||
summary: 'Довідка: правила очищення та відновлення транскрипту, специфічні для провайдера'
|
||||
title: Гігієна стенограми
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T19:39:03Z"
|
||||
generated_at: "2026-04-28T20:13:10Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 51459c719c6314b2980057d7e1e003e1598e8fe4a619c081aa25ce29200645a8
|
||||
source_hash: d95f065d87ce58019ff2e6cdd6801879404d3b4fa402d26fc6fed9d51966b0a1
|
||||
source_path: reference/transcript-hygiene.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw застосовує **специфічні для провайдера виправлення** до транскриптів перед запуском (під час побудови контексту моделі). Більшість із них — це коригування **в пам’яті**, які використовуються для задоволення суворих вимог провайдера. Окремий прохід ремонту файлу сеансу також може переписати збережений JSONL до завантаження сеансу: або відкинувши некоректні рядки JSONL, або виправивши збережені репліки, які синтаксично валідні, але відомо, що їх відхиляє
|
||||
провайдер під час повторного відтворення. Коли відбувається ремонт, оригінальний файл резервно копіюється поруч із
|
||||
файлом сеансу.
|
||||
OpenClaw застосовує **виправлення, специфічні для провайдера**, до транскриптів перед запуском (під час побудови контексту моделі). Більшість із них — це коригування **в пам’яті**, які потрібні для дотримання суворих вимог провайдерів. Окремий прохід відновлення файлу сесії також може переписувати збережений JSONL до завантаження сесії: або видаляючи некоректні рядки JSONL, або відновлюючи збережені ходи, які є синтаксично коректними, але відомо, що їх відхиляє
|
||||
провайдер під час повторного відтворення. Коли відновлення відбувається, резервна копія оригінального файлу створюється поруч
|
||||
із файлом сесії.
|
||||
|
||||
Область охоплює:
|
||||
Область охоплення:
|
||||
|
||||
- Контекст prompt лише під час виконання, який не потрапляє в видимі користувачу репліки транскрипту
|
||||
- Контекст підказки лише для часу виконання не потрапляє до видимих користувачу ходів транскрипту
|
||||
- Очищення ідентифікаторів викликів інструментів
|
||||
- Перевірка вхідних даних викликів інструментів
|
||||
- Ремонт зіставлення результатів інструментів
|
||||
- Перевірка / упорядкування реплік
|
||||
- Очищення підписів думок
|
||||
- Очищення підписів мислення
|
||||
- Відновлення відповідності результатів інструментів
|
||||
- Перевірка / впорядкування ходів
|
||||
- Очищення сигнатур думок
|
||||
- Очищення сигнатур мислення
|
||||
- Очищення корисного навантаження зображень
|
||||
- Позначення походження користувацького вводу (для prompt, маршрутизованих між сеансами)
|
||||
- Ремонт порожніх помилкових реплік асистента для повторного відтворення Bedrock Converse
|
||||
- Очищення порожніх текстових блоків перед повторним відтворенням у провайдера
|
||||
- Позначення походження введення користувача (для підказок, маршрутизованих між сесіями)
|
||||
- Відновлення порожніх помилкових ходів асистента для повторного відтворення Bedrock Converse
|
||||
|
||||
Якщо вам потрібні деталі зберігання транскриптів, див.:
|
||||
Якщо вам потрібні подробиці про зберігання транскриптів, дивіться:
|
||||
|
||||
- [Поглиблений огляд керування сеансами](/uk/reference/session-management-compaction)
|
||||
- [Докладний розбір керування сесіями й Compaction](/uk/reference/session-management-compaction)
|
||||
|
||||
---
|
||||
|
||||
## Глобальне правило: контекст виконання не є користувацьким транскриптом
|
||||
## Глобальне правило: контекст часу виконання не є користувацьким транскриптом
|
||||
|
||||
Контекст виконання/системи може бути доданий до prompt моделі для репліки, але це
|
||||
не контент, створений кінцевим користувачем. OpenClaw зберігає окреме тіло
|
||||
prompt, орієнтоване на транскрипт, для відповідей Gateway, чергових подальших повідомлень, ACP, CLI та вбудованих запусків Pi.
|
||||
Збережені видимі користувацькі репліки використовують це тіло транскрипту замість
|
||||
збагаченого під час виконання prompt.
|
||||
Контекст часу виконання / системний контекст можна додати до підказки моделі для ходу, але це
|
||||
не вміст, створений кінцевим користувачем. OpenClaw зберігає окреме, орієнтоване на транскрипт
|
||||
тіло підказки для відповідей Gateway, поставлених у чергу подальших повідомлень, ACP, CLI та вбудованих запусків Pi.
|
||||
Збережені видимі користувацькі ходи використовують це тіло транскрипту замість
|
||||
підказки, збагаченої контекстом часу виконання.
|
||||
|
||||
Для застарілих сеансів, які вже зберегли обгортки виконання, поверхні історії Gateway
|
||||
Для застарілих сесій, у яких уже були збережені обгортки часу виконання, поверхні історії Gateway
|
||||
застосовують проєкцію відображення перед поверненням повідомлень клієнтам WebChat,
|
||||
TUI, REST або SSE.
|
||||
|
||||
@ -56,11 +57,11 @@ TUI, REST або SSE.
|
||||
Уся гігієна транскриптів централізована у вбудованому runner:
|
||||
|
||||
- Вибір політики: `src/agents/transcript-policy.ts`
|
||||
- Застосування очищення/ремонту: `sanitizeSessionHistory` у `src/agents/pi-embedded-runner/replay-history.ts`
|
||||
- Застосування очищення / відновлення: `sanitizeSessionHistory` у `src/agents/pi-embedded-runner/replay-history.ts`
|
||||
|
||||
Політика використовує `provider`, `modelApi` і `modelId`, щоб вирішити, що застосовувати.
|
||||
Політика використовує `provider`, `modelApi` та `modelId`, щоб вирішити, що застосовувати.
|
||||
|
||||
Окремо від гігієни транскриптів файли сеансів ремонтуються (за потреби) перед завантаженням:
|
||||
Окремо від гігієни транскриптів файли сесій відновлюються (за потреби) перед завантаженням:
|
||||
|
||||
- `repairSessionFileIfNeeded` у `src/agents/session-file-repair.ts`
|
||||
- Викликається з `run/attempt.ts` і `compact.ts` (вбудований runner)
|
||||
@ -69,25 +70,28 @@ TUI, REST або SSE.
|
||||
|
||||
## Глобальне правило: очищення зображень
|
||||
|
||||
Корисне навантаження зображень завжди очищується, щоб запобігти відхиленню на боці провайдера через обмеження
|
||||
розміру (зменшення масштабу/повторне стиснення надмірно великих зображень base64).
|
||||
Корисне навантаження зображень завжди очищається, щоб запобігти відхиленню на боці провайдера через обмеження
|
||||
розміру (зменшення масштабу / повторне стискання надмірно великих base64-зображень).
|
||||
|
||||
Це також допомагає контролювати тиск токенів від зображень для моделей із підтримкою зору.
|
||||
Менші максимальні розміри зазвичай зменшують використання токенів; більші розміри зберігають деталізацію.
|
||||
Це також допомагає контролювати тиск на токени від зображень для моделей із підтримкою бачення.
|
||||
Менші максимальні розміри зазвичай зменшують використання токенів; більші розміри зберігають деталі.
|
||||
|
||||
Реалізація:
|
||||
|
||||
- `sanitizeSessionMessagesImages` у `src/agents/pi-embedded-helpers/images.ts`
|
||||
- `sanitizeContentBlocksImages` у `src/agents/tool-images.ts`
|
||||
- Максимальна сторона зображення налаштовується через `agents.defaults.imageMaxDimensionPx` (типово: `1200`).
|
||||
- Порожні текстові блоки видаляються, поки цей прохід обходить вміст для повторного відтворення. Ходи асистента,
|
||||
які стають порожніми, видаляються з копії для повторного відтворення; користувацькі ходи та ходи результатів інструментів,
|
||||
які стають порожніми, отримують непорожній заповнювач пропущеного вмісту.
|
||||
|
||||
---
|
||||
|
||||
## Глобальне правило: некоректні виклики інструментів
|
||||
|
||||
Блоки викликів інструментів асистента, у яких відсутні і `input`, і `arguments`, відкидаються
|
||||
до побудови контексту моделі. Це запобігає відхиленням провайдером через частково
|
||||
збережені виклики інструментів (наприклад, після збою через ліміт частоти).
|
||||
Блоки викликів інструментів асистента, у яких відсутні і `input`, і `arguments`, видаляються
|
||||
до побудови контексту моделі. Це запобігає відхиленням провайдерами через частково
|
||||
збережені виклики інструментів (наприклад, після помилки обмеження швидкості).
|
||||
|
||||
Реалізація:
|
||||
|
||||
@ -96,22 +100,22 @@ TUI, REST або SSE.
|
||||
|
||||
---
|
||||
|
||||
## Глобальне правило: походження міжсеансового вводу
|
||||
## Глобальне правило: походження введення між сесіями
|
||||
|
||||
Коли агент надсилає prompt в інший сеанс через `sessions_send` (зокрема
|
||||
кроки відповіді/оголошення між агентами), OpenClaw зберігає створену користувацьку репліку з:
|
||||
Коли агент надсилає підказку в іншу сесію через `sessions_send` (зокрема
|
||||
кроки відповіді / оголошення від агента до агента), OpenClaw зберігає створений користувацький хід із:
|
||||
|
||||
- `message.provenance.kind = "inter_session"`
|
||||
|
||||
OpenClaw також додає на початок тієї самої репліки маркер `[Inter-session message ... isUser=false]`
|
||||
перед текстом маршрутизованого prompt, щоб активний виклик моделі міг відрізнити
|
||||
вивід стороннього сеансу від зовнішніх інструкцій кінцевого користувача. Цей маркер містить
|
||||
вихідний сеанс, канал і інструмент, коли вони доступні. Транскрипт усе ще використовує
|
||||
`role: "user"` для сумісності з провайдером, але і видимий текст, і метадані
|
||||
походження позначають репліку як міжсеансові дані.
|
||||
OpenClaw також додає на початок того самого ходу маркер `[Inter-session message ... isUser=false]`
|
||||
перед текстом маршрутизованої підказки, щоб активний виклик моделі міг відрізнити
|
||||
вивід чужої сесії від зовнішніх інструкцій кінцевого користувача. Цей маркер містить
|
||||
вихідну сесію, канал і інструмент, коли вони доступні. Транскрипт усе ще використовує
|
||||
`role: "user"` для сумісності з провайдерами, але видимий текст і метадані походження
|
||||
обидва позначають хід як міжсесійні дані.
|
||||
|
||||
Під час перебудови контексту OpenClaw застосовує той самий маркер до старіших збережених
|
||||
міжсеансових користувацьких реплік, які мають лише метадані походження.
|
||||
міжсесійних користувацьких ходів, які мають лише метадані походження.
|
||||
|
||||
---
|
||||
|
||||
@ -120,63 +124,65 @@ OpenClaw також додає на початок тієї самої репл
|
||||
**OpenAI / OpenAI Codex**
|
||||
|
||||
- Лише очищення зображень.
|
||||
- Відкидати осиротілі підписи reasoning (окремі елементи reasoning без наступного блока контенту) для транскриптів OpenAI Responses/Codex і відкидати повторно відтворюваний OpenAI reasoning після перемикання маршруту моделі.
|
||||
- Зберігати повторно відтворювані payload елементів reasoning OpenAI Responses, зокрема зашифровані елементи з порожнім підсумком, щоб ручне/WebSocket повторне відтворення зберігало потрібний стан `rs_*`, поєднаний з елементами виводу асистента.
|
||||
- Без очищення ідентифікаторів викликів інструментів.
|
||||
- Ремонт зіставлення результатів інструментів може переміщувати реальні зіставлені виводи та синтезувати Codex-стилю виводи `aborted` для відсутніх викликів інструментів.
|
||||
- Без перевірки чи переупорядкування реплік.
|
||||
- Відсутні виводи інструментів сімейства OpenAI Responses синтезуються як `aborted`, щоб відповідати нормалізації повторного відтворення Codex.
|
||||
- Без видалення підписів думок.
|
||||
- Видаляються осиротілі сигнатури reasoning (окремі елементи reasoning без наступного блоку вмісту) для транскриптів OpenAI Responses/Codex, а також видаляється придатний до повторного відтворення OpenAI reasoning після перемикання маршруту моделі.
|
||||
- Зберігаються корисні навантаження елементів reasoning OpenAI Responses, придатні до повторного відтворення, включно із зашифрованими елементами з порожнім summary, щоб ручне / WebSocket-повторне відтворення зберігало потрібний стан `rs_*` у парі з елементами виводу асистента.
|
||||
- Очищення ідентифікаторів викликів інструментів не виконується.
|
||||
- Відновлення відповідності результатів інструментів може переміщувати справжні зіставлені виходи та синтезувати Codex-стилізовані виходи `aborted` для відсутніх викликів інструментів.
|
||||
- Перевірка або перевпорядкування ходів не виконується.
|
||||
- Відсутні виходи інструментів сімейства OpenAI Responses синтезуються як `aborted`, щоб відповідати нормалізації повторного відтворення Codex.
|
||||
- Сигнатури думок не видаляються.
|
||||
|
||||
**OpenAI-сумісна Gemma 4**
|
||||
|
||||
- Історичні блоки мислення/reasoning асистента видаляються перед повторним відтворенням, щоб локальні
|
||||
OpenAI-сумісні сервери Gemma 4 не отримували контент reasoning із попередніх реплік.
|
||||
- Поточні продовження викликів інструментів у межах тієї самої репліки зберігають блок reasoning асистента
|
||||
приєднаним до виклику інструмента, доки результат інструмента не буде повторно відтворено.
|
||||
- Історичні блоки thinking/reasoning асистента видаляються перед повторним відтворенням, щоб локальні
|
||||
OpenAI-сумісні сервери Gemma 4 не отримували вміст reasoning із попередніх ходів.
|
||||
- Поточні продовження викликів інструментів у тому самому ході зберігають блок reasoning асистента,
|
||||
прикріплений до виклику інструмента, доки результат інструмента не буде повторно відтворено.
|
||||
|
||||
**Google (Generative AI / Gemini CLI / Antigravity)**
|
||||
|
||||
- Очищення ідентифікаторів викликів інструментів: суворо літерно-цифрові.
|
||||
- Ремонт зіставлення результатів інструментів і синтетичні результати інструментів.
|
||||
- Перевірка реплік (чергування реплік у стилі Gemini).
|
||||
- Виправлення порядку реплік Google (додавання на початок крихітного користувацького bootstrap, якщо історія починається з асистента).
|
||||
- Antigravity Claude: нормалізувати підписи мислення; відкидати непідписані блоки мислення.
|
||||
- Очищення ідентифікаторів викликів інструментів: суворо буквено-цифрові.
|
||||
- Відновлення відповідності результатів інструментів і синтетичні результати інструментів.
|
||||
- Перевірка ходів (чергування ходів у стилі Gemini).
|
||||
- Виправлення порядку ходів Google (додає крихітний користувацький bootstrap на початок, якщо історія починається з асистента).
|
||||
- Antigravity Claude: нормалізуються сигнатури thinking; непідписані блоки thinking видаляються.
|
||||
|
||||
**Anthropic / Minimax (Anthropic-сумісні)**
|
||||
**Anthropic / Minimax (Anthropic-сумісний)**
|
||||
|
||||
- Ремонт зіставлення результатів інструментів і синтетичні результати інструментів.
|
||||
- Перевірка реплік (об’єднання послідовних користувацьких реплік для задоволення суворого чергування).
|
||||
- Кінцеві репліки попереднього заповнення асистента видаляються з вихідних payload Anthropic Messages,
|
||||
коли мислення ввімкнено, зокрема для маршрутів Cloudflare AI Gateway.
|
||||
- Блоки мислення з відсутніми, порожніми або blank підписами повторного відтворення видаляються
|
||||
перед перетворенням для провайдера. Якщо це спорожнює репліку асистента, OpenClaw зберігає
|
||||
форму репліки з непорожнім текстом про пропущене reasoning.
|
||||
- Старіші репліки асистента лише з мисленням, які потрібно видалити, замінюються
|
||||
непорожнім текстом про пропущене reasoning, щоб адаптери провайдерів не відкидали репліку
|
||||
- Відновлення відповідності результатів інструментів і синтетичні результати інструментів.
|
||||
- Перевірка ходів (об’єднання послідовних користувацьких ходів для дотримання суворого чергування).
|
||||
- Кінцеві ходи попереднього заповнення асистента видаляються з вихідних корисних навантажень Anthropic Messages,
|
||||
коли thinking увімкнено, включно з маршрутами Cloudflare AI Gateway.
|
||||
- Блоки thinking з відсутніми, порожніми або blank-сигнатурами повторного відтворення видаляються
|
||||
перед перетворенням для провайдера. Якщо це робить хід асистента порожнім, OpenClaw зберігає
|
||||
форму ходу з непорожнім текстом пропущеного reasoning.
|
||||
- Старіші ходи асистента лише з thinking, які потрібно видалити, замінюються
|
||||
непорожнім текстом пропущеного reasoning, щоб адаптери провайдерів не видаляли хід
|
||||
повторного відтворення.
|
||||
|
||||
**Amazon Bedrock (Converse API)**
|
||||
|
||||
- Порожні репліки асистента з помилкою stream ремонтуються в непорожній fallback текстовий блок
|
||||
- Порожні помилкові ходи потоку асистента відновлюються до непорожнього резервного текстового блока
|
||||
перед повторним відтворенням. Bedrock Converse відхиляє повідомлення асистента з `content: []`, тому
|
||||
збережені репліки асистента з `stopReason: "error"` і порожнім контентом також
|
||||
ремонтуються на диску перед завантаженням.
|
||||
- Блоки мислення Claude з відсутніми, порожніми або blank підписами повторного відтворення
|
||||
видаляються перед повторним відтворенням Converse. Якщо це спорожнює репліку асистента, OpenClaw
|
||||
зберігає форму репліки з непорожнім текстом про пропущене reasoning.
|
||||
- Старіші репліки асистента лише з мисленням, які потрібно видалити, замінюються
|
||||
непорожнім текстом про пропущене reasoning, щоб повторне відтворення Converse зберігало сувору форму реплік.
|
||||
- Повторне відтворення фільтрує delivery-mirror OpenClaw і вставлені gateway репліки асистента.
|
||||
збережені ходи асистента з `stopReason: "error"` і порожнім вмістом також
|
||||
відновлюються на диску перед завантаженням.
|
||||
- Помилкові ходи потоку асистента, які містять лише порожні текстові блоки, видаляються
|
||||
з копії повторного відтворення в пам’яті замість повторного відтворення некоректного порожнього блока.
|
||||
- Блоки thinking Claude з відсутніми, порожніми або blank-сигнатурами повторного відтворення
|
||||
видаляються перед повторним відтворенням Converse. Якщо це робить хід асистента порожнім, OpenClaw
|
||||
зберігає форму ходу з непорожнім текстом пропущеного reasoning.
|
||||
- Старіші ходи асистента лише з thinking, які потрібно видалити, замінюються
|
||||
непорожнім текстом пропущеного reasoning, щоб повторне відтворення Converse зберігало сувору форму ходу.
|
||||
- Повторне відтворення фільтрує ходи асистента, які є delivery-mirror OpenClaw і вставлені Gateway.
|
||||
- Очищення зображень застосовується через глобальне правило.
|
||||
|
||||
**Mistral (зокрема виявлення на основі ідентифікатора моделі)**
|
||||
**Mistral (включно з виявленням на основі model-id)**
|
||||
|
||||
- Очищення ідентифікаторів викликів інструментів: strict9 (літерно-цифрові довжиною 9).
|
||||
- Очищення ідентифікаторів викликів інструментів: strict9 (буквено-цифрові, довжина 9).
|
||||
|
||||
**OpenRouter Gemini**
|
||||
|
||||
- Очищення підписів думок: видаляти не-base64 значення `thought_signature` (залишати base64).
|
||||
- Очищення сигнатур думок: видалення не-base64 значень `thought_signature` (base64 зберігається).
|
||||
|
||||
**Усе інше**
|
||||
|
||||
@ -186,22 +192,22 @@ OpenClaw також додає на початок тієї самої репл
|
||||
|
||||
## Історична поведінка (до 2026.1.22)
|
||||
|
||||
До випуску 2026.1.22 OpenClaw застосовував кілька шарів гігієни транскриптів:
|
||||
До випуску 2026.1.22 OpenClaw застосовував кілька рівнів гігієни транскриптів:
|
||||
|
||||
- **transcript-sanitize extension** виконувався під час кожної побудови контексту і міг:
|
||||
- Ремонтувати зіставлення використання/результатів інструментів.
|
||||
- Очищати ідентифікатори викликів інструментів (зокрема несуворий режим, який зберігав `_`/`-`).
|
||||
- Runner також виконував специфічне для провайдера очищення, що дублювало роботу.
|
||||
- Додаткові мутації відбувалися поза політикою провайдера, зокрема:
|
||||
- Видалення тегів `<final>` із тексту асистента перед збереженням.
|
||||
- Відкидання порожніх помилкових реплік асистента.
|
||||
- Обрізання контенту асистента після викликів інструментів.
|
||||
- **transcript-sanitize extension** виконувався під час кожної побудови контексту й міг:
|
||||
- Відновлювати відповідність використання інструментів / результатів.
|
||||
- Очищати ідентифікатори викликів інструментів (включно з несуворим режимом, який зберігав `_`/`-`).
|
||||
- Runner також виконував очищення, специфічне для провайдера, що дублювало роботу.
|
||||
- Додаткові мутації відбувалися поза політикою провайдера, включно з:
|
||||
- Видаленням тегів `<final>` із тексту асистента перед збереженням.
|
||||
- Видаленням порожніх помилкових ходів асистента.
|
||||
- Обрізанням вмісту асистента після викликів інструментів.
|
||||
|
||||
Ця складність спричиняла регресії між провайдерами (особливо для зіставлення `openai-responses`
|
||||
Ця складність спричиняла регресії між провайдерами (зокрема відповідність `openai-responses`
|
||||
`call_id|fc_id`). Очищення 2026.1.22 видалило extension, централізувало
|
||||
логіку в runner і зробило OpenAI **без змін** поза очищенням зображень.
|
||||
логіку в runner і зробило OpenAI **no-touch** поза очищенням зображень.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Керування сеансами](/uk/concepts/session)
|
||||
- [Обрізання сеансів](/uk/concepts/session-pruning)
|
||||
- [Керування сесіями](/uk/concepts/session)
|
||||
- [Скорочення сесії](/uk/concepts/session-pruning)
|
||||
|
||||
@ -1,50 +1,47 @@
|
||||
---
|
||||
read_when:
|
||||
- Розуміння того, що відбувається під час першого запуску agent
|
||||
- Пояснення, де розміщуються файли початкового налаштування
|
||||
- Розуміння того, що відбувається під час першого запуску агента
|
||||
- Пояснення, де розташовані файли початкової ініціалізації
|
||||
- Налагодження налаштування ідентичності під час онбордингу
|
||||
sidebarTitle: Bootstrapping
|
||||
summary: Ритуал початкового налаштування agent, що заповнює workspace і файли ідентичності
|
||||
title: Початкове налаштування agent
|
||||
summary: Ритуал початкового налаштування агента, який ініціалізує робочий простір і файли ідентичності
|
||||
title: Ініціалізація агента
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T19:53:07Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-04-28T20:13:44Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 435eb2a14707623903ab7873774cc8d4489b960719cf6a525d547983f8338027
|
||||
source_hash: de829f82016ae1e4dcd7714502ca8d11755556fed18b985a7e2bada4149a2d46
|
||||
source_path: start/bootstrapping.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Початкове налгодування — це ритуал **першого запуску**, який готує workspace agent і
|
||||
збирає відомості про ідентичність. Він відбувається після онбордингу, коли agent
|
||||
запускається вперше.
|
||||
Початкове налаштування — це ритуал **першого запуску**, який готує робочий простір агента й збирає дані ідентичності. Воно відбувається після онбордингу, коли агент запускається вперше.
|
||||
|
||||
## Що робить початкове налаштування
|
||||
|
||||
Під час першого запуску agent OpenClaw ініціалізує workspace (типово
|
||||
Під час першого запуску агента OpenClaw виконує початкове налаштування робочого простору (типово
|
||||
`~/.openclaw/workspace`):
|
||||
|
||||
- Заповнює `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
|
||||
- Створює початкові `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
|
||||
- Запускає короткий ритуал запитань і відповідей (по одному запитанню за раз).
|
||||
- Записує ідентичність і налаштування до `IDENTITY.md`, `USER.md`, `SOUL.md`.
|
||||
- Видаляє `BOOTSTRAP.md` після завершення, щоб він виконувався лише один раз.
|
||||
- Записує ідентичність і вподобання до `IDENTITY.md`, `USER.md`, `SOUL.md`.
|
||||
- Після завершення видаляє `BOOTSTRAP.md`, щоб він запускався лише один раз.
|
||||
|
||||
Для запусків із вбудованими/локальними моделями OpenClaw не включає `BOOTSTRAP.md` до привілейованого системного контексту. Під час основного інтерактивного першого запуску він усе одно передає вміст файла в користувацькому запиті, щоб моделі, які не завжди надійно викликають інструмент `read`, могли завершити ритуал. Якщо поточний запуск не може безпечно отримати доступ до робочого простору, агент отримує обмежену нотатку початкового налаштування замість загального привітання.
|
||||
|
||||
## Пропуск початкового налаштування
|
||||
|
||||
Щоб пропустити це для попередньо заповненого workspace, виконайте `openclaw onboard --skip-bootstrap`.
|
||||
Щоб пропустити це для попередньо заповненого робочого простору, виконайте `openclaw onboard --skip-bootstrap`.
|
||||
|
||||
## Де це виконується
|
||||
## Де воно запускається
|
||||
|
||||
Початкове налаштування завжди виконується на **хості gateway**. Якщо застосунок macOS підключається до
|
||||
віддаленого Gateway, workspace і файли початкового налаштування зберігаються на тій віддаленій
|
||||
машині.
|
||||
Початкове налаштування завжди запускається на **хості Gateway**. Якщо застосунок macOS підключається до віддаленого Gateway, робочий простір і файли початкового налаштування розташовані на цій віддаленій машині.
|
||||
|
||||
<Note>
|
||||
Коли Gateway працює на іншій машині, редагуйте файли workspace на хості gateway
|
||||
(наприклад, `user@gateway-host:~/.openclaw/workspace`).
|
||||
Коли Gateway працює на іншій машині, редагуйте файли робочого простору на хості Gateway (наприклад, `user@gateway-host:~/.openclaw/workspace`).
|
||||
</Note>
|
||||
|
||||
## Пов’язана документація
|
||||
|
||||
- Онбординг застосунку macOS: [Онбординг](/uk/start/onboarding)
|
||||
- Структура workspace: [Workspace agent](/uk/concepts/agent-workspace)
|
||||
- Структура робочого простору: [Робочий простір агента](/uk/concepts/agent-workspace)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user