chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
5688c7e9a0
commit
25a271da1d
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете зрозуміти, що означає “context” в OpenClaw
|
||||
- Ви налагоджуєте, чому модель “знає” щось (або забула це)
|
||||
- Ви хочете зменшити накладні витрати контексту (/context, /status, /compact)
|
||||
summary: 'Контекст: що бачить модель, як він формується і як його перевірити'
|
||||
title: Context
|
||||
- Ви хочете зрозуміти, що означає «контекст» в OpenClaw
|
||||
- Ви налагоджуєте, чому модель щось «знає» (або забула це)
|
||||
- Ви хочете зменшити накладні витрати контексту (`/context`, `/status`, `/compact`)
|
||||
summary: 'Контекст: що бачить модель, як він будується та як його перевірити'
|
||||
title: Контекст
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T18:00:56Z"
|
||||
generated_at: "2026-04-05T18:48:31Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a75b4cd65bf6385d46265b9ce1643310bc99d220e35ec4b4924096bed3ca4aa0
|
||||
source_hash: fe7dfe52cb1a64df229c8622feed1804df6c483a6243e0d2f309f6ff5c9fe521
|
||||
source_path: concepts/context.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Context
|
||||
# Контекст
|
||||
|
||||
«Контекст» — це **все, що OpenClaw надсилає моделі для одного запуску**. Він обмежений **вікном контексту** моделі (лімітом токенів).
|
||||
«Контекст» — це **все, що OpenClaw надсилає моделі для запуску**. Він обмежений **вікном контексту** моделі (лімітом токенів).
|
||||
|
||||
Базова ментальна модель:
|
||||
Проста ментальна модель для початківців:
|
||||
|
||||
- **System prompt** (побудований OpenClaw): правила, інструменти, список Skills, час/runtime та впроваджені файли робочого простору.
|
||||
- **Історія розмови**: ваші повідомлення + повідомлення асистента для цієї сесії.
|
||||
- **Системний запит** (збудований OpenClaw): правила, інструменти, список Skills, час/середовище виконання та впроваджені файли робочого простору.
|
||||
- **Історія розмови**: ваші повідомлення + повідомлення помічника для цієї сесії.
|
||||
- **Виклики/результати інструментів + вкладення**: вивід команд, читання файлів, зображення/аудіо тощо.
|
||||
|
||||
Контекст _це не те саме_, що й «memory»: memory може зберігатися на диску й повторно завантажуватися пізніше; context — це те, що міститься в поточному вікні моделі.
|
||||
Контекст _не є тим самим_, що й «пам’ять»: пам’ять може зберігатися на диску та повторно завантажуватися пізніше; контекст — це те, що міститься в поточному вікні моделі.
|
||||
|
||||
## Швидкий старт (перевірка context)
|
||||
## Швидкий старт (перевірка контексту)
|
||||
|
||||
- `/status` → швидкий перегляд «наскільки заповнене моє вікно?» + налаштування сесії.
|
||||
- `/context list` → що впроваджується + приблизні розміри (для кожного файлу + підсумки).
|
||||
- `/context detail` → глибший розбір: розміри для кожного файлу, для кожної схеми інструмента, для кожного запису skill і розмір system prompt.
|
||||
- `/usage tokens` → додає до звичайних відповідей нижній колонтитул із використанням.
|
||||
- `/compact` → підсумовує старішу історію в compact entry, щоб звільнити місце у вікні.
|
||||
- `/status` → швидкий перегляд «наскільки заповнене моє вікно?» + параметри сесії.
|
||||
- `/context list` → що впроваджено + приблизні розміри (для кожного файла + загальні).
|
||||
- `/context detail` → глибший розбір: для кожного файла, розміри схем кожного інструмента, розміри записів кожного skill та розмір системного запиту.
|
||||
- `/usage tokens` → додає нижній колонтитул використання для кожної відповіді до звичайних відповідей.
|
||||
- `/compact` → узагальнює старішу історію в компактний запис, щоб звільнити місце у вікні.
|
||||
|
||||
Див. також: [Slash commands](/tools/slash-commands), [Використання токенів і вартість](/reference/token-use), [Compaction](/concepts/compaction).
|
||||
Див. також: [Слеш-команди](/uk/tools/slash-commands), [Використання токенів і витрати](/uk/reference/token-use), [Компресія](/uk/concepts/compaction).
|
||||
|
||||
## Приклад виводу
|
||||
|
||||
@ -43,11 +43,11 @@ x-i18n:
|
||||
### `/context list`
|
||||
|
||||
```
|
||||
🧠 Розбивка контексту
|
||||
🧠 Розподіл контексту
|
||||
Робочий простір: <workspaceDir>
|
||||
Макс. bootstrap/file: 20,000 chars
|
||||
Sandbox: mode=non-main sandboxed=false
|
||||
System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok))
|
||||
Макс. bootstrap на файл: 20,000 chars
|
||||
Пісочниця: mode=non-main sandboxed=false
|
||||
Системний запит (запуск): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok))
|
||||
|
||||
Впроваджені файли робочого простору:
|
||||
- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok)
|
||||
@ -58,58 +58,58 @@ System prompt (run): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5
|
||||
- HEARTBEAT.md: MISSING | raw 0 | injected 0
|
||||
- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok)
|
||||
|
||||
Список Skills (текст system prompt): 2,184 chars (~546 tok) (12 skills)
|
||||
Tools: read, edit, write, exec, process, browser, message, sessions_send, …
|
||||
Список інструментів (текст system prompt): 1,032 chars (~258 tok)
|
||||
Схеми інструментів (JSON): 31,988 chars (~7,997 tok) (враховується в context; не показується як текст)
|
||||
Tools: (те саме, що вище)
|
||||
Список Skills (текст системного запиту): 2,184 chars (~546 tok) (12 skills)
|
||||
Інструменти: read, edit, write, exec, process, browser, message, sessions_send, …
|
||||
Список інструментів (текст системного запиту): 1,032 chars (~258 tok)
|
||||
Схеми інструментів (JSON): 31,988 chars (~7,997 tok) (враховуються в контексті; не показуються як текст)
|
||||
Інструменти: (те саме, що вище)
|
||||
|
||||
Токени сесії (cached): 14,250 total / ctx=32,000
|
||||
Токени сесії (кешовані): 14,250 total / ctx=32,000
|
||||
```
|
||||
|
||||
### `/context detail`
|
||||
|
||||
```
|
||||
🧠 Розбивка контексту (детально)
|
||||
🧠 Розподіл контексту (детально)
|
||||
…
|
||||
Найбільші skills (розмір запису в prompt):
|
||||
Найбільші skills (розмір запису в запиті):
|
||||
- frontend-design: 412 chars (~103 tok)
|
||||
- oracle: 401 chars (~101 tok)
|
||||
… (+10 more skills)
|
||||
… (+ще 10 skills)
|
||||
|
||||
Найбільші tools (розмір схеми):
|
||||
Найбільші інструменти (розмір схеми):
|
||||
- browser: 9,812 chars (~2,453 tok)
|
||||
- exec: 6,240 chars (~1,560 tok)
|
||||
… (+N more tools)
|
||||
… (+ще N)
|
||||
```
|
||||
|
||||
## Що враховується у вікні контексту
|
||||
|
||||
Усе, що отримує модель, враховується, зокрема:
|
||||
Враховується все, що отримує модель, зокрема:
|
||||
|
||||
- System prompt (усі розділи).
|
||||
- Системний запит (усі розділи).
|
||||
- Історія розмови.
|
||||
- Виклики інструментів + результати інструментів.
|
||||
- Вкладення/транскрипти (зображення/аудіо/файли).
|
||||
- Підсумки compaction і артефакти pruning.
|
||||
- Підсумки компресії та артефакти обрізання.
|
||||
- «Обгортки» провайдера або приховані заголовки (не видимі, але все одно враховуються).
|
||||
|
||||
## Як OpenClaw будує system prompt
|
||||
## Як OpenClaw будує системний запит
|
||||
|
||||
System prompt **належить OpenClaw** і перебудовується для кожного запуску. Він включає:
|
||||
Системний запит **належить OpenClaw** і перебудовується для кожного запуску. Він містить:
|
||||
|
||||
- Список інструментів + короткі описи.
|
||||
- Список Skills (лише метадані; див. нижче).
|
||||
- Розташування робочого простору.
|
||||
- Час (UTC + перетворений користувацький час, якщо налаштовано).
|
||||
- Метадані runtime (хост/OS/модель/thinking).
|
||||
- Час (UTC + перетворений час користувача, якщо налаштовано).
|
||||
- Метадані середовища виконання (хост/ОС/модель/thinking).
|
||||
- Впроваджені bootstrap-файли робочого простору в розділі **Project Context**.
|
||||
|
||||
Повна розбивка: [System Prompt](/concepts/system-prompt).
|
||||
Повний розбір: [Системний запит](/uk/concepts/system-prompt).
|
||||
|
||||
## Впроваджені файли робочого простору (Project Context)
|
||||
|
||||
Типово OpenClaw впроваджує фіксований набір файлів робочого простору (якщо вони існують):
|
||||
Типово OpenClaw впроваджує фіксований набір файлів робочого простору (якщо вони є):
|
||||
|
||||
- `AGENTS.md`
|
||||
- `SOUL.md`
|
||||
@ -119,68 +119,68 @@ System prompt **належить OpenClaw** і перебудовується д
|
||||
- `HEARTBEAT.md`
|
||||
- `BOOTSTRAP.md` (лише під час першого запуску)
|
||||
|
||||
Великі файли обрізаються для кожного файлу окремо через `agents.defaults.bootstrapMaxChars` (типово `20000` chars). OpenClaw також примусово застосовує загальне обмеження на впровадження bootstrap у всіх файлах через `agents.defaults.bootstrapTotalMaxChars` (типово `150000` chars). `/context` показує розміри **raw vs injected** і те, чи відбулося обрізання.
|
||||
Великі файли обрізаються окремо для кожного файла за допомогою `agents.defaults.bootstrapMaxChars` (типово `20000` символів). OpenClaw також застосовує загальне обмеження на впровадження bootstrap для всіх файлів через `agents.defaults.bootstrapTotalMaxChars` (типово `150000` символів). `/context` показує розміри **raw vs injected** і те, чи відбулося обрізання.
|
||||
|
||||
Коли відбувається обрізання, runtime може впровадити в prompt блок попередження в розділі Project Context. Це налаштовується через `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; типово `once`).
|
||||
Коли відбувається обрізання, середовище виконання може впровадити в запит блок попередження в розділі Project Context. Налаштовується це через `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; типово `once`).
|
||||
|
||||
## Skills: впроваджені чи завантажені на вимогу
|
||||
|
||||
System prompt включає компактний **список Skills** (назва + опис + розташування). Цей список має реальні накладні витрати.
|
||||
Системний запит містить компактний **список skills** (назва + опис + розташування). Цей список створює реальні накладні витрати.
|
||||
|
||||
Інструкції Skills _типово не включаються_. Очікується, що модель викличе `read` для `SKILL.md` skill **лише за потреби**.
|
||||
Інструкції skill _не_ включаються типово. Очікується, що модель виконає `read` для `SKILL.md` цього skill **лише за потреби**.
|
||||
|
||||
## Tools: є дві вартості
|
||||
## Інструменти: є дві складові вартості
|
||||
|
||||
Інструменти впливають на context двома способами:
|
||||
Інструменти впливають на контекст двома способами:
|
||||
|
||||
1. **Текст списку інструментів** у system prompt (те, що ви бачите як «Tooling»).
|
||||
2. **Схеми інструментів** (JSON). Вони надсилаються моделі, щоб вона могла викликати інструменти. Вони враховуються в context, навіть якщо ви не бачите їх як звичайний текст.
|
||||
1. **Текст списку інструментів** у системному запиті (те, що ви бачите як “Tooling”).
|
||||
2. **Схеми інструментів** (JSON). Вони надсилаються моделі, щоб вона могла викликати інструменти. Вони враховуються в контексті, навіть якщо ви не бачите їх як звичайний текст.
|
||||
|
||||
`/context detail` розбиває найбільші схеми інструментів, щоб ви могли побачити, що домінує.
|
||||
|
||||
## Команди, директиви й "inline shortcuts"
|
||||
## Команди, директиви та "вбудовані скорочення"
|
||||
|
||||
Slash-команди обробляються Gateway. Є кілька різних типів поведінки:
|
||||
Слеш-команди обробляються Gateway. Існує кілька різних варіантів поведінки:
|
||||
|
||||
- **Standalone commands**: повідомлення, яке складається лише з `/...`, виконується як команда.
|
||||
- **Directives**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/model`, `/queue` прибираються до того, як модель побачить повідомлення.
|
||||
- Повідомлення лише з директивами зберігають налаштування сесії.
|
||||
- Inline directives у звичайному повідомленні діють як підказки для конкретного повідомлення.
|
||||
- **Inline shortcuts** (лише для allowlisted senders): деякі токени `/...` всередині звичайного повідомлення можуть виконуватися негайно (приклад: «hey /status») і прибираються до того, як модель побачить решту тексту.
|
||||
- **Окремі команди**: повідомлення, яке складається лише з `/...`, виконується як команда.
|
||||
- **Директиви**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/model`, `/queue` прибираються до того, як модель побачить повідомлення.
|
||||
- Повідомлення лише з директивами зберігають параметри сесії.
|
||||
- Вбудовані директиви у звичайному повідомленні діють як підказки для конкретного повідомлення.
|
||||
- **Вбудовані скорочення** (лише для відправників із allowlist): певні токени `/...` усередині звичайного повідомлення можуть виконуватися негайно (приклад: “hey /status”), а потім прибираються до того, як модель побачить решту тексту.
|
||||
|
||||
Подробиці: [Slash commands](/tools/slash-commands).
|
||||
Докладніше: [Слеш-команди](/uk/tools/slash-commands).
|
||||
|
||||
## Sessions, compaction і pruning (що зберігається)
|
||||
## Сесії, компресія та обрізання (що зберігається)
|
||||
|
||||
Те, що зберігається між повідомленнями, залежить від механізму:
|
||||
Що саме зберігається між повідомленнями, залежить від механізму:
|
||||
|
||||
- **Normal history** зберігається в session transcript, доки не буде ущільнено/обрізано політикою.
|
||||
- **Compaction** зберігає підсумок у transcript і залишає нещодавні повідомлення без змін.
|
||||
- **Pruning** видаляє старі результати інструментів із prompt _у пам’яті_ для запуску, але не переписує transcript.
|
||||
- **Звичайна історія** зберігається в транскрипті сесії, доки не буде стиснута/обрізана відповідно до політики.
|
||||
- **Компресія** зберігає підсумок у транскрипті та залишає недавні повідомлення без змін.
|
||||
- **Обрізання** видаляє старі результати інструментів із _внутрішньої_ підказки для запуску, але не переписує транскрипт.
|
||||
|
||||
Документація: [Session](/concepts/session), [Compaction](/concepts/compaction), [Session pruning](/concepts/session-pruning).
|
||||
Документація: [Сесія](/uk/concepts/session), [Компресія](/uk/concepts/compaction), [Обрізання сесії](/uk/concepts/session-pruning).
|
||||
|
||||
Типово OpenClaw використовує вбудований `legacy` context engine для збирання і
|
||||
compaction. Якщо ви встановите plugin, який надає `kind: "context-engine"`, і
|
||||
виберете його через `plugins.slots.contextEngine`, OpenClaw делегує збирання
|
||||
context, `/compact` та пов’язані hooks життєвого циклу контексту субагентів цьому
|
||||
engine. `ownsCompaction: false` не спричиняє автоматичний резервний перехід до
|
||||
legacy engine; активний engine все одно має коректно реалізовувати `compact()`. Див.
|
||||
[Context Engine](/concepts/context-engine), щоб ознайомитися з повним
|
||||
інтерфейсом підключення, hooks життєвого циклу та конфігурацією.
|
||||
Типово OpenClaw використовує вбудований контекстний рушій `legacy` для збирання
|
||||
та компресії. Якщо ви встановите плагін, який надає `kind: "context-engine"`, і
|
||||
виберете його через `plugins.slots.contextEngine`, OpenClaw натомість делегує
|
||||
цьому рушію збирання контексту, `/compact` і пов’язані гачки життєвого циклу
|
||||
контексту субагента. `ownsCompaction: false` не вмикає автоматичний fallback до
|
||||
рушія legacy; активний рушій усе одно має коректно реалізовувати `compact()`. Див.
|
||||
[Context Engine](/uk/concepts/context-engine), щоб ознайомитися з повним
|
||||
підключуваним інтерфейсом, гачками життєвого циклу та конфігурацією.
|
||||
|
||||
## Що насправді показує `/context`
|
||||
|
||||
`/context` за можливості надає перевагу найсвіжішому звіту про system prompt, **побудованого під час запуску**:
|
||||
`/context` за можливості віддає перевагу найновішому звіту про системний запит, **побудований під час запуску**:
|
||||
|
||||
- `System prompt (run)` = захоплено з останнього вбудованого запуску (з підтримкою інструментів) і збережено в session store.
|
||||
- `System prompt (estimate)` = обчислено на льоту, коли звіту про запуск немає (або під час виконання через CLI backend, який не генерує такого звіту).
|
||||
- `System prompt (run)` = зафіксований з останнього вбудованого запуску (з підтримкою інструментів) і збережений у сховищі сесії.
|
||||
- `System prompt (estimate)` = обчислений на льоту, якщо звіту про запуску ще немає.
|
||||
|
||||
У будь-якому разі він повідомляє розміри та найбільші складові; він **не** виводить повний system prompt або схеми інструментів.
|
||||
У будь-якому випадку він показує розміри та найбільших учасників; він **не** вивантажує повний системний запит або схеми інструментів.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Context Engine](/concepts/context-engine) — власне впровадження контексту через plugins
|
||||
- [Compaction](/concepts/compaction) — підсумовування довгих розмов
|
||||
- [System Prompt](/concepts/system-prompt) — як будується system prompt
|
||||
- [Agent Loop](/concepts/agent-loop) — повний цикл виконання агента
|
||||
- [Context Engine](/uk/concepts/context-engine) — користувацьке впровадження контексту через плагіни
|
||||
- [Компресія](/uk/concepts/compaction) — узагальнення довгих розмов
|
||||
- [Системний запит](/uk/concepts/system-prompt) — як будується системний запит
|
||||
- [Цикл агента](/uk/concepts/agent-loop) — повний цикл виконання агента
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -1,90 +1,96 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви створюєте новий plugin каналу повідомлень
|
||||
- Ви створюєте новий плагін каналу обміну повідомленнями
|
||||
- Ви хочете підключити OpenClaw до платформи обміну повідомленнями
|
||||
- Вам потрібно зрозуміти поверхню адаптера ChannelPlugin
|
||||
sidebarTitle: Channel Plugins
|
||||
summary: Покроковий посібник зі створення plugin каналу повідомлень для OpenClaw
|
||||
title: Створення plugin каналів
|
||||
summary: Покроковий посібник зі створення плагіна каналу обміну повідомленнями для OpenClaw
|
||||
title: Створення плагінів каналів
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T18:12:37Z"
|
||||
generated_at: "2026-04-05T18:49:07Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 68a6ad2c75549db8ce54f7e22ca9850d7ed68c5cd651c9bb41c9f73769f48aba
|
||||
source_hash: 66b52c10945a8243d803af3bf7e1ea0051869ee92eda2af5718d9bb24fbb8552
|
||||
source_path: plugins/sdk-channel-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Створення plugin каналів
|
||||
# Створення плагінів каналів
|
||||
|
||||
Цей посібник покроково пояснює створення plugin каналу, який підключає OpenClaw до
|
||||
платформи обміну повідомленнями. Наприкінці ви матимете робочий канал із безпекою DM,
|
||||
pairing, гілками відповідей і вихідними повідомленнями.
|
||||
Цей посібник описує створення плагіна каналу, який підключає OpenClaw до
|
||||
платформи обміну повідомленнями. Наприкінці у вас буде робочий канал із
|
||||
захистом DM, паруванням, потоковістю відповідей і вихідними повідомленнями.
|
||||
|
||||
<Info>
|
||||
Якщо ви ще не створювали жодного plugin для OpenClaw, спочатку прочитайте
|
||||
[Getting Started](/plugins/building-plugins) про базову структуру пакета
|
||||
Якщо ви раніше не створювали жодного плагіна OpenClaw, спочатку прочитайте
|
||||
[Getting Started](/uk/plugins/building-plugins) про базову структуру пакета
|
||||
та налаштування маніфесту.
|
||||
</Info>
|
||||
|
||||
## Як працюють plugin каналів
|
||||
## Як працюють плагіни каналів
|
||||
|
||||
Plugin каналів не потребують власних інструментів send/edit/react. OpenClaw зберігає один
|
||||
спільний інструмент `message` у core. Ваш plugin відповідає за:
|
||||
Плагінам каналів не потрібні власні інструменти send/edit/react. OpenClaw
|
||||
зберігає один спільний інструмент `message` у core. Вашому плагіну належать:
|
||||
|
||||
- **Config** — визначення облікового запису та майстер налаштування
|
||||
- **Security** — політику DM і allowlist
|
||||
- **Pairing** — потік підтвердження DM
|
||||
- **Граматику сесій** — те, як специфічні для провайдера ідентифікатори розмов зіставляються з базовими чатами, ідентифікаторами гілок і резервними батьківськими значеннями
|
||||
- **Outbound** — надсилання тексту, медіа та опитувань на платформу
|
||||
- **Threading** — як упорядковуються відповіді в гілках
|
||||
- **Конфігурація** — визначення облікового запису та майстер налаштування
|
||||
- **Безпека** — політика DM та allowlist-и
|
||||
- **Парування** — процес підтвердження DM
|
||||
- **Граматика сесій** — як conversation id, специфічні для провайдера, зіставляються з базовими чатами, id потоків і резервними батьківськими значеннями
|
||||
- **Вихідні повідомлення** — надсилання тексту, медіа та опитувань на платформу
|
||||
- **Потоковість** — як упорядковуються відповіді
|
||||
|
||||
Core відповідає за спільний інструмент message, підключення prompt, зовнішню форму ключа сесії,
|
||||
загальний облік `:thread:` і диспетчеризацію.
|
||||
Core належить спільний інструмент message, зв’язування prompt-ів, зовнішня
|
||||
форма ключа сесії, загальний облік `:thread:` та диспетчеризація.
|
||||
|
||||
Якщо ваша платформа зберігає додаткову область в ідентифікаторах розмов, залиште цей розбір
|
||||
у plugin через `messaging.resolveSessionConversation(...)`. Це
|
||||
канонічний hook для зіставлення `rawId` з базовим ідентифікатором розмови, необов’язковим
|
||||
ідентифікатором гілки, явним `baseConversationId` і будь-якими
|
||||
Якщо ваша платформа зберігає додаткову область в межах conversation id,
|
||||
залишайте цей розбір у плагіні через
|
||||
`messaging.resolveSessionConversation(...)`. Це канонічний хук для
|
||||
зіставлення `rawId` з базовим conversation id, необов’язковим id потоку,
|
||||
явним `baseConversationId` і будь-якими
|
||||
`parentConversationCandidates`.
|
||||
Коли ви повертаєте `parentConversationCandidates`, зберігайте їх порядок
|
||||
від найвужчого батьківського елемента до найширшої/базової розмови.
|
||||
Коли ви повертаєте `parentConversationCandidates`, зберігайте їх порядок від
|
||||
найвужчого батьківського значення до найширшої/базової розмови.
|
||||
|
||||
Bundled plugin, яким потрібен той самий розбір до запуску реєстру каналів,
|
||||
також можуть надавати файл верхнього рівня `session-key-api.ts` із відповідним
|
||||
експортом `resolveSessionConversation(...)`. Core використовує цю безпечну для bootstrap поверхню
|
||||
лише тоді, коли реєстр runtime plugin ще недоступний.
|
||||
Вбудовані плагіни, яким потрібен той самий розбір до запуску реєстру каналів,
|
||||
також можуть експортувати файл верхнього рівня `session-key-api.ts` із
|
||||
відповідним експортом `resolveSessionConversation(...)`. Core використовує цю
|
||||
безпечну для bootstrap поверхню лише тоді, коли реєстр runtime-плагінів ще
|
||||
недоступний.
|
||||
|
||||
`messaging.resolveParentConversationCandidates(...)` і далі доступний як
|
||||
застарілий сумісний резервний механізм, коли plugin потрібні лише
|
||||
резервні батьківські значення поверх загального/raw id. Якщо існують обидва hooks, core використовує
|
||||
спочатку `resolveSessionConversation(...).parentConversationCandidates` і лише потім
|
||||
повертається до `resolveParentConversationCandidates(...)`, якщо канонічний hook
|
||||
`messaging.resolveParentConversationCandidates(...)` залишається доступним як
|
||||
застарілий резервний механізм сумісності, коли плагіну потрібні лише резервні
|
||||
батьківські значення поверх загального/сирого id. Якщо існують обидва хуки,
|
||||
core спочатку використовує
|
||||
`resolveSessionConversation(...).parentConversationCandidates` і повертається
|
||||
до `resolveParentConversationCandidates(...)` лише тоді, коли канонічний хук
|
||||
їх не надає.
|
||||
|
||||
## Підтвердження та можливості каналів
|
||||
## Погодження та можливості каналів
|
||||
|
||||
Більшості plugin каналів не потрібен код, специфічний для підтверджень.
|
||||
Більшості плагінів каналів не потрібен код, специфічний для погоджень.
|
||||
|
||||
- Core відповідає за `/approve` у тому самому чаті, спільні payload кнопок підтвердження та загальну резервну доставку.
|
||||
- Надавайте перевагу одному об’єкту `approvalCapability` у plugin каналу, коли каналу потрібна специфічна для підтверджень поведінка.
|
||||
- `approvalCapability.authorizeActorAction` і `approvalCapability.getActionAvailabilityState` — це канонічний шов авторизації підтверджень.
|
||||
- Використовуйте `outbound.shouldSuppressLocalPayloadPrompt` або `outbound.beforeDeliverPayload` для поведінки життєвого циклу payload, специфічної для каналу, наприклад приховування дублікатів локальних prompt підтвердження або надсилання індикаторів набору тексту перед доставкою.
|
||||
- Використовуйте `approvalCapability.delivery` лише для нативної маршрутизації підтверджень або придушення резервного механізму.
|
||||
- Використовуйте `approvalCapability.render` лише тоді, коли каналу справді потрібні власні payload підтверджень замість спільного renderer.
|
||||
- Якщо канал може виводити стабільні DM-ідентичності, подібні до власника, з наявного config, використовуйте `createResolvedApproverActionAuthAdapter` з `openclaw/plugin-sdk/approval-runtime`, щоб обмежити `/approve` у тому самому чаті без додавання специфічної для підтверджень логіки в core.
|
||||
- Якщо каналу потрібна нативна доставка підтверджень, зосередьте код каналу на нормалізації цілей і транспортних hooks. Використовуйте `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver`, `createApproverRestrictedNativeApprovalCapability` і `createChannelNativeApprovalRuntime` з `openclaw/plugin-sdk/approval-runtime`, щоб core відповідав за фільтрацію запитів, маршрутизацію, дедуплікацію, термін дії та підписку gateway.
|
||||
- Канали з нативними підтвердженнями мають маршрутизувати і `accountId`, і `approvalKind` через ці helper. `accountId` забезпечує прив’язку політики підтверджень для кількох облікових записів до правильного bot account, а `approvalKind` зберігає доступність поведінки exec і plugin для каналу без жорстко закодованих гілок у core.
|
||||
- Зберігайте тип delivered approval id від початку до кінця. Нативні клієнти не повинні
|
||||
вгадувати або переписувати маршрутизацію exec чи plugin підтверджень на основі локального стану каналу.
|
||||
- Різні види підтверджень можуть навмисно відкривати різні нативні поверхні.
|
||||
Поточні bundled приклади:
|
||||
- Slack зберігає доступність нативної маршрутизації підтверджень і для exec, і для plugin id.
|
||||
- Matrix зберігає нативну DM/канальну маршрутизацію лише для exec-підтверджень і залишає
|
||||
plugin-підтвердження на спільному шляху `/approve` у тому самому чаті.
|
||||
- `createApproverRestrictedNativeApprovalAdapter` і далі існує як сумісна обгортка, але новий код має віддавати перевагу builder можливостей і надавати `approvalCapability` у plugin.
|
||||
- Core керує `/approve` у тому самому чаті, спільними payload-ами кнопок погодження та загальною резервною доставкою.
|
||||
- Віддавайте перевагу одному об’єкту `approvalCapability` у плагіні каналу, коли каналу потрібна поведінка, специфічна для погоджень.
|
||||
- `approvalCapability.authorizeActorAction` і `approvalCapability.getActionAvailabilityState` — це канонічний шар авторизації погоджень.
|
||||
- Якщо ваш канал надає нативні погодження exec, реалізуйте `approvalCapability.getActionAvailabilityState` навіть якщо нативний транспорт повністю живе в `approvalCapability.native`. Core використовує цей хук доступності, щоб розрізняти `enabled` і `disabled`, визначати, чи підтримує ініціюючий канал нативні погодження, і включати канал до підказок резервного сценарію для нативного клієнта.
|
||||
- Використовуйте `outbound.shouldSuppressLocalPayloadPrompt` або `outbound.beforeDeliverPayload` для поведінки життєвого циклу payload-ів, специфічної для каналу, наприклад приховування дубльованих локальних prompt-ів погодження або надсилання індикаторів набору тексту перед доставкою.
|
||||
- Використовуйте `approvalCapability.delivery` лише для нативної маршрутизації погоджень або придушення резервного сценарію.
|
||||
- Використовуйте `approvalCapability.render` лише тоді, коли каналу справді потрібні власні payload-и погодження замість спільного рендерера.
|
||||
- Використовуйте `approvalCapability.describeExecApprovalSetup`, коли канал хоче, щоб відповідь у гілці disabled пояснювала точні параметри конфігурації, потрібні для ввімкнення нативних погоджень exec. Хук отримує `{ channel, channelLabel, accountId }`; канали з іменованими обліковими записами мають рендерити шляхи, прив’язані до облікового запису, наприклад `channels.<channel>.accounts.<id>.execApprovals.*`, замість значень верхнього рівня за замовчуванням.
|
||||
- Якщо канал може вивести стабільні DM-ідентичності, подібні до власника, із наявної конфігурації, використовуйте `createResolvedApproverActionAuthAdapter` з `openclaw/plugin-sdk/approval-runtime`, щоб обмежити `/approve` у тому самому чаті без додавання логіки погоджень, специфічної для core.
|
||||
- Якщо каналу потрібна нативна доставка погоджень, тримайте код каналу зосередженим на нормалізації цілі та транспортних хуках. Використовуйте `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver`, `createApproverRestrictedNativeApprovalCapability` і `createChannelNativeApprovalRuntime` з `openclaw/plugin-sdk/approval-runtime`, щоб core керував фільтрацією запитів, маршрутизацією, дедуплікацією, строком дії та підпискою gateway.
|
||||
- Канали з нативними погодженнями мають маршрутизувати і `accountId`, і `approvalKind` через ці хелпери. `accountId` зберігає політику погоджень для кількох облікових записів у межах правильного облікового запису бота, а `approvalKind` зберігає поведінку погоджень exec і плагінів доступною для каналу без жорстко закодованих гілок у core.
|
||||
- Зберігайте тип id доставленого погодження від початку до кінця. Нативні клієнти не повинні
|
||||
вгадувати або переписувати маршрутизацію погоджень exec чи плагінів на основі локального стану каналу.
|
||||
- Різні типи погоджень можуть навмисно відкривати різні нативні поверхні.
|
||||
Поточні приклади вбудованих плагінів:
|
||||
- Slack зберігає доступність нативної маршрутизації погоджень як для id exec, так і для id плагінів.
|
||||
- Matrix зберігає нативну маршрутизацію DM/каналів лише для погоджень exec і залишає
|
||||
погодження плагінів на спільному шляху `/approve` у тому самому чаті.
|
||||
- `createApproverRestrictedNativeApprovalAdapter` усе ще існує як обгортка сумісності, але новий код має віддавати перевагу побудовнику можливостей і надавати `approvalCapability` у плагіні.
|
||||
|
||||
Для гарячих точок входу каналів надавайте перевагу вужчим runtime subpath, коли вам потрібна лише одна частина цієї сім’ї:
|
||||
Для гарячих entrypoint-ів каналів віддавайте перевагу вужчим runtime-підшляхам,
|
||||
коли вам потрібна лише одна частина цієї групи:
|
||||
|
||||
- `openclaw/plugin-sdk/approval-auth-runtime`
|
||||
- `openclaw/plugin-sdk/approval-client-runtime`
|
||||
@ -92,70 +98,74 @@ Bundled plugin, яким потрібен той самий розбір до з
|
||||
- `openclaw/plugin-sdk/approval-native-runtime`
|
||||
- `openclaw/plugin-sdk/approval-reply-runtime`
|
||||
|
||||
Так само надавайте перевагу `openclaw/plugin-sdk/setup-runtime`,
|
||||
Так само віддавайте перевагу `openclaw/plugin-sdk/setup-runtime`,
|
||||
`openclaw/plugin-sdk/setup-adapter-runtime`,
|
||||
`openclaw/plugin-sdk/reply-runtime`,
|
||||
`openclaw/plugin-sdk/reply-dispatch-runtime`,
|
||||
`openclaw/plugin-sdk/reply-reference` і
|
||||
`openclaw/plugin-sdk/reply-chunking`, коли вам не потрібна ширша umbrella-поверхня.
|
||||
`openclaw/plugin-sdk/reply-chunking`, якщо вам не потрібна ширша
|
||||
узагальнювальна поверхня.
|
||||
|
||||
Окремо для setup:
|
||||
Зокрема для setup:
|
||||
|
||||
- `openclaw/plugin-sdk/setup-runtime` охоплює безпечні для runtime helper для setup:
|
||||
безпечні для import адаптери patched setup (`createPatchedAccountSetupAdapter`,
|
||||
- `openclaw/plugin-sdk/setup-runtime` охоплює безпечні для runtime хелпери setup:
|
||||
безпечні для import адаптери патчів setup (`createPatchedAccountSetupAdapter`,
|
||||
`createEnvPatchedAccountSetupAdapter`,
|
||||
`createSetupInputPresenceValidator`), вивід приміток lookup,
|
||||
`promptResolvedAllowFrom`, `splitSetupEntries` і delegated
|
||||
builder setup-proxy
|
||||
- `openclaw/plugin-sdk/setup-adapter-runtime` — це вузький env-aware adapter
|
||||
seam для `createEnvPatchedAccountSetupAdapter`
|
||||
- `openclaw/plugin-sdk/channel-setup` охоплює builder optional-install setup
|
||||
плюс кілька безпечних для setup примітивів:
|
||||
`createSetupInputPresenceValidator`), вивід приміток пошуку,
|
||||
`promptResolvedAllowFrom`, `splitSetupEntries` і делеговані
|
||||
побудовники proxy для setup
|
||||
- `openclaw/plugin-sdk/setup-adapter-runtime` — це вузький env-aware шар
|
||||
адаптера для `createEnvPatchedAccountSetupAdapter`
|
||||
- `openclaw/plugin-sdk/channel-setup` охоплює побудовники setup для
|
||||
необов’язкового встановлення, а також кілька безпечних для setup примітивів:
|
||||
`createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`,
|
||||
`createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`,
|
||||
`createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` і
|
||||
`splitSetupEntries`
|
||||
- використовуйте ширший seam `openclaw/plugin-sdk/setup` лише тоді, коли вам також потрібні
|
||||
важчі спільні helper для setup/config, такі як
|
||||
- використовуйте ширший шар `openclaw/plugin-sdk/setup` лише тоді, коли вам також потрібні
|
||||
важчі спільні хелпери setup/config, наприклад
|
||||
`moveSingleAccountChannelSectionToDefaultAccount(...)`
|
||||
|
||||
Якщо ваш канал хоче лише рекламувати "спочатку встановіть цей plugin" у поверхнях setup,
|
||||
надавайте перевагу `createOptionalChannelSetupSurface(...)`. Згенеровані
|
||||
adapter/wizard закриваються безпечно для записів config і фіналізації, а також повторно використовують
|
||||
одне й те саме повідомлення про обов’язкове встановлення у валідації, finalize і тексті з посиланням на docs.
|
||||
Якщо ваш канал хоче лише повідомляти "спочатку встановіть цей плагін" на
|
||||
поверхнях setup, віддавайте перевагу `createOptionalChannelSetupSurface(...)`.
|
||||
Згенеровані adapter/wizard працюють у режимі fail closed для записів у конфігурацію
|
||||
та фіналізації й повторно використовують те саме повідомлення про необхідність
|
||||
встановлення у валідації, finalize та тексті з посиланням на документацію.
|
||||
|
||||
Для інших гарячих шляхів каналів надавайте перевагу вузьким helper замість ширших застарілих
|
||||
поверхонь:
|
||||
Для інших гарячих шляхів каналу віддавайте перевагу вузьким хелперам замість
|
||||
ширших застарілих поверхонь:
|
||||
|
||||
- `openclaw/plugin-sdk/account-core`,
|
||||
`openclaw/plugin-sdk/account-id`,
|
||||
`openclaw/plugin-sdk/account-resolution` і
|
||||
`openclaw/plugin-sdk/account-helpers` для config із кількома обліковими записами та
|
||||
резервного механізму account за замовчуванням
|
||||
`openclaw/plugin-sdk/account-helpers` для конфігурації кількох
|
||||
облікових записів і резервного повернення до облікового запису за
|
||||
замовчуванням
|
||||
- `openclaw/plugin-sdk/inbound-envelope` і
|
||||
`openclaw/plugin-sdk/inbound-reply-dispatch` для маршруту/конверта вхідних повідомлень та
|
||||
підключення запису і диспетчеризації
|
||||
`openclaw/plugin-sdk/inbound-reply-dispatch` для маршрутизації/конвертів
|
||||
вхідних повідомлень і зв’язування record-and-dispatch
|
||||
- `openclaw/plugin-sdk/messaging-targets` для розбору/зіставлення цілей
|
||||
- `openclaw/plugin-sdk/outbound-media` і
|
||||
`openclaw/plugin-sdk/outbound-runtime` для завантаження медіа плюс delegate
|
||||
вихідної ідентичності/надсилання
|
||||
- `openclaw/plugin-sdk/thread-bindings-runtime` для життєвого циклу прив’язок гілок
|
||||
і реєстрації adapter
|
||||
`openclaw/plugin-sdk/outbound-runtime` для завантаження медіа та
|
||||
делегатів ідентичності/надсилання вихідних повідомлень
|
||||
- `openclaw/plugin-sdk/thread-bindings-runtime` для життєвого циклу
|
||||
прив’язок потоків і реєстрації адаптерів
|
||||
- `openclaw/plugin-sdk/agent-media-payload` лише тоді, коли все ще потрібна
|
||||
застаріла схема полів payload агента/медіа
|
||||
- `openclaw/plugin-sdk/telegram-command-config` для нормалізації власних команд Telegram,
|
||||
валідації дублікатів/конфліктів і стабільного щодо резервного механізму контракту config команд
|
||||
застаріла структура полів payload-ів agent/media
|
||||
- `openclaw/plugin-sdk/telegram-command-config` для нормалізації
|
||||
користувацьких команд Telegram, валідації дублікатів/конфліктів і
|
||||
стабільного як резервний варіант контракту конфігурації команд
|
||||
|
||||
Канали лише з auth зазвичай можуть зупинитися на стандартному шляху: core обробляє підтвердження, а plugin просто надає можливості outbound/auth. Канали з нативними підтвердженнями, як-от Matrix, Slack, Telegram і custom chat transport, повинні використовувати спільні нативні helper замість власної реалізації життєвого циклу підтверджень.
|
||||
Канали лише з auth зазвичай можуть зупинитися на стандартному шляху: core керує погодженнями, а плагін лише надає можливості outbound/auth. Канали з нативними погодженнями, такі як Matrix, Slack, Telegram і власні транспортні рішення для чатів, мають використовувати спільні нативні хелпери замість створення власного життєвого циклу погоджень.
|
||||
|
||||
## Покроковий розбір
|
||||
## Покрокове проходження
|
||||
|
||||
<Steps>
|
||||
<a id="step-1-package-and-manifest"></a>
|
||||
<Step title="Пакет і маніфест">
|
||||
Створіть стандартні файли plugin. Поле `channel` у `package.json`
|
||||
робить цей plugin канальним plugin. Повний опис поверхні метаданих пакета
|
||||
див. у [Plugin Setup and Config](/plugins/sdk-setup#openclawchannel):
|
||||
Створіть стандартні файли плагіна. Поле `channel` у `package.json`
|
||||
визначає, що це плагін каналу. Повну поверхню метаданих пакета див. у
|
||||
[Plugin Setup and Config](/uk/plugins/sdk-setup#openclawchannel):
|
||||
|
||||
<CodeGroup>
|
||||
```json package.json
|
||||
@ -204,9 +214,9 @@ adapter/wizard закриваються безпечно для записів c
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Створіть об’єкт plugin каналу">
|
||||
Інтерфейс `ChannelPlugin` має багато необов’язкових поверхонь adapter. Почніть із
|
||||
мінімуму — `id` і `setup` — і додавайте adapter за потреби.
|
||||
<Step title="Створіть об’єкт плагіна каналу">
|
||||
Інтерфейс `ChannelPlugin` має багато необов’язкових поверхонь адаптерів. Почніть
|
||||
з мінімуму — `id` і `setup` — і додавайте адаптери за потреби.
|
||||
|
||||
Створіть `src/channel.ts`:
|
||||
|
||||
@ -216,7 +226,7 @@ adapter/wizard закриваються безпечно для записів c
|
||||
createChannelPluginBase,
|
||||
} from "openclaw/plugin-sdk/channel-core";
|
||||
import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
|
||||
import { acmeChatApi } from "./client.js"; // ваш клієнт API платформи
|
||||
import { acmeChatApi } from "./client.js"; // your platform API client
|
||||
|
||||
type ResolvedAccount = {
|
||||
accountId: string | null;
|
||||
@ -257,7 +267,7 @@ adapter/wizard закриваються безпечно для записів c
|
||||
},
|
||||
}),
|
||||
|
||||
// Безпека DM: хто може писати боту
|
||||
// DM security: who can message the bot
|
||||
security: {
|
||||
dm: {
|
||||
channelKey: "acme-chat",
|
||||
@ -267,7 +277,7 @@ adapter/wizard закриваються безпечно для записів c
|
||||
},
|
||||
},
|
||||
|
||||
// Pairing: потік підтвердження для нових контактів у DM
|
||||
// Pairing: approval flow for new DM contacts
|
||||
pairing: {
|
||||
text: {
|
||||
idLabel: "Acme Chat username",
|
||||
@ -278,10 +288,10 @@ adapter/wizard закриваються безпечно для записів c
|
||||
},
|
||||
},
|
||||
|
||||
// Threading: як доставляються відповіді
|
||||
// Threading: how replies are delivered
|
||||
threading: { topLevelReplyToMode: "reply" },
|
||||
|
||||
// Outbound: надсилання повідомлень на платформу
|
||||
// Outbound: send messages to the platform
|
||||
outbound: {
|
||||
attachedResults: {
|
||||
sendText: async (params) => {
|
||||
@ -302,23 +312,23 @@ adapter/wizard закриваються безпечно для записів c
|
||||
```
|
||||
|
||||
<Accordion title="Що для вас робить createChatChannelPlugin">
|
||||
Замість ручної реалізації низькорівневих інтерфейсів adapter ви передаєте
|
||||
декларативні параметри, а builder компонує їх:
|
||||
Замість ручної реалізації низькорівневих інтерфейсів адаптерів, ви
|
||||
передаєте декларативні параметри, а побудовник компонує їх:
|
||||
|
||||
| Параметр | Що він підключає |
|
||||
| Option | Що він підключає |
|
||||
| --- | --- |
|
||||
| `security.dm` | Scoped-резолвер безпеки DM з полів config |
|
||||
| `pairing.text` | Потік pairing у DM на основі тексту з обміном кодами |
|
||||
| `threading` | Резолвер режиму reply-to (фіксований, scoped за account або custom) |
|
||||
| `outbound.attachedResults` | Функції надсилання, які повертають метадані результату (ідентифікатори повідомлень) |
|
||||
| `security.dm` | Scoped-резолвер безпеки DM із полів конфігурації |
|
||||
| `pairing.text` | Текстовий процес парування DM з обміном кодом |
|
||||
| `threading` | Резолвер режиму reply-to (фіксований, прив’язаний до облікового запису або користувацький) |
|
||||
| `outbound.attachedResults` | Функції надсилання, які повертають метадані результату (ID повідомлень) |
|
||||
|
||||
Ви також можете передавати сирі об’єкти adapter замість декларативних параметрів,
|
||||
Ви також можете передавати сирі об’єкти адаптерів замість декларативних параметрів,
|
||||
якщо вам потрібен повний контроль.
|
||||
</Accordion>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Підключіть точку входу">
|
||||
<Step title="Підключіть entry point">
|
||||
Створіть `index.ts`:
|
||||
|
||||
```typescript index.ts
|
||||
@ -354,22 +364,22 @@ adapter/wizard закриваються безпечно для записів c
|
||||
});
|
||||
```
|
||||
|
||||
Розміщуйте CLI descriptors, якими володіє канал, у `registerCliMetadata(...)`, щоб OpenClaw
|
||||
Розміщуйте дескриптори CLI, що належать каналу, у `registerCliMetadata(...)`, щоб OpenClaw
|
||||
міг показувати їх у кореневій довідці без активації повного runtime каналу,
|
||||
а звичайні повні завантаження все одно підхоплювали ті самі descriptors для реєстрації реальних команд.
|
||||
Залишайте `registerFull(...)` для роботи лише під час runtime.
|
||||
Якщо `registerFull(...)` реєструє gateway RPC methods, використовуйте
|
||||
prefix, специфічний для plugin. Простори імен адміністрування core (`config.*`,
|
||||
тоді як звичайні повні завантаження все одно підхоплюватимуть ті самі дескриптори для реєстрації
|
||||
реальних команд. Залишайте `registerFull(...)` для роботи, потрібної лише в runtime.
|
||||
Якщо `registerFull(...)` реєструє gateway RPC-методи, використовуйте
|
||||
префікс, специфічний для плагіна. Простори імен адмін-інтерфейсу core (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими і завжди
|
||||
зіставляються з `operator.admin`.
|
||||
`defineChannelPluginEntry` автоматично обробляє поділ режимів реєстрації. Див.
|
||||
[Entry Points](/plugins/sdk-entrypoints#definechannelpluginentry) для всіх
|
||||
параметрів.
|
||||
`defineChannelPluginEntry` автоматично обробляє цей поділ режимів реєстрації. У
|
||||
[Entry Points](/uk/plugins/sdk-entrypoints#definechannelpluginentry) див. усі
|
||||
параметри.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте setup entry">
|
||||
Створіть `setup-entry.ts` для легкого завантаження під час onboarding:
|
||||
Створіть `setup-entry.ts` для легкого завантаження під час онбордингу:
|
||||
|
||||
```typescript setup-entry.ts
|
||||
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
@ -378,28 +388,28 @@ adapter/wizard закриваються безпечно для записів c
|
||||
export default defineSetupPluginEntry(acmeChatPlugin);
|
||||
```
|
||||
|
||||
OpenClaw завантажує цей файл замість повної точки входу, коли канал вимкнено
|
||||
або не налаштовано. Це дозволяє уникнути підтягування важкого runtime-коду під час потоків setup.
|
||||
Подробиці див. у [Setup and Config](/plugins/sdk-setup#setup-entry).
|
||||
OpenClaw завантажує це замість повного entry, коли канал вимкнений
|
||||
або не налаштований. Це дає змогу не підтягувати важкий runtime-код під час процесів setup.
|
||||
Докладніше див. у [Setup and Config](/uk/plugins/sdk-setup#setup-entry).
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Обробляйте вхідні повідомлення">
|
||||
Ваш plugin має отримувати повідомлення з платформи та пересилати їх до
|
||||
OpenClaw. Типовий шаблон — webhook, який перевіряє запит і
|
||||
диспетчеризує його через inbound handler вашого каналу:
|
||||
Ваш плагін має отримувати повідомлення з платформи та переспрямовувати їх до
|
||||
OpenClaw. Типовий шаблон — це webhook, який перевіряє запит і
|
||||
диспетчеризує його через обробник вхідних повідомлень вашого каналу:
|
||||
|
||||
```typescript
|
||||
registerFull(api) {
|
||||
api.registerHttpRoute({
|
||||
path: "/acme-chat/webhook",
|
||||
auth: "plugin", // auth під керуванням plugin (перевіряйте підписи самостійно)
|
||||
auth: "plugin", // plugin-managed auth (verify signatures yourself)
|
||||
handler: async (req, res) => {
|
||||
const event = parseWebhookPayload(req);
|
||||
|
||||
// Ваш inbound handler диспетчеризує повідомлення до OpenClaw.
|
||||
// Точне підключення залежить від SDK вашої платформи —
|
||||
// див. реальний приклад у пакеті bundled plugin Microsoft Teams або Google Chat.
|
||||
// Your inbound handler dispatches the message to OpenClaw.
|
||||
// The exact wiring depends on your platform SDK —
|
||||
// see a real example in the bundled Microsoft Teams or Google Chat plugin package.
|
||||
await handleAcmeChatInbound(api, event);
|
||||
|
||||
res.statusCode = 200;
|
||||
@ -411,16 +421,16 @@ adapter/wizard закриваються безпечно для записів c
|
||||
```
|
||||
|
||||
<Note>
|
||||
Обробка вхідних повідомлень є специфічною для каналу. Кожен plugin каналу
|
||||
володіє власним inbound-конвеєром. Подивіться на bundled plugin каналів
|
||||
(наприклад пакет plugin Microsoft Teams або Google Chat), щоб побачити реальні шаблони.
|
||||
Обробка вхідних повідомлень є специфічною для каналу. Кожен плагін каналу
|
||||
володіє власним конвеєром вхідних повідомлень. Перегляньте вбудовані плагіни каналів
|
||||
(наприклад пакет плагіна Microsoft Teams або Google Chat), щоб побачити реальні шаблони.
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
|
||||
<a id="step-6-test"></a>
|
||||
<Step title="Тестування">
|
||||
Пишіть colocated-тести у `src/channel.test.ts`:
|
||||
Пишіть колоковані тести у `src/channel.test.ts`:
|
||||
|
||||
```typescript src/channel.test.ts
|
||||
import { describe, it, expect } from "vitest";
|
||||
@ -458,7 +468,7 @@ adapter/wizard закриваються безпечно для записів c
|
||||
pnpm test -- <bundled-plugin-root>/acme-chat/
|
||||
```
|
||||
|
||||
Спільні helper для тестування див. у [Testing](/plugins/sdk-testing).
|
||||
Спільні хелпери для тестування див. у [Testing](/uk/plugins/sdk-testing).
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
@ -467,8 +477,8 @@ adapter/wizard закриваються безпечно для записів c
|
||||
|
||||
```
|
||||
<bundled-plugin-root>/acme-chat/
|
||||
├── package.json # Метадані openclaw.channel
|
||||
├── openclaw.plugin.json # Маніфест зі схемою config
|
||||
├── package.json # metadata openclaw.channel
|
||||
├── openclaw.plugin.json # Маніфест зі схемою конфігурації
|
||||
├── index.ts # defineChannelPluginEntry
|
||||
├── setup-entry.ts # defineSetupPluginEntry
|
||||
├── api.ts # Публічні експорти (необов’язково)
|
||||
@ -476,37 +486,37 @@ adapter/wizard закриваються безпечно для записів c
|
||||
└── src/
|
||||
├── channel.ts # ChannelPlugin через createChatChannelPlugin
|
||||
├── channel.test.ts # Тести
|
||||
├── client.ts # Клієнт API платформи
|
||||
└── runtime.ts # Сховище runtime (за потреби)
|
||||
├── client.ts # API-клієнт платформи
|
||||
└── runtime.ts # Runtime-сховище (за потреби)
|
||||
```
|
||||
|
||||
## Розширені теми
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Параметри threading" icon="git-branch" href="/plugins/sdk-entrypoints#registration-mode">
|
||||
Фіксовані reply-режими, scoped за account або custom
|
||||
<Card title="Параметри потоковості" icon="git-branch" href="/uk/plugins/sdk-entrypoints#registration-mode">
|
||||
Фіксовані, прив’язані до облікового запису або користувацькі режими reply
|
||||
</Card>
|
||||
<Card title="Інтеграція інструмента message" icon="puzzle" href="/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
<Card title="Інтеграція інструмента message" icon="puzzle" href="/uk/plugins/architecture#channel-plugins-and-the-shared-message-tool">
|
||||
describeMessageTool і виявлення дій
|
||||
</Card>
|
||||
<Card title="Визначення цілей" icon="crosshair" href="/plugins/architecture#channel-target-resolution">
|
||||
<Card title="Визначення цілі" icon="crosshair" href="/uk/plugins/architecture#channel-target-resolution">
|
||||
inferTargetChatType, looksLikeId, resolveTarget
|
||||
</Card>
|
||||
<Card title="Runtime helper" icon="settings" href="/plugins/sdk-runtime">
|
||||
TTS, STT, медіа, subagent через api.runtime
|
||||
<Card title="Runtime-хелпери" icon="settings" href="/uk/plugins/sdk-runtime">
|
||||
TTS, STT, media, subagent через api.runtime
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Note>
|
||||
Деякі bundled helper seams і далі існують для підтримки bundled plugin і
|
||||
сумісності. Це не рекомендований шаблон для нових plugin каналів;
|
||||
надавайте перевагу загальним channel/setup/reply/runtime subpath зі спільної поверхні SDK,
|
||||
якщо тільки ви безпосередньо не підтримуєте цю сім’ю bundled plugin.
|
||||
Деякі вбудовані допоміжні шари все ще існують для супроводу вбудованих плагінів
|
||||
та сумісності. Це не рекомендований шаблон для нових плагінів каналів;
|
||||
віддавайте перевагу загальним підшляхам channel/setup/reply/runtime зі спільної
|
||||
поверхні SDK, якщо тільки ви не супроводжуєте безпосередньо цю сім’ю вбудованих плагінів.
|
||||
</Note>
|
||||
|
||||
## Наступні кроки
|
||||
|
||||
- [Provider Plugins](/plugins/sdk-provider-plugins) — якщо ваш plugin також надає моделі
|
||||
- [SDK Overview](/plugins/sdk-overview) — повний довідник import subpath
|
||||
- [SDK Testing](/plugins/sdk-testing) — утиліти тестування та контрактні тести
|
||||
- [Plugin Manifest](/plugins/manifest) — повна схема маніфесту
|
||||
- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — якщо ваш плагін також надає моделі
|
||||
- [SDK Overview](/uk/plugins/sdk-overview) — повний довідник з імпортів підшляхів
|
||||
- [SDK Testing](/uk/plugins/sdk-testing) — тестові утиліти та контрактні тести
|
||||
- [Plugin Manifest](/uk/plugins/manifest) — повна схема маніфесту
|
||||
|
||||
@ -4,27 +4,27 @@ read_when:
|
||||
- Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi
|
||||
- Ви шукаєте конкретний експорт SDK
|
||||
sidebarTitle: SDK Overview
|
||||
summary: Карта імпортів, довідник API реєстрації та архітектура SDK
|
||||
summary: Карта імпорту, довідник API реєстрації та архітектура SDK
|
||||
title: Огляд Plugin SDK
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T18:13:38Z"
|
||||
generated_at: "2026-04-05T18:49:41Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fb25f3f96ca1f522780f5a52eaedb85a8adf3cfb2934df625db3fe8b5f7e0666
|
||||
source_hash: d70ea8cc1343b2dc1b4243b0562d19bebb1fdf7eb5065220b17e87cfd8aecc3e
|
||||
source_path: plugins/sdk-overview.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Огляд Plugin SDK
|
||||
|
||||
Plugin SDK — це типізований контракт між плагінами та core. Ця сторінка є
|
||||
довідником для **що імпортувати** і **що ви можете реєструвати**.
|
||||
Plugin SDK — це типізований контракт між plugins і ядром. Ця сторінка є
|
||||
довідником про **що імпортувати** і **що можна реєструвати**.
|
||||
|
||||
<Tip>
|
||||
**Шукаєте практичний посібник?**
|
||||
- Перший плагін? Почніть із [Початок роботи](/plugins/building-plugins)
|
||||
- Плагін каналу? Див. [Плагіни каналів](/plugins/sdk-channel-plugins)
|
||||
- Плагін провайдера? Див. [Плагіни провайдерів](/plugins/sdk-provider-plugins)
|
||||
**Шукаєте покроковий посібник?**
|
||||
- Перший plugin? Почніть із [Getting Started](/uk/plugins/building-plugins)
|
||||
- Plugin каналу? Дивіться [Channel Plugins](/uk/plugins/sdk-channel-plugins)
|
||||
- Plugin постачальника? Дивіться [Provider Plugins](/uk/plugins/sdk-provider-plugins)
|
||||
</Tip>
|
||||
|
||||
## Угода щодо імпорту
|
||||
@ -36,39 +36,41 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
```
|
||||
|
||||
Кожен підшлях — це невеликий самодостатній модуль. Це зберігає швидкий запуск і
|
||||
запобігає проблемам із циклічними залежностями. Для специфічних для каналів
|
||||
допоміжних функцій entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте для
|
||||
ширшої umbrella-поверхні та спільних допоміжних функцій, таких як
|
||||
Кожен підшлях — це невеликий самодостатній модуль. Це забезпечує швидкий
|
||||
запуск і запобігає проблемам із циклічними залежностями. Для специфічних для
|
||||
каналів допоміжних засобів entry/build віддавайте перевагу
|
||||
`openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для
|
||||
ширшої узагальненої поверхні та спільних помічників, таких як
|
||||
`buildChannelConfigSchema`.
|
||||
|
||||
Не додавайте і не покладайтеся на зручні шви з іменами провайдерів, такі як
|
||||
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
|
||||
Не додавайте й не використовуйте зручні шви, названі на честь постачальників,
|
||||
такі як `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
|
||||
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, або
|
||||
допоміжні шви з брендуванням каналу. Пакети вбудованих плагінів мають компонувати загальні
|
||||
підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а core
|
||||
має або використовувати ці локальні barrel-файли плагіна, або додавати вузький загальний контракт SDK, коли потреба справді є міжканальною.
|
||||
допоміжні шви з брендуванням каналів. Вбудовані plugins мають компонувати
|
||||
узагальнені підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`,
|
||||
а ядро має або використовувати ці локальні barrel-файли plugin, або додавати
|
||||
вузький узагальнений контракт SDK, коли потреба справді є міжканальною.
|
||||
|
||||
Згенерована карта експортів усе ще містить невеликий набір
|
||||
допоміжних швів для вбудованих плагінів, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
|
||||
Згенерована карта експортів усе ще містить невеликий набір допоміжних швів
|
||||
вбудованих plugins, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
|
||||
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Ці
|
||||
підшляхи існують лише для супроводу вбудованих плагінів і сумісності; їх
|
||||
навмисно пропущено в загальній таблиці нижче, і вони не є рекомендованим
|
||||
шляхом імпорту для нових сторонніх плагінів.
|
||||
підшляхи існують лише для підтримки та сумісності вбудованих plugins; вони
|
||||
навмисно не включені до загальної таблиці нижче і не є рекомендованим шляхом
|
||||
імпорту для нових сторонніх plugins.
|
||||
|
||||
## Довідник підшляхів
|
||||
|
||||
Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список із
|
||||
понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список
|
||||
із понад 200 підшляхів міститься у `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
Зарезервовані допоміжні підшляхи для вбудованих плагінів усе ще з’являються в цьому згенерованому списку.
|
||||
Розглядайте їх як поверхні деталей реалізації/сумісності, якщо тільки сторінка документації
|
||||
явно не просуває один із них як публічний.
|
||||
Зарезервовані допоміжні підшляхи вбудованих plugins усе ще з’являються в цьому
|
||||
згенерованому списку. Розглядайте їх як поверхні деталей реалізації/сумісності,
|
||||
якщо лише сторінка документації явно не просуває одну з них як публічну.
|
||||
|
||||
### Entry плагіна
|
||||
### Entry plugin
|
||||
|
||||
| Підшлях | Ключові експорти |
|
||||
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Підшлях | Ключові експорти |
|
||||
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
|
||||
| `plugin-sdk/config-schema` | `OpenClawSchema` |
|
||||
@ -81,259 +83,257 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) |
|
||||
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/setup` | Спільні допоміжні функції майстра налаштування, запити allowlist, побудовники статусу налаштування |
|
||||
| `plugin-sdk/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` | Допоміжні функції конфігурації/контролю дій для кількох облікових записів, допоміжні функції резервного переходу до типового облікового запису |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні функції нормалізації ідентифікатора облікового запису |
|
||||
| `plugin-sdk/account-resolution` | Допоміжні функції пошуку облікового запису + резервного переходу до типового |
|
||||
| `plugin-sdk/account-helpers` | Вузькі допоміжні функції списку облікових записів/дій з обліковим записом |
|
||||
| `plugin-sdk/account-core` | Помічники для конфігурації/обмеження дій для кількох облікових записів, помічники резервного переходу на типовий обліковий запис |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, помічники нормалізації id облікового запису |
|
||||
| `plugin-sdk/account-resolution` | Помічники пошуку облікового запису + резервного переходу до типового |
|
||||
| `plugin-sdk/account-helpers` | Вузькі помічники для списку облікових записів/дій з обліковими записами |
|
||||
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | Типи схеми конфігурації каналу |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні функції нормалізації/валідації кастомних команд Telegram із резервним переходом до контракту вбудованого пакета |
|
||||
| `plugin-sdk/telegram-command-config` | Помічники нормалізації/валідації користувацьких команд Telegram із резервною підтримкою вбудованого контракту |
|
||||
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
|
||||
| `plugin-sdk/inbound-envelope` | Спільні допоміжні функції маршруту вхідних даних + побудовника envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні функції запису та диспетчеризації вхідних даних |
|
||||
| `plugin-sdk/messaging-targets` | Допоміжні функції розбору/зіставлення цілей |
|
||||
| `plugin-sdk/outbound-media` | Спільні допоміжні функції завантаження вихідних медіа |
|
||||
| `plugin-sdk/outbound-runtime` | Допоміжні функції делегування вихідної ідентичності/надсилання |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Життєвий цикл прив’язок потоків та допоміжні функції адаптера |
|
||||
| `plugin-sdk/agent-media-payload` | Застарілий побудовник медіапейлоада агента |
|
||||
| `plugin-sdk/conversation-runtime` | Допоміжні функції прив’язки розмови/потоку, парування та налаштованої прив’язки |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Допоміжна функція знімка конфігурації runtime |
|
||||
| `plugin-sdk/runtime-group-policy` | Допоміжні функції розв’язання політики груп runtime |
|
||||
| `plugin-sdk/channel-status` | Спільні допоміжні функції знімка/підсумку стану каналу |
|
||||
| `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу |
|
||||
| `plugin-sdk/channel-config-writes` | Допоміжні функції авторизації запису конфігурації каналу |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільні експорти прелюдії плагіна каналу |
|
||||
| `plugin-sdk/allowlist-config-edit` | Допоміжні функції редагування/читання конфігурації allowlist |
|
||||
| `plugin-sdk/group-access` | Спільні допоміжні функції рішень щодо доступу до груп |
|
||||
| `plugin-sdk/direct-dm` | Спільні допоміжні функції auth/guard для прямих DM |
|
||||
| `plugin-sdk/interactive-runtime` | Допоміжні функції нормалізації/скорочення інтерактивного пейлоада відповіді |
|
||||
| `plugin-sdk/channel-inbound` | Допоміжні функції debounce, зіставлення згадок, envelope |
|
||||
| `plugin-sdk/inbound-envelope` | Спільні помічники для маршрутизації вхідних повідомлень + побудови envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Спільні помічники запису й диспетчеризації вхідних повідомлень |
|
||||
| `plugin-sdk/messaging-targets` | Помічники розбору/зіставлення цілей |
|
||||
| `plugin-sdk/outbound-media` | Спільні помічники завантаження вихідних медіа |
|
||||
| `plugin-sdk/outbound-runtime` | Помічники вихідної ідентичності/делегування надсилання |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Помічники життєвого циклу та адаптерів прив’язок потоків |
|
||||
| `plugin-sdk/agent-media-payload` | Застарілий побудовник медіа-пейлоаду агента |
|
||||
| `plugin-sdk/conversation-runtime` | Помічники прив’язки розмови/потоку, pairing і configured-binding |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Помічник знімка конфігурації часу виконання |
|
||||
| `plugin-sdk/runtime-group-policy` | Помічники визначення group-policy під час виконання |
|
||||
| `plugin-sdk/channel-status` | Спільні помічники знімка/зведення статусу каналу |
|
||||
| `plugin-sdk/channel-config-primitives` | Вузькі примітиви config-schema каналу |
|
||||
| `plugin-sdk/channel-config-writes` | Помічники авторизації запису конфігурації каналу |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільні прелюд-експорти plugin каналу |
|
||||
| `plugin-sdk/allowlist-config-edit` | Помічники редагування/читання конфігурації списку дозволених |
|
||||
| `plugin-sdk/group-access` | Спільні помічники рішень щодо group-access |
|
||||
| `plugin-sdk/direct-dm` | Спільні помічники auth/guard для прямих DM |
|
||||
| `plugin-sdk/interactive-runtime` | Помічники нормалізації/скорочення пейлоаду інтерактивних відповідей |
|
||||
| `plugin-sdk/channel-inbound` | Debounce, зіставлення згадок, помічники envelope |
|
||||
| `plugin-sdk/channel-send-result` | Типи результатів відповіді |
|
||||
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
|
||||
| `plugin-sdk/channel-targets` | Допоміжні функції розбору/зіставлення цілей |
|
||||
| `plugin-sdk/channel-targets` | Помічники розбору/зіставлення цілей |
|
||||
| `plugin-sdk/channel-contract` | Типи контракту каналу |
|
||||
| `plugin-sdk/channel-feedback` | Підключення feedback/reaction |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи провайдерів">
|
||||
<Accordion title="Підшляхи постачальників">
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/provider-setup` | Кураторські допоміжні функції налаштування локального/self-hosted провайдера |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні функції налаштування self-hosted провайдера, сумісного з OpenAI |
|
||||
| `plugin-sdk/cli-backend` | Типові значення CLI backend + константи watchdog |
|
||||
| `plugin-sdk/provider-auth-runtime` | Допоміжні функції runtime для розв’язання API-ключа для плагінів провайдерів |
|
||||
| `plugin-sdk/provider-auth-api-key` | Допоміжні функції онбордингу/запису профілю API-ключа |
|
||||
| `plugin-sdk/provider-setup` | Добірні помічники налаштування локальних/self-hosted постачальників |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Сфокусовані помічники налаштування self-hosted постачальника, сумісного з OpenAI |
|
||||
| `plugin-sdk/provider-auth-runtime` | Помічники визначення API-ключа під час виконання для plugins постачальників |
|
||||
| `plugin-sdk/provider-auth-api-key` | Помічники онбордингу/запису профілю для API-ключів |
|
||||
| `plugin-sdk/provider-auth-result` | Стандартний побудовник результату OAuth auth |
|
||||
| `plugin-sdk/provider-auth-login` | Спільні допоміжні функції інтерактивного входу для плагінів провайдерів |
|
||||
| `plugin-sdk/provider-env-vars` | Допоміжні функції пошуку env var для auth провайдера |
|
||||
| `plugin-sdk/provider-auth-login` | Спільні помічники інтерактивного входу для plugins постачальників |
|
||||
| `plugin-sdk/provider-env-vars` | Помічники пошуку env vars auth постачальника |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники політики повторення, допоміжні функції endpoint провайдера та допоміжні функції нормалізації model-id, такі як `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники replay-policy, помічники endpoint постачальників і помічники нормалізації model-id, такі як `normalizeNativeXaiModelId` |
|
||||
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-http` | Загальні допоміжні функції HTTP/можливостей endpoint провайдера |
|
||||
| `plugin-sdk/provider-web-fetch` | Допоміжні функції реєстрації/кешу web-fetch провайдера |
|
||||
| `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/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-onboard` | Допоміжні функції патчів конфігурації онбордингу |
|
||||
| `plugin-sdk/global-singleton` | Допоміжні функції локальних для процесу singleton/map/cache |
|
||||
| `plugin-sdk/provider-http` | Узагальнені помічники HTTP/можливостей endpoint постачальника |
|
||||
| `plugin-sdk/provider-web-fetch` | Помічники реєстрації/кешу постачальника web-fetch |
|
||||
| `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/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-onboard` | Помічники виправлення конфігурації онбордингу |
|
||||
| `plugin-sdk/global-singleton` | Помічники локальних для процесу singleton/map/cache |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи auth і безпеки">
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні функції реєстру команд, допоміжні функції авторизації відправника |
|
||||
| `plugin-sdk/approval-auth-runtime` | Допоміжні функції розв’язання approver і auth дій у тому самому чаті |
|
||||
| `plugin-sdk/approval-client-runtime` | Допоміжні функції профілю/фільтра схвалення native exec |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Адаптери доставки/можливостей native approval |
|
||||
| `plugin-sdk/approval-native-runtime` | Допоміжні функції native approval target + прив’язки облікового запису |
|
||||
| `plugin-sdk/approval-reply-runtime` | Допоміжні функції пейлоада відповіді схвалення exec/plugin |
|
||||
| `plugin-sdk/command-auth-native` | Допоміжні функції native command auth + native session-target |
|
||||
| `plugin-sdk/command-detection` | Спільні допоміжні функції виявлення команд |
|
||||
| `plugin-sdk/command-surface` | Допоміжні функції нормалізації тіла команди та поверхні команд |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, помічники реєстру команд, помічники авторизації відправника |
|
||||
| `plugin-sdk/approval-auth-runtime` | Помічники визначення approver і auth дій у тому самому чаті |
|
||||
| `plugin-sdk/approval-client-runtime` | Помічники профілю/фільтра native exec approval |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Адаптери native approval capability/delivery |
|
||||
| `plugin-sdk/approval-native-runtime` | Помічники native approval target + прив’язки облікового запису |
|
||||
| `plugin-sdk/approval-reply-runtime` | Помічники пейлоаду відповіді exec/plugin approval |
|
||||
| `plugin-sdk/command-auth-native` | Native command auth + помічники native session-target |
|
||||
| `plugin-sdk/command-detection` | Спільні помічники визначення команд |
|
||||
| `plugin-sdk/command-surface` | Помічники нормалізації тіла команди й командної поверхні |
|
||||
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/security-runtime` | Спільні допоміжні функції довіри, DM gating, зовнішнього вмісту та збору секретів |
|
||||
| `plugin-sdk/ssrf-policy` | Допоміжні функції allowlist хостів і політики SSRF для приватної мережі |
|
||||
| `plugin-sdk/ssrf-runtime` | Допоміжні функції pinned-dispatcher, fetch із захистом SSRF та політики SSRF |
|
||||
| `plugin-sdk/secret-input` | Допоміжні функції розбору секретного вводу |
|
||||
| `plugin-sdk/webhook-ingress` | Допоміжні функції запиту/цілі webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Допоміжні функції розміру тіла запиту/таймауту |
|
||||
| `plugin-sdk/security-runtime` | Спільні помічники довіри, DM gating, external-content і збору секретів |
|
||||
| `plugin-sdk/ssrf-policy` | Помічники allowlist хостів і політики SSRF для приватної мережі |
|
||||
| `plugin-sdk/ssrf-runtime` | Помічники pinned-dispatcher, fetch із захистом SSRF і політики SSRF |
|
||||
| `plugin-sdk/secret-input` | Помічники розбору введення секретів |
|
||||
| `plugin-sdk/webhook-ingress` | Помічники запитів/цілей webhook |
|
||||
| `plugin-sdk/webhook-request-guards` | Помічники розміру тіла запиту/timeout |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи runtime і сховища">
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/runtime` | Широкі допоміжні функції runtime/logging/backup/install плагінів |
|
||||
| `plugin-sdk/runtime-env` | Вузькі допоміжні функції env, logger, timeout, retry і backoff для runtime |
|
||||
| `plugin-sdk/runtime` | Широка поверхня помічників runtime/logging/backup/install plugin |
|
||||
| `plugin-sdk/runtime-env` | Вузькі помічники env runtime, logger, timeout, retry і backoff |
|
||||
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні допоміжні функції команди/hook/http/interactive плагіна |
|
||||
| `plugin-sdk/hook-runtime` | Спільні допоміжні функції конвеєра webhook/internal hook |
|
||||
| `plugin-sdk/lazy-runtime` | Допоміжні функції lazy імпорту/прив’язки runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Допоміжні функції виконання процесів |
|
||||
| `plugin-sdk/cli-runtime` | Допоміжні функції форматування CLI, очікування та версії |
|
||||
| `plugin-sdk/gateway-runtime` | Клієнт Gateway і допоміжні функції патчів стану каналу |
|
||||
| `plugin-sdk/config-runtime` | Допоміжні функції завантаження/запису конфігурації |
|
||||
| `plugin-sdk/telegram-command-config` | Нормалізація імен/описів команд Telegram і перевірки дублювання/конфліктів, навіть коли поверхня контракту вбудованого Telegram недоступна |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні функції схвалення exec/plugin, побудовники можливостей approval, auth/profile, native routing/runtime |
|
||||
| `plugin-sdk/reply-runtime` | Спільні допоміжні функції runtime для вхідних даних/відповідей, chunking, dispatch, heartbeat, planner відповіді |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції dispatch/finalize відповіді |
|
||||
| `plugin-sdk/reply-history` | Спільні допоміжні функції коротковіконної історії відповідей, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні помічники команд/hook/http/interactive plugin |
|
||||
| `plugin-sdk/hook-runtime` | Спільні помічники pipeline webhook/internal hook |
|
||||
| `plugin-sdk/lazy-runtime` | Помічники лінивого імпорту/прив’язки runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Помічники виконання процесів |
|
||||
| `plugin-sdk/cli-runtime` | Помічники форматування CLI, очікування та версії |
|
||||
| `plugin-sdk/gateway-runtime` | Помічники клієнта gateway і виправлення статусу каналу |
|
||||
| `plugin-sdk/config-runtime` | Помічники завантаження/запису конфігурації |
|
||||
| `plugin-sdk/telegram-command-config` | Нормалізація імен/описів команд Telegram та перевірки дублікатів/конфліктів, навіть коли поверхня контракту вбудованого Telegram недоступна |
|
||||
| `plugin-sdk/approval-runtime` | Помічники exec/plugin approval, побудовники approval-capability, помічники auth/profile, native routing/runtime |
|
||||
| `plugin-sdk/reply-runtime` | Спільні помічники runtime для вхідних повідомлень/відповідей, chunking, dispatch, heartbeat, planner відповіді |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі помічники dispatch/finalize відповіді |
|
||||
| `plugin-sdk/reply-history` | Спільні помічники reply-history для коротких вікон, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | Вузькі допоміжні функції chunking тексту/markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Допоміжні функції шляху до session store + updated-at |
|
||||
| `plugin-sdk/state-paths` | Допоміжні функції шляхів до каталогів state/OAuth |
|
||||
| `plugin-sdk/routing` | Допоміжні функції маршруту/ключа сесії/прив’язки облікового запису, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Спільні допоміжні функції підсумку стану каналу/облікового запису, типові стани runtime і допоміжні функції метаданих 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` | Загальні рідери параметрів інструментів/CLI |
|
||||
| `plugin-sdk/tool-send` | Видобування канонічних полів цілі надсилання з аргументів інструмента |
|
||||
| `plugin-sdk/temp-path` | Спільні допоміжні функції шляхів для тимчасових завантажень |
|
||||
| `plugin-sdk/logging-core` | Допоміжні функції logger підсистеми та редагування |
|
||||
| `plugin-sdk/markdown-table-runtime` | Допоміжні функції режиму таблиць Markdown |
|
||||
| `plugin-sdk/json-store` | Невеликі допоміжні функції читання/запису стану JSON |
|
||||
| `plugin-sdk/file-lock` | Допоміжні функції повторно вхідного file lock |
|
||||
| `plugin-sdk/persistent-dedupe` | Допоміжні функції дискового кешу дедуплікації |
|
||||
| `plugin-sdk/acp-runtime` | Допоміжні функції runtime/сесії ACP і reply-dispatch |
|
||||
| `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime агента |
|
||||
| `plugin-sdk/boolean-param` | Рідер нечіткого boolean-параметра |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Допоміжні функції розв’язання збігів небезпечних імен |
|
||||
| `plugin-sdk/device-bootstrap` | Допоміжні функції початкового налаштування пристрою та токенів парування |
|
||||
| `plugin-sdk/extension-shared` | Спільні примітиви passive-channel і статусу |
|
||||
| `plugin-sdk/models-provider-runtime` | Допоміжні функції відповіді провайдера/команди `/models` |
|
||||
| `plugin-sdk/skill-commands-runtime` | Допоміжні функції списку команд Skills |
|
||||
| `plugin-sdk/native-command-registry` | Допоміжні функції реєстру/build/serialize native-команд |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Допоміжні функції виявлення endpoint Z.AI |
|
||||
| `plugin-sdk/infra-runtime` | Допоміжні функції системних подій/heartbeat |
|
||||
| `plugin-sdk/collection-runtime` | Невеликі допоміжні функції обмеженого кешу |
|
||||
| `plugin-sdk/diagnostic-runtime` | Допоміжні функції діагностичних прапорців і подій |
|
||||
| `plugin-sdk/error-runtime` | Граф помилок, форматування, спільні допоміжні функції класифікації помилок, `isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | Обгорнутий fetch, proxy і pinned lookup helpers |
|
||||
| `plugin-sdk/host-runtime` | Допоміжні функції нормалізації hostname і SCP host |
|
||||
| `plugin-sdk/retry-runtime` | Допоміжні функції конфігурації повторів і запуску повторів |
|
||||
| `plugin-sdk/agent-runtime` | Допоміжні функції каталогу/ідентичності/робочого простору агента |
|
||||
| `plugin-sdk/directory-runtime` | Запит/дедуплікація каталогів на основі конфігурації |
|
||||
| `plugin-sdk/reply-chunking` | Вузькі помічники chunking тексту/markdown |
|
||||
| `plugin-sdk/session-store-runtime` | Помічники шляху сховища сесії + updated-at |
|
||||
| `plugin-sdk/state-paths` | Помічники шляхів до директорій state/OAuth |
|
||||
| `plugin-sdk/routing` | Помічники маршруту/ключа сесії/прив’язки облікового запису, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Спільні помічники зведення статусу каналу/облікового запису, типові значення runtime-state і помічники метаданих проблем |
|
||||
| `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` | Загальні читачі параметрів tool/CLI |
|
||||
| `plugin-sdk/tool-send` | Витягуйте канонічні поля цілі надсилання з аргументів tool |
|
||||
| `plugin-sdk/temp-path` | Спільні помічники шляхів для тимчасових завантажень |
|
||||
| `plugin-sdk/logging-core` | Помічники logger підсистеми та редагування |
|
||||
| `plugin-sdk/markdown-table-runtime` | Помічники режиму таблиць Markdown |
|
||||
| `plugin-sdk/json-store` | Невеликі помічники читання/запису стану JSON |
|
||||
| `plugin-sdk/file-lock` | Помічники повторно вхідного file-lock |
|
||||
| `plugin-sdk/persistent-dedupe` | Помічники дискового кешу дедуплікації |
|
||||
| `plugin-sdk/acp-runtime` | Помічники runtime/session ACP і dispatch відповіді |
|
||||
| `plugin-sdk/agent-config-primitives` | Вузькі примітиви config-schema runtime агента |
|
||||
| `plugin-sdk/boolean-param` | Читач параметрів для нестрогих булевих значень |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Помічники визначення збігів небезпечних імен |
|
||||
| `plugin-sdk/device-bootstrap` | Помічники bootstrap пристрою і токенів pairing |
|
||||
| `plugin-sdk/extension-shared` | Спільні примітиви для passive-channel і статусних помічників |
|
||||
| `plugin-sdk/models-provider-runtime` | Помічники `/models` command/provider reply |
|
||||
| `plugin-sdk/skill-commands-runtime` | Помічники переліку команд Skills |
|
||||
| `plugin-sdk/native-command-registry` | Помічники реєстру/build/serialize native command |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Помічники визначення endpoint Z.A.I |
|
||||
| `plugin-sdk/infra-runtime` | Помічники системних подій/heartbeat |
|
||||
| `plugin-sdk/collection-runtime` | Невеликі помічники обмеженого кешу |
|
||||
| `plugin-sdk/diagnostic-runtime` | Помічники діагностичних прапорців і подій |
|
||||
| `plugin-sdk/error-runtime` | Граф помилок, форматування, спільні помічники класифікації помилок, `isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | Помічники обгорнутого fetch, proxy і pinned lookup |
|
||||
| `plugin-sdk/host-runtime` | Помічники нормалізації hostname і SCP host |
|
||||
| `plugin-sdk/retry-runtime` | Помічники конфігурації retry і виконавця retry |
|
||||
| `plugin-sdk/agent-runtime` | Помічники директорії/ідентичності/workspace агента |
|
||||
| `plugin-sdk/directory-runtime` | Запит/дедуплікація директорій на основі конфігурації |
|
||||
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи можливостей і тестування">
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/media-runtime` | Спільні допоміжні функції fetch/transform/store для медіа, а також побудовники медіапейлоадів |
|
||||
| `plugin-sdk/media-understanding` | Типи провайдера media understanding, а також експорти допоміжних функцій зображень/аудіо для провайдерів |
|
||||
| `plugin-sdk/text-runtime` | Спільні допоміжні функції тексту/markdown/logging, такі як вилучення видимого асистенту тексту, render/chunking/table helpers для markdown, допоміжні функції редагування, directive-tag helpers і safe-text utilities |
|
||||
| `plugin-sdk/text-chunking` | Допоміжна функція chunking вихідного тексту |
|
||||
| `plugin-sdk/speech` | Типи speech-провайдера, а також експорти directive, registry і validation для провайдерів |
|
||||
| `plugin-sdk/speech-core` | Спільні типи speech-провайдера, registry, directive і normalization helpers |
|
||||
| `plugin-sdk/realtime-transcription` | Типи провайдера realtime transcription і допоміжні функції registry |
|
||||
| `plugin-sdk/realtime-voice` | Типи провайдера realtime voice і допоміжні функції registry |
|
||||
| `plugin-sdk/image-generation` | Типи провайдера генерації зображень |
|
||||
| `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, failover, auth і допоміжні функції registry |
|
||||
| `plugin-sdk/video-generation` | Типи провайдера/запиту/результату генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні функції failover, пошуку провайдера та розбору model-ref |
|
||||
| `plugin-sdk/webhook-targets` | Реєстр цілей webhook і допоміжні функції встановлення маршрутів |
|
||||
| `plugin-sdk/webhook-path` | Допоміжні функції нормалізації шляху webhook |
|
||||
| `plugin-sdk/web-media` | Спільні допоміжні функції завантаження віддалених/локальних медіа |
|
||||
| `plugin-sdk/zod` | Реекспортований `zod` для споживачів Plugin SDK |
|
||||
| `plugin-sdk/media-runtime` | Спільні помічники fetch/transform/store медіа, а також побудовники медіа-пейлоаду |
|
||||
| `plugin-sdk/media-understanding` | Типи постачальників media understanding, а також експорти помічників зображень/аудіо для постачальників |
|
||||
| `plugin-sdk/text-runtime` | Спільні помічники тексту/markdown/logging, такі як видалення видимого для асистента тексту, render/chunking/table-помічники markdown, помічники редагування, помічники тегів директив і утиліти безпечного тексту |
|
||||
| `plugin-sdk/text-chunking` | Помічник chunking вихідного тексту |
|
||||
| `plugin-sdk/speech` | Типи постачальників мовлення, а також помічники директив, реєстру та валідації для постачальників |
|
||||
| `plugin-sdk/speech-core` | Спільні типи постачальників мовлення, реєстр, директиви та помічники нормалізації |
|
||||
| `plugin-sdk/realtime-transcription` | Типи постачальників realtime transcription і помічники реєстру |
|
||||
| `plugin-sdk/realtime-voice` | Типи постачальників realtime voice і помічники реєстру |
|
||||
| `plugin-sdk/image-generation` | Типи постачальників генерації зображень |
|
||||
| `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, failover, auth і помічники реєстру |
|
||||
| `plugin-sdk/video-generation` | Типи постачальників/запитів/результатів генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільні типи генерації відео, помічники failover, пошук постачальника і розбір model-ref |
|
||||
| `plugin-sdk/webhook-targets` | Помічники реєстру цілей webhook і встановлення маршрутів |
|
||||
| `plugin-sdk/webhook-path` | Помічники нормалізації шляху webhook |
|
||||
| `plugin-sdk/web-media` | Спільні помічники завантаження віддалених/локальних медіа |
|
||||
| `plugin-sdk/zod` | Повторно експортований `zod` для користувачів plugin SDK |
|
||||
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи пам’яті">
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/memory-core` | Поверхня допоміжних функцій bundled memory-core для manager/config/file/CLI helpers |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексу/пошуку пам’яті |
|
||||
| `plugin-sdk/memory-core` | Поверхня допоміжних засобів вбудованого memory-core для manager/config/file/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексації/пошуку пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Експорти engine embeddings хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Експорти engine QMD хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Експорти engine storage хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Допоміжні функції multimodal хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-query` | Допоміжні функції query хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-secret` | Допоміжні функції secret хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-status` | Допоміжні функції 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` | Допоміжні функції file/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-lancedb` | Поверхня допоміжних функцій bundled memory-lancedb |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Експорти embedding engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Мультимодальні помічники хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-query` | Помічники запитів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-secret` | Помічники секретів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-status` | Помічники статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Помічники runtime CLI хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Помічники core runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Помічники файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів вбудованого memory-lancedb |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Зарезервовані допоміжні підшляхи для вбудованих пакетів">
|
||||
| Family | Поточні підшляхи | Призначення |
|
||||
<Accordion title="Зарезервовані допоміжні підшляхи вбудованих компонентів">
|
||||
| Сімейство | Поточні підшляхи | Призначене використання |
|
||||
| --- | --- | --- |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-support` | Допоміжні функції підтримки вбудованого browser-плагіна |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня допоміжних функцій/runtime для вбудованого Matrix |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних функцій/runtime для вбудованого LINE |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних функцій для вбудованого IRC |
|
||||
| Допоміжні функції, специфічні для каналів | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шви сумісності/допоміжних функцій для вбудованих каналів |
|
||||
| Допоміжні функції, специфічні для auth/плагінів | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви допоміжних функцій для вбудованих можливостей/плагінів; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки вбудованого browser plugin |
|
||||
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня helper/runtime вбудованого Matrix |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня helper/runtime вбудованого LINE |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів вбудованого IRC |
|
||||
| Специфічні для каналу помічники | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шви сумісності/допоміжні шви вбудованих каналів |
|
||||
| Специфічні для auth/plugin помічники | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Допоміжні шви вбудованих можливостей/plugins; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## API реєстрації
|
||||
|
||||
Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими
|
||||
Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` з такими
|
||||
методами:
|
||||
|
||||
### Реєстрація можливостей
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ------------------------------------------------ | -------------------------------- |
|
||||
| `api.registerProvider(...)` | Текстовий inference (LLM) |
|
||||
| `api.registerCliBackend(...)` | Локальний CLI backend inference |
|
||||
| `api.registerChannel(...)` | Канал повідомлень |
|
||||
| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Потокова realtime transcription |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Двобічні сеанси realtime voice |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео |
|
||||
| `api.registerImageGenerationProvider(...)` | Генерація зображень |
|
||||
| `api.registerVideoGenerationProvider(...)` | Генерація відео |
|
||||
| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape |
|
||||
| Метод | Що реєструє |
|
||||
| ------------------------------------------------ | ------------------------------ |
|
||||
| `api.registerProvider(...)` | Текстовий inference (LLM) |
|
||||
| `api.registerChannel(...)` | Канал повідомлень |
|
||||
| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Потокова transcription realtime |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Двобічні сесії realtime voice |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео |
|
||||
| `api.registerImageGenerationProvider(...)` | Генерація зображень |
|
||||
| `api.registerVideoGenerationProvider(...)` | Генерація відео |
|
||||
| `api.registerWebFetchProvider(...)` | Постачальник web fetch / scrape |
|
||||
| `api.registerWebSearchProvider(...)` | Вебпошук |
|
||||
|
||||
### Інструменти й команди
|
||||
### Tools і команди
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ------------------------------- | --------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | Користувацька команда (обходить LLM) |
|
||||
| Метод | Що реєструє |
|
||||
| ------------------------------ | --------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Agent tool (обов’язковий або `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | Користувацька команда (обходить LLM) |
|
||||
|
||||
### Інфраструктура
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ---------------------------------------------- | --------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Хук події |
|
||||
| `api.registerHttpRoute(params)` | HTTP endpoint Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | Метод RPC Gateway |
|
||||
| `api.registerCli(registrar, opts?)` | Підкоманда CLI |
|
||||
| `api.registerService(service)` | Фонова служба |
|
||||
| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник |
|
||||
| Метод | Що реєструє |
|
||||
| --------------------------------------------- | --------------------- |
|
||||
| `api.registerHook(events, handler, opts?)` | Hook події |
|
||||
| `api.registerHttpRoute(params)` | HTTP endpoint gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | RPC-метод gateway |
|
||||
| `api.registerCli(registrar, opts?)` | Підкоманду CLI |
|
||||
| `api.registerService(service)` | Фоновий сервіс |
|
||||
| `api.registerInteractiveHandler(registration)` | Інтерактивний handler |
|
||||
|
||||
Зарезервовані простори імен core admin (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити
|
||||
вужчу область gateway method. Для методів, що належать плагіну,
|
||||
віддавайте перевагу префіксам, специфічним для плагіна.
|
||||
`update.*`) завжди залишаються `operator.admin`, навіть якщо plugin намагається
|
||||
призначити вужчу область gateway method. Для методів, що належать plugin,
|
||||
віддавайте перевагу префіксам, специфічним для plugin.
|
||||
|
||||
### Метадані реєстрації CLI
|
||||
|
||||
`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня:
|
||||
|
||||
- `commands`: явні корені команд, що належать реєстратору
|
||||
- `descriptors`: дескриптори команд на етапі парсингу, що використовуються для кореневої довідки CLI,
|
||||
маршрутизації та lazy-реєстрації CLI плагіна
|
||||
- `commands`: явні корені команд, що належать registrar
|
||||
- `descriptors`: дескриптори команд на етапі розбору, що використовуються для
|
||||
довідки кореневого CLI, маршрутизації та лінивої реєстрації CLI plugin
|
||||
|
||||
Якщо ви хочете, щоб команда плагіна залишалася lazy-loaded у звичайному кореневому шляху CLI,
|
||||
надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, який відкриває
|
||||
цей реєстратор.
|
||||
Якщо ви хочете, щоб команда plugin залишалася ліниво завантажуваною в
|
||||
звичайному шляху кореневого CLI, надайте `descriptors`, які охоплюють кожен
|
||||
корінь команди верхнього рівня, що надається цим registrar.
|
||||
|
||||
```typescript
|
||||
api.registerCli(
|
||||
@ -353,116 +353,121 @@ api.registerCli(
|
||||
);
|
||||
```
|
||||
|
||||
Використовуйте лише `commands`, коли вам не потрібна lazy-реєстрація кореневого CLI.
|
||||
Цей сумісний eager-шлях і далі підтримується, але він не встановлює
|
||||
плейсхолдери на основі descriptor для lazy loading на етапі парсингу.
|
||||
Використовуйте `commands` окремо лише тоді, коли вам не потрібна лінива
|
||||
реєстрація кореневого CLI. Цей сумісний eager-шлях усе ще підтримується, але
|
||||
він не встановлює placeholders на основі descriptor для лінивого завантаження
|
||||
на етапі розбору.
|
||||
|
||||
### Ексклюзивні слоти
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ------------------------------------------ | ------------------------------------- |
|
||||
| Метод | Що реєструє |
|
||||
| ------------------------------------------ | ------------------------------------ |
|
||||
| `api.registerContextEngine(id, factory)` | Context engine (одночасно активний лише один) |
|
||||
| `api.registerMemoryPromptSection(builder)` | Побудовник секції prompt пам’яті |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush пам’яті |
|
||||
| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті |
|
||||
| `api.registerMemoryPromptSection(builder)` | Побудовник секції prompt пам’яті |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Resolver плану скидання пам’яті |
|
||||
| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті |
|
||||
|
||||
### Адаптери embedding пам’яті
|
||||
### Адаптери embeddings пам’яті
|
||||
|
||||
| Метод | Що він реєструє |
|
||||
| ---------------------------------------------- | ---------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного плагіна |
|
||||
| Метод | Що реєструє |
|
||||
| ---------------------------------------------- | ------------------------------------------------ |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embeddings пам’яті для активного plugin |
|
||||
|
||||
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` і
|
||||
`registerMemoryRuntime` є ексклюзивними для плагінів пам’яті.
|
||||
- `registerMemoryEmbeddingProvider` дає активному плагіну пам’яті змогу реєструвати один
|
||||
або більше ідентифікаторів адаптерів embedding (наприклад `openai`, `gemini` або користувацький
|
||||
ідентифікатор, визначений плагіном).
|
||||
`registerMemoryRuntime` є ексклюзивними для plugins пам’яті.
|
||||
- `registerMemoryEmbeddingProvider` дозволяє активному plugin пам’яті
|
||||
зареєструвати один або кілька id адаптерів embeddings (наприклад `openai`,
|
||||
`gemini` або користувацький id, визначений plugin).
|
||||
- Користувацька конфігурація, така як `agents.defaults.memorySearch.provider` і
|
||||
`agents.defaults.memorySearch.fallback`, розв’язується відносно зареєстрованих ідентифікаторів
|
||||
адаптерів.
|
||||
`agents.defaults.memorySearch.fallback`, визначається відносно зареєстрованих
|
||||
id цих адаптерів.
|
||||
|
||||
### Події та життєвий цикл
|
||||
|
||||
| Метод | Що він робить |
|
||||
| -------------------------------------------- | ----------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу |
|
||||
| `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки розмови |
|
||||
| Метод | Що робить |
|
||||
| ------------------------------------------- | ---------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Типізований hook життєвого циклу |
|
||||
| `api.onConversationBindingResolved(handler)` | Колбек прив’язки розмови |
|
||||
|
||||
### Семантика рішень hook
|
||||
|
||||
- `before_tool_call`: повернення `{ block: true }` є фінальним. Щойно будь-який обробник встановлює його, обробники нижчого пріоритету пропускаються.
|
||||
- `before_tool_call`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як і пропуск `block`), а не як перевизначення.
|
||||
- `before_install`: повернення `{ block: true }` є фінальним. Щойно будь-який обробник встановлює його, обробники нижчого пріоритету пропускаються.
|
||||
- `before_install`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як і пропуск `block`), а не як перевизначення.
|
||||
- `reply_dispatch`: повернення `{ handled: true, ... }` є фінальним. Щойно будь-який обробник бере на себе диспетчеризацію, обробники нижчого пріоритету й типовий шлях диспетчеризації моделі пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: true }` є фінальним. Щойно будь-який обробник встановлює його, обробники нижчого пріоритету пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: false }` розглядається як відсутність рішення (так само, як і пропуск `cancel`), а не як перевизначення.
|
||||
- `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 бере диспетчеризацію на себе, handlers із нижчим пріоритетом і типовий шлях диспетчеризації моделі пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який handler встановлює це значення, handlers із нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: false }` вважається відсутністю рішення (так само, як пропуск `cancel`), а не перевизначенням.
|
||||
|
||||
### Поля об’єкта API
|
||||
|
||||
| Поле | Тип | Опис |
|
||||
| Поле | Тип | Опис |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | Ідентифікатор плагіна |
|
||||
| `api.name` | `string` | Відображувана назва |
|
||||
| `api.version` | `string?` | Версія плагіна (необов’язково) |
|
||||
| `api.description` | `string?` | Опис плагіна (необов’язково) |
|
||||
| `api.source` | `string` | Шлях до джерела плагіна |
|
||||
| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) |
|
||||
| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок runtime у пам’яті, коли доступний) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Конфігурація, специфічна для плагіна, з `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [Допоміжні функції runtime](/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | Логер з областю видимості (`debug`, `info`, `warn`, `error`) |
|
||||
| `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"` — це полегшене вікно запуску/налаштування до повного entry |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Розв’язати шлях відносно кореня плагіна |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Визначити шлях відносно кореня plugin |
|
||||
|
||||
## Угода щодо внутрішніх модулів
|
||||
|
||||
Усередині вашого плагіна використовуйте локальні barrel-файли для внутрішніх імпортів:
|
||||
Усередині вашого plugin використовуйте локальні barrel-файли для внутрішніх
|
||||
імпортів:
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
api.ts # Публічні експорти для зовнішніх споживачів
|
||||
runtime-api.ts # Внутрішні експорти лише для runtime
|
||||
index.ts # Точка входу плагіна
|
||||
runtime-api.ts # Лише внутрішні експорти runtime
|
||||
index.ts # Точка входу plugin
|
||||
setup-entry.ts # Полегшений entry лише для налаштування (необов’язково)
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/<your-plugin>`
|
||||
Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/<your-plugin>`
|
||||
у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або
|
||||
`./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт.
|
||||
`./runtime-api.ts`. Шлях SDK є лише зовнішнім контрактом.
|
||||
</Warning>
|
||||
|
||||
Завантажувані через facade публічні поверхні вбудованих плагінів (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` та подібні публічні entry-файли) тепер віддають перевагу
|
||||
активному знімку конфігурації runtime, коли OpenClaw уже працює. Якщо знімок runtime
|
||||
ще не існує, вони повертаються до розв’язаного файлу конфігурації на диску.
|
||||
Публічні поверхні вбудованих plugins, що завантажуються через facade (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` та подібні публічні entry-файли), тепер віддають
|
||||
перевагу активному знімку конфігурації runtime, коли OpenClaw уже запущено. Якщо
|
||||
знімка runtime ще немає, вони переходять до резервного варіанту з визначеним
|
||||
файлом конфігурації на диску.
|
||||
|
||||
Плагіни провайдерів також можуть відкривати вузький локальний barrel-контракт плагіна, коли
|
||||
допоміжна функція навмисно є специфічною для провайдера і ще не належить до загального підшляху SDK.
|
||||
Поточний вбудований приклад: провайдер Anthropic зберігає свої допоміжні функції потоку Claude
|
||||
у власному публічному шві `api.ts` / `contract-api.ts` замість того, щоб просувати логіку Anthropic beta-header і `service_tier`
|
||||
до загального контракту `plugin-sdk/*`.
|
||||
Plugins постачальників також можуть надавати вузький локальний barrel-контракт
|
||||
plugin, коли помічник навмисно є специфічним для постачальника і ще не належить
|
||||
до узагальненого підшляху SDK. Поточний вбудований приклад: постачальник
|
||||
Anthropic зберігає свої помічники потоку Claude у власному публічному шві
|
||||
`api.ts` / `contract-api.ts` замість того, щоб просувати логіку beta-header і
|
||||
`service_tier` Anthropic до узагальненого контракту `plugin-sdk/*`.
|
||||
|
||||
Інші поточні вбудовані приклади:
|
||||
|
||||
- `@openclaw/openai-provider`: `api.ts` експортує побудовники провайдера,
|
||||
допоміжні функції типових моделей і побудовники realtime-провайдера
|
||||
- `@openclaw/openrouter-provider`: `api.ts` експортує побудовник провайдера плюс
|
||||
допоміжні функції онбордингу/конфігурації
|
||||
- `@openclaw/openai-provider`: `api.ts` експортує побудовники постачальника,
|
||||
помічники типових моделей і побудовники realtime-постачальників
|
||||
- `@openclaw/openrouter-provider`: `api.ts` експортує побудовник постачальника, а також
|
||||
помічники онбордингу/конфігурації
|
||||
|
||||
<Warning>
|
||||
Production-код розширення також має уникати імпортів `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Якщо допоміжна функція справді є спільною, підніміть її до нейтрального підшляху SDK,
|
||||
такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої
|
||||
поверхні, орієнтованої на можливості, замість зчеплення двох плагінів між собою.
|
||||
Production-код extensions також має уникати імпортів
|
||||
`openclaw/plugin-sdk/<other-plugin>`. Якщо помічник справді є спільним,
|
||||
просуньте його до нейтрального підшляху SDK, такого як
|
||||
`openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої
|
||||
поверхні, орієнтованої на можливості, замість того щоб жорстко зв’язувати два plugins.
|
||||
</Warning>
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Точки входу](/plugins/sdk-entrypoints) — параметри `definePluginEntry` і `defineChannelPluginEntry`
|
||||
- [Допоміжні функції runtime](/plugins/sdk-runtime) — повний довідник простору імен `api.runtime`
|
||||
- [Налаштування та конфігурація](/plugins/sdk-setup) — пакування, маніфести, схеми конфігурації
|
||||
- [Тестування](/plugins/sdk-testing) — утиліти тестування та правила lint
|
||||
- [Міграція SDK](/plugins/sdk-migration) — міграція із застарілих поверхонь
|
||||
- [Внутрішня будова плагінів](/plugins/architecture) — поглиблена архітектура й модель можливостей
|
||||
- [Entry Points](/uk/plugins/sdk-entrypoints) — параметри `definePluginEntry` і `defineChannelPluginEntry`
|
||||
- [Runtime Helpers](/uk/plugins/sdk-runtime) — повний довідник простору імен `api.runtime`
|
||||
- [Setup and Config](/uk/plugins/sdk-setup) — пакування, маніфести, схеми конфігурації
|
||||
- [Testing](/uk/plugins/sdk-testing) — утиліти тестування та правила lint
|
||||
- [SDK Migration](/uk/plugins/sdk-migration) — міграція із застарілих поверхонь
|
||||
- [Plugin Internals](/uk/plugins/architecture) — глибока архітектура та модель можливостей
|
||||
|
||||
@ -1,30 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- Потрібно налагодити ідентифікатори сесій, JSONL транскриптів або поля sessions.json
|
||||
- Ви змінюєте поведінку автоущільнення або додаєте підготовчі дії перед ущільненням
|
||||
- Потрібно налагодити ідентифікатори сесій, JSONL транскрипту або поля в sessions.json
|
||||
- Ви змінюєте поведінку автоущільнення або додаєте службові дії “перед ущільненням”
|
||||
- Ви хочете реалізувати скидання пам’яті або тихі системні ходи
|
||||
summary: 'Детальний розбір: сховище сесій + транскрипти, життєвий цикл і внутрішня логіка (авто)ущільнення'
|
||||
title: Детальний розбір керування сесіями
|
||||
summary: 'Глибокий розбір: сховище сесій і транскрипти, життєвий цикл та внутрішні механізми (авто)ущільнення'
|
||||
title: Глибокий розбір керування сесіями
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T18:17:29Z"
|
||||
generated_at: "2026-04-05T18:49:16Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e379d624dd7808d3af25ed011079268ce6a9da64bb3f301598884ad4c46ab091
|
||||
source_hash: e0d8c2d30be773eac0424f7a4419ab055fdd50daac8bc654e7d250c891f2c3b8
|
||||
source_path: reference/session-management-compaction.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Керування сесіями та ущільнення (детальний розбір)
|
||||
# Керування сесіями та ущільнення (глибокий розбір)
|
||||
|
||||
У цьому документі пояснюється, як OpenClaw керує сесіями від початку до кінця:
|
||||
У цьому документі пояснюється, як OpenClaw керує сесіями наскрізно:
|
||||
|
||||
- **Маршрутизація сесій** (як вхідні повідомлення зіставляються з `sessionKey`)
|
||||
- **Сховище сесій** (`sessions.json`) і що в ньому відстежується
|
||||
- **Збереження транскриптів** (`*.jsonl`) та їхня структура
|
||||
- **Гігієна транскриптів** (специфічні для провайдера виправлення перед запусками)
|
||||
- **Сховище сесій** (`sessions.json`) і що воно відстежує
|
||||
- **Збереження транскрипту** (`*.jsonl`) та його структура
|
||||
- **Гігієна транскрипту** (виправлення для конкретних провайдерів перед запусками)
|
||||
- **Обмеження контексту** (вікно контексту проти відстежуваних токенів)
|
||||
- **Ущільнення** (ручне + автоущільнення) і де підключати підготовчі дії перед ущільненням
|
||||
- **Тихе службове обслуговування** (наприклад, записи в пам’ять, які не повинні створювати видимий для користувача вивід)
|
||||
- **Ущільнення** (ручне + автоущільнення) і куди підключати роботу перед ущільненням
|
||||
- **Тихі службові дії** (наприклад, запис пам’яті, який не повинен створювати видимий для користувача вивід)
|
||||
|
||||
Якщо спочатку потрібен огляд вищого рівня, почніть із:
|
||||
|
||||
@ -33,31 +33,31 @@ x-i18n:
|
||||
- [/concepts/memory](/uk/concepts/memory)
|
||||
- [/concepts/memory-search](/uk/concepts/memory-search)
|
||||
- [/concepts/session-pruning](/uk/concepts/session-pruning)
|
||||
- [/reference/transcript-hygiene](/reference/transcript-hygiene)
|
||||
- [/reference/transcript-hygiene](/uk/reference/transcript-hygiene)
|
||||
|
||||
---
|
||||
|
||||
## Джерело істини: Gateway
|
||||
|
||||
OpenClaw спроєктований навколо єдиного **процесу Gateway**, який володіє станом сесій.
|
||||
OpenClaw спроєктовано навколо єдиного **процесу Gateway**, який володіє станом сесій.
|
||||
|
||||
- Інтерфейси (macOS app, web Control UI, TUI) мають звертатися до Gateway по списки сесій і кількість токенів.
|
||||
- У віддаленому режимі файли сесій знаходяться на віддаленому хості; «перевірка локальних файлів на Mac» не відображатиме те, що використовує Gateway.
|
||||
- Інтерфейси (macOS app, веб-інтерфейс Control UI, TUI) мають запитувати в Gateway списки сесій і кількість токенів.
|
||||
- У віддаленому режимі файли сесій розміщені на віддаленому хості; “перевірка локальних файлів на Mac” не покаже те, що використовує Gateway.
|
||||
|
||||
---
|
||||
|
||||
## Два рівні збереження
|
||||
## Два шари збереження
|
||||
|
||||
OpenClaw зберігає сесії на двох рівнях:
|
||||
OpenClaw зберігає сесії у двох шарах:
|
||||
|
||||
1. **Сховище сесій (`sessions.json`)**
|
||||
- Карта ключ/значення: `sessionKey -> SessionEntry`
|
||||
- Невелике, змінюване, безпечне для редагування (або видалення записів)
|
||||
- Відстежує метадані сесії (поточний ідентифікатор сесії, останню активність, перемикачі, лічильники токенів тощо)
|
||||
- Мапа ключ/значення: `sessionKey -> SessionEntry`
|
||||
- Маленьке, змінюване, безпечно редагувати (або видаляти записи)
|
||||
- Відстежує метадані сесії (поточний id сесії, останню активність, перемикачі, лічильники токенів тощо)
|
||||
|
||||
2. **Транскрипт (`<sessionId>.jsonl`)**
|
||||
- Транскрипт із дозаписом і деревоподібною структурою (записи мають `id` + `parentId`)
|
||||
- Зберігає фактичну розмову + виклики інструментів + підсумки ущільнення
|
||||
- Транскрипт лише з додаванням записів із деревоподібною структурою (записи мають `id` + `parentId`)
|
||||
- Зберігає фактичну розмову + виклики інструментів + зведення ущільнення
|
||||
- Використовується для відновлення контексту моделі для майбутніх ходів
|
||||
|
||||
---
|
||||
@ -74,27 +74,27 @@ OpenClaw визначає ці шляхи через `src/config/sessions.ts`.
|
||||
|
||||
---
|
||||
|
||||
## Обслуговування сховища та керування диском
|
||||
## Обслуговування сховища та контроль диска
|
||||
|
||||
Збереження сесій має автоматичні механізми обслуговування (`session.maintenance`) для `sessions.json` і артефактів транскриптів:
|
||||
|
||||
- `mode`: `warn` (типово) або `enforce`
|
||||
- `pruneAfter`: поріг давності для видалення застарілих записів (типово `30d`)
|
||||
- `pruneAfter`: поріг віку застарілих записів для очищення (типово `30d`)
|
||||
- `maxEntries`: обмеження кількості записів у `sessions.json` (типово `500`)
|
||||
- `rotateBytes`: ротація `sessions.json`, коли файл стає завеликим (типово `10mb`)
|
||||
- `resetArchiveRetention`: строк зберігання для архівів транскриптів `*.reset.<timestamp>` (типово: такий самий, як `pruneAfter`; `false` вимикає очищення)
|
||||
- `maxDiskBytes`: необов’язковий ліміт для каталогу сесій
|
||||
- `highWaterBytes`: необов’язкове цільове значення після очищення (типово `80%` від `maxDiskBytes`)
|
||||
- `resetArchiveRetention`: термін зберігання архівів транскриптів `*.reset.<timestamp>` (типово: такий самий, як `pruneAfter`; `false` вимикає очищення)
|
||||
- `maxDiskBytes`: необов’язковий бюджет каталогу sessions на диску
|
||||
- `highWaterBytes`: необов’язкова ціль після очищення (типово `80%` від `maxDiskBytes`)
|
||||
|
||||
Порядок примусового очищення за бюджетом диска (`mode: "enforce"`):
|
||||
Порядок примусового очищення для бюджету диска (`mode: "enforce"`):
|
||||
|
||||
1. Спочатку видалити найстаріші архівні або осиротілі артефакти транскриптів.
|
||||
2. Якщо ціль і далі не досягнута, видаляти найстаріші записи сесій і їхні файли транскриптів.
|
||||
3. Продовжувати, доки використання не стане меншим або рівним `highWaterBytes`.
|
||||
1. Спочатку видалити найстаріші архівовані або осиротілі артефакти транскриптів.
|
||||
2. Якщо все ще вище за ціль, витіснити найстаріші записи сесій і їхні файли транскриптів.
|
||||
3. Продовжувати, доки використання не стане на рівні або нижче `highWaterBytes`.
|
||||
|
||||
У режимі `mode: "warn"` OpenClaw повідомляє про потенційні видалення, але не змінює сховище/файли.
|
||||
У режимі `mode: "warn"` OpenClaw повідомляє про можливі витіснення, але не змінює сховище/файли.
|
||||
|
||||
Запустити обслуговування за потреби:
|
||||
Запустити обслуговування на вимогу:
|
||||
|
||||
```bash
|
||||
openclaw sessions cleanup --dry-run
|
||||
@ -105,10 +105,10 @@ openclaw sessions cleanup --enforce
|
||||
|
||||
## Cron-сесії та журнали запусків
|
||||
|
||||
Ізольовані запуски cron також створюють записи сесій/транскрипти, і для них є окремі механізми керування зберіганням:
|
||||
Ізольовані запуски cron також створюють записи сесій/транскрипти, і для них є окремі налаштування зберігання:
|
||||
|
||||
- `cron.sessionRetention` (типово `24h`) видаляє старі сесії ізольованих запусків cron зі сховища сесій (`false` вимикає).
|
||||
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` очищають файли `~/.openclaw/cron/runs/<jobId>.jsonl` (типові значення: `2_000_000` байтів і `2000` рядків).
|
||||
- `cron.sessionRetention` (типово `24h`) очищає старі сесії ізольованих запусків cron зі сховища сесій (`false` вимикає).
|
||||
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` обрізають файли `~/.openclaw/cron/runs/<jobId>.jsonl` (типові значення: `2_000_000` байтів і `2000` рядків).
|
||||
|
||||
---
|
||||
|
||||
@ -118,7 +118,7 @@ openclaw sessions cleanup --enforce
|
||||
|
||||
Поширені шаблони:
|
||||
|
||||
- Основний/прямий чат (на агента): `agent:<agentId>:<mainKey>` (типово `main`)
|
||||
- Основний/приватний чат (на агента): `agent:<agentId>:<mainKey>` (типово `main`)
|
||||
- Група: `agent:<agentId>:<channel>:group:<id>`
|
||||
- Кімната/канал (Discord/Slack): `agent:<agentId>:<channel>:channel:<id>` або `...:room:<id>`
|
||||
- Cron: `cron:<job.id>`
|
||||
@ -132,12 +132,12 @@ openclaw sessions cleanup --enforce
|
||||
|
||||
Кожен `sessionKey` вказує на поточний `sessionId` (файл транскрипту, який продовжує розмову).
|
||||
|
||||
Орієнтовні правила:
|
||||
Основні правила:
|
||||
|
||||
- **Скидання** (`/new`, `/reset`) створює новий `sessionId` для цього `sessionKey`.
|
||||
- **Щоденне скидання** (типово о 4:00 за місцевим часом на хості gateway) створює новий `sessionId` при наступному повідомленні після межі скидання.
|
||||
- **Завершення через неактивність** (`session.reset.idleMinutes` або застарілий `session.idleMinutes`) створює новий `sessionId`, коли повідомлення надходить після вікна неактивності. Якщо налаштовано і щоденне скидання, і неактивність, спрацьовує те, що настане раніше.
|
||||
- **Захист від розгалуження батьківського транскрипту** (`session.parentForkMaxTokens`, типово `100000`) пропускає розгалуження батьківського транскрипту, якщо батьківська сесія вже надто велика; новий потік починається з нуля. Установіть `0`, щоб вимкнути.
|
||||
- **Щоденне скидання** (типово о 4:00 ранку за місцевим часом на хості gateway) створює новий `sessionId` у наступному повідомленні після межі скидання.
|
||||
- **Завершення через простій** (`session.reset.idleMinutes` або застаріле `session.idleMinutes`) створює новий `sessionId`, коли повідомлення надходить після вікна простою. Якщо налаштовано і щоденне скидання, і простій, спрацьовує те, що настане раніше.
|
||||
- **Захист від форку батьківського ланцюжка** (`session.parentForkMaxTokens`, типово `100000`) пропускає форк батьківського транскрипту, коли батьківська сесія вже надто велика; новий потік починається з нуля. Установіть `0`, щоб вимкнути.
|
||||
|
||||
Деталь реалізації: рішення приймається в `initSessionState()` у `src/auto-reply/reply/session.ts`.
|
||||
|
||||
@ -147,25 +147,25 @@ openclaw sessions cleanup --enforce
|
||||
|
||||
Тип значення сховища — `SessionEntry` у `src/config/sessions.ts`.
|
||||
|
||||
Ключові поля (не вичерпно):
|
||||
Ключові поля (не вичерпний список):
|
||||
|
||||
- `sessionId`: поточний ідентифікатор транскрипту (ім’я файлу походить із нього, якщо не задано `sessionFile`)
|
||||
- `updatedAt`: час останньої активності
|
||||
- `sessionFile`: необов’язкове явне перевизначення шляху до транскрипту
|
||||
- `sessionId`: поточний id транскрипту (ім’я файлу виводиться з нього, якщо не задано `sessionFile`)
|
||||
- `updatedAt`: мітка часу останньої активності
|
||||
- `sessionFile`: необов’язкове явне перевизначення шляху транскрипту
|
||||
- `chatType`: `direct | group | room` (допомагає інтерфейсам і політиці надсилання)
|
||||
- `provider`, `subject`, `room`, `space`, `displayName`: метадані для позначення групи/каналу
|
||||
- `provider`, `subject`, `room`, `space`, `displayName`: метадані для позначення груп/каналів
|
||||
- Перемикачі:
|
||||
- `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel`
|
||||
- `sendPolicy` (перевизначення для конкретної сесії)
|
||||
- Вибір моделі:
|
||||
- `providerOverride`, `modelOverride`, `authProfileOverride`
|
||||
- Лічильники токенів (найкраще наближення / залежать від провайдера):
|
||||
- Лічильники токенів (best-effort / залежать від провайдера):
|
||||
- `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens`
|
||||
- `compactionCount`: як часто автоущільнення завершувалося для цього ключа сесії
|
||||
- `memoryFlushAt`: часовий штамп останнього скидання пам’яті перед ущільненням
|
||||
- `compactionCount`: скільки разів автоущільнення завершувалося для цього ключа сесії
|
||||
- `memoryFlushAt`: мітка часу останнього скидання пам’яті перед ущільненням
|
||||
- `memoryFlushCompactionCount`: лічильник ущільнень, коли востаннє виконувався flush
|
||||
|
||||
Сховище безпечно редагувати, але джерелом істини є Gateway: під час роботи сесій він може перезаписувати або повторно гідратувати записи.
|
||||
Сховище безпечно редагувати, але Gateway є джерелом істини: під час виконання сесій він може переписувати або повторно гідратувати записи.
|
||||
|
||||
---
|
||||
|
||||
@ -181,12 +181,12 @@ openclaw sessions cleanup --enforce
|
||||
Помітні типи записів:
|
||||
|
||||
- `message`: повідомлення user/assistant/toolResult
|
||||
- `custom_message`: повідомлення, вставлені розширенням, які _потрапляють_ у контекст моделі (можуть бути прихованими в інтерфейсі)
|
||||
- `custom`: стан розширення, який _не потрапляє_ в контекст моделі
|
||||
- `compaction`: збережений підсумок ущільнення з `firstKeptEntryId` і `tokensBefore`
|
||||
- `branch_summary`: збережений підсумок під час навігації по гілці дерева
|
||||
- `custom_message`: повідомлення, інжектовані розширенням, які _потрапляють_ у контекст моделі (можуть бути приховані від UI)
|
||||
- `custom`: стан розширення, який _не потрапляє_ у контекст моделі
|
||||
- `compaction`: збережене зведення ущільнення з `firstKeptEntryId` і `tokensBefore`
|
||||
- `branch_summary`: збережене зведення під час навігації гілкою дерева
|
||||
|
||||
OpenClaw навмисно **не** «виправляє» транскрипти; Gateway використовує `SessionManager` для їх читання/запису.
|
||||
OpenClaw навмисно **не** “виправляє” транскрипти; Gateway використовує `SessionManager` для їх читання/запису.
|
||||
|
||||
---
|
||||
|
||||
@ -195,39 +195,39 @@ OpenClaw навмисно **не** «виправляє» транскрипти
|
||||
Важливі два різні поняття:
|
||||
|
||||
1. **Вікно контексту моделі**: жорстке обмеження для кожної моделі (токени, видимі моделі)
|
||||
2. **Лічильники сховища сесій**: ковзні статистики, що записуються в `sessions.json` (використовуються для /status і панелей керування)
|
||||
2. **Лічильники сховища сесій**: ковзна статистика, що записується в `sessions.json` (використовується для /status і панелей)
|
||||
|
||||
Якщо ви налаштовуєте ліміти:
|
||||
Якщо ви налаштовуєте обмеження:
|
||||
|
||||
- Вікно контексту береться з каталогу моделей (і може бути перевизначене через конфігурацію).
|
||||
- `contextTokens` у сховищі — це оцінка/значення для звітності під час виконання; не сприймайте його як сувору гарантію.
|
||||
- `contextTokens` у сховищі — це оцінка/значення звітності під час виконання; не сприймайте його як сувору гарантію.
|
||||
|
||||
Докладніше див. у [/token-use](/reference/token-use).
|
||||
Докладніше див. у [/token-use](/uk/reference/token-use).
|
||||
|
||||
---
|
||||
|
||||
## Ущільнення: що це таке
|
||||
|
||||
Ущільнення підсумовує старішу частину розмови в збережений запис `compaction` у транскрипті та зберігає недоторканими недавні повідомлення.
|
||||
Ущільнення підсумовує старішу частину розмови в збережений запис `compaction` у транскрипті та залишає недоторканими недавні повідомлення.
|
||||
|
||||
Після ущільнення майбутні ходи бачать:
|
||||
|
||||
- Підсумок ущільнення
|
||||
- Зведення ущільнення
|
||||
- Повідомлення після `firstKeptEntryId`
|
||||
|
||||
Ущільнення є **постійним** (на відміну від обрізання сесій). Див. [/concepts/session-pruning](/uk/concepts/session-pruning).
|
||||
Ущільнення є **постійним** (на відміну від очищення сесії). Див. [/concepts/session-pruning](/uk/concepts/session-pruning).
|
||||
|
||||
## Межі фрагментів ущільнення та парування інструментів
|
||||
## Межі чанків ущільнення та поєднання інструментів
|
||||
|
||||
Коли OpenClaw розбиває довгий транскрипт на фрагменти для ущільнення, він зберігає
|
||||
виклики інструментів помічником у парі з відповідними записами `toolResult`.
|
||||
Коли OpenClaw розбиває довгий транскрипт на чанки для ущільнення, він зберігає
|
||||
виклики інструментів асистента поєднаними з відповідними записами `toolResult`.
|
||||
|
||||
- Якщо поділ за часткою токенів припадає між викликом інструмента та його результатом, OpenClaw
|
||||
зсуває межу до повідомлення помічника з викликом інструмента, замість того щоб
|
||||
розділяти пару.
|
||||
- Якщо кінцевий блок результатів інструмента інакше виштовхнув би фрагмент за цільовий розмір,
|
||||
OpenClaw зберігає цей очікуваний блок інструмента та залишає неузагальнений хвіст недоторканим.
|
||||
- Перервані/помилкові блоки викликів інструментів не утримують відкритою межу очікуваного поділу.
|
||||
зміщує межу до повідомлення асистента з викликом інструмента, а не розділяє
|
||||
пару.
|
||||
- Якщо кінцевий блок результатів інструмента інакше перевищив би цільовий розмір чанка,
|
||||
OpenClaw зберігає цей очікувальний блок інструмента і залишає неузагальнений хвіст недоторканим.
|
||||
- Перервані/помилкові блоки викликів інструментів не утримують відкритим очікувальний поділ.
|
||||
|
||||
---
|
||||
|
||||
@ -239,7 +239,7 @@ OpenClaw навмисно **не** «виправляє» транскрипти
|
||||
(`request_too_large`, `context length exceeded`, `input exceeds the maximum
|
||||
number of tokens`, `input token count exceeds the maximum number of input
|
||||
tokens`, `input is too long for the model`, `ollama error: context length
|
||||
exceeded` та подібні варіанти у стилі конкретного провайдера) → ущільнити → повторити.
|
||||
exceeded` та подібні варіанти, характерні для конкретних провайдерів) → ущільнити → повторити спробу.
|
||||
2. **Порогове обслуговування**: після успішного ходу, коли:
|
||||
|
||||
`contextTokens > contextWindow - reserveTokens`
|
||||
@ -249,13 +249,13 @@ exceeded` та подібні варіанти у стилі конкретно
|
||||
- `contextWindow` — це вікно контексту моделі
|
||||
- `reserveTokens` — це запас токенів, зарезервований для промптів + наступного виводу моделі
|
||||
|
||||
Це семантика середовища Pi (OpenClaw споживає події, але Pi вирішує, коли виконувати ущільнення).
|
||||
Це семантика середовища Pi (OpenClaw споживає події, але коли ущільнювати, вирішує Pi).
|
||||
|
||||
---
|
||||
|
||||
## Налаштування ущільнення (`reserveTokens`, `keepRecentTokens`)
|
||||
|
||||
Налаштування ущільнення Pi знаходяться в параметрах Pi:
|
||||
Налаштування ущільнення Pi зберігаються в налаштуваннях Pi:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -267,14 +267,14 @@ exceeded` та подібні варіанти у стилі конкретно
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw також застосовує нижню межу безпеки для вбудованих запусків:
|
||||
OpenClaw також застосовує мінімальний захисний поріг для вбудованих запусків:
|
||||
|
||||
- Якщо `compaction.reserveTokens < reserveTokensFloor`, OpenClaw підвищує це значення.
|
||||
- Типове значення нижньої межі — `20000` токенів.
|
||||
- Установіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути нижню межу.
|
||||
- Якщо `compaction.reserveTokens < reserveTokensFloor`, OpenClaw підвищує значення.
|
||||
- Типовий поріг — `20000` токенів.
|
||||
- Установіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути цей поріг.
|
||||
- Якщо значення вже вище, OpenClaw залишає його без змін.
|
||||
|
||||
Навіщо: залишити достатній запас для багатокрокового «службового обслуговування» (наприклад, записів у пам’ять), перш ніж ущільнення стане неминучим.
|
||||
Чому: залишити достатньо запасу для багатокрокових “службових” дій (наприклад, записів пам’яті), перш ніж ущільнення стане неминучим.
|
||||
|
||||
Реалізація: `ensurePiCompactionReserveTokens()` у `src/agents/pi-settings.ts`
|
||||
(викликається з `src/agents/pi-embedded-runner.ts`).
|
||||
@ -283,46 +283,46 @@ OpenClaw також застосовує нижню межу безпеки дл
|
||||
|
||||
## Поверхні, видимі користувачу
|
||||
|
||||
Ви можете спостерігати ущільнення та стан сесії через:
|
||||
Ви можете спостерігати ущільнення і стан сесії через:
|
||||
|
||||
- `/status` (у будь-якій сесії чату)
|
||||
- `/status` (у будь-якому чаті сесії)
|
||||
- `openclaw status` (CLI)
|
||||
- `openclaw sessions` / `sessions --json`
|
||||
- Докладний режим: `🧹 Auto-compaction complete` + кількість ущільнень
|
||||
- Режим verbose: `🧹 Auto-compaction complete` + кількість ущільнень
|
||||
|
||||
---
|
||||
|
||||
## Тихе службове обслуговування (`NO_REPLY`)
|
||||
## Тихі службові дії (`NO_REPLY`)
|
||||
|
||||
OpenClaw підтримує «тихі» ходи для фонових завдань, де користувач не повинен бачити проміжний вивід.
|
||||
OpenClaw підтримує “тихі” ходи для фонових завдань, де користувач не повинен бачити проміжний вивід.
|
||||
|
||||
Домовленість:
|
||||
Умова:
|
||||
|
||||
- Помічник починає свій вивід із точного тихого токена `NO_REPLY` /
|
||||
`no_reply`, щоб позначити «не доставляти відповідь користувачу».
|
||||
- OpenClaw видаляє/пригнічує це на рівні доставки.
|
||||
- Пригнічення точного тихого токена не залежить від регістру, тож `NO_REPLY` і
|
||||
`no_reply` зараховуються, коли весь вміст складається лише з тихого токена.
|
||||
- Це призначено лише для справжніх фонових ходів без доставки; це не скорочення
|
||||
для звичайних дієвих запитів користувача.
|
||||
- Асистент починає свій вивід з точного тихого токена `NO_REPLY` /
|
||||
`no_reply`, щоб позначити “не доставляти відповідь користувачу”.
|
||||
- OpenClaw прибирає/приглушує це на рівні доставки.
|
||||
- Приглушення точного тихого токена нечутливе до регістру, тож `NO_REPLY` і
|
||||
`no_reply` обидва зараховуються, коли весь payload — це лише тихий токен.
|
||||
- Це лише для справді фонових ходів/ходів без доставки; це не скорочений шлях
|
||||
для звичайних практичних запитів користувача.
|
||||
|
||||
Починаючи з `2026.1.10`, OpenClaw також пригнічує **потокову передачу чернеток/набору**, коли
|
||||
частковий фрагмент починається з `NO_REPLY`, щоб тихі операції не розкривали частковий
|
||||
Починаючи з `2026.1.10`, OpenClaw також приглушує **чернетковий/набірний стримінг**, коли
|
||||
частковий чанк починається з `NO_REPLY`, щоб тихі операції не видавали частковий
|
||||
вивід посеред ходу.
|
||||
|
||||
---
|
||||
|
||||
## «Скидання пам’яті» перед ущільненням (реалізовано)
|
||||
## "Скидання пам’яті" перед ущільненням (реалізовано)
|
||||
|
||||
Мета: перед тим як відбудеться автоущільнення, виконати тихий агентний хід, який запише довготривалий
|
||||
Мета: перед тим як відбудеться автоущільнення, виконати тихий агентний хід, який записує стійкий
|
||||
стан на диск (наприклад, `memory/YYYY-MM-DD.md` у робочому просторі агента), щоб ущільнення не могло
|
||||
стерти критичний контекст.
|
||||
|
||||
OpenClaw використовує підхід **скидання перед порогом**:
|
||||
OpenClaw використовує підхід **flush до порога**:
|
||||
|
||||
1. Відстежувати використання контексту сесії.
|
||||
2. Коли воно перетинає «м’який поріг» (нижче від порога ущільнення Pi), виконати тиху
|
||||
директиву «запиши пам’ять зараз» для агента.
|
||||
2. Коли воно перетинає “м’який поріг” (нижчий за поріг ущільнення Pi), виконати тиху
|
||||
директиву “запиши пам’ять зараз” для агента.
|
||||
3. Використовувати точний тихий токен `NO_REPLY` / `no_reply`, щоб користувач
|
||||
нічого не бачив.
|
||||
|
||||
@ -330,29 +330,29 @@ OpenClaw використовує підхід **скидання перед п
|
||||
|
||||
- `enabled` (типово: `true`)
|
||||
- `softThresholdTokens` (типово: `4000`)
|
||||
- `prompt` (повідомлення користувача для ходу flush)
|
||||
- `systemPrompt` (додатковий системний промпт, доданий для ходу flush)
|
||||
- `prompt` (повідомлення user для ходу flush)
|
||||
- `systemPrompt` (додатковий системний промпт, який додається для ходу flush)
|
||||
|
||||
Примітки:
|
||||
|
||||
- Типові `prompt`/`systemPrompt` містять підказку `NO_REPLY` для пригнічення
|
||||
- Типові значення prompt/system prompt містять підказку `NO_REPLY` для приглушення
|
||||
доставки.
|
||||
- Flush виконується один раз за цикл ущільнення (відстежується в `sessions.json`).
|
||||
- Flush виконується лише для вбудованих сесій Pi (бекенди CLI його пропускають).
|
||||
- Flush виконується лише для вбудованих сесій Pi.
|
||||
- Flush пропускається, коли робочий простір сесії доступний лише для читання (`workspaceAccess: "ro"` або `"none"`).
|
||||
- Див. [Memory](/uk/concepts/memory), щоб дізнатися про структуру файлів у робочому просторі та шаблони запису.
|
||||
- Див. [Memory](/uk/concepts/memory) щодо структури файлів робочого простору та шаблонів запису.
|
||||
|
||||
Pi також надає хук `session_before_compact` в API розширень, але логіка
|
||||
flush в OpenClaw сьогодні знаходиться на боці Gateway.
|
||||
Pi також надає хук `session_before_compact` в API розширень, але логіка flush в OpenClaw
|
||||
сьогодні живе на боці Gateway.
|
||||
|
||||
---
|
||||
|
||||
## Контрольний список для усунення несправностей
|
||||
## Контрольний список усунення несправностей
|
||||
|
||||
- Неправильний ключ сесії? Почніть із [/concepts/session](/uk/concepts/session) і підтвердьте `sessionKey` у `/status`.
|
||||
- Невідповідність між сховищем і транскриптом? Підтвердьте хост Gateway і шлях до сховища з `openclaw status`.
|
||||
- Неправильний ключ сесії? Почніть із [/concepts/session](/uk/concepts/session) і перевірте `sessionKey` у `/status`.
|
||||
- Невідповідність між сховищем і транскриптом? Перевірте хост Gateway і шлях до сховища з `openclaw status`.
|
||||
- Спам ущільненням? Перевірте:
|
||||
- вікно контексту моделі (замале)
|
||||
- налаштування ущільнення (`reserveTokens`, занадто велике для вікна моделі, може спричиняти раніше ущільнення)
|
||||
- роздування `toolResult`: увімкніть/налаштуйте обрізання сесій
|
||||
- Тихі ходи «просочуються»? Переконайтеся, що відповідь починається з `NO_REPLY` (точний токен без урахування регістру) і що ви використовуєте збірку, яка містить виправлення для пригнічення потокової передачі.
|
||||
- налаштування ущільнення (`reserveTokens` завелике для вікна моделі може спричиняти раніше ущільнення)
|
||||
- роздуття tool-result: увімкніть/налаштуйте очищення сесії
|
||||
- Тихі ходи протікають? Переконайтеся, що відповідь починається з `NO_REPLY` (нечутливий до регістру точний токен) і що у вас збірка, яка містить виправлення приглушення стримінгу.
|
||||
|
||||
@ -1,230 +1,229 @@
|
||||
---
|
||||
read_when:
|
||||
- Запуск coding harness через ACP
|
||||
- Налаштування ACP-сесій, прив’язаних до розмов, у каналах обміну повідомленнями
|
||||
- Прив’язка розмови в каналі повідомлень до постійної ACP-сесії
|
||||
- Усунення проблем із бекендом ACP і wiring плагінів
|
||||
- Керування командами /acp із чату
|
||||
summary: Використовуйте runtime-сесії ACP для Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP та інших harness-агентів
|
||||
title: ACP-агенти
|
||||
- Запуск harness-оточень для кодування через ACP
|
||||
- Налаштування прив’язаних до розмови сеансів ACP у каналах обміну повідомленнями
|
||||
- Прив’язування розмови в каналі повідомлень до постійного сеансу ACP
|
||||
- Усунення несправностей бекенду ACP і підключення плагінів
|
||||
- Керування командами /acp з чату
|
||||
summary: Використовуйте сеанси середовища виконання ACP для Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP та інших агентів harness
|
||||
title: Агенти ACP
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T18:20:13Z"
|
||||
generated_at: "2026-04-05T18:49:57Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 99e4d5af60fe89314b53655bbad01494d972b55416cf5a529171c010a0b8547d
|
||||
source_hash: 302f3fe25b1ffe0576592b6e0ad9e8a5781fa5702b31d508d9ba8908f7df33bd
|
||||
source_path: tools/acp-agents.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# ACP-агенти
|
||||
# Агенти ACP
|
||||
|
||||
Сесії [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають OpenClaw змогу запускати зовнішні coding harness (наприклад Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX harness) через плагін бекенда ACP.
|
||||
Сеанси [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають змогу OpenClaw запускати зовнішні harness-оточення для кодування (наприклад Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX-harness-оточення) через плагін бекенду ACP.
|
||||
|
||||
Якщо ви просите OpenClaw звичайною мовою «запусти це в Codex» або «запусти Claude Code у треді», OpenClaw має спрямувати цей запит до runtime ACP (а не до нативного runtime субагента). Кожен запуск ACP-сесії відстежується як [фонове завдання](/uk/automation/tasks).
|
||||
Якщо ви попросите OpenClaw звичайною мовою «запусти це в Codex» або «запусти Claude Code у гілці», OpenClaw має спрямувати цей запит до середовища виконання ACP (а не до нативного середовища виконання субагента). Кожен запуск сеансу ACP відстежується як [фонове завдання](/uk/automation/tasks).
|
||||
|
||||
Якщо ви хочете, щоб Codex або Claude Code підключалися як зовнішній MCP-клієнт безпосередньо
|
||||
до наявних розмов OpenClaw у каналах, використовуйте [`openclaw mcp serve`](/cli/mcp)
|
||||
до наявних розмов у каналах OpenClaw, використовуйте [`openclaw mcp serve`](/cli/mcp)
|
||||
замість ACP.
|
||||
|
||||
## Яка сторінка мені потрібна?
|
||||
## Яку сторінку мені потрібно?
|
||||
|
||||
Поруч є три схожі поверхні, які легко переплутати:
|
||||
Поруч є три поверхні, які легко сплутати:
|
||||
|
||||
| Ви хочете... | Використовуйте це | Примітки |
|
||||
| --------------------------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
||||
| Запускати Codex, Claude Code, Gemini CLI або інший зовнішній harness _через_ OpenClaw | Ця сторінка: ACP-агенти | Сесії, прив’язані до чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, runtime-керування |
|
||||
| Експонувати сесію OpenClaw Gateway _як_ ACP-сервер для редактора або клієнта | [`openclaw acp`](/cli/acp) | Режим моста. IDE/клієнт спілкується з OpenClaw через ACP поверх stdio/WebSocket |
|
||||
| Ви хочете... | Використовуйте це | Примітки |
|
||||
| --------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| Запускати Codex, Claude Code, Gemini CLI або інше зовнішнє harness-оточення _через_ OpenClaw | Ця сторінка: агенти ACP | Прив’язані до чату сеанси, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, елементи керування середовищем виконання |
|
||||
| Відкрити сеанс OpenClaw Gateway _як_ ACP-сервер для редактора або клієнта | [`openclaw acp`](/cli/acp) | Режим мосту. IDE/клієнт спілкується з OpenClaw через ACP поверх stdio/WebSocket |
|
||||
|
||||
## Чи працює це одразу після встановлення?
|
||||
## Це працює одразу після встановлення?
|
||||
|
||||
Зазвичай так.
|
||||
|
||||
- Нові встановлення тепер постачаються з комплектним runtime-плагіном `acpx`, увімкненим типово.
|
||||
- Комплектний плагін `acpx` надає перевагу своєму локально закріпленому бінарнику `acpx`.
|
||||
- Під час запуску OpenClaw перевіряє цей бінарник і за потреби самостійно відновлює його.
|
||||
- Нові встановлення тепер постачаються з увімкненим за замовчуванням вбудованим плагіном середовища виконання `acpx`.
|
||||
- Вбудований плагін `acpx` віддає перевагу своєму локально закріпленому бінарному файлу `acpx`.
|
||||
- Під час запуску OpenClaw перевіряє цей бінарний файл і за потреби самостійно його відновлює.
|
||||
- Почніть із `/acp doctor`, якщо хочете швидко перевірити готовність.
|
||||
|
||||
Що все ще може статися під час першого використання:
|
||||
|
||||
- Адаптер цільового harness може бути завантажений за вимогою через `npx` під час першого використання цього harness.
|
||||
- На хості все одно має бути налаштована автентифікація постачальника для цього harness.
|
||||
- Якщо хост не має доступу до npm/мережі, завантаження адаптера під час першого запуску може завершитися невдачею, доки кеші не буде прогріто або адаптер не буде встановлено іншим способом.
|
||||
- Цільовий адаптер harness може бути завантажений за запитом через `npx` під час першого використання цього harness.
|
||||
- На хості для цього harness все одно має бути наявна автентифікація постачальника.
|
||||
- Якщо хост не має доступу до npm/мережі, перше завантаження адаптерів може завершитися помилкою, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом.
|
||||
|
||||
Приклади:
|
||||
|
||||
- `/acp spawn codex`: OpenClaw має бути готовий ініціалізувати `acpx`, але адаптер Codex ACP усе ще може потребувати завантаження під час першого запуску.
|
||||
- `/acp spawn claude`: та сама історія для адаптера Claude ACP, плюс автентифікація на боці Claude на цьому хості.
|
||||
- `/acp spawn codex`: OpenClaw має бути готовий ініціалізувати `acpx`, але адаптер Codex ACP усе ще може потребувати першого завантаження.
|
||||
- `/acp spawn claude`: те саме для адаптера Claude ACP, плюс автентифікація на боці Claude на цьому хості.
|
||||
|
||||
## Швидкий операторський сценарій
|
||||
## Швидкий операторський потік
|
||||
|
||||
Використовуйте це, якщо вам потрібен практичний runbook для `/acp`:
|
||||
Використовуйте це, якщо вам потрібна практична інструкція для `/acp`:
|
||||
|
||||
1. Створіть сесію:
|
||||
1. Запустіть сеанс:
|
||||
- `/acp spawn codex --bind here`
|
||||
- `/acp spawn codex --mode persistent --thread auto`
|
||||
2. Працюйте в прив’язаній розмові або треді (або явно вкажіть ключ цієї сесії).
|
||||
3. Перевірте стан runtime:
|
||||
2. Працюйте в прив’язаній розмові або гілці (або явно вкажіть ключ цього сеансу).
|
||||
3. Перевірте стан середовища виконання:
|
||||
- `/acp status`
|
||||
4. За потреби налаштуйте параметри runtime:
|
||||
4. За потреби налаштуйте параметри середовища виконання:
|
||||
- `/acp model <provider/model>`
|
||||
- `/acp permissions <profile>`
|
||||
- `/acp timeout <seconds>`
|
||||
5. Скоригуйте активну сесію без заміни контексту:
|
||||
5. Скоригуйте активний сеанс без заміни контексту:
|
||||
- `/acp steer tighten logging and continue`
|
||||
6. Зупиніть роботу:
|
||||
- `/acp cancel` (зупинити поточний хід), або
|
||||
- `/acp close` (закрити сесію та прибрати прив’язки)
|
||||
- `/acp close` (закрити сеанс і прибрати прив’язки)
|
||||
|
||||
## Швидкий старт для людей
|
||||
|
||||
Приклади природних запитів:
|
||||
|
||||
- «Прив’яжи цей канал Discord до Codex.»
|
||||
- «Запусти постійну сесію Codex у треді тут і тримай її сфокусованою.»
|
||||
- «Запусти це як одноразову ACP-сесію Claude Code і підсумуй результат.»
|
||||
- «Прив’яжи цей чат iMessage до Codex і зберігай подальші повідомлення в тому самому workspace.»
|
||||
- «Використай Gemini CLI для цього завдання в треді, а потім зберігай подальші повідомлення в цьому самому треді.»
|
||||
- «Прив’яжи цей канал Discord до Codex».
|
||||
- «Запусти тут постійний сеанс Codex у гілці й тримай його зосередженим».
|
||||
- «Виконай це як одноразовий сеанс Claude Code ACP і підсумуй результат».
|
||||
- «Прив’яжи цей чат iMessage до Codex і зберігай наступні повідомлення в тому самому робочому просторі».
|
||||
- «Використай Gemini CLI для цього завдання в гілці, а потім зберігай наступні повідомлення в цій самій гілці».
|
||||
|
||||
Що має зробити OpenClaw:
|
||||
|
||||
1. Вибрати `runtime: "acp"`.
|
||||
2. Визначити запитаний цільовий harness (`agentId`, наприклад `codex`).
|
||||
3. Якщо запитується прив’язка до поточної розмови і активний канал це підтримує, прив’язати ACP-сесію до цієї розмови.
|
||||
4. Інакше, якщо запитується прив’язка до треда і поточний канал це підтримує, прив’язати ACP-сесію до треда.
|
||||
5. Маршрутизувати подальші прив’язані повідомлення до тієї самої ACP-сесії, доки її не буде розфокусовано/закрито/прострочено.
|
||||
2. Визначити цільове harness-оточення (`agentId`, наприклад `codex`).
|
||||
3. Якщо запитано прив’язку до поточної розмови й активний канал це підтримує, прив’язати сеанс ACP до цієї розмови.
|
||||
4. Інакше, якщо запитано прив’язку до гілки й поточний канал це підтримує, прив’язати сеанс ACP до гілки.
|
||||
5. Спрямовувати наступні прив’язані повідомлення до того самого сеансу ACP, доки він не буде розфокусований, закритий або прострочений.
|
||||
|
||||
## ACP проти субагентів
|
||||
|
||||
Використовуйте ACP, коли вам потрібен зовнішній harness runtime. Використовуйте субагентів, коли вам потрібні делеговані запуски, нативні для OpenClaw.
|
||||
Використовуйте ACP, коли потрібне зовнішнє середовище виконання harness. Використовуйте субагентів, коли потрібні делеговані запуски OpenClaw.
|
||||
|
||||
| Область | ACP-сесія | Запуск субагента |
|
||||
| ------------- | ------------------------------------- | ----------------------------------- |
|
||||
| Runtime | Плагін бекенда ACP (наприклад acpx) | Нативний runtime субагента OpenClaw |
|
||||
| Ключ сесії | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
|
||||
| Основні команди | `/acp ...` | `/subagents ...` |
|
||||
| Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (типовий runtime) |
|
||||
| Область | Сеанс ACP | Запуск субагента |
|
||||
| ------------- | -------------------------------------- | ----------------------------------- |
|
||||
| Середовище виконання | Плагін бекенду ACP (наприклад acpx) | Нативне середовище виконання субагента OpenClaw |
|
||||
| Ключ сеансу | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
|
||||
| Основні команди | `/acp ...` | `/subagents ...` |
|
||||
| Інструмент запуску | `sessions_spawn` with `runtime:"acp"` | `sessions_spawn` (середовище виконання за замовчуванням) |
|
||||
|
||||
Див. також [Субагенти](/tools/subagents).
|
||||
Див. також [Субагенти](/uk/tools/subagents).
|
||||
|
||||
## Як ACP запускає Claude Code
|
||||
|
||||
Для Claude Code через ACP стек такий:
|
||||
|
||||
1. Керувальна площина ACP-сесії OpenClaw
|
||||
2. комплектний runtime-плагін `acpx`
|
||||
1. Площина керування сеансом OpenClaw ACP
|
||||
2. вбудований плагін середовища виконання `acpx`
|
||||
3. адаптер Claude ACP
|
||||
4. runtime/механізми сесій на боці Claude
|
||||
4. механізм середовища виконання/сеансу на боці Claude
|
||||
|
||||
Важлива відмінність:
|
||||
|
||||
- ACP Claude — це harness-сесія з ACP-керуванням, відновленням сесій, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/треда.
|
||||
- ACP Claude — це сеанс harness з елементами керування ACP, відновленням сеансу, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/гілки.
|
||||
Для операторів практичне правило таке:
|
||||
|
||||
- потрібні `/acp spawn`, сесії з прив’язкою, runtime-керування або постійна робота harness: використовуйте ACP
|
||||
- потрібен простий локальний текстовий fallback через сирий CLI: використовуйте CLI-бекенди
|
||||
- якщо потрібні `/acp spawn`, сеанси з прив’язкою, елементи керування середовищем виконання або постійна робота harness — використовуйте ACP
|
||||
|
||||
## Прив’язані сесії
|
||||
## Прив’язані сеанси
|
||||
|
||||
### Прив’язки до поточної розмови
|
||||
|
||||
Використовуйте `/acp spawn <harness> --bind here`, якщо хочете, щоб поточна розмова стала довготривалим ACP-workspace без створення дочірнього треда.
|
||||
Використовуйте `/acp spawn <harness> --bind here`, коли хочете, щоб поточна розмова стала довговічним робочим простором ACP без створення дочірньої гілки.
|
||||
|
||||
Поведінка:
|
||||
|
||||
- OpenClaw продовжує керувати транспортом каналу, автентифікацією, безпекою та доставкою.
|
||||
- Поточна розмова закріплюється за ключем створеної ACP-сесії.
|
||||
- Подальші повідомлення в цій розмові маршрутизуються до тієї самої ACP-сесії.
|
||||
- `/new` і `/reset` скидають цю саму прив’язану ACP-сесію на місці.
|
||||
- `/acp close` закриває сесію та прибирає прив’язку поточної розмови.
|
||||
- OpenClaw і далі керує транспортом каналу, автентифікацією, безпекою та доставкою.
|
||||
- Поточна розмова закріплюється за ключем створеного сеансу ACP.
|
||||
- Наступні повідомлення в цій розмові спрямовуються до того самого сеансу ACP.
|
||||
- `/new` і `/reset` скидають той самий прив’язаний сеанс ACP на місці.
|
||||
- `/acp close` закриває сеанс і прибирає прив’язку до поточної розмови.
|
||||
|
||||
Що це означає на практиці:
|
||||
|
||||
- `--bind here` зберігає ту саму поверхню чату. У Discord поточний канал залишається поточним каналом.
|
||||
- `--bind here` все одно може створити нову ACP-сесію, якщо ви запускаєте нову роботу. Прив’язка приєднує цю сесію до поточної розмови.
|
||||
- `--bind here` сам по собі не створює дочірній тред Discord або тему Telegram.
|
||||
- Runtime ACP усе одно може мати власний робочий каталог (`cwd`) або workspace на диску, яким керує бекенд. Цей runtime-workspace відокремлений від поверхні чату і не означає створення нового треда повідомлень.
|
||||
- Якщо ви створюєте сесію для іншого ACP-агента і не передаєте `--cwd`, OpenClaw типово успадковує workspace **цільового агента**, а не того, хто робить запит.
|
||||
- Якщо цей успадкований шлях до workspace відсутній (`ENOENT`/`ENOTDIR`), OpenClaw повертається до типового cwd бекенда замість того, щоб непомітно повторно використати неправильне дерево.
|
||||
- Якщо успадкований workspace існує, але до нього немає доступу (наприклад `EACCES`), запуск повертає реальну помилку доступу замість відкидання `cwd`.
|
||||
- `--bind here` все одно може створити новий сеанс ACP, якщо ви запускаєте нову роботу. Прив’язка прикріплює цей сеанс до поточної розмови.
|
||||
- `--bind here` сам по собі не створює дочірню гілку Discord або тему Telegram.
|
||||
- Середовище виконання ACP все одно може мати власну робочу директорію (`cwd`) або робочий простір на диску, яким керує бекенд. Цей робочий простір середовища виконання є окремим від поверхні чату й не означає створення нової гілки повідомлень.
|
||||
- Якщо ви запускаєте інший ACP-агент і не передаєте `--cwd`, OpenClaw за замовчуванням успадковує робочий простір **цільового агента**, а не запитувача.
|
||||
- Якщо цей успадкований шлях до робочого простору відсутній (`ENOENT`/`ENOTDIR`), OpenClaw повертається до стандартного cwd бекенду замість того, щоб мовчки повторно використати неправильне дерево.
|
||||
- Якщо успадкований робочий простір існує, але доступ до нього неможливий (наприклад `EACCES`), запуск повертає реальну помилку доступу замість відкидання `cwd`.
|
||||
|
||||
Ментальна модель:
|
||||
|
||||
- поверхня чату: де люди продовжують спілкуватися (`канал Discord`, `тема Telegram`, `чат iMessage`)
|
||||
- ACP-сесія: довготривалий стан runtime Codex/Claude/Gemini, до якого маршрутизує OpenClaw
|
||||
- дочірній тред/тема: необов’язкова додаткова поверхня повідомлень, яка створюється лише через `--thread ...`
|
||||
- runtime-workspace: розташування у файловій системі, де виконується harness (`cwd`, checkout репозиторію, workspace бекенда)
|
||||
- сеанс ACP: довговічний стан середовища виконання Codex/Claude/Gemini, до якого OpenClaw спрямовує запити
|
||||
- дочірня гілка/тема: необов’язкова додаткова поверхня повідомлень, що створюється лише через `--thread ...`
|
||||
- робочий простір середовища виконання: розташування у файловій системі, де працює harness (`cwd`, checkout репозиторію, робочий простір бекенду)
|
||||
|
||||
Приклади:
|
||||
|
||||
- `/acp spawn codex --bind here`: зберегти цей чат, створити або приєднати сесію Codex ACP і маршрутизувати до неї майбутні повідомлення звідси
|
||||
- `/acp spawn codex --thread auto`: OpenClaw може створити дочірній тред/тему і прив’язати ACP-сесію там
|
||||
- `/acp spawn codex --bind here --cwd /workspace/repo`: така сама прив’язка чату, як вище, але Codex працює в `/workspace/repo`
|
||||
- `/acp spawn codex --bind here`: зберегти цей чат, створити або під’єднати сеанс Codex ACP і спрямовувати сюди майбутні повідомлення
|
||||
- `/acp spawn codex --thread auto`: OpenClaw може створити дочірню гілку/тему і прив’язати там сеанс ACP
|
||||
- `/acp spawn codex --bind here --cwd /workspace/repo`: та сама прив’язка до чату, що й вище, але Codex працює в `/workspace/repo`
|
||||
|
||||
Підтримка прив’язки поточної розмови:
|
||||
Підтримка прив’язки до поточної розмови:
|
||||
|
||||
- Канали чату/повідомлень, які оголошують підтримку прив’язки поточної розмови, можуть використовувати `--bind here` через спільний шлях прив’язки розмов.
|
||||
- Канали з нестандартною семантикою тредів/тем усе одно можуть надавати канало-специфічну канонікалізацію за тим самим спільним інтерфейсом.
|
||||
- Чат-канали/канали повідомлень, які заявляють підтримку прив’язки до поточної розмови, можуть використовувати `--bind here` через спільний шлях прив’язки розмов.
|
||||
- Канали з особливою семантикою гілок/тем усе одно можуть надавати канально-специфічну канонізацію за тим самим спільним інтерфейсом.
|
||||
- `--bind here` завжди означає «прив’язати поточну розмову на місці».
|
||||
- Узагальнені прив’язки поточної розмови використовують спільне сховище прив’язок OpenClaw і переживають звичайні перезапуски gateway.
|
||||
- Загальні прив’язки до поточної розмови використовують спільне сховище прив’язок OpenClaw і зберігаються після звичайних перезапусків gateway.
|
||||
|
||||
Примітки:
|
||||
|
||||
- `--bind here` і `--thread ...` взаємовиключні в `/acp spawn`.
|
||||
- У Discord `--bind here` прив’язує поточний канал або тред на місці. `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірній тред для `--thread auto|here`.
|
||||
- Якщо активний канал не надає прив’язок ACP до поточної розмови, OpenClaw повертає зрозуміле повідомлення про непідтримуваність.
|
||||
- `resume` і питання «нова сесія» — це питання ACP-сесії, а не каналу. Ви можете повторно використати або замінити стан runtime без зміни поточної поверхні чату.
|
||||
- У Discord `--bind here` прив’язує поточний канал або гілку на місці. `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірню гілку для `--thread auto|here`.
|
||||
- Якщо активний канал не надає ACP-прив’язок до поточної розмови, OpenClaw повертає зрозуміле повідомлення про непідтримку.
|
||||
- `resume` і питання «нового сеансу» — це питання сеансу ACP, а не каналу. Ви можете повторно використовувати або замінювати стан середовища виконання, не змінюючи поточну поверхню чату.
|
||||
|
||||
### Сесії, прив’язані до треда
|
||||
### Сеанси з прив’язкою до гілки
|
||||
|
||||
Коли для адаптера каналу ввімкнено прив’язки тредів, ACP-сесії можна прив’язувати до тредів:
|
||||
Коли для адаптера каналу ввімкнено прив’язки до гілок, сеанси ACP можна прив’язувати до гілок:
|
||||
|
||||
- OpenClaw прив’язує тред до цільової ACP-сесії.
|
||||
- Подальші повідомлення в цьому треді маршрутизуються до прив’язаної ACP-сесії.
|
||||
- Вивід ACP доставляється назад у той самий тред.
|
||||
- Розфокусування/закриття/архівування/тайм-аут бездіяльності або перевищення max-age прибирає прив’язку.
|
||||
- OpenClaw прив’язує гілку до цільового сеансу ACP.
|
||||
- Наступні повідомлення в цій гілці спрямовуються до прив’язаного сеансу ACP.
|
||||
- Вивід ACP доставляється назад у ту саму гілку.
|
||||
- Розфокусування, закриття, архівування, тайм-аут бездіяльності або завершення max-age прибирає прив’язку.
|
||||
|
||||
Підтримка прив’язки тредів залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки тредів, OpenClaw повертає зрозуміле повідомлення про непідтримуваність/недоступність.
|
||||
Підтримка прив’язки до гілки залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки до гілки, OpenClaw повертає зрозуміле повідомлення про непідтримку/недоступність.
|
||||
|
||||
Потрібні feature flags для ACP, прив’язаного до тредів:
|
||||
Необхідні прапорці функцій для ACP із прив’язкою до гілки:
|
||||
|
||||
- `acp.enabled=true`
|
||||
- `acp.dispatch.enabled` типово увімкнено (встановіть `false`, щоб призупинити ACP-dispatch)
|
||||
- Увімкнений прапорець створення ACP-тредів для адаптера каналу (залежить від адаптера)
|
||||
- `acp.dispatch.enabled` увімкнено за замовчуванням (встановіть `false`, щоб призупинити диспетчеризацію ACP)
|
||||
- Увімкнено прапорець запуску ACP у гілках адаптера каналу (залежить від адаптера)
|
||||
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
|
||||
|
||||
### Канали з підтримкою тредів
|
||||
### Канали з підтримкою гілок
|
||||
|
||||
- Будь-який адаптер каналу, який надає можливість прив’язки сесії/треда.
|
||||
- Будь-який адаптер каналу, який надає можливість прив’язки сеансу/гілки.
|
||||
- Поточна вбудована підтримка:
|
||||
- треди/канали Discord
|
||||
- теми Telegram (теми форуму в групах/супергрупах і DM-теми)
|
||||
- гілки/канали Discord
|
||||
- теми Telegram (форумні теми в групах/супергрупах і DM-теми)
|
||||
- Канали-плагіни можуть додавати підтримку через той самий інтерфейс прив’язки.
|
||||
|
||||
## Налаштування для конкретних каналів
|
||||
|
||||
Для неепізодичних сценаріїв налаштовуйте постійні ACP-прив’язки у верхньорівневих записах `bindings[]`.
|
||||
Для неепізодичних робочих процесів налаштуйте постійні ACP-прив’язки в записах верхнього рівня `bindings[]`.
|
||||
|
||||
### Модель прив’язки
|
||||
|
||||
- `bindings[].type="acp"` позначає постійну ACP-прив’язку розмови.
|
||||
- `bindings[].match` ідентифікує цільову розмову:
|
||||
- канал або тред Discord: `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
|
||||
- тема форуму Telegram: `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
|
||||
- DM/груповий чат BlueBubbles: `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Для стабільних прив’язок груп надавайте перевагу `chat_id:*` або `chat_identifier:*`.
|
||||
- DM/груповий чат iMessage: `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Для стабільних прив’язок груп надавайте перевагу `chat_id:*`.
|
||||
- `bindings[].agentId` — це id власника-агента OpenClaw.
|
||||
- Необов’язкові ACP-перевизначення розміщуються в `bindings[].acp`:
|
||||
- `bindings[].match` визначає цільову розмову:
|
||||
- канал або гілка Discord: `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
|
||||
- форумна тема Telegram: `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
|
||||
- чат BlueBubbles DM/груповий чат: `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Для стабільних прив’язок груп віддавайте перевагу `chat_id:*` або `chat_identifier:*`.
|
||||
- чат iMessage DM/груповий чат: `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Для стабільних прив’язок груп віддавайте перевагу `chat_id:*`.
|
||||
- `bindings[].agentId` — це id агента OpenClaw-власника.
|
||||
- Необов’язкові перевизначення ACP містяться в `bindings[].acp`:
|
||||
- `mode` (`persistent` або `oneshot`)
|
||||
- `label`
|
||||
- `cwd`
|
||||
- `backend`
|
||||
|
||||
### Типові значення runtime для агента
|
||||
### Стандартні параметри середовища виконання для кожного агента
|
||||
|
||||
Використовуйте `agents.list[].runtime`, щоб один раз визначити типові значення ACP для кожного агента:
|
||||
Використовуйте `agents.list[].runtime`, щоб один раз визначити стандартні параметри ACP для кожного агента:
|
||||
|
||||
- `agents.list[].runtime.type="acp"`
|
||||
- `agents.list[].runtime.acp.agent` (id harness, наприклад `codex` або `claude`)
|
||||
@ -232,11 +231,11 @@ x-i18n:
|
||||
- `agents.list[].runtime.acp.mode`
|
||||
- `agents.list[].runtime.acp.cwd`
|
||||
|
||||
Пріоритет перевизначень для прив’язаних ACP-сесій:
|
||||
Пріоритет перевизначень для прив’язаних сеансів ACP:
|
||||
|
||||
1. `bindings[].acp.*`
|
||||
2. `agents.list[].runtime.acp.*`
|
||||
3. глобальні типові значення ACP (наприклад `acp.backend`)
|
||||
3. глобальні стандартні параметри ACP (наприклад `acp.backend`)
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -320,18 +319,18 @@ x-i18n:
|
||||
|
||||
Поведінка:
|
||||
|
||||
- OpenClaw гарантує існування налаштованої ACP-сесії перед використанням.
|
||||
- Повідомлення в цьому каналі або темі маршрутизуються до налаштованої ACP-сесії.
|
||||
- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ ACP-сесії на місці.
|
||||
- Тимчасові runtime-прив’язки (наприклад створені потоками фокусування тредів) усе ще застосовуються там, де вони є.
|
||||
- Для міжагентних ACP-запусків без явного `cwd` OpenClaw успадковує workspace цільового агента з конфігурації агента.
|
||||
- Відсутні успадковані шляхи workspace повертаються до типового cwd бекенда; невідсутні помилки доступу повертаються як помилки запуску.
|
||||
- OpenClaw гарантує, що налаштований сеанс ACP існує до початку використання.
|
||||
- Повідомлення в цьому каналі або темі спрямовуються до налаштованого сеансу ACP.
|
||||
- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ сеансу ACP на місці.
|
||||
- Тимчасові прив’язки середовища виконання (наприклад створені потоками фокусування на гілці) усе ще застосовуються, де вони є.
|
||||
- Для міжагентних запусків ACP без явного `cwd` OpenClaw успадковує робочий простір цільового агента з конфігурації агента.
|
||||
- Відсутні успадковані шляхи до робочого простору призводять до повернення до стандартного cwd бекенду; невідсутні помилки доступу повертаються як помилки запуску.
|
||||
|
||||
## Запуск ACP-сесій (інтерфейси)
|
||||
## Запуск сеансів ACP (інтерфейси)
|
||||
|
||||
### Із `sessions_spawn`
|
||||
|
||||
Використовуйте `runtime: "acp"`, щоб запустити ACP-сесію з ходу агента або виклику інструмента.
|
||||
Використовуйте `runtime: "acp"`, щоб запустити сеанс ACP із ходу агента або виклику інструмента.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -345,29 +344,29 @@ x-i18n:
|
||||
|
||||
Примітки:
|
||||
|
||||
- `runtime` типово дорівнює `subagent`, тому для ACP-сесій явно встановлюйте `runtime: "acp"`.
|
||||
- Якщо `agentId` пропущено, OpenClaw використовує `acp.defaultAgent`, якщо його налаштовано.
|
||||
- `runtime` за замовчуванням має значення `subagent`, тому для сеансів ACP явно встановлюйте `runtime: "acp"`.
|
||||
- Якщо `agentId` не вказано, OpenClaw використовує `acp.defaultAgent`, якщо його налаштовано.
|
||||
- `mode: "session"` вимагає `thread: true`, щоб зберегти постійну прив’язану розмову.
|
||||
|
||||
Подробиці інтерфейсу:
|
||||
Відомості про інтерфейс:
|
||||
|
||||
- `task` (обов’язково): початковий запит, що надсилається до ACP-сесії.
|
||||
- `task` (обов’язково): початковий промпт, надісланий до сеансу ACP.
|
||||
- `runtime` (обов’язково для ACP): має бути `"acp"`.
|
||||
- `agentId` (необов’язково): id цільового ACP-harness. Якщо не задано, використовується `acp.defaultAgent`.
|
||||
- `thread` (необов’язково, типово `false`): запросити сценарій прив’язки до треда там, де він підтримується.
|
||||
- `agentId` (необов’язково): id цільового harness ACP. Якщо не вказано, використовується `acp.defaultAgent`, якщо налаштовано.
|
||||
- `thread` (необов’язково, за замовчуванням `false`): запитати потік прив’язки до гілки там, де це підтримується.
|
||||
- `mode` (необов’язково): `run` (одноразовий) або `session` (постійний).
|
||||
- типове значення — `run`
|
||||
- якщо `thread: true` і `mode` не задано, OpenClaw може за runtime-шляхом типово обрати постійну поведінку
|
||||
- за замовчуванням використовується `run`
|
||||
- якщо `thread: true` і mode не вказано, OpenClaw може за замовчуванням використовувати постійну поведінку залежно від шляху середовища виконання
|
||||
- `mode: "session"` вимагає `thread: true`
|
||||
- `cwd` (необов’язково): запитаний робочий каталог runtime (перевіряється політикою бекенда/runtime). Якщо не задано, ACP-запуск успадковує workspace цільового агента, якщо його налаштовано; відсутні успадковані шляхи повертаються до типових значень бекенда, тоді як реальні помилки доступу повертаються назовні.
|
||||
- `label` (необов’язково): операторська мітка, що використовується в тексті сесії/банера.
|
||||
- `resumeSessionId` (необов’язково): відновити наявну ACP-сесію замість створення нової. Агент відтворює свою історію розмов через `session/load`. Потребує `runtime: "acp"`.
|
||||
- `streamTo` (необов’язково): `"parent"` транслює підсумки прогресу початкового ACP-запуску назад до сесії-запитувача як системні події.
|
||||
- Коли це доступно, прийняті відповіді можуть містити `streamLogPath`, що вказує на JSONL-журнал у межах сесії (`<sessionId>.acp-stream.jsonl`), який можна відстежувати для повної історії ретрансляції.
|
||||
- `cwd` (необов’язково): запитувана робоча директорія середовища виконання (перевіряється політикою бекенду/середовища виконання). Якщо не вказано, під час запуску ACP успадковується робочий простір цільового агента, якщо він налаштований; відсутні успадковані шляхи повертаються до стандартних параметрів бекенду, а реальні помилки доступу повертаються.
|
||||
- `label` (необов’язково): операторська мітка, що використовується в тексті сеансу/банера.
|
||||
- `resumeSessionId` (необов’язково): відновити наявний сеанс ACP замість створення нового. Агент відтворює свою історію розмов через `session/load`. Вимагає `runtime: "acp"`.
|
||||
- `streamTo` (необов’язково): `"parent"` передає підсумки прогресу початкового запуску ACP назад до сеансу-запитувача як системні події.
|
||||
- За наявності прийнятні відповіді включають `streamLogPath`, який вказує на JSONL-журнал у межах сеансу (`<sessionId>.acp-stream.jsonl`), який можна відстежувати для повної історії ретрансляції.
|
||||
|
||||
### Відновлення наявної сесії
|
||||
### Відновлення наявного сеансу
|
||||
|
||||
Використовуйте `resumeSessionId`, щоб продовжити попередню ACP-сесію замість нового запуску. Агент відтворює свою історію розмов через `session/load`, тож продовжує з повним контекстом попередніх подій.
|
||||
Використовуйте `resumeSessionId`, щоб продовжити попередній сеанс ACP замість запуску з нуля. Агент відтворює свою історію розмов через `session/load`, тому відновлює роботу з повним контекстом попередніх дій.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -378,43 +377,43 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Поширені сценарії використання:
|
||||
Типові сценарії використання:
|
||||
|
||||
- Передати сесію Codex із ноутбука на телефон — скажіть агенту продовжити звідти, де ви зупинилися
|
||||
- Продовжити coding-сесію, яку ви почали інтерактивно в CLI, тепер у headless-режимі через агента
|
||||
- Відновити роботу, перервану перезапуском gateway або тайм-аутом бездіяльності
|
||||
- Передати сеанс Codex з ноутбука на телефон — попросіть агента продовжити з того місця, де ви зупинилися
|
||||
- Продовжити сеанс кодування, який ви почали інтерактивно в CLI, а тепер хочете виконувати безголово через агента
|
||||
- Відновити роботу, яку перервав перезапуск gateway або тайм-аут бездіяльності
|
||||
|
||||
Примітки:
|
||||
|
||||
- `resumeSessionId` вимагає `runtime: "acp"` — при використанні з runtime субагента повертається помилка.
|
||||
- `resumeSessionId` відновлює upstream-історію розмов ACP; `thread` і `mode` усе одно застосовуються звичайним чином до нової сесії OpenClaw, яку ви створюєте, тому `mode: "session"` усе ще вимагає `thread: true`.
|
||||
- Цільовий агент має підтримувати `session/load` (Codex і Claude Code підтримують).
|
||||
- Якщо id сесії не знайдено, запуск завершується зрозумілою помилкою — без тихого fallback до нової сесії.
|
||||
- `resumeSessionId` вимагає `runtime: "acp"` — повертає помилку, якщо використовується із середовищем виконання субагента.
|
||||
- `resumeSessionId` відновлює історію вхідної ACP-розмови; `thread` і `mode` як і раніше застосовуються звичайним чином до нового сеансу OpenClaw, який ви створюєте, тож `mode: "session"` усе ще вимагає `thread: true`.
|
||||
- Цільовий агент має підтримувати `session/load` (Codex і Claude Code це підтримують).
|
||||
- Якщо id сеансу не знайдено, запуск завершиться зрозумілою помилкою — без тихого повернення до нового сеансу.
|
||||
|
||||
### Операторський smoke test
|
||||
|
||||
Використовуйте це після розгортання gateway, якщо хочете швидко перевірити наживо, що ACP-запуск
|
||||
справді працює end-to-end, а не лише проходить unit-тести.
|
||||
Використовуйте це після розгортання gateway, коли потрібна швидка жива перевірка того, що запуск ACP
|
||||
справді працює наскрізь, а не лише проходить модульні тести.
|
||||
|
||||
Рекомендований gate:
|
||||
Рекомендований бар’єр перевірки:
|
||||
|
||||
1. Перевірте версію/коміт розгорнутого gateway на цільовому хості.
|
||||
2. Підтвердьте, що в розгорнутому source-коді є прийняття lineage ACP у
|
||||
2. Підтвердьте, що розгорнуте джерело містить прийняття лінійності ACP у
|
||||
`src/gateway/sessions-patch.ts` (`subagent:* or acp:* sessions`).
|
||||
3. Відкрийте тимчасову сесію мосту ACPX до живого агента (наприклад
|
||||
3. Відкрийте тимчасовий сеанс мосту ACPX до живого агента (наприклад
|
||||
`razor(main)` на `jpclawhq`).
|
||||
4. Попросіть цього агента викликати `sessions_spawn` із:
|
||||
- `runtime: "acp"`
|
||||
- `agentId: "codex"`
|
||||
- `mode: "run"`
|
||||
- завданням: `Reply with exactly LIVE-ACP-SPAWN-OK`
|
||||
- task: `Reply with exactly LIVE-ACP-SPAWN-OK`
|
||||
5. Переконайтеся, що агент повідомляє:
|
||||
- `accepted=yes`
|
||||
- реальний `childSessionKey`
|
||||
- відсутність помилки валідатора
|
||||
6. Приберіть тимчасову сесію мосту ACPX.
|
||||
6. Приберіть тимчасовий сеанс мосту ACPX.
|
||||
|
||||
Приклад запиту до живого агента:
|
||||
Приклад промпту для живого агента:
|
||||
|
||||
```text
|
||||
Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run".
|
||||
@ -424,25 +423,25 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
|
||||
Примітки:
|
||||
|
||||
- Тримайте цей smoke test у режимі `mode: "run"`, якщо ви не тестуєте навмисно
|
||||
постійні ACP-сесії, прив’язані до тредів.
|
||||
- Не вимагайте `streamTo: "parent"` для базового gate. Цей шлях залежить від
|
||||
можливостей запитувача/сесії і є окремою інтеграційною перевіркою.
|
||||
- Розглядайте тестування прив’язаного до треда `mode: "session"` як другий, багатший інтеграційний
|
||||
прохід із реального треда Discord або теми Telegram.
|
||||
- Для цього smoke test використовуйте `mode: "run"`, якщо тільки ви навмисно не тестуєте
|
||||
постійні сеанси ACP із прив’язкою до гілки.
|
||||
- Не вимагайте `streamTo: "parent"` для базового бар’єра. Цей шлях залежить від
|
||||
можливостей запитувача/сеансу й є окремою інтеграційною перевіркою.
|
||||
- Розглядайте тестування `mode: "session"` із прив’язкою до гілки як другу, ширшу інтеграційну
|
||||
перевірку з реальної гілки Discord або теми Telegram.
|
||||
|
||||
## Сумісність із sandbox
|
||||
|
||||
ACP-сесії наразі виконуються в runtime хоста, а не всередині sandbox OpenClaw.
|
||||
Наразі сеанси ACP працюють у середовищі виконання хоста, а не всередині sandbox OpenClaw.
|
||||
|
||||
Поточні обмеження:
|
||||
|
||||
- Якщо сесія-запитувач ізольована, ACP-запуски блокуються як для `sessions_spawn({ runtime: "acp" })`, так і для `/acp spawn`.
|
||||
- Якщо сеанс-запитувач ізольований sandbox, запуски ACP блокуються як для `sessions_spawn({ runtime: "acp" })`, так і для `/acp spawn`.
|
||||
- Помилка: `Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.`
|
||||
- `sessions_spawn` з `runtime: "acp"` не підтримує `sandbox: "require"`.
|
||||
- Помилка: `sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".`
|
||||
|
||||
Використовуйте `runtime: "subagent"`, коли вам потрібне виконання із примусовим sandbox.
|
||||
Використовуйте `runtime: "subagent"`, коли потрібне виконання, примусово обмежене sandbox.
|
||||
|
||||
### Із команди `/acp`
|
||||
|
||||
@ -455,7 +454,7 @@ ACP-сесії наразі виконуються в runtime хоста, а н
|
||||
/acp spawn codex --thread here
|
||||
```
|
||||
|
||||
Ключові прапорці:
|
||||
Основні прапорці:
|
||||
|
||||
- `--mode persistent|oneshot`
|
||||
- `--bind here|off`
|
||||
@ -463,11 +462,11 @@ ACP-сесії наразі виконуються в runtime хоста, а н
|
||||
- `--cwd <absolute-path>`
|
||||
- `--label <name>`
|
||||
|
||||
Див. [Слеш-команди](/tools/slash-commands).
|
||||
Див. [Слеш-команди](/uk/tools/slash-commands).
|
||||
|
||||
## Визначення цілі сесії
|
||||
## Визначення цілі сеансу
|
||||
|
||||
Більшість дій `/acp` приймають необов’язкову ціль сесії (`session-key`, `session-id` або `session-label`).
|
||||
Більшість дій `/acp` приймають необов’язкову ціль сеансу (`session-key`, `session-id` або `session-label`).
|
||||
|
||||
Порядок визначення:
|
||||
|
||||
@ -475,48 +474,48 @@ ACP-сесії наразі виконуються в runtime хоста, а н
|
||||
- спочатку пробує ключ
|
||||
- потім session id у форматі UUID
|
||||
- потім мітку
|
||||
2. Поточна прив’язка треда (якщо ця розмова/тред прив’язана до ACP-сесії)
|
||||
3. Fallback до поточної сесії запитувача
|
||||
2. Прив’язка поточної гілки (якщо ця розмова/гілка прив’язана до сеансу ACP)
|
||||
3. Резервний варіант: поточний сеанс запитувача
|
||||
|
||||
Прив’язки як до поточної розмови, так і до треда, беруть участь у кроці 2.
|
||||
Прив’язки до поточної розмови та прив’язки до гілки беруть участь у кроці 2.
|
||||
|
||||
Якщо ціль не визначено, OpenClaw повертає зрозумілу помилку (`Unable to resolve session target: ...`).
|
||||
Якщо жодної цілі не вдається визначити, OpenClaw повертає зрозумілу помилку (`Unable to resolve session target: ...`).
|
||||
|
||||
## Режими прив’язки під час запуску
|
||||
|
||||
`/acp spawn` підтримує `--bind here|off`.
|
||||
|
||||
| Режим | Поведінка |
|
||||
| ------ | ----------------------------------------------------------------------- |
|
||||
| `here` | Прив’язати поточну активну розмову на місці; завершити з помилкою, якщо активної немає. |
|
||||
| `off` | Не створювати прив’язку до поточної розмови. |
|
||||
| Режим | Поведінка |
|
||||
| ------ | ---------------------------------------------------------------------- |
|
||||
| `here` | Прив’язати поточну активну розмову на місці; помилка, якщо її немає. |
|
||||
| `off` | Не створювати прив’язку до поточної розмови. |
|
||||
|
||||
Примітки:
|
||||
|
||||
- `--bind here` — найпростіший операторський шлях для сценарію «зробити цей канал або чат підкріпленим Codex».
|
||||
- `--bind here` не створює дочірній тред.
|
||||
- `--bind here` доступний лише на каналах, які надають підтримку прив’язки до поточної розмови.
|
||||
- `--bind here` — найпростіший операторський шлях для «зробити цей канал або чат підкріпленим Codex».
|
||||
- `--bind here` не створює дочірню гілку.
|
||||
- `--bind here` доступний лише в каналах, які підтримують прив’язку до поточної розмови.
|
||||
- `--bind` і `--thread` не можна поєднувати в одному виклику `/acp spawn`.
|
||||
|
||||
## Режими тредів під час запуску
|
||||
## Режими гілок під час запуску
|
||||
|
||||
`/acp spawn` підтримує `--thread auto|here|off`.
|
||||
|
||||
| Режим | Поведінка |
|
||||
| ------ | ---------------------------------------------------------------------------------------------------- |
|
||||
| `auto` | У активному треді: прив’язати цей тред. Поза тредом: створити/прив’язати дочірній тред, якщо підтримується. |
|
||||
| `here` | Вимагати поточний активний тред; завершити з помилкою, якщо ви не в треді. |
|
||||
| `off` | Без прив’язки. Сесія запускається без прив’язки. |
|
||||
| `auto` | В активній гілці: прив’язати цю гілку. Поза гілкою: створити/прив’язати дочірню гілку, якщо це підтримується. |
|
||||
| `here` | Вимагає поточної активної гілки; помилка, якщо ви не в гілці. |
|
||||
| `off` | Без прив’язки. Сеанс запускається без прив’язки. |
|
||||
|
||||
Примітки:
|
||||
|
||||
- На поверхнях без прив’язки тредів типова поведінка фактично дорівнює `off`.
|
||||
- Запуск із прив’язкою треда вимагає підтримки політики каналу:
|
||||
- На поверхнях без підтримки прив’язки до гілки поведінка за замовчуванням фактично дорівнює `off`.
|
||||
- Запуск із прив’язкою до гілки вимагає підтримки політики каналу:
|
||||
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
|
||||
- Використовуйте `--bind here`, коли хочете закріпити поточну розмову без створення дочірнього треда.
|
||||
- Використовуйте `--bind here`, якщо хочете закріпити поточну розмову без створення дочірньої гілки.
|
||||
|
||||
## Керування ACP
|
||||
## Елементи керування ACP
|
||||
|
||||
Доступне сімейство команд:
|
||||
|
||||
@ -536,49 +535,49 @@ ACP-сесії наразі виконуються в runtime хоста, а н
|
||||
- `/acp doctor`
|
||||
- `/acp install`
|
||||
|
||||
`/acp status` показує ефективні параметри runtime і, коли доступно, ідентифікатори сесії як на рівні runtime, так і на рівні бекенда.
|
||||
`/acp status` показує ефективні параметри середовища виконання і, за наявності, ідентифікатори сеансів як на рівні середовища виконання, так і на рівні бекенду.
|
||||
|
||||
Деякі елементи керування залежать від можливостей бекенда. Якщо бекенд не підтримує певний елемент керування, OpenClaw повертає зрозумілу помилку про непідтримуваний елемент керування.
|
||||
Деякі елементи керування залежать від можливостей бекенду. Якщо бекенд не підтримує певний елемент керування, OpenClaw повертає зрозумілу помилку про непідтримуваний елемент керування.
|
||||
|
||||
## Кулінарна книга команд ACP
|
||||
## Книга рецептів для команд ACP
|
||||
|
||||
| Команда | Що робить | Приклад |
|
||||
| -------------------- | -------------------------------------------------------- | ------------------------------------------------------------- |
|
||||
| `/acp spawn` | Створює ACP-сесію; необов’язкова прив’язка тут або до треда. | `/acp spawn codex --bind here --cwd /repo` |
|
||||
| `/acp cancel` | Скасовує хід у процесі для цільової сесії. | `/acp cancel agent:codex:acp:<uuid>` |
|
||||
| `/acp steer` | Надсилає інструкцію керування до запущеної сесії. | `/acp steer --session support inbox prioritize failing tests` |
|
||||
| `/acp close` | Закриває сесію та відв’язує цілі тредів. | `/acp close` |
|
||||
| `/acp status` | Показує бекенд, режим, стан, параметри runtime, можливості. | `/acp status` |
|
||||
| `/acp set-mode` | Встановлює режим runtime для цільової сесії. | `/acp set-mode plan` |
|
||||
| `/acp set` | Загальний запис параметра конфігурації runtime. | `/acp set model openai/gpt-5.4` |
|
||||
| `/acp cwd` | Встановлює перевизначення робочого каталогу runtime. | `/acp cwd /Users/user/Projects/repo` |
|
||||
| `/acp permissions` | Встановлює профіль політики схвалення. | `/acp permissions strict` |
|
||||
| `/acp timeout` | Встановлює timeout runtime (секунди). | `/acp timeout 120` |
|
||||
| `/acp model` | Встановлює перевизначення моделі runtime. | `/acp model anthropic/claude-opus-4-6` |
|
||||
| `/acp reset-options` | Прибирає перевизначення параметрів runtime для сесії. | `/acp reset-options` |
|
||||
| `/acp sessions` | Перелічує недавні ACP-сесії зі сховища. | `/acp sessions` |
|
||||
| `/acp doctor` | Стан бекенда, можливості, дії для виправлення. | `/acp doctor` |
|
||||
| `/acp install` | Виводить детерміновані кроки встановлення та ввімкнення. | `/acp install` |
|
||||
| Команда | Що вона робить | Приклад |
|
||||
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
|
||||
| `/acp spawn` | Створює сеанс ACP; необов’язкова поточна прив’язка або прив’язка до гілки. | `/acp spawn codex --bind here --cwd /repo` |
|
||||
| `/acp cancel` | Скасовує поточний хід для цільового сеансу. | `/acp cancel agent:codex:acp:<uuid>` |
|
||||
| `/acp steer` | Надсилає інструкцію коригування до запущеного сеансу. | `/acp steer --session support inbox prioritize failing tests` |
|
||||
| `/acp close` | Закриває сеанс і відв’язує цілі гілок. | `/acp close` |
|
||||
| `/acp status` | Показує бекенд, режим, стан, параметри середовища виконання, можливості. | `/acp status` |
|
||||
| `/acp set-mode` | Встановлює режим середовища виконання для цільового сеансу. | `/acp set-mode plan` |
|
||||
| `/acp set` | Загальний запис параметра конфігурації середовища виконання. | `/acp set model openai/gpt-5.4` |
|
||||
| `/acp cwd` | Встановлює перевизначення робочої директорії середовища виконання. | `/acp cwd /Users/user/Projects/repo` |
|
||||
| `/acp permissions` | Встановлює профіль політики схвалення. | `/acp permissions strict` |
|
||||
| `/acp timeout` | Встановлює тайм-аут середовища виконання (секунди). | `/acp timeout 120` |
|
||||
| `/acp model` | Встановлює перевизначення моделі середовища виконання. | `/acp model anthropic/claude-opus-4-6` |
|
||||
| `/acp reset-options` | Прибирає перевизначення параметрів середовища виконання сеансу. | `/acp reset-options` |
|
||||
| `/acp sessions` | Показує список нещодавніх сеансів ACP зі сховища. | `/acp sessions` |
|
||||
| `/acp doctor` | Стан бекенду, можливості, практичні виправлення. | `/acp doctor` |
|
||||
| `/acp install` | Виводить детерміновані кроки встановлення та ввімкнення. | `/acp install` |
|
||||
|
||||
`/acp sessions` читає сховище для поточної прив’язаної сесії або сесії запитувача. Команди, які приймають токени `session-key`, `session-id` або `session-label`, визначають цілі через пошук сесій gateway, включно з кастомними коренями `session.store` для окремих агентів.
|
||||
`/acp sessions` читає сховище для поточного прив’язаного сеансу або сеансу запитувача. Команди, які приймають токени `session-key`, `session-id` або `session-label`, визначають цілі через виявлення сеансів gateway, включно з користувацькими коренями `session.store` для окремих агентів.
|
||||
|
||||
## Відображення параметрів runtime
|
||||
## Відображення параметрів середовища виконання
|
||||
|
||||
`/acp` має зручні команди та універсальний setter.
|
||||
`/acp` має зручні команди та загальний сеттер.
|
||||
|
||||
Еквівалентні операції:
|
||||
|
||||
- `/acp model <id>` відповідає ключу конфігурації runtime `model`.
|
||||
- `/acp permissions <profile>` відповідає ключу конфігурації runtime `approval_policy`.
|
||||
- `/acp timeout <seconds>` відповідає ключу конфігурації runtime `timeout`.
|
||||
- `/acp cwd <path>` напряму оновлює перевизначення cwd runtime.
|
||||
- `/acp set <key> <value>` — універсальний шлях.
|
||||
- Спеціальний випадок: `key=cwd` використовує шлях перевизначення cwd.
|
||||
- `/acp reset-options` очищає всі перевизначення runtime для цільової сесії.
|
||||
- `/acp model <id>` відповідає ключу конфігурації середовища виконання `model`.
|
||||
- `/acp permissions <profile>` відповідає ключу конфігурації середовища виконання `approval_policy`.
|
||||
- `/acp timeout <seconds>` відповідає ключу конфігурації середовища виконання `timeout`.
|
||||
- `/acp cwd <path>` безпосередньо оновлює перевизначення cwd середовища виконання.
|
||||
- `/acp set <key> <value>` — це загальний шлях.
|
||||
- Особливий випадок: `key=cwd` використовує шлях перевизначення cwd.
|
||||
- `/acp reset-options` очищає всі перевизначення середовища виконання для цільового сеансу.
|
||||
|
||||
## Підтримка harness acpx (поточна)
|
||||
|
||||
Поточні вбудовані псевдоніми harness в acpx:
|
||||
Поточні вбудовані псевдоніми harness acpx:
|
||||
|
||||
- `claude`
|
||||
- `codex`
|
||||
@ -595,12 +594,12 @@ ACP-сесії наразі виконуються в runtime хоста, а н
|
||||
- `pi`
|
||||
- `qwen`
|
||||
|
||||
Коли OpenClaw використовує бекенд acpx, надавайте перевагу цим значенням для `agentId`, якщо у вашій конфігурації acpx не визначено власні псевдоніми агентів.
|
||||
Якщо ваша локальна інсталяція Cursor усе ще експонує ACP як `agent acp`, перевизначте команду агента `cursor` у своїй конфігурації acpx замість зміни вбудованого типового значення.
|
||||
Коли OpenClaw використовує бекенд acpx, віддавайте перевагу цим значенням для `agentId`, якщо тільки у вашій конфігурації acpx не визначено користувацькі псевдоніми агентів.
|
||||
Якщо ваш локальний Cursor усе ще показує ACP як `agent acp`, перевизначте команду агента `cursor` у своїй конфігурації acpx замість зміни вбудованого стандартного значення.
|
||||
|
||||
Пряме використання CLI acpx також може націлюватися на довільні адаптери через `--agent <command>`, але цей сирий escape hatch є можливістю CLI acpx (а не звичайного шляху OpenClaw через `agentId`).
|
||||
Безпосереднє використання CLI acpx також може націлюватися на довільні адаптери через `--agent <command>`, але цей сирий обхідний шлях є функцією CLI acpx (а не звичайним шляхом `agentId` в OpenClaw).
|
||||
|
||||
## Обов’язкова конфігурація
|
||||
## Необхідна конфігурація
|
||||
|
||||
Базова конфігурація ACP:
|
||||
|
||||
@ -608,7 +607,7 @@ ACP-сесії наразі виконуються в runtime хоста, а н
|
||||
{
|
||||
acp: {
|
||||
enabled: true,
|
||||
// Необов’язково. Типове значення true; встановіть false, щоб призупинити ACP-dispatch, зберігши /acp controls.
|
||||
// Необов’язково. За замовчуванням true; встановіть false, щоб призупинити диспетчеризацію ACP, зберігши елементи керування /acp.
|
||||
dispatch: { enabled: true },
|
||||
backend: "acpx",
|
||||
defaultAgent: "codex",
|
||||
@ -640,7 +639,7 @@ ACP-сесії наразі виконуються в runtime хоста, а н
|
||||
}
|
||||
```
|
||||
|
||||
Конфігурація прив’язки тредів залежить від адаптера каналу. Приклад для Discord:
|
||||
Конфігурація прив’язки до гілок залежить від адаптера каналу. Приклад для Discord:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -662,18 +661,18 @@ ACP-сесії наразі виконуються в runtime хоста, а н
|
||||
}
|
||||
```
|
||||
|
||||
Якщо запуск ACP із прив’язкою треда не працює, спершу перевірте feature flag адаптера:
|
||||
Якщо запуск ACP із прив’язкою до гілки не працює, спочатку перевірте прапорець функції адаптера:
|
||||
|
||||
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
|
||||
Прив’язки до поточної розмови не вимагають створення дочірнього треда. Вони вимагають активного контексту розмови й адаптера каналу, який надає прив’язки ACP до розмови.
|
||||
Прив’язки до поточної розмови не потребують створення дочірньої гілки. Вони потребують активного контексту розмови й адаптера каналу, який надає ACP-прив’язки розмов.
|
||||
|
||||
Див. [Довідник із конфігурації](/uk/gateway/configuration-reference).
|
||||
|
||||
## Налаштування плагіна для бекенда acpx
|
||||
## Налаштування плагіна для бекенду acpx
|
||||
|
||||
Нові встановлення постачаються з комплектним runtime-плагіном `acpx`, увімкненим типово, тож ACP
|
||||
зазвичай працює без ручного кроку встановлення плагіна.
|
||||
Нові встановлення постачаються з увімкненим за замовчуванням вбудованим плагіном
|
||||
середовища виконання `acpx`, тому ACP зазвичай працює без ручного кроку встановлення плагіна.
|
||||
|
||||
Почніть із:
|
||||
|
||||
@ -682,34 +681,34 @@ ACP-сесії наразі виконуються в runtime хоста, а н
|
||||
```
|
||||
|
||||
Якщо ви вимкнули `acpx`, заборонили його через `plugins.allow` / `plugins.deny` або хочете
|
||||
перемкнутися на локальний checkout для розробки, використовуйте явний шлях плагіна:
|
||||
перейти на локальний checkout для розробки, скористайтеся явним шляхом плагіна:
|
||||
|
||||
```bash
|
||||
openclaw plugins install acpx
|
||||
openclaw config set plugins.entries.acpx.enabled true
|
||||
```
|
||||
|
||||
Локальне встановлення workspace під час розробки:
|
||||
Локальне встановлення робочого простору під час розробки:
|
||||
|
||||
```bash
|
||||
openclaw plugins install ./path/to/local/acpx-plugin
|
||||
```
|
||||
|
||||
Потім перевірте стан бекенда:
|
||||
Після цього перевірте стан бекенду:
|
||||
|
||||
```text
|
||||
/acp doctor
|
||||
```
|
||||
|
||||
### Конфігурація команди та версії acpx
|
||||
### Конфігурація команди й версії acpx
|
||||
|
||||
Типово комплектний плагін бекенда acpx (`acpx`) використовує локальний у плагіні закріплений бінарник:
|
||||
За замовчуванням вбудований плагін бекенду acpx (`acpx`) використовує локальний закріплений бінарний файл плагіна:
|
||||
|
||||
1. Команда типово вказує на локальний у плагіні `node_modules/.bin/acpx` всередині пакета плагіна ACPX.
|
||||
2. Очікувана версія типово дорівнює pin розширення.
|
||||
3. Під час запуску OpenClaw негайно реєструє бекенд ACP як not-ready.
|
||||
4. Фонове ensure-завдання перевіряє `acpx --version`.
|
||||
5. Якщо локальний у плагіні бінарник відсутній або не збігається, виконується:
|
||||
1. За замовчуванням команда вказує на локальний `node_modules/.bin/acpx` усередині пакета плагіна ACPX.
|
||||
2. Очікувана версія за замовчуванням відповідає закріпленню розширення.
|
||||
3. Під час запуску реєстрація бекенду ACP одразу позначається як not-ready.
|
||||
4. Фонове завдання ensure перевіряє `acpx --version`.
|
||||
5. Якщо локальний бінарний файл плагіна відсутній або не збігається за версією, виконується:
|
||||
`npm install --omit=dev --no-save acpx@<pinned>` і повторна перевірка.
|
||||
|
||||
Ви можете перевизначити команду/версію в конфігурації плагіна:
|
||||
@ -733,27 +732,27 @@ openclaw plugins install ./path/to/local/acpx-plugin
|
||||
Примітки:
|
||||
|
||||
- `command` приймає абсолютний шлях, відносний шлях або ім’я команди (`acpx`).
|
||||
- Відносні шляхи обчислюються від каталогу workspace OpenClaw.
|
||||
- `expectedVersion: "any"` вимикає сувору перевірку збігу версії.
|
||||
- Коли `command` вказує на кастомний бінарник/шлях, автоматичне локальне встановлення в плагіні вимикається.
|
||||
- Запуск OpenClaw залишається неблокувальним, поки виконується перевірка стану бекенда.
|
||||
- Відносні шляхи визначаються від директорії робочого простору OpenClaw.
|
||||
- `expectedVersion: "any"` вимикає сувору перевірку відповідності версії.
|
||||
- Коли `command` вказує на користувацький бінарний файл/шлях, автоматичне локальне встановлення плагіна вимикається.
|
||||
- Запуск OpenClaw залишається неблокувальним, поки триває фонова перевірка стану бекенду.
|
||||
|
||||
Див. [Плагіни](/tools/plugin).
|
||||
Див. [Плагіни](/uk/tools/plugin).
|
||||
|
||||
### Автоматичне встановлення залежностей
|
||||
|
||||
Коли ви встановлюєте OpenClaw глобально через `npm install -g openclaw`, runtime-залежності acpx
|
||||
(платформозалежні бінарники) встановлюються автоматично
|
||||
через postinstall-хук. Якщо автоматичне встановлення не вдається, gateway однаково запускається
|
||||
нормально та повідомляє про відсутню залежність через `openclaw acp doctor`.
|
||||
Коли ви встановлюєте OpenClaw глобально через `npm install -g openclaw`, залежності
|
||||
середовища виконання acpx (платформозалежні бінарні файли) встановлюються автоматично
|
||||
через хук postinstall. Якщо автоматичне встановлення завершується помилкою, gateway все одно запускається
|
||||
нормально і повідомляє про відсутню залежність через `openclaw acp doctor`.
|
||||
|
||||
### MCP-міст для інструментів плагінів
|
||||
### MCP-міст інструментів плагіна
|
||||
|
||||
Типово сесії ACPX **не** експонують зареєстровані в плагінах OpenClaw інструменти до
|
||||
ACP-harness.
|
||||
За замовчуванням сеанси ACPX **не** відкривають зареєстровані плагінами OpenClaw інструменти
|
||||
для ACP-harness-оточення.
|
||||
|
||||
Якщо ви хочете, щоб ACP-агенти, такі як Codex або Claude Code, могли викликати встановлені
|
||||
інструменти плагінів OpenClaw, наприклад memory recall/store, увімкніть спеціальний міст:
|
||||
інструменти плагінів OpenClaw, такі як збереження/отримання пам’яті, увімкніть спеціальний міст:
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
|
||||
@ -761,49 +760,50 @@ openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
|
||||
|
||||
Що це робить:
|
||||
|
||||
- Інжектує в bootstrap сесії ACPX вбудований MCP-сервер з іменем `openclaw-plugin-tools`.
|
||||
- Експонує інструменти плагінів, уже зареєстровані встановленими та увімкненими плагінами OpenClaw.
|
||||
- Робить функцію явно ввімкненою та типово вимкненою.
|
||||
- Вбудовує в bootstrap сеансу ACPX вбудований MCP-сервер з назвою `openclaw-plugin-tools`.
|
||||
- Відкриває інструменти плагінів, уже зареєстровані встановленими та ввімкненими
|
||||
плагінами OpenClaw.
|
||||
- Робить цю функцію явною і вимкненою за замовчуванням.
|
||||
|
||||
Примітки щодо безпеки й довіри:
|
||||
|
||||
- Це розширює поверхню інструментів ACP-harness.
|
||||
- ACP-агенти отримують доступ лише до інструментів плагінів, уже активних у gateway.
|
||||
- Це розширює поверхню інструментів ACP-harness-оточення.
|
||||
- ACP-агенти отримують доступ лише до інструментів плагінів, які вже активні в gateway.
|
||||
- Розглядайте це як ту саму межу довіри, що й дозвіл цим плагінам виконуватися
|
||||
в самому OpenClaw.
|
||||
- Перегляньте встановлені плагіни перед увімкненням цього.
|
||||
у самому OpenClaw.
|
||||
- Перевіряйте встановлені плагіни перед увімкненням цієї функції.
|
||||
|
||||
Кастомні `mcpServers` і надалі працюють як раніше. Вбудований міст plugin-tools —
|
||||
це додаткова зручність за явною згодою, а не заміна узагальненої конфігурації MCP-серверів.
|
||||
Користувацькі `mcpServers` і надалі працюють як раніше. Вбудований міст інструментів плагінів є
|
||||
додатковою зручною функцією за явним увімкненням, а не заміною загальної конфігурації MCP-сервера.
|
||||
|
||||
## Налаштування дозволів
|
||||
## Конфігурація дозволів
|
||||
|
||||
ACP-сесії працюють неінтерактивно — немає TTY, у якому можна схвалювати або відхиляти запити на дозвіл на запис файлів і виконання shell-команд. Плагін acpx надає два ключі конфігурації, які визначають, як обробляються дозволи:
|
||||
Сеанси ACP працюють неінтерактивно — TTY для схвалення або відхилення запитів дозволів на запис у файли й виконання shell-команд немає. Плагін acpx надає два ключі конфігурації, які керують обробкою дозволів:
|
||||
|
||||
Ці дозволи ACPX-harness відокремлені від схвалень exec в OpenClaw і від окремих прапорців обходу на боці CLI-бекенда, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний перемикач на рівні harness для ACP-сесій.
|
||||
Ці дозволи harness ACPX відокремлені від схвалень exec в OpenClaw і відокремлені від прапорців обходу постачальника в бекендах CLI, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний перемикач на рівні harness для сеансів ACP.
|
||||
|
||||
### `permissionMode`
|
||||
|
||||
Керує тим, які операції агент harness може виконувати без запиту.
|
||||
|
||||
| Значення | Поведінка |
|
||||
| --------------- | ---------------------------------------------------------- |
|
||||
| `approve-all` | Автоматично схвалювати всі записи файлів і shell-команди. |
|
||||
| `approve-reads` | Автоматично схвалювати лише читання; запис і exec вимагають запитів. |
|
||||
| `deny-all` | Відхиляти всі запити на дозвіл. |
|
||||
| Значення | Поведінка |
|
||||
| --------------- | -------------------------------------------------------- |
|
||||
| `approve-all` | Автоматично схвалює всі записи у файли та shell-команди. |
|
||||
| `approve-reads` | Автоматично схвалює лише читання; запис і exec вимагають запитів. |
|
||||
| `deny-all` | Відхиляє всі запити дозволів. |
|
||||
|
||||
### `nonInteractivePermissions`
|
||||
|
||||
Керує тим, що відбувається, коли мав би з’явитися запит на дозвіл, але інтерактивний TTY недоступний (що для ACP-сесій відбувається завжди).
|
||||
Керує тим, що відбувається, коли мав би з’явитися запит на дозвіл, але інтерактивний TTY недоступний (а для сеансів ACP це завжди так).
|
||||
|
||||
| Значення | Поведінка |
|
||||
| -------- | ----------------------------------------------------------------- |
|
||||
| `fail` | Перервати сесію з `AcpRuntimeError`. **(типово)** |
|
||||
| `deny` | Мовчки відхилити дозвіл і продовжити (плавна деградація). |
|
||||
| Значення | Поведінка |
|
||||
| -------- | ---------------------------------------------------------------- |
|
||||
| `fail` | Перервати сеанс з `AcpRuntimeError`. **(за замовчуванням)** |
|
||||
| `deny` | Мовчки відхилити дозвіл і продовжити роботу (плавна деградація). |
|
||||
|
||||
### Конфігурація
|
||||
|
||||
Установлюється через конфігурацію плагіна:
|
||||
Налаштовується через конфігурацію плагіна:
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
|
||||
@ -812,27 +812,27 @@ openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
|
||||
|
||||
Після зміни цих значень перезапустіть gateway.
|
||||
|
||||
> **Важливо:** OpenClaw наразі типово використовує `permissionMode=approve-reads` і `nonInteractivePermissions=fail`. У неінтерактивних ACP-сесіях будь-який запис або exec, що спричиняє запит на дозвіл, може завершитися помилкою `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`.
|
||||
> **Важливо:** OpenClaw наразі за замовчуванням використовує `permissionMode=approve-reads` і `nonInteractivePermissions=fail`. У неінтерактивних сеансах ACP будь-який запис або exec, що викликає запит дозволу, може завершитися помилкою `AcpRuntimeError: Permission prompt unavailable in non-interactive mode`.
|
||||
>
|
||||
> Якщо вам потрібно обмежити дозволи, установіть `nonInteractivePermissions` у `deny`, щоб сесії плавно деградували замість аварійного завершення.
|
||||
> Якщо вам потрібно обмежити дозволи, встановіть `nonInteractivePermissions` у `deny`, щоб сеанси плавно деградували замість аварійного завершення.
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
| Симптом | Імовірна причина | Виправлення |
|
||||
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ACP runtime backend is not configured` | Плагін бекенда відсутній або вимкнений. | Установіть і ввімкніть плагін бекенда, потім виконайте `/acp doctor`. |
|
||||
| `ACP is disabled by policy (acp.enabled=false)` | ACP глобально вимкнено. | Установіть `acp.enabled=true`. |
|
||||
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Dispatch із нормальних повідомлень треда вимкнено. | Установіть `acp.dispatch.enabled=true`. |
|
||||
| `ACP agent "<id>" is not allowed by policy` | Агент відсутній у списку дозволених. | Використовуйте дозволений `agentId` або оновіть `acp.allowedAgents`. |
|
||||
| `Unable to resolve session target: ...` | Неправильний токен ключа/id/мітки. | Виконайте `/acp sessions`, скопіюйте точний ключ/мітку та повторіть. |
|
||||
| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, яку можна прив’язати. | Перейдіть до цільового чату/каналу й повторіть, або використайте запуск без прив’язки. |
|
||||
| `Conversation bindings are unavailable for <channel>.` | Адаптер не має можливості ACP-прив’язки до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте верхньорівневі `bindings[]` або перейдіть до підтримуваного каналу. |
|
||||
| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом треда. | Перейдіть до цільового треда або використовуйте `--thread auto`/`off`. |
|
||||
| `Only <user-id> can rebind this channel/conversation/thread.` | Інший користувач володіє активною ціллю прив’язки. | Переприв’яжіть як власник або використовуйте іншу розмову чи тред. |
|
||||
| `Thread bindings are unavailable for <channel>.` | Адаптер не має можливості прив’язки тредів. | Використовуйте `--thread off` або перейдіть до підтримуваного адаптера/каналу. |
|
||||
| `Sandboxed sessions cannot spawn ACP sessions ...` | Runtime ACP працює на боці хоста; сесія-запитувач ізольована. | Використовуйте `runtime="subagent"` з ізольованих сесій або запускайте ACP зі сесії без sandbox. |
|
||||
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для runtime ACP запитано `sandbox="require"`. | Використовуйте `runtime="subagent"` для обов’язкової ізоляції або ACP із `sandbox="inherit"` із сесії без sandbox. |
|
||||
| Missing ACP metadata for bound session | Застарілі/видалені метадані ACP-сесії. | Створіть заново через `/acp spawn`, а потім переприв’яжіть/сфокусуйте тред. |
|
||||
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокує запис/exec у неінтерактивній ACP-сесії. | Установіть `plugins.entries.acpx.config.permissionMode` у `approve-all` і перезапустіть gateway. Див. [Налаштування дозволів](#permission-configuration). |
|
||||
| ACP session fails early with little output | Запити на дозвіл блокуються через `permissionMode`/`nonInteractivePermissions`. | Перевірте журнали gateway на `AcpRuntimeError`. Для повних дозволів установіть `permissionMode=approve-all`; для плавної деградації — `nonInteractivePermissions=deny`. |
|
||||
| ACP session stalls indefinitely after completing work | Процес harness завершився, але ACP-сесія не повідомила про завершення. | Відстежуйте через `ps aux \| grep acpx`; вручну завершіть завислі процеси. |
|
||||
| Симптом | Імовірна причина | Виправлення |
|
||||
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `ACP runtime backend is not configured` | Плагін бекенду відсутній або вимкнений. | Встановіть і ввімкніть плагін бекенду, потім виконайте `/acp doctor`. |
|
||||
| `ACP is disabled by policy (acp.enabled=false)` | ACP глобально вимкнено. | Встановіть `acp.enabled=true`. |
|
||||
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Диспетчеризацію зі звичайних повідомлень у гілках вимкнено. | Встановіть `acp.dispatch.enabled=true`. |
|
||||
| `ACP agent "<id>" is not allowed by policy` | Агента немає у списку дозволених. | Використовуйте дозволений `agentId` або оновіть `acp.allowedAgents`. |
|
||||
| `Unable to resolve session target: ...` | Неправильний токен ключа/id/мітки. | Виконайте `/acp sessions`, скопіюйте точний ключ/мітку й повторіть спробу. |
|
||||
| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, до якої можна прив’язатися. | Перейдіть у цільовий чат/канал і повторіть спробу або використайте запуск без прив’язки. |
|
||||
| `Conversation bindings are unavailable for <channel>.` | Адаптер не має можливості ACP-прив’язки до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте верхньорівневі `bindings[]` або перейдіть у підтримуваний канал. |
|
||||
| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом гілки. | Перейдіть у цільову гілку або використайте `--thread auto`/`off`. |
|
||||
| `Only <user-id> can rebind this channel/conversation/thread.` | Активна ціль прив’язки належить іншому користувачу. | Переприв’яжіть як власник або використайте іншу розмову чи гілку. |
|
||||
| `Thread bindings are unavailable for <channel>.` | Адаптер не має можливості прив’язки до гілки. | Використовуйте `--thread off` або перейдіть у підтримуваний адаптер/канал. |
|
||||
| `Sandboxed sessions cannot spawn ACP sessions ...` | Середовище виконання ACP працює на хості; сеанс-запитувач ізольований sandbox. | Використовуйте `runtime="subagent"` з ізольованих sandbox сеансів або запускайте ACP з неізольованого сеансу. |
|
||||
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для середовища виконання ACP запитано `sandbox="require"`. | Використовуйте `runtime="subagent"` для обов’язкової ізоляції sandbox або ACP із `sandbox="inherit"` з неізольованого сеансу. |
|
||||
| Missing ACP metadata for bound session | Застарілі/видалені метадані сеансу ACP. | Створіть заново через `/acp spawn`, потім повторно прив’яжіть/сфокусуйте гілку. |
|
||||
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокує запис/exec у неінтерактивному сеансі ACP. | Встановіть `plugins.entries.acpx.config.permissionMode` у `approve-all` і перезапустіть gateway. Див. [Конфігурація дозволів](#конфігурація-дозволів). |
|
||||
| ACP session fails early with little output | Запити дозволів блокуються через `permissionMode`/`nonInteractivePermissions`. | Перевірте журнали gateway на `AcpRuntimeError`. Для повних дозволів встановіть `permissionMode=approve-all`; для плавної деградації встановіть `nonInteractivePermissions=deny`. |
|
||||
| ACP session stalls indefinitely after completing work | Процес harness завершився, але сеанс ACP не повідомив про завершення. | Відстежуйте за допомогою `ps aux \| grep acpx`; вручну завершіть завислі процеси. |
|
||||
|
||||
Loading…
Reference in New Issue
Block a user