chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
99aec48bc8
commit
589d3c593c
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете зрозуміти, що означає «контекст» в OpenClaw
|
||||
- Ви налагоджуєте, чому модель щось «знає» (або забула це)
|
||||
- Ви налагоджуєте, чому модель «знає» щось (або забула це)
|
||||
- Ви хочете зменшити накладні витрати контексту (`/context`, `/status`, `/compact`)
|
||||
summary: 'Контекст: що бачить модель, як він будується та як його перевірити'
|
||||
summary: 'Контекст: що бачить модель, як він формується та як його перевірити'
|
||||
title: Контекст
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T18:48:31Z"
|
||||
generated_at: "2026-04-06T12:42:54Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fe7dfe52cb1a64df229c8622feed1804df6c483a6243e0d2f309f6ff5c9fe521
|
||||
source_hash: a75b4cd65bf6385d46265b9ce1643310bc99d220e35ec4b4924096bed3ca4aa0
|
||||
source_path: concepts/context.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -20,51 +20,51 @@ x-i18n:
|
||||
|
||||
Проста ментальна модель для початківців:
|
||||
|
||||
- **Системний запит** (збудований OpenClaw): правила, інструменти, список Skills, час/середовище виконання та впроваджені файли робочого простору.
|
||||
- **Історія розмови**: ваші повідомлення + повідомлення помічника для цієї сесії.
|
||||
- **Системний prompt** (збудований OpenClaw): правила, інструменти, список Skills, час/середовище виконання та вбудовані файли робочого простору.
|
||||
- **Історія розмови**: ваші повідомлення + повідомлення асистента для цієї сесії.
|
||||
- **Виклики/результати інструментів + вкладення**: вивід команд, читання файлів, зображення/аудіо тощо.
|
||||
|
||||
Контекст _не є тим самим_, що й «пам’ять»: пам’ять може зберігатися на диску та повторно завантажуватися пізніше; контекст — це те, що міститься в поточному вікні моделі.
|
||||
Контекст _це не те саме_, що «пам’ять»: пам’ять може зберігатися на диску та повторно завантажуватися пізніше; контекст — це те, що знаходиться всередині поточного вікна моделі.
|
||||
|
||||
## Швидкий старт (перевірка контексту)
|
||||
|
||||
- `/status` → швидкий перегляд «наскільки заповнене моє вікно?» + параметри сесії.
|
||||
- `/context list` → що впроваджено + приблизні розміри (для кожного файла + загальні).
|
||||
- `/context detail` → глибший розбір: для кожного файла, розміри схем кожного інструмента, розміри записів кожного skill та розмір системного запиту.
|
||||
- `/usage tokens` → додає нижній колонтитул використання для кожної відповіді до звичайних відповідей.
|
||||
- `/compact` → узагальнює старішу історію в компактний запис, щоб звільнити місце у вікні.
|
||||
- `/status` → швидкий перегляд «наскільки заповнене моє вікно?» + налаштування сесії.
|
||||
- `/context list` → що вбудовано + приблизні розміри (для кожного файла + загалом).
|
||||
- `/context detail` → детальніший розподіл: пофайлово, розміри схем кожного інструмента, розміри записів кожного skill та розмір системного prompt.
|
||||
- `/usage tokens` → додає нижній колонтитул із використанням до звичайних відповідей.
|
||||
- `/compact` → підсумовує старішу історію в компактний запис, щоб звільнити місце у вікні.
|
||||
|
||||
Див. також: [Слеш-команди](/uk/tools/slash-commands), [Використання токенів і витрати](/uk/reference/token-use), [Компресія](/uk/concepts/compaction).
|
||||
Див. також: [Slash commands](/uk/tools/slash-commands), [Використання токенів і витрати](/uk/reference/token-use), [Стиснення](/uk/concepts/compaction).
|
||||
|
||||
## Приклад виводу
|
||||
|
||||
Значення залежать від моделі, провайдера, політики інструментів і того, що є у вашому робочому просторі.
|
||||
Значення відрізняються залежно від моделі, провайдера, політики інструментів і вмісту вашого робочого простору.
|
||||
|
||||
### `/context list`
|
||||
|
||||
```
|
||||
🧠 Розподіл контексту
|
||||
Робочий простір: <workspaceDir>
|
||||
Макс. bootstrap на файл: 20,000 chars
|
||||
Максимум bootstrap на файл: 20,000 символів
|
||||
Пісочниця: mode=non-main sandboxed=false
|
||||
Системний запит (запуск): 38,412 chars (~9,603 tok) (Project Context 23,901 chars (~5,976 tok))
|
||||
Системний prompt (запуск): 38,412 символів (~9,603 ток) (Контекст проєкту 23,901 символів (~5,976 ток))
|
||||
|
||||
Впроваджені файли робочого простору:
|
||||
- AGENTS.md: OK | raw 1,742 chars (~436 tok) | injected 1,742 chars (~436 tok)
|
||||
- SOUL.md: OK | raw 912 chars (~228 tok) | injected 912 chars (~228 tok)
|
||||
- TOOLS.md: TRUNCATED | raw 54,210 chars (~13,553 tok) | injected 20,962 chars (~5,241 tok)
|
||||
- IDENTITY.md: OK | raw 211 chars (~53 tok) | injected 211 chars (~53 tok)
|
||||
- USER.md: OK | raw 388 chars (~97 tok) | injected 388 chars (~97 tok)
|
||||
Вбудовані файли робочого простору:
|
||||
- AGENTS.md: OK | raw 1,742 символів (~436 ток) | injected 1,742 символів (~436 ток)
|
||||
- SOUL.md: OK | raw 912 символів (~228 ток) | injected 912 символів (~228 ток)
|
||||
- TOOLS.md: TRUNCATED | raw 54,210 символів (~13,553 ток) | injected 20,962 символів (~5,241 ток)
|
||||
- IDENTITY.md: OK | raw 211 символів (~53 ток) | injected 211 символів (~53 ток)
|
||||
- USER.md: OK | raw 388 символів (~97 ток) | injected 388 символів (~97 ток)
|
||||
- HEARTBEAT.md: MISSING | raw 0 | injected 0
|
||||
- BOOTSTRAP.md: OK | raw 0 chars (~0 tok) | injected 0 chars (~0 tok)
|
||||
- BOOTSTRAP.md: OK | raw 0 символів (~0 ток) | injected 0 символів (~0 ток)
|
||||
|
||||
Список Skills (текст системного запиту): 2,184 chars (~546 tok) (12 skills)
|
||||
Список Skills (текст системного prompt): 2,184 символів (~546 ток) (12 skills)
|
||||
Інструменти: read, edit, write, exec, process, browser, message, sessions_send, …
|
||||
Список інструментів (текст системного запиту): 1,032 chars (~258 tok)
|
||||
Схеми інструментів (JSON): 31,988 chars (~7,997 tok) (враховуються в контексті; не показуються як текст)
|
||||
Інструменти: (те саме, що вище)
|
||||
Список інструментів (текст системного prompt): 1,032 символів (~258 ток)
|
||||
Схеми інструментів (JSON): 31,988 символів (~7,997 ток) (враховуються в контексті; не показані як текст)
|
||||
Інструменти: (ті самі, що вище)
|
||||
|
||||
Токени сесії (кешовані): 14,250 total / ctx=32,000
|
||||
Токени сесії (кешовані): 14,250 усього / ctx=32,000
|
||||
```
|
||||
|
||||
### `/context detail`
|
||||
@ -72,44 +72,44 @@ x-i18n:
|
||||
```
|
||||
🧠 Розподіл контексту (детально)
|
||||
…
|
||||
Найбільші skills (розмір запису в запиті):
|
||||
- frontend-design: 412 chars (~103 tok)
|
||||
- oracle: 401 chars (~101 tok)
|
||||
… (+ще 10 skills)
|
||||
Найбільші skills (розмір запису в prompt):
|
||||
- frontend-design: 412 символів (~103 ток)
|
||||
- oracle: 401 символ (~101 ток)
|
||||
… (+10 more skills)
|
||||
|
||||
Найбільші інструменти (розмір схеми):
|
||||
- browser: 9,812 chars (~2,453 tok)
|
||||
- exec: 6,240 chars (~1,560 tok)
|
||||
… (+ще N)
|
||||
- browser: 9,812 символів (~2,453 ток)
|
||||
- exec: 6,240 символів (~1,560 ток)
|
||||
… (+N more tools)
|
||||
```
|
||||
|
||||
## Що враховується у вікні контексту
|
||||
|
||||
Враховується все, що отримує модель, зокрема:
|
||||
Усе, що отримує модель, враховується, зокрема:
|
||||
|
||||
- Системний запит (усі розділи).
|
||||
- Системний prompt (усі розділи).
|
||||
- Історія розмови.
|
||||
- Виклики інструментів + результати інструментів.
|
||||
- Вкладення/транскрипти (зображення/аудіо/файли).
|
||||
- Підсумки компресії та артефакти обрізання.
|
||||
- Підсумки стиснення та артефакти обрізання.
|
||||
- «Обгортки» провайдера або приховані заголовки (не видимі, але все одно враховуються).
|
||||
|
||||
## Як OpenClaw будує системний запит
|
||||
## Як OpenClaw будує системний prompt
|
||||
|
||||
Системний запит **належить OpenClaw** і перебудовується для кожного запуску. Він містить:
|
||||
Системний prompt **належить OpenClaw** і перебудовується для кожного запуску. Він містить:
|
||||
|
||||
- Список інструментів + короткі описи.
|
||||
- Список Skills (лише метадані; див. нижче).
|
||||
- Розташування робочого простору.
|
||||
- Час (UTC + перетворений час користувача, якщо налаштовано).
|
||||
- Метадані середовища виконання (хост/ОС/модель/thinking).
|
||||
- Впроваджені bootstrap-файли робочого простору в розділі **Project Context**.
|
||||
- Вбудовані bootstrap-файли робочого простору в розділі **Контекст проєкту**.
|
||||
|
||||
Повний розбір: [Системний запит](/uk/concepts/system-prompt).
|
||||
Повний розбір: [System Prompt](/uk/concepts/system-prompt).
|
||||
|
||||
## Впроваджені файли робочого простору (Project Context)
|
||||
## Вбудовані файли робочого простору (Контекст проєкту)
|
||||
|
||||
Типово OpenClaw впроваджує фіксований набір файлів робочого простору (якщо вони є):
|
||||
Типово OpenClaw вбудовує фіксований набір файлів робочого простору (якщо вони є):
|
||||
|
||||
- `AGENTS.md`
|
||||
- `SOUL.md`
|
||||
@ -119,68 +119,69 @@ x-i18n:
|
||||
- `HEARTBEAT.md`
|
||||
- `BOOTSTRAP.md` (лише під час першого запуску)
|
||||
|
||||
Великі файли обрізаються окремо для кожного файла за допомогою `agents.defaults.bootstrapMaxChars` (типово `20000` символів). OpenClaw також застосовує загальне обмеження на впровадження bootstrap для всіх файлів через `agents.defaults.bootstrapTotalMaxChars` (типово `150000` символів). `/context` показує розміри **raw vs injected** і те, чи відбулося обрізання.
|
||||
Великі файли обрізаються для кожного файла окремо за допомогою `agents.defaults.bootstrapMaxChars` (типове значення `20000` символів). OpenClaw також застосовує загальне обмеження на вбудовування bootstrap для всіх файлів через `agents.defaults.bootstrapTotalMaxChars` (типове значення `150000` символів). `/context` показує розміри **raw vs injected** і те, чи відбулося обрізання.
|
||||
|
||||
Коли відбувається обрізання, середовище виконання може впровадити в запит блок попередження в розділі Project Context. Налаштовується це через `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; типово `once`).
|
||||
Коли відбувається обрізання, середовище виконання може вставити в prompt блок попередження в розділі Контекст проєкту. Це налаштовується через `agents.defaults.bootstrapPromptTruncationWarning` (`off`, `once`, `always`; типове значення `once`).
|
||||
|
||||
## Skills: впроваджені чи завантажені на вимогу
|
||||
## Skills: вбудовані чи завантажувані на вимогу
|
||||
|
||||
Системний запит містить компактний **список skills** (назва + опис + розташування). Цей список створює реальні накладні витрати.
|
||||
Системний prompt містить компактний **список Skills** (назва + опис + розташування). Цей список має реальні накладні витрати.
|
||||
|
||||
Інструкції skill _не_ включаються типово. Очікується, що модель виконає `read` для `SKILL.md` цього skill **лише за потреби**.
|
||||
Інструкції skill _не_ включаються типово. Очікується, що модель прочитає `SKILL.md` відповідного skill через `read` **лише за потреби**.
|
||||
|
||||
## Інструменти: є дві складові вартості
|
||||
## Інструменти: є дві складові витрат
|
||||
|
||||
Інструменти впливають на контекст двома способами:
|
||||
|
||||
1. **Текст списку інструментів** у системному запиті (те, що ви бачите як “Tooling”).
|
||||
2. **Схеми інструментів** (JSON). Вони надсилаються моделі, щоб вона могла викликати інструменти. Вони враховуються в контексті, навіть якщо ви не бачите їх як звичайний текст.
|
||||
1. **Текст списку інструментів** у системному prompt (те, що ви бачите як «Інструменти»).
|
||||
2. **Схеми інструментів** (JSON). Вони надсилаються моделі, щоб вона могла викликати інструменти. Вони враховуються в контексті, хоча ви не бачите їх як звичайний текст.
|
||||
|
||||
`/context detail` розбиває найбільші схеми інструментів, щоб ви могли побачити, що домінує.
|
||||
|
||||
## Команди, директиви та "вбудовані скорочення"
|
||||
|
||||
Слеш-команди обробляються Gateway. Існує кілька різних варіантів поведінки:
|
||||
Slash-команди обробляються Gateway. Є кілька різних варіантів поведінки:
|
||||
|
||||
- **Окремі команди**: повідомлення, яке складається лише з `/...`, виконується як команда.
|
||||
- **Директиви**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/model`, `/queue` прибираються до того, як модель побачить повідомлення.
|
||||
- Повідомлення лише з директивами зберігають параметри сесії.
|
||||
- **Окремі команди**: повідомлення, що складається лише з `/...`, виконується як команда.
|
||||
- **Директиви**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/model`, `/queue` видаляються до того, як модель побачить повідомлення.
|
||||
- Повідомлення, що містять лише директиви, зберігають налаштування сесії.
|
||||
- Вбудовані директиви у звичайному повідомленні діють як підказки для конкретного повідомлення.
|
||||
- **Вбудовані скорочення** (лише для відправників із allowlist): певні токени `/...` усередині звичайного повідомлення можуть виконуватися негайно (приклад: “hey /status”), а потім прибираються до того, як модель побачить решту тексту.
|
||||
- **Вбудовані скорочення** (лише для відправників із allowlist): певні токени `/...` всередині звичайного повідомлення можуть виконуватися негайно (наприклад: «hey /status»), і видаляються до того, як модель побачить решту тексту.
|
||||
|
||||
Докладніше: [Слеш-команди](/uk/tools/slash-commands).
|
||||
Докладніше: [Slash commands](/uk/tools/slash-commands).
|
||||
|
||||
## Сесії, компресія та обрізання (що зберігається)
|
||||
## Сесії, стиснення та обрізання (що зберігається)
|
||||
|
||||
Що саме зберігається між повідомленнями, залежить від механізму:
|
||||
|
||||
- **Звичайна історія** зберігається в транскрипті сесії, доки не буде стиснута/обрізана відповідно до політики.
|
||||
- **Компресія** зберігає підсумок у транскрипті та залишає недавні повідомлення без змін.
|
||||
- **Обрізання** видаляє старі результати інструментів із _внутрішньої_ підказки для запуску, але не переписує транскрипт.
|
||||
- **Звичайна історія** зберігається в транскрипті сесії, доки не буде стиснена/обрізана згідно з політикою.
|
||||
- **Стиснення** зберігає підсумок у транскрипті та залишає недоторканими нещодавні повідомлення.
|
||||
- **Обрізання** видаляє старі результати інструментів із prompt _у пам’яті_ для запуску, але не переписує транскрипт.
|
||||
|
||||
Документація: [Сесія](/uk/concepts/session), [Компресія](/uk/concepts/compaction), [Обрізання сесії](/uk/concepts/session-pruning).
|
||||
Документація: [Сесія](/uk/concepts/session), [Стиснення](/uk/concepts/compaction), [Обрізання сесії](/uk/concepts/session-pruning).
|
||||
|
||||
Типово OpenClaw використовує вбудований контекстний рушій `legacy` для збирання
|
||||
та компресії. Якщо ви встановите плагін, який надає `kind: "context-engine"`, і
|
||||
Типово OpenClaw використовує вбудований рушій контексту `legacy` для складання
|
||||
та стиснення. Якщо ви встановите plugin, який надає `kind: "context-engine"`, і
|
||||
виберете його через `plugins.slots.contextEngine`, OpenClaw натомість делегує
|
||||
цьому рушію збирання контексту, `/compact` і пов’язані гачки життєвого циклу
|
||||
контексту субагента. `ownsCompaction: false` не вмикає автоматичний fallback до
|
||||
рушія legacy; активний рушій усе одно має коректно реалізовувати `compact()`. Див.
|
||||
складання контексту, `/compact` і пов’язані гачки життєвого циклу контексту
|
||||
підлеглого агента цьому рушію. `ownsCompaction: false` не викликає
|
||||
автоматичного повернення до рушія `legacy`; активний рушій усе одно має
|
||||
коректно реалізовувати `compact()`. Див.
|
||||
[Context Engine](/uk/concepts/context-engine), щоб ознайомитися з повним
|
||||
підключуваним інтерфейсом, гачками життєвого циклу та конфігурацією.
|
||||
|
||||
## Що насправді показує `/context`
|
||||
|
||||
`/context` за можливості віддає перевагу найновішому звіту про системний запит, **побудований під час запуску**:
|
||||
`/context` за можливості віддає перевагу найновішому звіту про системний prompt, **побудований під час запуску**:
|
||||
|
||||
- `System prompt (run)` = зафіксований з останнього вбудованого запуску (з підтримкою інструментів) і збережений у сховищі сесії.
|
||||
- `System prompt (estimate)` = обчислений на льоту, якщо звіту про запуску ще немає.
|
||||
- `System prompt (run)` = захоплений з останнього вбудованого запуску (із підтримкою інструментів) і збережений у сховищі сесії.
|
||||
- `System prompt (estimate)` = обчислений на льоту, коли звіт про запуск відсутній (або під час роботи через бекенд CLI, який не генерує цей звіт).
|
||||
|
||||
У будь-якому випадку він показує розміри та найбільших учасників; він **не** вивантажує повний системний запит або схеми інструментів.
|
||||
У будь-якому разі він повідомляє розміри та найбільші складові; він **не** виводить повний системний prompt або схеми інструментів.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Context Engine](/uk/concepts/context-engine) — користувацьке впровадження контексту через плагіни
|
||||
- [Компресія](/uk/concepts/compaction) — узагальнення довгих розмов
|
||||
- [Системний запит](/uk/concepts/system-prompt) — як будується системний запит
|
||||
- [Context Engine](/uk/concepts/context-engine) — користувацьке вбудовування контексту через plugins
|
||||
- [Стиснення](/uk/concepts/compaction) — підсумовування довгих розмов
|
||||
- [System Prompt](/uk/concepts/system-prompt) — як будується системний prompt
|
||||
- [Цикл агента](/uk/concepts/agent-loop) — повний цикл виконання агента
|
||||
|
||||
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібен довідник із налаштування моделей для кожного постачальника окремо
|
||||
- Ви хочете приклади конфігурацій або команд CLI для онбордингу постачальників моделей
|
||||
- Вам потрібні приклади конфігурацій або команд CLI для онбордингу постачальників моделей
|
||||
summary: Огляд постачальників моделей із прикладами конфігурацій і потоків CLI
|
||||
title: Постачальники моделей
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T23:54:07Z"
|
||||
generated_at: "2026-04-06T12:44:34Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 15e4b82e07221018a723279d309e245bb4023bc06e64b3c910ef2cae3dfa2599
|
||||
source_hash: ec33cbfeec86c3f79ea0ec38932eebb819eba5932024b73fcf3acbc41fbce203
|
||||
source_path: concepts/model-providers.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Постачальники моделей
|
||||
|
||||
Ця сторінка охоплює **постачальників LLM/моделей** (а не канали чату, як-от WhatsApp/Telegram).
|
||||
На цій сторінці описано **постачальників LLM/моделей** (а не канали чату, як-от WhatsApp/Telegram).
|
||||
Правила вибору моделей див. у [/concepts/models](/uk/concepts/models).
|
||||
|
||||
## Швидкі правила
|
||||
|
||||
- Посилання на моделі використовують формат `provider/model` (приклад: `opencode/claude-opus-4-6`).
|
||||
- Якщо ви задаєте `agents.defaults.models`, це стає списком дозволених значень.
|
||||
- Якщо ви задаєте `agents.defaults.models`, це стає списком дозволених моделей.
|
||||
- Допоміжні команди CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set <provider/model>`.
|
||||
- Правила резервного перемикання під час виконання, перевірки стану після cooldown і збереження перевизначень сесії
|
||||
задокументовано в [/concepts/model-failover](/uk/concepts/model-failover).
|
||||
- Правила резервного перемикання під час виконання, проби періоду охолодження та збереження перевизначень сесії
|
||||
задокументовані в [/concepts/model-failover](/uk/concepts/model-failover).
|
||||
- `models.providers.*.models[].contextWindow` — це нативні метадані моделі;
|
||||
`models.providers.*.models[].contextTokens` — це фактичне обмеження під час виконання.
|
||||
- Плагіни постачальників можуть впроваджувати каталоги моделей через `registerProvider({ catalog })`;
|
||||
OpenClaw об’єднує цей вивід у `models.providers` перед записом
|
||||
- Плагіни постачальників можуть додавати каталоги моделей через `registerProvider({ catalog })`;
|
||||
OpenClaw об'єднує цей вивід у `models.providers` перед записом
|
||||
`models.json`.
|
||||
- Маніфести постачальників можуть оголошувати `providerAuthEnvVars`, щоб загальним перевіркам
|
||||
автентифікації через змінні середовища не потрібно було завантажувати код плагіна під час виконання. Решта мапи змінних середовища в core
|
||||
тепер призначена лише для неплагінових/core постачальників і кількох випадків
|
||||
загального пріоритету, як-от онбординг Anthropic зі сценарієм «спочатку API-ключ».
|
||||
- Плагіни постачальників також можуть керувати поведінкою постачальника під час виконання через
|
||||
автентифікації на основі змінних середовища не потрібно було завантажувати середовище виконання плагіна. Решта мапи змінних середовища ядра
|
||||
тепер використовується лише для не-плагінних/вбудованих постачальників і кількох випадків
|
||||
загального пріоритету, як-от онбординг Anthropic із пріоритетом API-ключа.
|
||||
- Плагіни постачальників також можуть володіти логікою виконання постачальника через
|
||||
`normalizeModelId`, `normalizeTransport`, `normalizeConfig`,
|
||||
`applyNativeStreamingUsageCompat`, `resolveConfigApiKey`,
|
||||
`resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`,
|
||||
@ -52,170 +52,177 @@ x-i18n:
|
||||
`resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`,
|
||||
`prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, and
|
||||
`onModelSelected`.
|
||||
- Примітка: `capabilities` постачальника під час виконання — це спільні метадані runner-а (сімейство постачальника, особливості transcript/tooling, підказки щодо transport/cache). Це не те саме, що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model),
|
||||
яка описує, що саме реєструє плагін (текстовий inference, speech тощо).
|
||||
- Примітка: `capabilities` середовища виконання постачальника — це спільні метадані виконавця (сімейство постачальника,
|
||||
особливості транскрипту/інструментів, підказки щодо транспорту/кешу). Це не
|
||||
те саме, що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model),
|
||||
яка описує, що реєструє плагін (текстовий inference, мовлення тощо).
|
||||
|
||||
## Поведінка постачальника, якою володіє плагін
|
||||
## Поведінка постачальника, що належить плагіну
|
||||
|
||||
Плагіни постачальників тепер можуть керувати більшістю логіки, специфічної для постачальника, тоді як OpenClaw зберігає
|
||||
Плагіни постачальників тепер можуть володіти більшістю специфічної для постачальника логіки, тоді як OpenClaw зберігає
|
||||
загальний цикл inference.
|
||||
|
||||
Типовий розподіл:
|
||||
|
||||
- `auth[].run` / `auth[].runNonInteractive`: постачальник керує потоками онбордингу/входу
|
||||
- `auth[].run` / `auth[].runNonInteractive`: постачальник володіє потоками онбордингу/входу
|
||||
для `openclaw onboard`, `openclaw models auth` і безголового налаштування
|
||||
- `wizard.setup` / `wizard.modelPicker`: постачальник керує мітками вибору автентифікації,
|
||||
застарілими псевдонімами, підказками щодо allowlist під час онбордингу та записами налаштування у вибірниках онбордингу/моделей
|
||||
- `catalog`: постачальник з’являється в `models.providers`
|
||||
- `wizard.setup` / `wizard.modelPicker`: постачальник володіє мітками вибору автентифікації,
|
||||
застарілими псевдонімами, підказками для списку дозволених моделей під час онбордингу та записами налаштування у вибірниках онбордингу/моделей
|
||||
- `catalog`: постачальник з'являється в `models.providers`
|
||||
- `normalizeModelId`: постачальник нормалізує застарілі/preview ідентифікатори моделей перед
|
||||
пошуком або канонізацією
|
||||
- `normalizeTransport`: постачальник нормалізує transport-family `api` / `baseUrl`
|
||||
перед загальним збиранням моделі; OpenClaw спочатку перевіряє відповідного постачальника,
|
||||
потім інші плагіни постачальників, здатні виконувати цей hook, доки один із них справді не змінить
|
||||
transport
|
||||
- `normalizeTransport`: постачальник нормалізує `api` / `baseUrl` сімейства транспорту
|
||||
перед загальним складанням моделі; OpenClaw спочатку перевіряє відповідного постачальника,
|
||||
потім інші плагіни постачальників, що підтримують хуки, поки один із них фактично не змінить
|
||||
транспорт
|
||||
- `normalizeConfig`: постачальник нормалізує конфігурацію `models.providers.<id>` перед
|
||||
використанням під час виконання; OpenClaw спочатку перевіряє відповідного постачальника, потім інші
|
||||
плагіни постачальників, здатні виконувати цей hook, доки один із них справді не змінить конфігурацію. Якщо жоден
|
||||
hook постачальника не переписує конфігурацію, вбудовані допоміжні засоби для сімейства Google все одно
|
||||
плагіни постачальників, що підтримують хуки, поки один із них фактично не змінить конфігурацію. Якщо жоден
|
||||
хук постачальника не переписує конфігурацію, вбудовані допоміжні засоби сімейства Google все одно
|
||||
нормалізують підтримувані записи постачальників Google.
|
||||
- `applyNativeStreamingUsageCompat`: постачальник застосовує переписування сумісності для нативного streaming-usage, зумовлене endpoint, для конфігурованих постачальників
|
||||
- `resolveConfigApiKey`: постачальник визначає автентифікацію через env-marker для конфігурованих постачальників
|
||||
без примусового повного завантаження runtime-автентифікації. `amazon-bedrock` також має тут
|
||||
вбудований resolver AWS env-marker, хоча runtime-автентифікація Bedrock використовує
|
||||
стандартний ланцюжок AWS SDK.
|
||||
- `resolveSyntheticAuth`: постачальник може повідомляти про доступність локальної/self-hosted або іншої
|
||||
автентифікації, що базується на конфігурації, без збереження відкритих секретів
|
||||
- `shouldDeferSyntheticProfileAuth`: постачальник може позначати збережені синтетичні заповнювачі профілю
|
||||
як менш пріоритетні, ніж автентифікація через env/config
|
||||
- `applyNativeStreamingUsageCompat`: постачальник застосовує переписування сумісності нативного обліку використання потокового режиму для постачальників конфігурації, зумовлені кінцевою точкою
|
||||
- `resolveConfigApiKey`: постачальник визначає автентифікацію маркера середовища для постачальників конфігурації
|
||||
без примусового повного завантаження автентифікації під час виконання. `amazon-bedrock` тут також має
|
||||
вбудований резолвер маркерів середовища AWS, хоча автентифікація Bedrock під час виконання використовує
|
||||
ланцюжок за замовчуванням AWS SDK.
|
||||
- `resolveSyntheticAuth`: постачальник може показувати доступність локальної/self-hosted або іншої
|
||||
автентифікації на основі конфігурації без збереження відкритих секретів
|
||||
- `shouldDeferSyntheticProfileAuth`: постачальник може позначати збережені синтетичні профілі-
|
||||
заповнювачі як такі, що мають нижчий пріоритет, ніж автентифікація на основі env/config
|
||||
- `resolveDynamicModel`: постачальник приймає ідентифікатори моделей, яких ще немає в локальному
|
||||
статичному каталозі
|
||||
- `prepareDynamicModel`: постачальнику потрібне оновлення метаданих перед повторною спробою
|
||||
- `prepareDynamicModel`: постачальнику потрібно оновити метадані перед повторною спробою
|
||||
динамічного визначення
|
||||
- `normalizeResolvedModel`: постачальнику потрібні переписування transport або base URL
|
||||
- `normalizeResolvedModel`: постачальнику потрібно переписати транспорт або базову URL-адресу
|
||||
- `contributeResolvedModelCompat`: постачальник додає прапорці сумісності для своїх
|
||||
моделей постачальника, навіть коли вони надходять через інший сумісний transport
|
||||
- `capabilities`: постачальник публікує особливості transcript/tooling/provider-family
|
||||
- `normalizeToolSchemas`: постачальник очищує схеми інструментів перед тим, як вбудований
|
||||
runner їх побачить
|
||||
- `inspectToolSchemas`: постачальник показує транспортно-специфічні попередження щодо схем
|
||||
моделей постачальника, навіть коли вони надходять через інший сумісний транспорт
|
||||
- `capabilities`: постачальник публікує особливості транскрипту/інструментів/сімейства постачальників
|
||||
- `normalizeToolSchemas`: постачальник очищує схеми інструментів перед тим, як їх побачить
|
||||
вбудований виконавець
|
||||
- `inspectToolSchemas`: постачальник показує специфічні для транспорту попередження схеми
|
||||
після нормалізації
|
||||
- `resolveReasoningOutputMode`: постачальник обирає нативні або теговані
|
||||
контракти reasoning-output
|
||||
- `prepareExtraParams`: постачальник задає типові значення або нормалізує параметри запиту для кожної моделі
|
||||
- `createStreamFn`: постачальник замінює звичайний шлях stream повністю
|
||||
користувацьким transport
|
||||
- `wrapStreamFn`: постачальник застосовує обгортки сумісності для заголовків/тіла/моделі запиту
|
||||
- `resolveTransportTurnState`: постачальник надає нативні заголовки transport або метадані
|
||||
для кожного turn
|
||||
- `resolveReasoningOutputMode`: постачальник вибирає нативні чи теговані
|
||||
контракти виводу reasoning
|
||||
- `prepareExtraParams`: постачальник задає типові значення або нормалізує параметри запиту для окремих моделей
|
||||
- `createStreamFn`: постачальник замінює звичайний шлях потоку повністю
|
||||
кастомним транспортом
|
||||
- `wrapStreamFn`: постачальник застосовує обгортки сумісності запиту заголовків/тіла/моделі
|
||||
- `resolveTransportTurnState`: постачальник надає нативні заголовки транспорту
|
||||
або метадані для кожного ходу
|
||||
- `resolveWebSocketSessionPolicy`: постачальник надає нативні заголовки сесії WebSocket
|
||||
або політику cooldown сесії
|
||||
- `createEmbeddingProvider`: постачальник керує поведінкою embedding для пам’яті, коли вона
|
||||
належить плагіну постачальника, а не core-перемикачу embedding
|
||||
- `formatApiKey`: постачальник форматує збережені профілі автентифікації в runtime-рядок
|
||||
`apiKey`, який очікує transport
|
||||
- `refreshOAuth`: постачальник керує оновленням OAuth, коли спільних
|
||||
refresher-ів `pi-ai` недостатньо
|
||||
- `buildAuthDoctorHint`: постачальник додає підказку щодо виправлення, коли оновлення OAuth
|
||||
завершується помилкою
|
||||
або політику охолодження сесії
|
||||
- `createEmbeddingProvider`: постачальник володіє логікою embedding для пам'яті, коли вона
|
||||
належить плагіну постачальника, а не центральному перемикачу embedding у ядрі
|
||||
- `formatApiKey`: постачальник форматує збережені профілі автентифікації у
|
||||
рядок `apiKey`, який очікує транспорт під час виконання
|
||||
- `refreshOAuth`: постачальник володіє оновленням OAuth, коли спільних
|
||||
оновлювачів `pi-ai` недостатньо
|
||||
- `buildAuthDoctorHint`: постачальник додає вказівки з відновлення, коли оновлення OAuth
|
||||
не вдається
|
||||
- `matchesContextOverflowError`: постачальник розпізнає специфічні для постачальника
|
||||
помилки переповнення контекстного вікна, які загальні евристики не виявляють
|
||||
- `classifyFailoverReason`: постачальник зіставляє специфічні для постачальника сирі помилки transport/API
|
||||
із причинами резервного перемикання, наприклад обмеження швидкості або перевантаження
|
||||
- `isCacheTtlEligible`: постачальник визначає, які upstream-ідентифікатори моделей підтримують TTL кешу prompt
|
||||
помилки переповнення вікна контексту, які загальні евристики можуть пропустити
|
||||
- `classifyFailoverReason`: постачальник зіставляє специфічні для постачальника сирі помилки транспорту/API
|
||||
з причинами резервного перемикання, як-от ліміт запитів або перевантаження
|
||||
- `isCacheTtlEligible`: постачальник визначає, які ідентифікатори моделей вище за потоком підтримують TTL кешу підказок
|
||||
- `buildMissingAuthMessage`: постачальник замінює загальну помилку сховища автентифікації
|
||||
на специфічну для постачальника підказку щодо відновлення
|
||||
на специфічну для постачальника підказку з відновлення
|
||||
- `suppressBuiltInModel`: постачальник приховує застарілі upstream-рядки й може повертати
|
||||
помилку від постачальника у разі збоїв прямого визначення
|
||||
помилку, що належить постачальнику, для прямих збоїв визначення
|
||||
- `augmentModelCatalog`: постачальник додає синтетичні/фінальні рядки каталогу після
|
||||
виявлення та злиття конфігурації
|
||||
- `isBinaryThinking`: постачальник керує UX двійкового thinking увімк./вимк.
|
||||
- `supportsXHighThinking`: постачальник додає вибраним моделям підтримку `xhigh`
|
||||
- `resolveDefaultThinkingLevel`: постачальник керує типовою політикою `/think` для
|
||||
виявлення та об'єднання конфігурації
|
||||
- `isBinaryThinking`: постачальник володіє UX двійкового thinking увімк./вимк.
|
||||
- `supportsXHighThinking`: постачальник вмикає `xhigh` для вибраних моделей
|
||||
- `resolveDefaultThinkingLevel`: постачальник володіє типовою політикою `/think` для
|
||||
сімейства моделей
|
||||
- `applyConfigDefaults`: постачальник застосовує специфічні для постачальника глобальні значення за замовчуванням
|
||||
під час матеріалізації конфігурації на основі режиму автентифікації, env або сімейства моделей
|
||||
- `isModernModelRef`: постачальник керує зіставленням пріоритетних моделей для live/smoke
|
||||
- `prepareRuntimeAuth`: постачальник перетворює налаштовані облікові дані на короткочасний
|
||||
runtime-токен
|
||||
- `resolveUsageAuth`: постачальник визначає облікові дані usage/quota для `/usage`
|
||||
і пов’язаних поверхонь status/reporting
|
||||
- `fetchUsageSnapshot`: постачальник керує отриманням/парсингом endpoint usage, тоді як
|
||||
core усе ще керує оболонкою зведення та форматуванням
|
||||
- `onModelSelected`: постачальник виконує побічні ефекти після вибору моделі, наприклад
|
||||
телеметрію або ведення сесії, що належить постачальнику
|
||||
- `applyConfigDefaults`: постачальник застосовує глобальні значення за замовчуванням, специфічні для постачальника,
|
||||
під час матеріалізації конфігурації залежно від режиму автентифікації, середовища чи сімейства моделей
|
||||
- `isModernModelRef`: постачальник володіє зіставленням бажаних моделей для live/smoke
|
||||
- `prepareRuntimeAuth`: постачальник перетворює налаштовані облікові дані на короткоживучий
|
||||
токен для виконання
|
||||
- `resolveUsageAuth`: постачальник визначає облікові дані використання/квоти для `/usage`
|
||||
та пов'язаних поверхонь статусу/звітності
|
||||
- `fetchUsageSnapshot`: постачальник володіє отриманням/розбором кінцевої точки використання, тоді як
|
||||
ядро все ще володіє оболонкою підсумку та форматуванням
|
||||
- `onModelSelected`: постачальник виконує побічні ефекти після вибору моделі, як-от
|
||||
телеметрію або облік сесії, що належить постачальнику
|
||||
|
||||
Поточні вбудовані приклади:
|
||||
|
||||
- `anthropic`: резервна сумісність уперед для Claude 4.6, підказки щодо ремонту автентифікації, отримання
|
||||
endpoint usage, метадані cache-TTL/provider-family та глобальні
|
||||
значення конфігурації за замовчуванням, що враховують автентифікацію
|
||||
- `amazon-bedrock`: визначення переповнення контексту й класифікація
|
||||
причин failover для специфічних помилок Bedrock про throttle/not-ready, а також
|
||||
спільне сімейство повторного програвання `anthropic-by-model` для захистів політики replay лише для Claude
|
||||
- `anthropic`: резервна сумісність уперед для Claude 4.6, підказки з відновлення автентифікації, отримання даних
|
||||
з кінцевої точки використання, метадані TTL кешу/сімейства постачальника та глобальні
|
||||
значення конфігурації за замовчуванням з урахуванням автентифікації
|
||||
- `amazon-bedrock`: специфічне для постачальника зіставлення переповнення контексту та
|
||||
класифікація причин резервного перемикання для помилок Bedrock throttle/not-ready, а також
|
||||
спільне сімейство відтворення `anthropic-by-model` для захистів політики повтору лише Claude
|
||||
на трафіку Anthropic
|
||||
- `anthropic-vertex`: захисти політики replay лише для Claude на Anthropic-message
|
||||
- `anthropic-vertex`: захисти політики повтору лише Claude на Anthropic-message
|
||||
трафіку
|
||||
- `openrouter`: наскрізні ідентифікатори моделей, обгортки запитів, підказки щодо
|
||||
можливостей постачальника, очищення thought-signature Gemini на проксійованому Gemini-трафіку,
|
||||
впровадження reasoning для proxy через сімейство stream `openrouter-thinking`,
|
||||
передавання метаданих маршрутизації та політика cache-TTL
|
||||
- `github-copilot`: онбординг/вхід із пристрою, резервна сумісність моделей уперед,
|
||||
підказки щодо transcript для Claude-thinking, обмін runtime-токенів і отримання endpoint
|
||||
usage
|
||||
- `openai`: резервна сумісність уперед для GPT-5.4, пряма нормалізація transport OpenAI,
|
||||
- `openrouter`: наскрізні ідентифікатори моделей, обгортки запитів, підказки щодо можливостей постачальника,
|
||||
санітизація підпису thought у Gemini-трафіку через проксі, ін'єкція reasoning через проксі
|
||||
через сімейство потоків `openrouter-thinking`, пересилання метаданих маршрутизації
|
||||
та політика TTL кешу
|
||||
- `github-copilot`: онбординг/вхід через пристрій, резервна сумісність уперед моделей,
|
||||
підказки транскрипту Claude-thinking, обмін токенів під час виконання та отримання даних
|
||||
з кінцевої точки використання
|
||||
- `openai`: резервна сумісність уперед для GPT-5.4, пряма нормалізація транспорту OpenAI,
|
||||
підказки про відсутню автентифікацію з урахуванням Codex, приглушення Spark, синтетичні
|
||||
рядки каталогу OpenAI/Codex, політика thinking/live-model, нормалізація псевдонімів usage-token
|
||||
(`input` / `output` і сімейства `prompt` / `completion`), спільне сімейство stream `openai-responses-defaults` для нативних
|
||||
обгорток OpenAI/Codex, метадані сімейства постачальника, реєстрація
|
||||
вбудованого постачальника генерації зображень для `gpt-image-1` і вбудованого постачальника
|
||||
генерації відео для `sora-2`
|
||||
- `google`: резервна сумісність уперед для Gemini 3.1, нативна перевірка replay Gemini,
|
||||
очищення bootstrap replay, режим тегованого reasoning-output,
|
||||
зіставлення modern-model, реєстрація вбудованого постачальника генерації зображень для
|
||||
Gemini image-preview models і вбудованого постачальника генерації відео
|
||||
для моделей Veo
|
||||
- `moonshot`: спільний transport, нормалізація payload thinking, якою володіє плагін
|
||||
- `kilocode`: спільний transport, заголовки запитів, якими володіє плагін, нормалізація payload reasoning,
|
||||
очищення thought-signature для proxy-Gemini та політика cache-TTL
|
||||
- `zai`: резервна сумісність уперед для GLM-5, значення `tool_stream` за замовчуванням, cache-TTL
|
||||
policy, binary-thinking/live-model policy, а також usage auth + отримання квот;
|
||||
невідомі ідентифікатори `glm-5*` синтезуються на основі вбудованого шаблону `glm-4.7`
|
||||
- `xai`: нативна нормалізація transport Responses, переписування псевдонімів `/fast` для
|
||||
рядки каталогу OpenAI/Codex, політика thinking/live-моделей, нормалізація псевдонімів токенів використання
|
||||
(`input` / `output` і сімейства `prompt` / `completion`), спільне сімейство потоків
|
||||
`openai-responses-defaults` для нативних обгорток OpenAI/Codex,
|
||||
метадані сімейства постачальника, реєстрація вбудованого постачальника генерації зображень
|
||||
для `gpt-image-1` і реєстрація вбудованого постачальника генерації відео
|
||||
для `sora-2`
|
||||
- `google` і `google-gemini-cli`: резервна сумісність уперед для Gemini 3.1,
|
||||
нативна валідація повтору Gemini, санітизація bootstrap-повтору, тегований
|
||||
режим виводу reasoning, зіставлення сучасних моделей, реєстрація вбудованого постачальника
|
||||
генерації зображень для preview-моделей Gemini image та вбудована
|
||||
реєстрація постачальника генерації відео для моделей Veo; Gemini CLI OAuth також
|
||||
володіє форматуванням токенів профілю автентифікації, розбором токенів використання та
|
||||
отриманням кінцевої точки квоти для поверхонь використання
|
||||
- `moonshot`: спільний транспорт, нормалізація payload thinking, що належить плагіну
|
||||
- `kilocode`: спільний транспорт, заголовки запитів, що належать плагіну, payload reasoning
|
||||
нормалізація, санітизація підпису thought у проксі-Gemini та політика TTL кешу
|
||||
- `zai`: резервна сумісність уперед для GLM-5, типові значення `tool_stream`, політика TTL кешу,
|
||||
політика двійкового thinking/live-моделей і автентифікація використання + отримання квоти;
|
||||
невідомі ідентифікатори `glm-5*` синтезуються з вбудованого шаблону `glm-4.7`
|
||||
- `xai`: нативна нормалізація транспорту Responses, переписування псевдонімів `/fast` для
|
||||
швидких варіантів Grok, типове `tool_stream`, очищення схем інструментів /
|
||||
payload reasoning, специфічне для xAI, і реєстрація вбудованого постачальника генерації відео
|
||||
payload reasoning, специфічне для xAI, і вбудована реєстрація постачальника генерації відео
|
||||
для `grok-imagine-video`
|
||||
- `mistral`: метадані можливостей, якими володіє плагін
|
||||
- `opencode` і `opencode-go`: метадані можливостей, якими володіє плагін, плюс
|
||||
очищення thought-signature для proxy-Gemini
|
||||
- `alibaba`: каталог генерації відео, яким володіє плагін, для прямих посилань на моделі Wan
|
||||
таких як `alibaba/wan2.6-t2v`
|
||||
- `byteplus`: каталоги, якими володіє плагін, плюс реєстрація вбудованого постачальника генерації відео
|
||||
- `mistral`: метадані можливостей, що належать плагіну
|
||||
- `opencode` і `opencode-go`: метадані можливостей, що належать плагіну, плюс
|
||||
санітизація підпису thought у проксі-Gemini
|
||||
- `alibaba`: каталог генерації відео, що належить плагіну, для прямих посилань на моделі Wan
|
||||
як-от `alibaba/wan2.6-t2v`
|
||||
- `byteplus`: каталоги, що належать плагіну, плюс вбудована реєстрація постачальника генерації відео
|
||||
для моделей Seedance text-to-video/image-to-video
|
||||
- `fal`: реєстрація вбудованого постачальника генерації відео для розміщених сторонніх
|
||||
моделей, реєстрація постачальника генерації зображень для моделей FLUX плюс вбудована
|
||||
реєстрація постачальника генерації відео для розміщених сторонніх відеомоделей
|
||||
- `fal`: вбудована реєстрація постачальника генерації відео для хостованих сторонніх
|
||||
моделей, реєстрація постачальника генерації зображень для моделей зображень FLUX, а також вбудована
|
||||
реєстрація постачальника генерації відео для хостованих сторонніх відеомоделей
|
||||
- `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`,
|
||||
`stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` і `volcengine`:
|
||||
лише каталоги, якими володіє плагін
|
||||
- `qwen`: каталоги текстових моделей, якими володіє плагін, плюс спільні
|
||||
лише каталоги, що належать плагіну
|
||||
- `qwen`: каталоги, що належать плагіну, для текстових моделей плюс спільні
|
||||
реєстрації постачальників media-understanding і генерації відео для його
|
||||
мультимодальних поверхонь; генерація відео Qwen використовує стандартні відеоendpoint-и DashScope з вбудованими моделями Wan, такими як `wan2.6-t2v` і `wan2.7-r2v`
|
||||
- `runway`: реєстрація постачальника генерації відео, якою володіє плагін, для нативних
|
||||
моделей Runway на основі завдань, таких як `gen4.5`
|
||||
- `minimax`: каталоги, якими володіє плагін, вбудована реєстрація постачальника генерації відео
|
||||
для моделей Hailuo video, вбудована реєстрація постачальника генерації зображень
|
||||
для `image-01`, гібридний вибір політики replay Anthropic/OpenAI,
|
||||
а також логіка usage auth/snapshot
|
||||
- `together`: каталоги, якими володіє плагін, плюс реєстрація вбудованого постачальника генерації відео
|
||||
для моделей Wan video
|
||||
- `xiaomi`: каталоги, якими володіє плагін, плюс логіка usage auth/snapshot
|
||||
мультимодальних поверхонь; генерація відео Qwen використовує стандартні відео-
|
||||
кінцеві точки DashScope з вбудованими моделями Wan, такими як `wan2.6-t2v` і `wan2.7-r2v`
|
||||
- `runway`: реєстрація постачальника генерації відео, що належить плагіну, для нативних
|
||||
моделей Runway на основі завдань, як-от `gen4.5`
|
||||
- `minimax`: каталоги, що належать плагіну, вбудована реєстрація постачальника генерації відео
|
||||
для відеомоделей Hailuo, вбудована реєстрація постачальника генерації зображень
|
||||
для `image-01`, гібридний вибір політики повтору Anthropic/OpenAI та логіка
|
||||
автентифікації/знімка використання
|
||||
- `together`: каталоги, що належать плагіну, плюс вбудована реєстрація постачальника генерації відео
|
||||
для відеомоделей Wan
|
||||
- `xiaomi`: каталоги, що належать плагіну, плюс логіка
|
||||
автентифікації/знімка використання
|
||||
|
||||
Вбудований плагін `openai` тепер володіє обома ідентифікаторами постачальника: `openai` і
|
||||
`openai-codex`.
|
||||
|
||||
Це охоплює постачальників, які все ще вписуються в звичайні transports OpenClaw. Постачальник,
|
||||
якому потрібен повністю користувацький виконавець запитів, — це окрема, глибша
|
||||
поверхня розширення.
|
||||
Це охоплює постачальників, які ще вписуються в звичайні транспорти OpenClaw. Постачальник,
|
||||
якому потрібен повністю кастомний виконавець запитів, — це окрема, глибша поверхня
|
||||
розширення.
|
||||
|
||||
## Ротація API-ключів
|
||||
|
||||
@ -227,37 +234,37 @@ x-i18n:
|
||||
- `<PROVIDER>_API_KEY_*` (нумерований список, наприклад `<PROVIDER>_API_KEY_1`)
|
||||
- Для постачальників Google `GOOGLE_API_KEY` також включається як резервний варіант.
|
||||
- Порядок вибору ключів зберігає пріоритет і прибирає дублікати значень.
|
||||
- Запити повторюються з наступним ключем лише у відповідь на обмеження швидкості (наприклад
|
||||
- Запити повторюються з наступним ключем лише у відповідь на відповіді з обмеженням швидкості (наприклад,
|
||||
`429`, `rate_limit`, `quota`, `resource exhausted`, `Too many
|
||||
concurrent requests`, `ThrottlingException`, `concurrency limit reached`,
|
||||
`workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання).
|
||||
- Збої, не пов’язані з обмеженням швидкості, завершуються помилкою одразу; ротація ключів не виконується.
|
||||
- Коли всі кандидати-ключі не спрацьовують, повертається фінальна помилка з останньої спроби.
|
||||
- Збої, не пов'язані з лімітом запитів, завершуються негайно; ротація ключів не виконується.
|
||||
- Коли всі можливі ключі не спрацьовують, повертається фінальна помилка з останньої спроби.
|
||||
|
||||
## Вбудовані постачальники (каталог pi-ai)
|
||||
|
||||
OpenClaw постачається з каталогом pi‑ai. Ці постачальники **не**
|
||||
потребують конфігурації `models.providers`; просто налаштуйте автентифікацію й оберіть модель.
|
||||
OpenClaw постачається з каталогом pi‑ai. Для цих постачальників **не потрібна**
|
||||
конфігурація `models.providers`; достатньо налаштувати автентифікацію й вибрати модель.
|
||||
|
||||
### OpenAI
|
||||
|
||||
- Постачальник: `openai`
|
||||
- Автентифікація: `OPENAI_API_KEY`
|
||||
- Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, плюс `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення)
|
||||
- Необов'язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення)
|
||||
- Приклади моделей: `openai/gpt-5.4`, `openai/gpt-5.4-pro`
|
||||
- CLI: `openclaw onboard --auth-choice openai-api-key`
|
||||
- Transport за замовчуванням — `auto` (спочатку WebSocket, потім резервно SSE)
|
||||
- Типовий транспорт — `auto` (спочатку WebSocket, резервно SSE)
|
||||
- Перевизначення для окремої моделі через `agents.defaults.models["openai/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- Прогрівання OpenAI Responses WebSocket типово ввімкнене через `params.openaiWsWarmup` (`true`/`false`)
|
||||
- Розігрів WebSocket для OpenAI Responses типово ввімкнений через `params.openaiWsWarmup` (`true`/`false`)
|
||||
- Пріоритетну обробку OpenAI можна ввімкнути через `agents.defaults.models["openai/<model>"].params.serviceTier`
|
||||
- `/fast` і `params.fastMode` зіставляють прямі запити `openai/*` Responses із `service_tier=priority` на `api.openai.com`
|
||||
- Використовуйте `params.serviceTier`, якщо вам потрібен явний tier замість спільного перемикача `/fast`
|
||||
- Використовуйте `params.serviceTier`, якщо вам потрібен явний рівень замість спільного перемикача `/fast`
|
||||
- Приховані заголовки атрибуції OpenClaw (`originator`, `version`,
|
||||
`User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не до
|
||||
загальних OpenAI-сумісних proxy
|
||||
- Нативні маршрути OpenAI також зберігають `store` Responses, підказки кешу prompt і
|
||||
формування payload сумісності reasoning OpenAI; proxy-маршрути — ні
|
||||
- `openai/gpt-5.3-codex-spark` навмисно приглушено в OpenClaw, оскільки live API OpenAI його відхиляє; Spark розглядається лише як Codex
|
||||
`User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не
|
||||
до загальних проксі, сумісних з OpenAI
|
||||
- Нативні маршрути OpenAI також зберігають `store` для Responses, підказки кешу промптів і
|
||||
формування payload сумісності reasoning OpenAI; проксі-маршрути — ні
|
||||
- `openai/gpt-5.3-codex-spark` навмисно приглушено в OpenClaw, оскільки live API OpenAI його відхиляє; Spark вважається лише Codex
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -269,12 +276,12 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста
|
||||
|
||||
- Постачальник: `anthropic`
|
||||
- Автентифікація: `ANTHROPIC_API_KEY`
|
||||
- Необов’язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, плюс `OPENCLAW_LIVE_ANTHROPIC_KEY` (одне перевизначення)
|
||||
- Необов'язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (одне перевизначення)
|
||||
- Приклад моделі: `anthropic/claude-opus-4-6`
|
||||
- CLI: `openclaw onboard --auth-choice apiKey`
|
||||
- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком, автентифікованим через API-ключ і OAuth, який надсилається на `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` або `standard_only`)
|
||||
- Примітка щодо білінгу: для Anthropic в OpenClaw практичний поділ — це **API key** або **Claude subscription with Extra Usage**. Anthropic повідомив користувачам OpenClaw **4 квітня 2026 року о 12:00 PT / 8:00 PM BST**, що шлях входу Claude через **OpenClaw** вважається використанням через сторонній harness і потребує **Extra Usage**, що тарифікується окремо від підписки. Наші локальні відтворення також показують, що рядок prompt, який ідентифікує OpenClaw, не відтворюється на шляху Anthropic SDK + API key.
|
||||
- Setup-токен Anthropic знову доступний як застарілий/ручний шлях OpenClaw. Використовуйте його з урахуванням того, що Anthropic повідомив користувачам OpenClaw, що цей шлях потребує **Extra Usage**.
|
||||
- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, зокрема трафік, автентифікований через API-ключ і OAuth, надісланий до `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`)
|
||||
- Примітка щодо білінгу: для Anthropic в OpenClaw практичний поділ — це **API-ключ** або **підписка Claude з Extra Usage**. Anthropic повідомила користувачів OpenClaw **4 квітня 2026 року о 12:00 PT / 8:00 PM BST**, що шлях входу Claude у **OpenClaw** вважається використанням через сторонній harness і потребує **Extra Usage**, що оплачується окремо від підписки. Наші локальні відтворення також показують, що рядок промпту, який ідентифікує OpenClaw, не відтворюється на шляху Anthropic SDK + API-ключ.
|
||||
- Токен налаштування Anthropic знову доступний як застарілий/ручний шлях OpenClaw. Використовуйте його з розумінням, що Anthropic повідомила користувачів OpenClaw, що цей шлях потребує **Extra Usage**.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -288,16 +295,16 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста
|
||||
- Автентифікація: OAuth (ChatGPT)
|
||||
- Приклад моделі: `openai-codex/gpt-5.4`
|
||||
- CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex`
|
||||
- Transport за замовчуванням — `auto` (спочатку WebSocket, потім резервно SSE)
|
||||
- Типовий транспорт — `auto` (спочатку WebSocket, резервно SSE)
|
||||
- Перевизначення для окремої моделі через `agents.defaults.models["openai-codex/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- `params.serviceTier` також пересилається в нативних запитах Codex Responses (`chatgpt.com/backend-api`)
|
||||
- Приховані заголовки атрибуції OpenClaw (`originator`, `version`,
|
||||
`User-Agent`) додаються лише до нативного трафіку Codex на
|
||||
`chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних proxy
|
||||
- Використовує той самий перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority`
|
||||
- `openai-codex/gpt-5.3-codex-spark` залишається доступною, коли її надає каталог Codex OAuth; залежить від entitlement
|
||||
- `openai-codex/gpt-5.4` зберігає нативні `contextWindow = 1050000` і типове runtime-значення `contextTokens = 272000`; перевизначте runtime-ліміт через `models.providers.openai-codex.models[].contextTokens`
|
||||
- Примітка щодо політики: OAuth OpenAI Codex явно підтримується для зовнішніх інструментів/потоків роботи, таких як OpenClaw.
|
||||
`chatgpt.com/backend-api`, а не до загальних проксі, сумісних з OpenAI
|
||||
- Має спільний перемикач `/fast` і конфігурацію `params.fastMode`, як і прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority`
|
||||
- `openai-codex/gpt-5.3-codex-spark` залишається доступною, коли каталог OAuth Codex її показує; залежить від прав доступу
|
||||
- `openai-codex/gpt-5.4` зберігає нативне `contextWindow = 1050000` і типове обмеження під час виконання `contextTokens = 272000`; перевизначте це обмеження через `models.providers.openai-codex.models[].contextTokens`
|
||||
- Примітка щодо політики: OAuth OpenAI Codex явно підтримується для зовнішніх інструментів/робочих процесів, як-от OpenClaw.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -317,17 +324,17 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста
|
||||
}
|
||||
```
|
||||
|
||||
### Інші розміщені варіанти у стилі підписки
|
||||
### Інші хостовані варіанти у стилі підписки
|
||||
|
||||
- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud плюс зіставлення endpoint Alibaba DashScope і Coding Plan
|
||||
- [MiniMax](/uk/providers/minimax): OAuth або доступ за API key для MiniMax Coding Plan
|
||||
- [GLM Models](/uk/providers/glm): Z.AI Coding Plan або загальні API endpoint-и
|
||||
- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud плюс зіставлення кінцевих точок Alibaba DashScope і Coding Plan
|
||||
- [MiniMax](/uk/providers/minimax): доступ через OAuth або API-ключ MiniMax Coding Plan
|
||||
- [GLM Models](/uk/providers/glm): Z.AI Coding Plan або загальні кінцеві точки API
|
||||
|
||||
### OpenCode
|
||||
|
||||
- Автентифікація: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`)
|
||||
- Постачальник Zen runtime: `opencode`
|
||||
- Постачальник Go runtime: `opencode-go`
|
||||
- Постачальник виконання Zen: `opencode`
|
||||
- Постачальник виконання Go: `opencode-go`
|
||||
- Приклади моделей: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5`
|
||||
- CLI: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`
|
||||
|
||||
@ -337,24 +344,35 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста
|
||||
}
|
||||
```
|
||||
|
||||
### Google Gemini (API key)
|
||||
### Google Gemini (API-ключ)
|
||||
|
||||
- Постачальник: `google`
|
||||
- Автентифікація: `GEMINI_API_KEY`
|
||||
- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний варіант `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення)
|
||||
- Необов'язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення)
|
||||
- Приклади моделей: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview`
|
||||
- Сумісність: застаріла конфігурація OpenClaw з `google/gemini-3.1-flash-preview` нормалізується до `google/gemini-3-flash-preview`
|
||||
- CLI: `openclaw onboard --auth-choice gemini-api-key`
|
||||
- Прямі запуски Gemini також приймають `agents.defaults.models["google/<model>"].params.cachedContent`
|
||||
(або застаріле `cached_content`) для пересилання нативного для постачальника
|
||||
дескриптора `cachedContents/...`; збіги кешу Gemini відображаються як OpenClaw `cacheRead`
|
||||
(або застарілий `cached_content`) для пересилання нативного для постачальника
|
||||
дескриптора `cachedContents/...`; попадання в кеш Gemini відображаються як OpenClaw `cacheRead`
|
||||
|
||||
### Google Vertex
|
||||
### Google Vertex і Gemini CLI
|
||||
|
||||
- Постачальник: `google-vertex`
|
||||
- Автентифікація: gcloud ADC
|
||||
- JSON-відповіді Gemini CLI парсяться з `response`; usage резервно береться з
|
||||
`stats`, а `stats.cached` нормалізується в OpenClaw `cacheRead`.
|
||||
- Постачальники: `google-vertex`, `google-gemini-cli`
|
||||
- Автентифікація: Vertex використовує gcloud ADC; Gemini CLI — власний потік OAuth
|
||||
- Застереження: OAuth Gemini CLI в OpenClaw — це неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і, якщо вирішите продовжити, використовуйте некритичний обліковий запис.
|
||||
- Gemini CLI OAuth постачається як частина вбудованого плагіна `google`.
|
||||
- Спочатку встановіть Gemini CLI:
|
||||
- `brew install gemini-cli`
|
||||
- або `npm install -g @google/gemini-cli`
|
||||
- Увімкнення: `openclaw plugins enable google`
|
||||
- Вхід: `openclaw models auth login --provider google-gemini-cli --set-default`
|
||||
- Типова модель: `google-gemini-cli/gemini-3.1-pro-preview`
|
||||
- Примітка: вам **не потрібно** вставляти client id або secret в `openclaw.json`. Потік входу CLI зберігає
|
||||
токени в профілях автентифікації на gateway host.
|
||||
- Якщо після входу запити не працюють, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на gateway host.
|
||||
- JSON-відповіді Gemini CLI розбираються з `response`; використання резервно береться з
|
||||
`stats`, при цьому `stats.cached` нормалізується в OpenClaw `cacheRead`.
|
||||
|
||||
### Z.AI (GLM)
|
||||
|
||||
@ -363,7 +381,7 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста
|
||||
- Приклад моделі: `zai/glm-5`
|
||||
- CLI: `openclaw onboard --auth-choice zai-api-key`
|
||||
- Псевдоніми: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*`
|
||||
- `zai-api-key` автоматично визначає відповідний endpoint Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово вибирають конкретну поверхню
|
||||
- `zai-api-key` автоматично визначає відповідну кінцеву точку Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово використовують конкретну поверхню
|
||||
|
||||
### Vercel AI Gateway
|
||||
|
||||
@ -378,9 +396,10 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста
|
||||
- Автентифікація: `KILOCODE_API_KEY`
|
||||
- Приклад моделі: `kilocode/kilo/auto`
|
||||
- CLI: `openclaw onboard --auth-choice kilocode-api-key`
|
||||
- Base URL: `https://api.kilo.ai/api/gateway/`
|
||||
- Базова URL-адреса: `https://api.kilo.ai/api/gateway/`
|
||||
- Статичний резервний каталог постачається з `kilocode/kilo/auto`; live-виявлення
|
||||
`https://api.kilo.ai/api/gateway/models` може додатково розширювати runtime-каталог.
|
||||
`https://api.kilo.ai/api/gateway/models` може додатково розширити каталог
|
||||
під час виконання.
|
||||
- Точна upstream-маршрутизація за `kilocode/kilo/auto` належить Kilo Gateway,
|
||||
а не жорстко закодована в OpenClaw.
|
||||
|
||||
@ -390,26 +409,26 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста
|
||||
|
||||
- OpenRouter: `openrouter` (`OPENROUTER_API_KEY`)
|
||||
- Приклад моделі: `openrouter/auto`
|
||||
- OpenClaw застосовує задокументовані OpenRouter заголовки атрибуції застосунку лише тоді, коли
|
||||
запит справді спрямований на `openrouter.ai`
|
||||
- Специфічні для OpenRouter маркери Anthropic `cache_control` так само обмежуються
|
||||
перевіреними маршрутами OpenRouter, а не довільними proxy URL
|
||||
- OpenRouter лишається на шляху proxy-стилю OpenAI-compatible, тому специфічне лише для нативного
|
||||
OpenAI формування запитів (`serviceTier`, Responses `store`,
|
||||
підказки кешу prompt, payload сумісності reasoning OpenAI) не пересилається
|
||||
- Посилання OpenRouter на базі Gemini зберігають лише очищення thought-signature для proxy-Gemini;
|
||||
нативна перевірка replay Gemini та переписування bootstrap залишаються вимкненими
|
||||
- OpenClaw застосовує задокументовані заголовки атрибуції застосунку OpenRouter лише тоді,
|
||||
коли запит дійсно спрямовано на `openrouter.ai`
|
||||
- Специфічні для OpenRouter маркери Anthropic `cache_control` так само обмежені
|
||||
перевіреними маршрутами OpenRouter, а не довільними URL-адресами проксі
|
||||
- OpenRouter залишається на проксі-шляху у стилі OpenAI-compatible, тому нативне
|
||||
формування запитів лише для OpenAI (`serviceTier`, `store` для Responses,
|
||||
підказки кешу промптів, payload сумісності reasoning OpenAI) не пересилається
|
||||
- Посилання OpenRouter на базі Gemini зберігають лише санітизацію підпису thought у проксі-Gemini;
|
||||
нативна валідація повтору Gemini та переписування bootstrap залишаються вимкненими
|
||||
- Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`)
|
||||
- Приклад моделі: `kilocode/kilo/auto`
|
||||
- Посилання Kilo на базі Gemini зберігають той самий шлях очищення thought-signature
|
||||
для proxy-Gemini; `kilocode/kilo/auto` та інші підказки, які не підтримують proxy-reasoning,
|
||||
пропускають упровадження reasoning для proxy
|
||||
- MiniMax: `minimax` (API key) і `minimax-portal` (OAuth)
|
||||
- Посилання Kilo на базі Gemini зберігають той самий шлях санітизації підпису thought
|
||||
у проксі-Gemini; `kilocode/kilo/auto` та інші підказки, що не підтримують reasoning через проксі,
|
||||
пропускають ін'єкцію reasoning через проксі
|
||||
- MiniMax: `minimax` (API-ключ) і `minimax-portal` (OAuth)
|
||||
- Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal`
|
||||
- Приклад моделі: `minimax/MiniMax-M2.7` або `minimax-portal/MiniMax-M2.7`
|
||||
- Налаштування MiniMax через онбординг/API key записує явні визначення моделей M2.7 з
|
||||
`input: ["text", "image"]`; вбудований каталог постачальника зберігає chat-посилання
|
||||
лише для тексту, доки конфігурація цього постачальника не буде матеріалізована
|
||||
- Налаштування MiniMax під час онбордингу/API-ключа записує явні визначення моделей M2.7 з
|
||||
`input: ["text", "image"]`; вбудований каталог постачальника тримає chat-посилання
|
||||
лише текстовими, доки не буде матеріалізовано конфігурацію цього постачальника
|
||||
- Moonshot: `moonshot` (`MOONSHOT_API_KEY`)
|
||||
- Приклад моделі: `moonshot/kimi-k2.5`
|
||||
- Kimi Coding: `kimi` (`KIMI_API_KEY` або `KIMICODE_API_KEY`)
|
||||
@ -421,7 +440,7 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста
|
||||
- NVIDIA: `nvidia` (`NVIDIA_API_KEY`)
|
||||
- Приклад моделі: `nvidia/nvidia/llama-3.1-nemotron-70b-instruct`
|
||||
- StepFun: `stepfun` / `stepfun-plan` (`STEPFUN_API_KEY`)
|
||||
- Приклади моделей: `stepfun/step-3.5-flash`, `stepfun-plan/step-3.5-flash-2603`
|
||||
- Приклад моделі: `stepfun/step-3.5-flash`, `stepfun-plan/step-3.5-flash-2603`
|
||||
- Together: `together` (`TOGETHER_API_KEY`)
|
||||
- Приклад моделі: `together/moonshotai/Kimi-K2.5`
|
||||
- Venice: `venice` (`VENICE_API_KEY`)
|
||||
@ -438,33 +457,33 @@ OpenClaw постачається з каталогом pi‑ai. Ці поста
|
||||
- Нативні вбудовані запити xAI використовують шлях xAI Responses
|
||||
- `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`,
|
||||
`grok-4` і `grok-4-0709` на їхні варіанти `*-fast`
|
||||
- `tool_stream` типово ввімкнений; установіть
|
||||
`agents.defaults.models["xai/<model>"].params.tool_stream` у `false`, щоб
|
||||
- `tool_stream` типово ввімкнено; задайте
|
||||
`agents.defaults.models["xai/<model>"].params.tool_stream` як `false`, щоб
|
||||
вимкнути його
|
||||
- Mistral: `mistral` (`MISTRAL_API_KEY`)
|
||||
- Приклад моделі: `mistral/mistral-large-latest`
|
||||
- CLI: `openclaw onboard --auth-choice mistral-api-key`
|
||||
- Groq: `groq` (`GROQ_API_KEY`)
|
||||
- Cerebras: `cerebras` (`CEREBRAS_API_KEY`)
|
||||
- Моделі GLM у Cerebras використовують ідентифікатори `zai-glm-4.7` і `zai-glm-4.6`.
|
||||
- Base URL, сумісний з OpenAI: `https://api.cerebras.ai/v1`.
|
||||
- Моделі GLM на Cerebras використовують ідентифікатори `zai-glm-4.7` і `zai-glm-4.6`.
|
||||
- Базова URL-адреса, сумісна з OpenAI: `https://api.cerebras.ai/v1`.
|
||||
- GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`)
|
||||
- Приклад моделі Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Див. [Hugging Face (Inference)](/uk/providers/huggingface).
|
||||
|
||||
## Постачальники через `models.providers` (custom/base URL)
|
||||
## Постачальники через `models.providers` (кастомна/base URL)
|
||||
|
||||
Використовуйте `models.providers` (або `models.json`), щоб додати **custom** постачальників або
|
||||
OpenAI/Anthropic‑сумісні proxy.
|
||||
Використовуйте `models.providers` (або `models.json`), щоб додати **кастомних** постачальників або
|
||||
проксі, сумісні з OpenAI/Anthropic.
|
||||
|
||||
Багато з наведених нижче вбудованих плагінів постачальників уже публікують типовий каталог.
|
||||
Використовуйте явні записи `models.providers.<id>` лише тоді, коли хочете перевизначити
|
||||
типовий base URL, заголовки або список моделей.
|
||||
типову базову URL-адресу, заголовки або список моделей.
|
||||
|
||||
### Moonshot AI (Kimi)
|
||||
|
||||
Moonshot постачається як вбудований плагін постачальника. Використовуйте вбудованого постачальника
|
||||
типово, а явний запис `models.providers.moonshot` додавайте лише тоді, коли
|
||||
потрібно перевизначити base URL або метадані моделі:
|
||||
типово й додавайте явний запис `models.providers.moonshot` лише тоді, коли
|
||||
потрібно перевизначити базову URL-адресу або метадані моделі:
|
||||
|
||||
- Постачальник: `moonshot`
|
||||
- Автентифікація: `MOONSHOT_API_KEY`
|
||||
@ -503,7 +522,7 @@ Moonshot постачається як вбудований плагін пос
|
||||
|
||||
### Kimi Coding
|
||||
|
||||
Kimi Coding використовує Anthropic-compatible endpoint Moonshot AI:
|
||||
Kimi Coding використовує Anthropic-сумісну кінцеву точку Moonshot AI:
|
||||
|
||||
- Постачальник: `kimi`
|
||||
- Автентифікація: `KIMI_API_KEY`
|
||||
@ -518,7 +537,7 @@ Kimi Coding використовує Anthropic-compatible endpoint Moonshot AI:
|
||||
}
|
||||
```
|
||||
|
||||
Застарілий `kimi/k2p5` усе ще приймається як ідентифікатор моделі для сумісності.
|
||||
Застарілий `kimi/k2p5` і далі приймається як сумісний ідентифікатор моделі.
|
||||
|
||||
### Volcano Engine (Doubao)
|
||||
|
||||
@ -537,13 +556,13 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши
|
||||
}
|
||||
```
|
||||
|
||||
Під час онбордингу типово використовується coding-поверхня, але загальний каталог `volcengine/*`
|
||||
реєструється одночасно.
|
||||
Під час онбордингу типово використовується поверхня coding, але загальний каталог `volcengine/*`
|
||||
реєструється водночас.
|
||||
|
||||
У вибірниках моделей онбордингу/налаштування Volcengine варіант автентифікації
|
||||
віддає перевагу рядкам `volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажено,
|
||||
OpenClaw повертається до нефільтрованого каталогу замість того, щоб показувати порожній
|
||||
вибірник, прив’язаний до постачальника.
|
||||
У вибірниках онбордингу/налаштування моделі варіант автентифікації Volcengine надає перевагу і рядкам
|
||||
`volcengine/*`, і `volcengine-plan/*`. Якщо ці моделі ще не завантажені,
|
||||
OpenClaw резервно повертається до нефільтрованого каталогу, а не показує порожній
|
||||
вибірник у межах постачальника.
|
||||
|
||||
Доступні моделі:
|
||||
|
||||
@ -553,7 +572,7 @@ OpenClaw повертається до нефільтрованого катал
|
||||
- `volcengine/glm-4-7-251222` (GLM 4.7)
|
||||
- `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K)
|
||||
|
||||
Coding-моделі (`volcengine-plan`):
|
||||
Моделі coding (`volcengine-plan`):
|
||||
|
||||
- `volcengine-plan/ark-code-latest`
|
||||
- `volcengine-plan/doubao-seed-code`
|
||||
@ -563,7 +582,7 @@ Coding-моделі (`volcengine-plan`):
|
||||
|
||||
### BytePlus (International)
|
||||
|
||||
BytePlus ARK надає доступ до тих самих моделей, що й Volcano Engine, для міжнародних користувачів.
|
||||
BytePlus ARK надає міжнародним користувачам доступ до тих самих моделей, що й Volcano Engine.
|
||||
|
||||
- Постачальник: `byteplus` (coding: `byteplus-plan`)
|
||||
- Автентифікація: `BYTEPLUS_API_KEY`
|
||||
@ -578,13 +597,13 @@ BytePlus ARK надає доступ до тих самих моделей, що
|
||||
}
|
||||
```
|
||||
|
||||
Під час онбордингу типово використовується coding-поверхня, але загальний каталог `byteplus/*`
|
||||
реєструється одночасно.
|
||||
Під час онбордингу типово використовується поверхня coding, але загальний каталог `byteplus/*`
|
||||
реєструється водночас.
|
||||
|
||||
У вибірниках моделей онбордингу/налаштування варіант автентифікації BytePlus віддає перевагу як
|
||||
рядкам `byteplus/*`, так і `byteplus-plan/*`. Якщо ці моделі ще не завантажено,
|
||||
OpenClaw повертається до нефільтрованого каталогу замість того, щоб показувати порожній
|
||||
вибірник, прив’язаний до постачальника.
|
||||
У вибірниках онбордингу/налаштування моделі варіант автентифікації BytePlus надає перевагу і рядкам
|
||||
`byteplus/*`, і `byteplus-plan/*`. Якщо ці моделі ще не завантажені,
|
||||
OpenClaw резервно повертається до нефільтрованого каталогу, а не показує порожній
|
||||
вибірник у межах постачальника.
|
||||
|
||||
Доступні моделі:
|
||||
|
||||
@ -592,7 +611,7 @@ OpenClaw повертається до нефільтрованого катал
|
||||
- `byteplus/kimi-k2-5-260127` (Kimi K2.5)
|
||||
- `byteplus/glm-4-7-251222` (GLM 4.7)
|
||||
|
||||
Coding-моделі (`byteplus-plan`):
|
||||
Моделі coding (`byteplus-plan`):
|
||||
|
||||
- `byteplus-plan/ark-code-latest`
|
||||
- `byteplus-plan/doubao-seed-code`
|
||||
@ -602,7 +621,7 @@ Coding-моделі (`byteplus-plan`):
|
||||
|
||||
### Synthetic
|
||||
|
||||
Synthetic надає Anthropic-compatible моделі через постачальника `synthetic`:
|
||||
Synthetic надає Anthropic-сумісні моделі через постачальника `synthetic`:
|
||||
|
||||
- Постачальник: `synthetic`
|
||||
- Автентифікація: `SYNTHETIC_API_KEY`
|
||||
@ -630,27 +649,27 @@ Synthetic надає Anthropic-compatible моделі через постача
|
||||
|
||||
### MiniMax
|
||||
|
||||
MiniMax налаштовується через `models.providers`, оскільки використовує custom endpoint-и:
|
||||
MiniMax налаштовується через `models.providers`, оскільки використовує кастомні кінцеві точки:
|
||||
|
||||
- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth`
|
||||
- MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth`
|
||||
- MiniMax API key (Global): `--auth-choice minimax-global-api`
|
||||
- MiniMax API key (CN): `--auth-choice minimax-cn-api`
|
||||
- MiniMax API-ключ (Global): `--auth-choice minimax-global-api`
|
||||
- MiniMax API-ключ (CN): `--auth-choice minimax-cn-api`
|
||||
- Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або
|
||||
`MINIMAX_API_KEY` для `minimax-portal`
|
||||
|
||||
Деталі налаштування, варіанти моделей і фрагменти конфігурації див. у [/providers/minimax](/uk/providers/minimax).
|
||||
|
||||
На Anthropic-compatible streaming-шляху MiniMax OpenClaw типово вимикає thinking,
|
||||
якщо ви явно його не вкажете, а `/fast on` переписує
|
||||
На Anthropic-сумісному потоковому шляху MiniMax OpenClaw типово вимикає thinking,
|
||||
якщо ви явно його не задаєте, а `/fast on` переписує
|
||||
`MiniMax-M2.7` на `MiniMax-M2.7-highspeed`.
|
||||
|
||||
Розподіл можливостей, якими володіє плагін:
|
||||
Розподіл можливостей, що належать плагіну:
|
||||
|
||||
- Типові значення для тексту/chat лишаються на `minimax/MiniMax-M2.7`
|
||||
- Типові значення тексту/чату залишаються на `minimax/MiniMax-M2.7`
|
||||
- Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01`
|
||||
- Розуміння зображень — це `MiniMax-VL-01`, яким володіє плагін, на обох шляхах автентифікації MiniMax
|
||||
- Вебпошук лишається на ідентифікаторі постачальника `minimax`
|
||||
- Розуміння зображень — це `MiniMax-VL-01`, що належить плагіну, на обох шляхах автентифікації MiniMax
|
||||
- Вебпошук залишається на ідентифікаторі постачальника `minimax`
|
||||
|
||||
### Ollama
|
||||
|
||||
@ -659,10 +678,10 @@ Ollama постачається як вбудований плагін пост
|
||||
- Постачальник: `ollama`
|
||||
- Автентифікація: не потрібна (локальний сервер)
|
||||
- Приклад моделі: `ollama/llama3.3`
|
||||
- Установлення: [https://ollama.com/download](https://ollama.com/download)
|
||||
- Встановлення: [https://ollama.com/download](https://ollama.com/download)
|
||||
|
||||
```bash
|
||||
# Install Ollama, then pull a model:
|
||||
# Встановіть Ollama, потім завантажте модель:
|
||||
ollama pull llama3.3
|
||||
```
|
||||
|
||||
@ -674,10 +693,10 @@ ollama pull llama3.3
|
||||
}
|
||||
```
|
||||
|
||||
Ollama локально виявляється за адресою `http://127.0.0.1:11434`, коли ви ввімкнули її через
|
||||
Ollama локально виявляється за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте її через
|
||||
`OLLAMA_API_KEY`, а вбудований плагін постачальника додає Ollama безпосередньо до
|
||||
`openclaw onboard` і вибірника моделей. Див. [/providers/ollama](/uk/providers/ollama)
|
||||
для онбордингу, режиму cloud/local і custom-конфігурації.
|
||||
щодо онбордингу, хмарного/локального режиму та кастомної конфігурації.
|
||||
|
||||
### vLLM
|
||||
|
||||
@ -685,16 +704,16 @@ vLLM постачається як вбудований плагін поста
|
||||
серверів, сумісних з OpenAI:
|
||||
|
||||
- Постачальник: `vllm`
|
||||
- Автентифікація: необов’язкова (залежить від вашого сервера)
|
||||
- Base URL за замовчуванням: `http://127.0.0.1:8000/v1`
|
||||
- Автентифікація: необов'язкова (залежить від вашого сервера)
|
||||
- Типова базова URL-адреса: `http://127.0.0.1:8000/v1`
|
||||
|
||||
Щоб увімкнути автоматичне локальне виявлення (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації):
|
||||
Щоб увімкнути локальне автоматичне виявлення (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації):
|
||||
|
||||
```bash
|
||||
export VLLM_API_KEY="vllm-local"
|
||||
```
|
||||
|
||||
Потім задайте модель (замініть на один з ідентифікаторів, повернених `/v1/models`):
|
||||
Потім задайте модель (замініть на один з ідентифікаторів, які повертає `/v1/models`):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -712,17 +731,17 @@ SGLang постачається як вбудований плагін пост
|
||||
серверів, сумісних з OpenAI:
|
||||
|
||||
- Постачальник: `sglang`
|
||||
- Автентифікація: необов’язкова (залежить від вашого сервера)
|
||||
- Base URL за замовчуванням: `http://127.0.0.1:30000/v1`
|
||||
- Автентифікація: необов'язкова (залежить від вашого сервера)
|
||||
- Типова базова URL-адреса: `http://127.0.0.1:30000/v1`
|
||||
|
||||
Щоб увімкнути автоматичне локальне виявлення (підійде будь-яке значення, якщо ваш сервер не
|
||||
Щоб увімкнути локальне автоматичне виявлення (підійде будь-яке значення, якщо ваш сервер не
|
||||
вимагає автентифікації):
|
||||
|
||||
```bash
|
||||
export SGLANG_API_KEY="sglang-local"
|
||||
```
|
||||
|
||||
Потім задайте модель (замініть на один з ідентифікаторів, повернених `/v1/models`):
|
||||
Потім задайте модель (замініть на один з ідентифікаторів, які повертає `/v1/models`):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -734,9 +753,9 @@ export SGLANG_API_KEY="sglang-local"
|
||||
|
||||
Деталі див. у [/providers/sglang](/uk/providers/sglang).
|
||||
|
||||
### Локальні proxy (LM Studio, vLLM, LiteLLM тощо)
|
||||
### Локальні проксі (LM Studio, vLLM, LiteLLM тощо)
|
||||
|
||||
Приклад (сумісний з OpenAI):
|
||||
Приклад (OpenAI-compatible):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -771,21 +790,20 @@ export SGLANG_API_KEY="sglang-local"
|
||||
|
||||
Примітки:
|
||||
|
||||
- Для custom-постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими.
|
||||
Якщо їх пропущено, OpenClaw використовує такі типові значення:
|
||||
- Для кастомних постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов'язковими.
|
||||
Якщо їх не вказано, OpenClaw типово використовує:
|
||||
- `reasoning: false`
|
||||
- `input: ["text"]`
|
||||
- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
|
||||
- `contextWindow: 200000`
|
||||
- `maxTokens: 8192`
|
||||
- Рекомендовано: задавайте явні значення, які відповідають лімітам вашого proxy/моделі.
|
||||
- Для `api: "openai-completions"` на ненативних endpoint-ах (будь-який непорожній `baseUrl`, у якого host не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникати помилок 400 від постачальника для непідтримуваних ролей `developer`.
|
||||
- Маршрути OpenAI-compatible у стилі proxy також пропускають специфічне лише для нативного OpenAI
|
||||
формування запиту: без `service_tier`, без `store` у Responses, без підказок кешу prompt, без
|
||||
формування payload сумісності reasoning OpenAI та без прихованих заголовків атрибуції
|
||||
OpenClaw.
|
||||
- Якщо `baseUrl` порожній/пропущений, OpenClaw зберігає типову поведінку OpenAI (яка зіставляється з `api.openai.com`).
|
||||
- З міркувань безпеки явне `compat.supportsDeveloperRole: true` усе одно перевизначається на ненативних endpoint-ах `openai-completions`.
|
||||
- Рекомендація: задавайте явні значення, що відповідають обмеженням вашого проксі/моделі.
|
||||
- Для `api: "openai-completions"` на не-нативних кінцевих точках (будь-який непорожній `baseUrl`, чий host не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникнути помилок 400 від постачальника через непідтримувані ролі `developer`.
|
||||
- Проксі-маршрути у стилі OpenAI-compatible також пропускають нативне
|
||||
формування запитів лише для OpenAI: без `service_tier`, без `store` для Responses, без підказок кешу промптів, без
|
||||
формування payload сумісності reasoning OpenAI і без прихованих заголовків атрибуції OpenClaw.
|
||||
- Якщо `baseUrl` порожній/не вказаний, OpenClaw зберігає типову поведінку OpenAI (яка веде до `api.openai.com`).
|
||||
- Для безпеки явне `compat.supportsDeveloperRole: true` усе одно перевизначається на не-нативних кінцевих точках `openai-completions`.
|
||||
|
||||
## Приклади CLI
|
||||
|
||||
@ -797,9 +815,9 @@ openclaw models list
|
||||
|
||||
Див. також: [/gateway/configuration](/uk/gateway/configuration) для повних прикладів конфігурації.
|
||||
|
||||
## Пов’язане
|
||||
## Пов'язане
|
||||
|
||||
- [Models](/uk/concepts/models) — конфігурація моделей і псевдоніми
|
||||
- [Model Failover](/uk/concepts/model-failover) — ланцюжки резервного перемикання та поведінка повторних спроб
|
||||
- [Configuration Reference](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделі
|
||||
- [Providers](/uk/providers) — інструкції з налаштування для кожного постачальника
|
||||
- [Providers](/uk/providers) — окремі посібники з налаштування постачальників
|
||||
|
||||
294
docs/uk/gateway/cli-backends.md
Normal file
294
docs/uk/gateway/cli-backends.md
Normal file
@ -0,0 +1,294 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібен надійний резервний варіант, коли API-провайдери не працюють
|
||||
- Ви використовуєте Codex CLI або інші локальні AI CLI і хочете повторно використовувати їх
|
||||
- Ви хочете зрозуміти MCP loopback-міст для доступу CLI-бекенду до інструментів
|
||||
summary: 'CLI-бекенди: локальний резервний AI CLI з необов’язковим мостом інструментів MCP'
|
||||
title: CLI-бекенди
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T12:43:15Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fe30bb4d5f51adcda53bf69a4f88e27832e78630ed5bfd8a33a66b6412b66f2d
|
||||
source_path: gateway/cli-backends.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# CLI-бекенди (резервне середовище виконання)
|
||||
|
||||
OpenClaw може запускати **локальні AI CLI** як **лише текстовий резервний варіант**, коли API-провайдери недоступні,
|
||||
обмежені за частотою запитів або тимчасово працюють некоректно. Це навмисно консервативний підхід:
|
||||
|
||||
- **Інструменти OpenClaw не впроваджуються безпосередньо**, але бекенди з `bundleMcp: true`
|
||||
можуть отримувати інструменти gateway через loopback-міст MCP.
|
||||
- **JSONL-стримінг** для CLI, які це підтримують.
|
||||
- **Сеанси підтримуються** (тому наступні звернення залишаються узгодженими).
|
||||
- **Зображення можна передавати далі**, якщо CLI приймає шляхи до зображень.
|
||||
|
||||
Це задумано як **страхувальна сітка**, а не як основний шлях. Використовуйте це, коли вам
|
||||
потрібні текстові відповіді у стилі «завжди працює» без залежності від зовнішніх API.
|
||||
|
||||
Якщо вам потрібне повноцінне середовище виконання harness із керуванням сеансами ACP, фоновими завданнями,
|
||||
прив’язкою до потоку/розмови та постійними зовнішніми сеансами кодування, використовуйте
|
||||
[ACP Agents](/uk/tools/acp-agents). CLI-бекенди — це не ACP.
|
||||
|
||||
## Швидкий старт для початківців
|
||||
|
||||
Ви можете використовувати Codex CLI **без жодної конфігурації** (вбудований плагін OpenAI
|
||||
реєструє бекенд за замовчуванням):
|
||||
|
||||
```bash
|
||||
openclaw agent --message "hi" --model codex-cli/gpt-5.4
|
||||
```
|
||||
|
||||
Якщо ваш gateway працює під launchd/systemd і PATH мінімальний, додайте лише
|
||||
шлях до команди:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
cliBackends: {
|
||||
"codex-cli": {
|
||||
command: "/opt/homebrew/bin/codex",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Ось і все. Жодних ключів, жодної додаткової конфігурації автентифікації, окрім самої CLI.
|
||||
|
||||
Якщо ви використовуєте вбудований CLI-бекенд як **основного провайдера повідомлень** на
|
||||
хості gateway, OpenClaw тепер автоматично завантажує відповідний вбудований плагін, коли ваша конфігурація
|
||||
явно посилається на цей бекенд у model ref або в
|
||||
`agents.defaults.cliBackends`.
|
||||
|
||||
## Використання як резервного варіанта
|
||||
|
||||
Додайте CLI-бекенд до списку резервних, щоб він запускався лише тоді, коли основні моделі не працюють:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: {
|
||||
primary: "anthropic/claude-opus-4-6",
|
||||
fallbacks: ["codex-cli/gpt-5.4"],
|
||||
},
|
||||
models: {
|
||||
"anthropic/claude-opus-4-6": { alias: "Opus" },
|
||||
"codex-cli/gpt-5.4": {},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Примітки:
|
||||
|
||||
- Якщо ви використовуєте `agents.defaults.models` (список дозволених), ви також маєте включити туди моделі CLI-бекенду.
|
||||
- Якщо основний провайдер завершується помилкою (автентифікація, обмеження частоти, тайм-аути), OpenClaw
|
||||
спробує CLI-бекенд наступним.
|
||||
|
||||
## Огляд конфігурації
|
||||
|
||||
Усі CLI-бекенди розміщуються тут:
|
||||
|
||||
```
|
||||
agents.defaults.cliBackends
|
||||
```
|
||||
|
||||
Кожен запис має ключ у вигляді **ідентифікатора провайдера** (наприклад, `codex-cli`, `my-cli`).
|
||||
Ідентифікатор провайдера стає лівою частиною вашого model ref:
|
||||
|
||||
```
|
||||
<provider>/<model>
|
||||
```
|
||||
|
||||
### Приклад конфігурації
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
cliBackends: {
|
||||
"codex-cli": {
|
||||
command: "/opt/homebrew/bin/codex",
|
||||
},
|
||||
"my-cli": {
|
||||
command: "my-cli",
|
||||
args: ["--json"],
|
||||
output: "json",
|
||||
input: "arg",
|
||||
modelArg: "--model",
|
||||
modelAliases: {
|
||||
"claude-opus-4-6": "opus",
|
||||
"claude-sonnet-4-6": "sonnet",
|
||||
},
|
||||
sessionArg: "--session",
|
||||
sessionMode: "existing",
|
||||
sessionIdFields: ["session_id", "conversation_id"],
|
||||
systemPromptArg: "--system",
|
||||
systemPromptWhen: "first",
|
||||
imageArg: "--image",
|
||||
imageMode: "repeat",
|
||||
serialize: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Як це працює
|
||||
|
||||
1. **Вибирає бекенд** на основі префікса провайдера (`codex-cli/...`).
|
||||
2. **Формує system prompt** із використанням того самого prompt OpenClaw і контексту робочого простору.
|
||||
3. **Виконує CLI** з ідентифікатором сеансу (якщо підтримується), щоб історія залишалася узгодженою.
|
||||
4. **Розбирає вивід** (JSON або звичайний текст) і повертає фінальний текст.
|
||||
5. **Зберігає ідентифікатори сеансів** для кожного бекенду, щоб наступні звернення повторно використовували той самий сеанс CLI.
|
||||
|
||||
<Warning>
|
||||
Вбудований бекенд Anthropic `claude-cli` було видалено після того, як змінилася
|
||||
межа білінгу OpenClaw в Anthropic. OpenClaw і далі підтримує загальні CLI-
|
||||
бекенди, але трафік Anthropic API слід спрямовувати безпосередньо через провайдера Anthropic,
|
||||
а не через видалений локальний шлях Claude CLI.
|
||||
</Warning>
|
||||
|
||||
## Сеанси
|
||||
|
||||
- Якщо CLI підтримує сеанси, задайте `sessionArg` (наприклад, `--session-id`) або
|
||||
`sessionArgs` (заповнювач `{sessionId}`), коли ID потрібно вставити
|
||||
в кілька прапорців.
|
||||
- Якщо CLI використовує **підкоманду resume** з іншими прапорцями, задайте
|
||||
`resumeArgs` (замінює `args` під час відновлення) і, за потреби, `resumeOutput`
|
||||
(для відновлення не у форматі JSON).
|
||||
- `sessionMode`:
|
||||
- `always`: завжди передавати ідентифікатор сеансу (новий UUID, якщо нічого не збережено).
|
||||
- `existing`: передавати ідентифікатор сеансу, лише якщо його вже було збережено.
|
||||
- `none`: ніколи не передавати ідентифікатор сеансу.
|
||||
|
||||
Примітки щодо серіалізації:
|
||||
|
||||
- `serialize: true` зберігає впорядкованість запусків у тій самій смузі.
|
||||
- Більшість CLI серіалізують роботу в одній смузі провайдера.
|
||||
- OpenClaw скидає повторне використання збереженого CLI-сеансу, коли змінюється стан автентифікації бекенду, зокрема після повторного входу, ротації токена або зміни облікових даних профілю автентифікації.
|
||||
|
||||
## Зображення (передавання далі)
|
||||
|
||||
Якщо ваша CLI приймає шляхи до зображень, задайте `imageArg`:
|
||||
|
||||
```json5
|
||||
imageArg: "--image",
|
||||
imageMode: "repeat"
|
||||
```
|
||||
|
||||
OpenClaw записуватиме base64-зображення у тимчасові файли. Якщо задано `imageArg`, ці
|
||||
шляхи передаються як аргументи CLI. Якщо `imageArg` відсутній, OpenClaw додає
|
||||
шляхи до файлів у prompt (ін’єкція шляху), чого достатньо для CLI, які автоматично
|
||||
завантажують локальні файли зі звичайних шляхів.
|
||||
|
||||
## Входи / виходи
|
||||
|
||||
- `output: "json"` (типово) намагається розібрати JSON і витягти текст та ідентифікатор сеансу.
|
||||
- Для JSON-виводу Gemini CLI OpenClaw зчитує текст відповіді з `response`, а
|
||||
дані використання — зі `stats`, коли `usage` відсутній або порожній.
|
||||
- `output: "jsonl"` розбирає потоки JSONL (наприклад, Codex CLI `--json`) і витягує фінальне повідомлення агента, а також ідентифікатори сеансу,
|
||||
якщо вони присутні.
|
||||
- `output: "text"` трактує stdout як фінальну відповідь.
|
||||
|
||||
Режими введення:
|
||||
|
||||
- `input: "arg"` (типово) передає prompt як останній аргумент CLI.
|
||||
- `input: "stdin"` надсилає prompt через stdin.
|
||||
- Якщо prompt дуже довгий і задано `maxPromptArgChars`, використовується stdin.
|
||||
|
||||
## Типові значення (належать плагіну)
|
||||
|
||||
Вбудований плагін OpenAI також реєструє типові значення для `codex-cli`:
|
||||
|
||||
- `command: "codex"`
|
||||
- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
|
||||
- `resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
|
||||
- `output: "jsonl"`
|
||||
- `resumeOutput: "text"`
|
||||
- `modelArg: "--model"`
|
||||
- `imageArg: "--image"`
|
||||
- `sessionMode: "existing"`
|
||||
|
||||
Вбудований плагін Google також реєструє типові значення для `google-gemini-cli`:
|
||||
|
||||
- `command: "gemini"`
|
||||
- `args: ["--prompt", "--output-format", "json"]`
|
||||
- `resumeArgs: ["--resume", "{sessionId}", "--prompt", "--output-format", "json"]`
|
||||
- `modelArg: "--model"`
|
||||
- `sessionMode: "existing"`
|
||||
- `sessionIdFields: ["session_id", "sessionId"]`
|
||||
|
||||
Передумова: локальна Gemini CLI має бути встановлена та доступна як
|
||||
`gemini` у `PATH` (`brew install gemini-cli` або
|
||||
`npm install -g @google/gemini-cli`).
|
||||
|
||||
Примітки щодо JSON у Gemini CLI:
|
||||
|
||||
- Текст відповіді зчитується з поля JSON `response`.
|
||||
- Дані використання беруться зі `stats`, якщо `usage` відсутній або порожній.
|
||||
- `stats.cached` нормалізується у `cacheRead` OpenClaw.
|
||||
- Якщо `stats.input` відсутній, OpenClaw виводить кількість вхідних токенів із
|
||||
`stats.input_tokens - stats.cached`.
|
||||
|
||||
Перевизначайте лише за потреби (типовий випадок: абсолютний шлях `command`).
|
||||
|
||||
## Типові значення, що належать плагіну
|
||||
|
||||
Типові значення CLI-бекенду тепер є частиною поверхні плагіна:
|
||||
|
||||
- Плагіни реєструють їх через `api.registerCliBackend(...)`.
|
||||
- `id` бекенду стає префіксом провайдера в model ref.
|
||||
- Конфігурація користувача в `agents.defaults.cliBackends.<id>` і далі перевизначає типове значення плагіна.
|
||||
- Очищення конфігурації, специфічне для бекенду, і далі належить плагіну через необов’язковий
|
||||
хук `normalizeConfig`.
|
||||
|
||||
## Bundle MCP overlays
|
||||
|
||||
CLI-бекенди **не** отримують виклики інструментів OpenClaw безпосередньо, але бекенд може
|
||||
увімкнути згенероване накладання конфігурації MCP за допомогою `bundleMcp: true`.
|
||||
|
||||
Поточна вбудована поведінка:
|
||||
|
||||
- `codex-cli`: без накладання bundle MCP
|
||||
- `google-gemini-cli`: без накладання bundle MCP
|
||||
|
||||
Коли bundle MCP увімкнено, OpenClaw:
|
||||
|
||||
- запускає loopback HTTP MCP-сервер, який відкриває інструменти gateway для процесу CLI
|
||||
- автентифікує міст за допомогою токена для кожного сеансу (`OPENCLAW_MCP_TOKEN`)
|
||||
- обмежує доступ до інструментів поточним сеансом, обліковим записом і контекстом каналу
|
||||
- завантажує ввімкнені bundle-MCP-сервери для поточного робочого простору
|
||||
- об’єднує їх із будь-яким наявним `--mcp-config` бекенду
|
||||
- переписує аргументи CLI, щоб передати `--strict-mcp-config --mcp-config <generated-file>`
|
||||
|
||||
Якщо жоден MCP-сервер не ввімкнено, OpenClaw однаково впроваджує strict-конфігурацію, коли
|
||||
бекенд увімкнув bundle MCP, щоб фонові запуски залишалися ізольованими.
|
||||
|
||||
## Обмеження
|
||||
|
||||
- **Немає прямих викликів інструментів OpenClaw.** OpenClaw не впроваджує виклики інструментів у
|
||||
протокол CLI-бекенду. Бекенди бачать інструменти gateway лише тоді, коли вони вмикають
|
||||
`bundleMcp: true`.
|
||||
- **Стримінг залежить від бекенду.** Деякі бекенди транслюють JSONL; інші буферизують
|
||||
до завершення.
|
||||
- **Структуровані виходи** залежать від формату JSON CLI.
|
||||
- **Сеанси Codex CLI** відновлюються через текстовий вивід (без JSONL), що менш
|
||||
структуровано, ніж початковий запуск `--json`. Сеанси OpenClaw однаково працюють
|
||||
нормально.
|
||||
|
||||
## Усунення неполадок
|
||||
|
||||
- **CLI не знайдено**: задайте `command` як повний шлях.
|
||||
- **Неправильна назва моделі**: використовуйте `modelAliases`, щоб зіставити `provider/model` → модель CLI.
|
||||
- **Немає безперервності сеансу**: переконайтеся, що задано `sessionArg`, а `sessionMode` не дорівнює
|
||||
`none` (Codex CLI наразі не може відновлюватися з JSON-виводом).
|
||||
- **Зображення ігноруються**: задайте `imageArg` (і переконайтеся, що CLI підтримує шляхи до файлів).
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,22 +1,21 @@
|
||||
---
|
||||
read_when:
|
||||
- Додавання або зміна міграцій doctor
|
||||
- Упровадження несумісних змін конфігурації
|
||||
summary: 'Команда Doctor: перевірки стану, міграції конфігурації та кроки виправлення'
|
||||
- Запровадження несумісних змін конфігурації
|
||||
summary: 'Команда Doctor: перевірки стану, міграції конфігурації та кроки відновлення'
|
||||
title: Doctor
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T18:04:19Z"
|
||||
generated_at: "2026-04-06T12:44:06Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6c0a15c522994552a1eef39206bed71fc5bf45746776372f24f31c101bfbd411
|
||||
source_hash: f20637d373c3b1be7c4a3d5424228908b5639cfded8ad5acb9c29f882d0f8d2b
|
||||
source_path: gateway/doctor.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Doctor
|
||||
|
||||
`openclaw doctor` — це інструмент відновлення й міграції для OpenClaw. Він виправляє застарілий
|
||||
стан/конфігурацію, перевіряє працездатність і надає практичні кроки для виправлення.
|
||||
`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє справність і надає практичні кроки для виправлення.
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
@ -24,38 +23,38 @@ x-i18n:
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
### Headless / автоматизація
|
||||
### Безголовий режим / автоматизація
|
||||
|
||||
```bash
|
||||
openclaw doctor --yes
|
||||
```
|
||||
|
||||
Прийняти типові варіанти без запитів (включно з кроками відновлення restart/service/sandbox, якщо застосовно).
|
||||
Приймає типові значення без запитів (зокрема кроки відновлення перезапуску/служби/пісочниці, коли це застосовно).
|
||||
|
||||
```bash
|
||||
openclaw doctor --repair
|
||||
```
|
||||
|
||||
Застосувати рекомендовані виправлення без запитів (виправлення + перезапуски, де це безпечно).
|
||||
Застосовує рекомендовані виправлення без запитів (виправлення + перезапуски, де це безпечно).
|
||||
|
||||
```bash
|
||||
openclaw doctor --repair --force
|
||||
```
|
||||
|
||||
Застосувати також агресивні виправлення (перезаписує власні конфігурації supervisor).
|
||||
Застосовує також агресивні виправлення (перезаписує користувацькі конфігурації supervisor).
|
||||
|
||||
```bash
|
||||
openclaw doctor --non-interactive
|
||||
```
|
||||
|
||||
Запуск без запитів із застосуванням лише безпечних міграцій (нормалізація конфігурації + переміщення стану на диску). Пропускає дії restart/service/sandbox, які потребують підтвердження людини.
|
||||
Запускається без запитів і застосовує лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії з перезапуском/службами/пісочницею, які потребують підтвердження людини.
|
||||
Міграції застарілого стану запускаються автоматично, якщо їх виявлено.
|
||||
|
||||
```bash
|
||||
openclaw doctor --deep
|
||||
```
|
||||
|
||||
Просканувати системні служби на наявність додаткових інсталяцій gateway (launchd/systemd/schtasks).
|
||||
Сканує системні служби на наявність додаткових інсталяцій gateway (launchd/systemd/schtasks).
|
||||
|
||||
Якщо ви хочете переглянути зміни перед записом, спочатку відкрийте файл конфігурації:
|
||||
|
||||
@ -65,62 +64,62 @@ cat ~/.openclaw/openclaw.json
|
||||
|
||||
## Що він робить (коротко)
|
||||
|
||||
- Необов’язкове попереднє оновлення для git-інсталяцій (лише в інтерактивному режимі).
|
||||
- Перевірка актуальності протоколу UI (перезбирає Control UI, якщо схема протоколу новіша).
|
||||
- Перевірка стану + запит на перезапуск.
|
||||
- Підсумок стану Skills (доступні/відсутні/заблоковані) і стан плагінів.
|
||||
- Необов’язкове передстартове оновлення для git-інсталяцій (лише в інтерактивному режимі).
|
||||
- Перевірка актуальності протоколу UI (перебудовує Control UI, якщо схема протоколу новіша).
|
||||
- Перевірка справності + запит на перезапуск.
|
||||
- Зведення стану Skills (доступні/відсутні/заблоковані) і стану плагінів.
|
||||
- Нормалізація конфігурації для застарілих значень.
|
||||
- Міграція конфігурації Talk із застарілих плоских полів `talk.*` до `talk.provider` + `talk.providers.<provider>`.
|
||||
- Перевірки міграції browser для застарілих конфігурацій розширення Chrome і готовності Chrome MCP.
|
||||
- Попередження щодо перевизначень провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
|
||||
- Перевірка передумов TLS для OAuth-профілів OpenAI Codex.
|
||||
- Міграція застарілого стану на диску (sessions/agent dir/WhatsApp auth).
|
||||
- Міграція застарілих ключів контракту manifest плагінів (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
|
||||
- Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, `provider` у payload, прості резервні webhook-завдання з `notify: true`).
|
||||
- Перевірка lock-файлів сесій і очищення застарілих lock.
|
||||
- Перевірки цілісності стану та прав доступу (sessions, transcripts, каталог стану).
|
||||
- Перевірки прав доступу до файлу конфігурації (chmod 600) під час локального запуску.
|
||||
- Стан auth для моделей: перевіряє строк дії OAuth, може оновлювати токени, що скоро спливають, і повідомляє про cooldown/disabled стани auth-профілів.
|
||||
- Виявлення додаткового каталогу workspace (`~/openclaw`).
|
||||
- Відновлення образу sandbox, якщо sandboxing увімкнено.
|
||||
- Міграція конфігурації Talk із застарілих пласких полів `talk.*` у `talk.provider` + `talk.providers.<provider>`.
|
||||
- Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP.
|
||||
- Попередження про перевизначення постачальника OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
|
||||
- Перевірка TLS-передумов OAuth для профілів OpenAI Codex OAuth.
|
||||
- Міграція застарілого стану на диску (сесії/каталог агента/автентифікація WhatsApp).
|
||||
- Міграція застарілих ключів контрактів маніфесту плагінів (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
|
||||
- Міграція застарілого сховища cron (`jobId`, `schedule.cron`, верхньорівневі поля delivery/payload, `provider` у payload, прості резервні webhook-завдання з `notify: true`).
|
||||
- Перевірка файлів блокування сесій і очищення застарілих блокувань.
|
||||
- Перевірки цілісності стану та прав доступу (сесії, транскрипти, каталог стану).
|
||||
- Перевірки прав доступу до файла конфігурації (`chmod 600`) при локальному запуску.
|
||||
- Справність автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled для профілів автентифікації.
|
||||
- Виявлення додаткового робочого каталогу (`~/openclaw`).
|
||||
- Відновлення образу пісочниці, коли ізоляцію ввімкнено.
|
||||
- Міграція застарілих служб і виявлення додаткових gateway.
|
||||
- Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`).
|
||||
- Перевірки runtime gateway (службу встановлено, але вона не працює; кешований label launchd).
|
||||
- Попередження щодо стану каналів (перевіряються із запущеного gateway).
|
||||
- Перевірки runtime gateway (службу встановлено, але вона не запущена; кешований launchd label).
|
||||
- Попередження про стан каналів (перевіряються із запущеного gateway).
|
||||
- Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим відновленням.
|
||||
- Перевірки найкращих практик runtime gateway (Node проти Bun, шляхи version manager).
|
||||
- Діагностика конфліктів порту gateway (типово `18789`).
|
||||
- Попередження безпеки для відкритих політик DM.
|
||||
- Перевірки auth gateway для локального режиму token (пропонує генерацію token, якщо джерела token немає; не перезаписує конфігурації token SecretRef).
|
||||
- Перевірка `systemd linger` у Linux.
|
||||
- Перевірка розміру bootstrap-файлів workspace (попередження про обрізання/наближення до межі для контекстних файлів).
|
||||
- Перевірка стану shell completion і автоматичне встановлення/оновлення.
|
||||
- Перевірка готовності провайдера embeddings для memory search (локальна модель, віддалений API key або бінарний файл QMD).
|
||||
- Перевірки source install (невідповідність pnpm workspace, відсутні UI assets, відсутній бінарний файл tsx).
|
||||
- Запис оновленої конфігурації + метаданих wizard.
|
||||
- Перевірки автентифікації gateway для локального режиму токена (пропонує згенерувати токен, якщо джерела токена немає; не перезаписує конфігурації токена через SecretRef).
|
||||
- Перевірка systemd linger у Linux.
|
||||
- Перевірка розміру bootstrap-файлів робочого простору (попередження про обрізання/наближення до ліміту для контекстних файлів).
|
||||
- Перевірка стану shell completion та автоінсталяція/оновлення.
|
||||
- Перевірка готовності постачальника embedding для memory search (локальна модель, віддалений API-ключ або бінарник QMD).
|
||||
- Перевірки інсталяції з вихідного коду (невідповідність pnpm workspace, відсутні UI-ресурси, відсутній бінарник tsx).
|
||||
- Записує оновлену конфігурацію + метадані wizard.
|
||||
|
||||
## Докладна поведінка та обґрунтування
|
||||
|
||||
### 0) Необов’язкове оновлення (git-інсталяції)
|
||||
|
||||
Якщо це git checkout і doctor запущено в інтерактивному режимі, він пропонує
|
||||
оновити (fetch/rebase/build) перед запуском doctor.
|
||||
оновитися (fetch/rebase/build) перед запуском doctor.
|
||||
|
||||
### 1) Нормалізація конфігурації
|
||||
|
||||
Якщо конфігурація містить застарілі форми значень (наприклад `messages.ackReaction`
|
||||
Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction`
|
||||
без перевизначення для конкретного каналу), doctor нормалізує їх до поточної
|
||||
схеми.
|
||||
|
||||
Це також включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk —
|
||||
Це також включає застарілі пласкі поля Talk. Поточна публічна конфігурація Talk —
|
||||
це `talk.provider` + `talk.providers.<provider>`. Doctor переписує старі форми
|
||||
`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` /
|
||||
`talk.apiKey` у мапу провайдерів.
|
||||
`talk.apiKey` у мапу постачальників.
|
||||
|
||||
### 2) Міграції застарілих ключів конфігурації
|
||||
|
||||
Коли конфігурація містить застарілі ключі, інші команди відмовляються виконуватися та просять
|
||||
запустити `openclaw doctor`.
|
||||
Коли конфігурація містить застарілі ключі, інші команди відмовляються працювати
|
||||
й просять запустити `openclaw doctor`.
|
||||
|
||||
Doctor:
|
||||
|
||||
@ -129,8 +128,9 @@ Doctor:
|
||||
- Перезапише `~/.openclaw/openclaw.json` оновленою схемою.
|
||||
|
||||
Gateway також автоматично запускає міграції doctor під час старту, коли виявляє
|
||||
застарілий формат конфігурації, тож застарілі конфігурації виправляються без ручного втручання.
|
||||
Міграції сховища cron обробляються через `openclaw doctor --fix`.
|
||||
застарілий формат конфігурації, тож застарілі конфігурації виправляються без
|
||||
ручного втручання.
|
||||
Міграції сховища cron завдань обробляються через `openclaw doctor --fix`.
|
||||
|
||||
Поточні міграції:
|
||||
|
||||
@ -154,249 +154,253 @@ Gateway також автоматично запускає міграції doct
|
||||
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold`
|
||||
→ `plugins.entries.voice-call.config.streaming.providers.openai.*`
|
||||
- `bindings[].match.accountID` → `bindings[].match.accountId`
|
||||
- Для каналів з іменованими `accounts`, але зі збереженими однокористувацькими значеннями каналу на верхньому рівні, перенести ці значення, прив’язані до облікового запису, у підвищений обліковий запис, вибраний для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/типову ціль)
|
||||
- Для каналів з іменованими `accounts`, але зі збереженими верхньорівневими значеннями каналу для одиничного акаунта, перемістити ці значення, прив’язані до акаунта, у підвищений акаунт, вибраний для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/типову ціль)
|
||||
- `identity` → `agents.list[].identity`
|
||||
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
|
||||
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
|
||||
→ `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
|
||||
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
|
||||
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
|
||||
- видалити `browser.relayBindHost` (застаріле налаштування relay для розширення)
|
||||
- видалення `browser.relayBindHost` (застаріле налаштування relay для розширення)
|
||||
|
||||
Попередження doctor також містять рекомендації щодо account-default для каналів із кількома обліковими записами:
|
||||
Попередження doctor також включають рекомендації щодо акаунта за замовчуванням для багатокаунтних каналів:
|
||||
|
||||
- Якщо налаштовано два або більше записів `channels.<channel>.accounts` без `channels.<channel>.defaultAccount` або `accounts.default`, doctor попереджає, що fallback-маршрутизація може вибрати неочікуваний обліковий запис.
|
||||
- Якщо `channels.<channel>.defaultAccount` установлено на невідомий ID облікового запису, doctor попереджає та перелічує налаштовані ID облікових записів.
|
||||
- Якщо налаштовано два або більше записів `channels.<channel>.accounts` без `channels.<channel>.defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний акаунт.
|
||||
- Якщо `channels.<channel>.defaultAccount` вказано на невідомий ID акаунта, doctor попереджає і перелічує налаштовані ID акаунтів.
|
||||
|
||||
### 2b) Перевизначення провайдера OpenCode
|
||||
### 2b) Перевизначення постачальника OpenCode
|
||||
|
||||
Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`,
|
||||
це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`.
|
||||
Це може примусово спрямовувати моделі до неправильного API або обнулювати вартість. Doctor попереджає, щоб ви могли прибрати це перевизначення й відновити маршрутизацію API + вартість для кожної моделі.
|
||||
Через це моделі можуть використовувати неправильний API або мати нульову вартість. Doctor попереджає про це, щоб ви
|
||||
могли прибрати перевизначення і відновити маршрутизацію API та вартість для кожної моделі.
|
||||
|
||||
### 2c) Міграція browser і готовність Chrome MCP
|
||||
### 2c) Міграція браузера і готовність Chrome MCP
|
||||
|
||||
Якщо ваша конфігурація browser все ще вказує на вилучений шлях розширення Chrome, doctor
|
||||
нормалізує її до поточної моделі локального під’єднання Chrome MCP на тому самому хості:
|
||||
Якщо ваша конфігурація браузера все ще вказує на видалений шлях розширення Chrome, doctor
|
||||
нормалізує її до поточної моделі підключення host-local Chrome MCP:
|
||||
|
||||
- `browser.profiles.*.driver: "extension"` стає `"existing-session"`
|
||||
- `browser.relayBindHost` видаляється
|
||||
|
||||
Doctor також виконує аудит локального шляху Chrome MCP на тому ж хості, коли ви використовуєте `defaultProfile:
|
||||
Doctor також перевіряє шлях host-local Chrome MCP, коли ви використовуєте `defaultProfile:
|
||||
"user"` або налаштований профіль `existing-session`:
|
||||
|
||||
- перевіряє, чи встановлено Google Chrome на тому самому хості для типових
|
||||
профілів з auto-connect
|
||||
профілів автопідключення
|
||||
- перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144
|
||||
- нагадує ввімкнути remote debugging на сторінці inspect браузера (наприклад `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`,
|
||||
- нагадує ввімкнути remote debugging на сторінці inspect у браузері (наприклад,
|
||||
`chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`,
|
||||
або `edge://inspect/#remote-debugging`)
|
||||
|
||||
Doctor не може ввімкнути це налаштування на боці Chrome за вас. Локальний Chrome MCP
|
||||
і надалі вимагає:
|
||||
Doctor не може ввімкнути це налаштування у Chrome за вас. Host-local Chrome MCP
|
||||
усе ще вимагає:
|
||||
|
||||
- браузер на базі Chromium 144+ на хості gateway/node
|
||||
- локально запущений браузер
|
||||
- увімкнений remote debugging у цьому браузері
|
||||
- схвалення першого запиту на attach у браузері
|
||||
- підтвердження першого запиту згоди на підключення в браузері
|
||||
|
||||
Готовність тут стосується лише передумов для локального attach. Existing-session зберігає
|
||||
Готовність тут стосується лише передумов локального підключення. Existing-session зберігає
|
||||
поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF,
|
||||
перехоплення завантажень і пакетні дії, як і раніше потребують керованого
|
||||
browser або сирого профілю CDP.
|
||||
перехоплення завантажень і пакетні дії, як і раніше, потребують керованого
|
||||
браузера або сирого профілю CDP.
|
||||
|
||||
Ця перевірка **не** застосовується до Docker, sandbox, remote-browser чи інших
|
||||
headless-сценаріїв. Вони, як і раніше, використовують сирий CDP.
|
||||
безголових сценаріїв. Вони, як і раніше, використовують сирий CDP.
|
||||
|
||||
### 2d) Передумови TLS для OAuth
|
||||
### 2d) TLS-передумови OAuth
|
||||
|
||||
Коли налаштовано OAuth-профіль OpenAI Codex, doctor перевіряє endpoint авторизації OpenAI,
|
||||
щоб переконатися, що локальний стек TLS Node/OpenSSL може валідувати ланцюжок сертифікатів. Якщо
|
||||
перевірка завершується помилкою сертифіката (наприклад `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або self-signed сертифікат),
|
||||
doctor виводить платформо-специфічні інструкції з виправлення. У macOS з Node із Homebrew
|
||||
виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка виконується,
|
||||
Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє endpoint авторизації
|
||||
OpenAI, щоб упевнитися, що локальний стек TLS Node/OpenSSL може
|
||||
перевірити ланцюжок сертифікатів. Якщо перевірка не проходить через помилку сертифіката (наприклад,
|
||||
`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат),
|
||||
doctor виводить рекомендації щодо виправлення для конкретної платформи. У macOS із Node, встановленим через Homebrew,
|
||||
виправлення зазвичай таке: `brew postinstall ca-certificates`. З `--deep` перевірка виконується
|
||||
навіть якщо gateway справний.
|
||||
|
||||
### 3) Міграції застарілого стану (структура на диску)
|
||||
### 3) Міграції застарілого стану (розмітка на диску)
|
||||
|
||||
Doctor може мігрувати старіші структури на диску до поточної:
|
||||
Doctor може мігрувати старіші розмітки на диску до поточної структури:
|
||||
|
||||
- Сховище сесій + transcripts:
|
||||
- Сховище сесій + транскрипти:
|
||||
- з `~/.openclaw/sessions/` до `~/.openclaw/agents/<agentId>/sessions/`
|
||||
- Agent dir:
|
||||
- Каталог агента:
|
||||
- з `~/.openclaw/agent/` до `~/.openclaw/agents/<agentId>/agent/`
|
||||
- Стан auth WhatsApp (Baileys):
|
||||
- Стан автентифікації WhatsApp (Baileys):
|
||||
- із застарілого `~/.openclaw/credentials/*.json` (крім `oauth.json`)
|
||||
- до `~/.openclaw/credentials/whatsapp/<accountId>/...` (типовий ID облікового запису: `default`)
|
||||
- до `~/.openclaw/credentials/whatsapp/<accountId>/...` (типовий ID акаунта: `default`)
|
||||
|
||||
Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor видає попередження, коли
|
||||
залишає будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрують
|
||||
застарілі sessions + agent dir під час старту, тож history/auth/models потрапляють у
|
||||
шлях для конкретного агента без ручного запуску doctor. Auth WhatsApp навмисно
|
||||
мігрується лише через `openclaw doctor`. Нормалізація provider/provider-map для Talk тепер
|
||||
порівнює за структурною рівністю, тож відмінності лише в порядку ключів більше не спричиняють
|
||||
повторних холостих змін `doctor --fix`.
|
||||
Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виведе попередження, якщо
|
||||
залишить будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрує
|
||||
застарілі сесії + каталог агента під час старту, тож історія/автентифікація/моделі потрапляють у
|
||||
каталог для конкретного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно
|
||||
мігрується лише через `openclaw doctor`. Нормалізація постачальника Talk/мапи постачальників тепер
|
||||
порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не спричиняють
|
||||
повторних порожніх змін `doctor --fix`.
|
||||
|
||||
### 3a) Міграції застарілих manifest плагінів
|
||||
### 3a) Міграції застарілих маніфестів плагінів
|
||||
|
||||
Doctor сканує всі встановлені manifest плагінів на наявність застарілих верхньорівневих
|
||||
ключів можливостей (`speechProviders`, `realtimeTranscriptionProviders`,
|
||||
Doctor сканує всі встановлені маніфести плагінів на наявність застарілих верхньорівневих ключів
|
||||
можливостей (`speechProviders`, `realtimeTranscriptionProviders`,
|
||||
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
|
||||
`imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`,
|
||||
`webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх до об’єкта `contracts`
|
||||
і переписати файл manifest безпосередньо. Ця міграція є ідемпотентною;
|
||||
`webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх в об’єкт `contracts`
|
||||
і переписати файл маніфесту на місці. Ця міграція ідемпотентна;
|
||||
якщо ключ `contracts` уже містить ті самі значення, застарілий ключ видаляється
|
||||
без дублювання даних.
|
||||
|
||||
### 3b) Міграції застарілого сховища cron
|
||||
|
||||
Doctor також перевіряє сховище cron jobs (типово `~/.openclaw/cron/jobs.json`,
|
||||
або `cron.store`, якщо перевизначено) на старі форми завдань, які планувальник усе ще
|
||||
приймає для сумісності.
|
||||
Doctor також перевіряє сховище cron завдань (`~/.openclaw/cron/jobs.json` типово,
|
||||
або `cron.store`, якщо його перевизначено) на наявність старих форм завдань, які планувальник
|
||||
досі приймає для сумісності.
|
||||
|
||||
Поточні очищення cron включають:
|
||||
|
||||
- `jobId` → `id`
|
||||
- `schedule.cron` → `schedule.expr`
|
||||
- поля payload верхнього рівня (`message`, `model`, `thinking`, ...) → `payload`
|
||||
- поля delivery верхнього рівня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
|
||||
- верхньорівневі поля payload (`message`, `model`, `thinking`, ...) → `payload`
|
||||
- верхньорівневі поля delivery (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
|
||||
- псевдоніми delivery `provider` у payload → явний `delivery.channel`
|
||||
- прості застарілі резервні webhook-завдання з `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook`
|
||||
- прості застарілі резервні webhook-завдання з `notify: true` → явний `delivery.mode="webhook"` із `delivery.to=cron.webhook`
|
||||
|
||||
Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це
|
||||
без зміни поведінки. Якщо завдання поєднує застарілий резервний notify із наявним
|
||||
режимом доставки, що не є webhook, doctor попереджає і залишає це завдання для ручної перевірки.
|
||||
Doctor автоматично мігрує завдання `notify: true` лише тоді, коли це можна зробити без
|
||||
зміни поведінки. Якщо завдання поєднує застарілий резервний notify з уже наявним
|
||||
не-webhook режимом delivery, doctor попереджає і залишає це завдання для ручної перевірки.
|
||||
|
||||
### 3c) Очищення session lock
|
||||
### 3c) Очищення блокувань сесій
|
||||
|
||||
Doctor сканує каталог сесій кожного агента на наявність застарілих файлів lock запису — файлів,
|
||||
які залишилися після аварійного завершення сесії. Для кожного знайденого lock-файлу він повідомляє:
|
||||
шлях, PID, чи PID ще активний, вік lock і чи
|
||||
вважається він застарілим (мертвий PID або старіший за 30 хвилин). У режимі `--fix` / `--repair`
|
||||
він автоматично видаляє застарілі lock-файли; інакше друкує примітку та
|
||||
інструктує повторно запустити з `--fix`.
|
||||
Doctor сканує кожен каталог сесій агента на наявність застарілих write-lock файлів — файлів, що залишилися
|
||||
після аварійного завершення сесії. Для кожного знайденого файла блокування він повідомляє:
|
||||
шлях, PID, чи PID досі активний, вік блокування і чи
|
||||
вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair`
|
||||
він видаляє застарілі файли блокування автоматично; інакше лише виводить примітку і
|
||||
просить повторно запустити з `--fix`.
|
||||
|
||||
### 4) Перевірки цілісності стану (збереження сесій, маршрутизація та безпека)
|
||||
### 4) Перевірки цілісності стану (збереження сесій, маршрутизація і безпека)
|
||||
|
||||
Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите
|
||||
сесії, облікові дані, журнали та конфігурацію (якщо у вас немає резервних копій деінде).
|
||||
Каталог стану — це операційний стовбур системи. Якщо він зникне, ви втратите
|
||||
сесії, облікові дані, журнали і конфігурацію (якщо тільки у вас немає резервних копій деінде).
|
||||
|
||||
Doctor перевіряє:
|
||||
|
||||
- **Відсутній каталог стану**: попереджає про катастрофічну втрату стану, пропонує відтворити
|
||||
- **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує заново створити
|
||||
каталог і нагадує, що не може відновити відсутні дані.
|
||||
- **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує виправити права
|
||||
(і показує підказку `chown`, якщо виявлено невідповідність owner/group).
|
||||
- **Каталог стану macOS із хмарною синхронізацією**: попереджає, коли стан розташовується в iCloud Drive
|
||||
- **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує відновити права доступу
|
||||
(і виводить підказку `chown`, якщо виявлено невідповідність власника/групи).
|
||||
- **Каталог стану під хмарною синхронізацією macOS**: попереджає, коли стан знаходиться в iCloud Drive
|
||||
(`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або
|
||||
`~/Library/CloudStorage/...`, оскільки шляхи із синхронізацією можуть спричиняти повільніший I/O
|
||||
і конфлікти lock/sync.
|
||||
- **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розташовується на джерелі монтування `mmcblk*`,
|
||||
оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час запису сесій і облікових даних.
|
||||
- **Відсутні каталоги сесій**: `sessions/` і каталог сховища сесій
|
||||
потрібні для збереження history і запобігання збоям `ENOENT`.
|
||||
- **Невідповідність transcript**: попереджає, коли у нещодавніх записах сесій відсутні
|
||||
файли transcript.
|
||||
- **Основна сесія “1-line JSONL”**: позначає випадки, коли основний transcript має лише один
|
||||
рядок (history не накопичується).
|
||||
і конфлікти блокувань/синхронізації.
|
||||
- **Каталог стану на Linux на SD або eMMC**: попереджає, коли стан знаходиться на джерелі монтування `mmcblk*`,
|
||||
оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій
|
||||
під час запису сесій та облікових даних.
|
||||
- **Каталоги сесій відсутні**: `sessions/` і каталог сховища сесій
|
||||
потрібні для збереження історії та уникнення збоїв `ENOENT`.
|
||||
- **Невідповідність транскриптів**: попереджає, коли в останніх записах сесій відсутні
|
||||
файли транскриптів.
|
||||
- **Основна сесія “1-line JSONL”**: позначає випадки, коли основний транскрипт має лише один
|
||||
рядок (історія не накопичується).
|
||||
- **Кілька каталогів стану**: попереджає, коли існує кілька каталогів `~/.openclaw` у різних
|
||||
home-каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (history може
|
||||
домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може
|
||||
розділитися між інсталяціями).
|
||||
- **Нагадування про remote mode**: якщо `gateway.mode=remote`, doctor нагадує запустити
|
||||
- **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запустити
|
||||
його на віддаленому хості (стан зберігається там).
|
||||
- **Права доступу до файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json`
|
||||
доступний для читання групою/усіма, і пропонує обмежити права до `600`.
|
||||
- **Права доступу до файла конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` є
|
||||
доступним для читання групою/усіма, і пропонує обмежити до `600`.
|
||||
|
||||
### 5) Стан auth для моделей (строк дії OAuth)
|
||||
### 5) Справність автентифікації моделей (строк дії OAuth)
|
||||
|
||||
Doctor перевіряє OAuth-профілі в сховищі auth, попереджає, коли токени
|
||||
скоро спливають/вже спливли, і може оновити їх, коли це безпечно. Якщо OAuth/token-профіль
|
||||
Anthropic застарів, він пропонує API-ключ Anthropic або застарілий
|
||||
Doctor перевіряє OAuth-профілі в сховищі автентифікації, попереджає, коли токени
|
||||
ось-ось закінчаться або вже прострочені, і може оновити їх, коли це безпечно. Якщо профіль
|
||||
Anthropic OAuth/token застарів, він радить використати Anthropic API key або застарілий
|
||||
шлях setup-token Anthropic.
|
||||
Запити на оновлення з’являються лише в інтерактивному режимі (TTY); `--non-interactive`
|
||||
пропускає спроби оновлення.
|
||||
|
||||
Doctor також виявляє застарілий вилучений стан Anthropic Claude CLI. Якщо старі
|
||||
Doctor також виявляє застарілий видалений стан Anthropic Claude CLI. Якщо старі
|
||||
байти облікових даних `anthropic:claude-cli` все ще існують у `auth-profiles.json`,
|
||||
doctor перетворює їх назад на токен-/OAuth-профілі Anthropic і переписує
|
||||
застарілі посилання на моделі `claude-cli/...`.
|
||||
Якщо байтів уже немає, doctor видаляє застарілу конфігурацію та виводить
|
||||
команди для відновлення.
|
||||
doctor перетворює їх назад на профілі Anthropic token/OAuth і переписує
|
||||
застарілі посилання на моделі `claude-cli/...` та `agents.defaults.cliBackends.claude-cli`.
|
||||
Якщо цих байтів уже немає, doctor видаляє застарілу конфігурацію і виводить команди для відновлення.
|
||||
|
||||
Doctor також повідомляє про auth-профілі, які тимчасово непридатні через:
|
||||
Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні через:
|
||||
|
||||
- короткі cooldown (rate limit/timeouts/auth failures)
|
||||
- довші вимкнення (помилки billing/credit)
|
||||
- короткі cooldown (rate limit/timeout/auth failure)
|
||||
- триваліші відключення (збій billing/credit)
|
||||
|
||||
### 6) Валідація моделі hooks
|
||||
### 6) Перевірка моделі Hooks
|
||||
|
||||
Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель щодо
|
||||
каталогу й allowlist та попереджає, коли воно не буде визначене або заборонене.
|
||||
Якщо задано `hooks.gmail.model`, doctor перевіряє посилання на модель щодо
|
||||
каталогу та allowlist і попереджає, якщо воно не буде розв’язане або заборонене.
|
||||
|
||||
### 7) Відновлення образу sandbox
|
||||
|
||||
Коли sandboxing увімкнено, doctor перевіряє образи Docker і пропонує зібрати їх або
|
||||
перейти на застарілі імена, якщо поточний образ відсутній.
|
||||
Коли sandboxing увімкнено, doctor перевіряє Docker-образи і пропонує зібрати їх або
|
||||
перейти на застарілі назви, якщо поточний образ відсутній.
|
||||
|
||||
### 7b) Runtime-залежності вбудованих плагінів
|
||||
|
||||
Doctor перевіряє, чи присутні runtime-залежності вбудованих плагінів (наприклад
|
||||
runtime-пакунки плагіна Discord) у корені інсталяції OpenClaw.
|
||||
Якщо чогось бракує, doctor повідомляє про пакунки й установлює їх у режимі
|
||||
Doctor перевіряє, що runtime-залежності вбудованих плагінів (наприклад,
|
||||
пакети runtime плагіна Discord) присутні в корені інсталяції OpenClaw.
|
||||
Якщо чогось бракує, doctor повідомляє про пакети і встановлює їх у режимі
|
||||
`openclaw doctor --fix` / `openclaw doctor --repair`.
|
||||
|
||||
### 8) Міграції служб gateway і підказки з очищення
|
||||
|
||||
Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і
|
||||
пропонує видалити їх та встановити службу OpenClaw з використанням поточного порту gateway.
|
||||
Він також може просканувати наявність додаткових gateway-подібних служб і показати підказки для очищення.
|
||||
Іменовані служби gateway OpenClaw на основі профілів вважаються повноцінними й не позначаються як "extra".
|
||||
пропонує видалити їх та встановити службу OpenClaw з поточним
|
||||
портом gateway. Він також може сканувати додаткові gateway-подібні служби і виводити підказки щодо очищення.
|
||||
Служби OpenClaw gateway, названі за профілем, вважаються повноцінними і не
|
||||
позначаються як "додаткові".
|
||||
|
||||
### 8b) Стартова міграція Matrix
|
||||
|
||||
Коли обліковий запис каналу Matrix має очікувану або актуальну міграцію застарілого стану,
|
||||
doctor (у режимі `--fix` / `--repair`) створює знімок стану до міграції, а потім
|
||||
Коли обліковий запис каналу Matrix має відкладену або придатну до виконання міграцію застарілого стану,
|
||||
doctor (у режимі `--fix` / `--repair`) створює знімок стану перед міграцією, а потім
|
||||
запускає кроки міграції за принципом best-effort: міграцію застарілого стану Matrix і підготовку
|
||||
застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а
|
||||
startup продовжується. У режимі лише для читання (`openclaw doctor` без `--fix`) ця перевірка
|
||||
старт продовжується. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка
|
||||
повністю пропускається.
|
||||
|
||||
### 9) Попередження безпеки
|
||||
|
||||
Doctor видає попередження, коли провайдер відкритий для DM без allowlist, або
|
||||
коли політика налаштована небезпечним чином.
|
||||
Doctor виводить попередження, коли постачальник відкритий для DM без allowlist
|
||||
або коли політику налаштовано небезпечним чином.
|
||||
|
||||
### 10) systemd linger (Linux)
|
||||
|
||||
Якщо запуск виконується як користувацька служба systemd, doctor перевіряє, що lingering увімкнено, щоб
|
||||
Якщо запуск відбувається як служба користувача systemd, doctor перевіряє, що linger увімкнено, щоб
|
||||
gateway залишався активним після виходу з системи.
|
||||
|
||||
### 11) Стан workspace (skills, плагіни та застарілі каталоги)
|
||||
### 11) Стан робочого простору (Skills, плагіни і застарілі каталоги)
|
||||
|
||||
Doctor друкує підсумок стану workspace для типового агента:
|
||||
Doctor виводить зведення стану робочого простору для типового агента:
|
||||
|
||||
- **Стан Skills**: кількість доступних, із відсутніми вимогами та заблокованих allowlist навичок.
|
||||
- **Застарілі каталоги workspace**: попереджає, коли `~/openclaw` або інші застарілі каталоги workspace
|
||||
існують поруч із поточним workspace.
|
||||
- **Стан плагінів**: кількість завантажених/вимкнених/помилкових плагінів; перелічує ID плагінів для
|
||||
будь-яких помилок; повідомляє про можливості bundle plugin.
|
||||
- **Попередження про сумісність плагінів**: позначає плагіни, які мають проблеми сумісності з
|
||||
- **Стан Skills**: підраховує доступні, з відсутніми вимогами та заблоковані allowlist Skills.
|
||||
- **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору
|
||||
існують поруч із поточним робочим простором.
|
||||
- **Стан плагінів**: підраховує завантажені/вимкнені/з помилками плагіни; перелічує ID плагінів для будь-яких
|
||||
помилок; повідомляє про можливості bundle plugin.
|
||||
- **Попередження сумісності плагінів**: позначає плагіни, які мають проблеми сумісності з
|
||||
поточним runtime.
|
||||
- **Діагностика плагінів**: показує будь-які попередження або помилки під час завантаження, видані
|
||||
реєстром плагінів.
|
||||
- **Діагностика плагінів**: показує будь-які попередження або помилки під час завантаження, які були
|
||||
видані реєстром плагінів.
|
||||
|
||||
### 11b) Розмір bootstrap-файлів
|
||||
### 11b) Розмір bootstrap-файлу
|
||||
|
||||
Doctor перевіряє, чи bootstrap-файли workspace (наприклад `AGENTS.md`,
|
||||
`CLAUDE.md` або інші інʼєктовані контекстні файли) наближаються до
|
||||
налаштованого символьного бюджету або перевищують його. Він показує для кожного файла кількість сирих та інʼєктованих символів, відсоток обрізання,
|
||||
причину обрізання (`max/file` або `max/total`) і загальну кількість інʼєктованих
|
||||
символів як частку загального бюджету. Коли файли обрізаються або наближаються до межі,
|
||||
doctor друкує поради щодо налаштування `agents.defaults.bootstrapMaxChars`
|
||||
Doctor перевіряє, чи файли bootstrap робочого простору (наприклад, `AGENTS.md`,
|
||||
`CLAUDE.md` або інші інжектовані контекстні файли) не наближаються або не перевищують налаштований
|
||||
ліміт символів. Він повідомляє для кожного файла необроблену кількість символів порівняно з інжектованою,
|
||||
відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість
|
||||
інжектованих символів як частку від загального бюджету. Коли файли обрізаються або наближаються
|
||||
до ліміту, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars`
|
||||
і `agents.defaults.bootstrapTotalMaxChars`.
|
||||
|
||||
### 11c) Shell completion
|
||||
|
||||
Doctor перевіряє, чи встановлено tab completion для поточної оболонки
|
||||
Doctor перевіряє, чи встановлено автодоповнення для поточної оболонки
|
||||
(zsh, bash, fish або PowerShell):
|
||||
|
||||
- Якщо профіль оболонки використовує повільний шаблон динамічного completion
|
||||
@ -407,95 +411,97 @@ Doctor перевіряє, чи встановлено tab completion для п
|
||||
- Якщо completion взагалі не налаштовано, doctor пропонує встановити його
|
||||
(лише в інтерактивному режимі; пропускається з `--non-interactive`).
|
||||
|
||||
Виконайте `openclaw completion --write-state`, щоб вручну перегенерувати кеш.
|
||||
Запустіть `openclaw completion --write-state`, щоб вручну перегенерувати кеш.
|
||||
|
||||
### 12) Перевірки auth gateway (локальний token)
|
||||
### 12) Перевірки автентифікації gateway (локальний токен)
|
||||
|
||||
Doctor перевіряє готовність локальної auth gateway у режимі token.
|
||||
Doctor перевіряє готовність автентифікації локального токена gateway.
|
||||
|
||||
- Якщо режим token потребує token і джерела token немає, doctor пропонує згенерувати його.
|
||||
- Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає й не перезаписує його відкритим текстом.
|
||||
- `openclaw doctor --generate-gateway-token` примусово генерує token лише тоді, коли token SecretRef не налаштовано.
|
||||
- Якщо режим токена потребує токена і джерела токена немає, doctor пропонує згенерувати його.
|
||||
- Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає і не перезаписує його відкритим текстом.
|
||||
- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли токен SecretRef не налаштований.
|
||||
|
||||
### 12b) Виправлення лише для читання з урахуванням SecretRef
|
||||
### 12b) Відновлення лише для читання з урахуванням SecretRef
|
||||
|
||||
Деякі сценарії відновлення потребують перевірки налаштованих облікових даних без послаблення fail-fast поведінки runtime.
|
||||
|
||||
- `openclaw doctor --fix` тепер використовує ту саму модель підсумку SecretRef лише для читання, що й команди сімейства status, для цільових виправлень конфігурації.
|
||||
- Приклад: відновлення `@username` у `allowFrom` / `groupAllowFrom` Telegram намагається використовувати налаштовані облікові дані бота, коли вони доступні.
|
||||
- Якщо token бота Telegram налаштований через SecretRef, але недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає авторозв’язання замість збою або хибного повідомлення про відсутність token.
|
||||
- `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef лише для читання, що й команди сімейства status, для цільових виправлень конфігурації.
|
||||
- Приклад: відновлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використовувати налаштовані облікові дані бота, коли вони доступні.
|
||||
- Якщо токен Telegram-бота налаштовано через SecretRef, але він недоступний у поточному шляху виконання команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає авторозв’язання замість аварійного завершення або хибного повідомлення, що токен відсутній.
|
||||
|
||||
### 13) Перевірка стану gateway + перезапуск
|
||||
### 13) Перевірка справності gateway + перезапуск
|
||||
|
||||
Doctor запускає перевірку стану і пропонує перезапустити gateway, якщо той
|
||||
виглядає несправним.
|
||||
Doctor виконує перевірку справності і пропонує перезапустити gateway, коли він виглядає
|
||||
несправним.
|
||||
|
||||
### 13b) Готовність memory search
|
||||
|
||||
Doctor перевіряє, чи готовий налаштований провайдер embeddings для memory search
|
||||
для типового агента. Поведінка залежить від налаштованого backend і провайдера:
|
||||
Doctor перевіряє, чи готовий налаштований постачальник embedding для memory search
|
||||
для типового агента. Поведінка залежить від налаштованого backend і provider:
|
||||
|
||||
- **Backend QMD**: перевіряє, чи доступний і чи може запускатися бінарний файл `qmd`.
|
||||
Якщо ні, виводить інструкції з виправлення, включно з npm-пакунком і ручним варіантом шляху до бінарного файла.
|
||||
- **Явний локальний провайдер**: перевіряє наявність локального файлу моделі або розпізнаваного
|
||||
віддаленого/завантажуваного URL моделі. Якщо він відсутній, пропонує перейти на віддалений провайдер.
|
||||
- **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи
|
||||
присутній API key у середовищі або сховищі auth. Якщо його немає, показує практичні підказки щодо виправлення.
|
||||
- **Auto provider**: спочатку перевіряє доступність локальної моделі, а потім пробує кожен віддалений
|
||||
провайдер у порядку автовибору.
|
||||
- **QMD backend**: перевіряє, чи доступний і чи може запускатися бінарник `qmd`.
|
||||
Якщо ні, виводить рекомендації щодо виправлення, зокрема npm-пакет і параметр ручного шляху до бінарника.
|
||||
- **Явно вказаний локальний provider**: перевіряє наявність локального файла моделі або розпізнаного
|
||||
URL віддаленої/завантажуваної моделі. Якщо нічого не знайдено, пропонує перейти на віддаленого provider.
|
||||
- **Явно вказаний віддалений provider** (`openai`, `voyage` тощо): перевіряє, чи присутній API key
|
||||
у середовищі або сховищі автентифікації. Якщо його немає, виводить практичні підказки для виправлення.
|
||||
- **Auto provider**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого
|
||||
provider у порядку автодобору.
|
||||
|
||||
Коли доступний результат перевірки gateway (gateway був справний на момент
|
||||
перевірки), doctor звіряє його з конфігурацією, видимою в CLI, і зазначає
|
||||
перевірки), doctor зіставляє його з конфігурацією, видимою з CLI, і зазначає
|
||||
будь-які розбіжності.
|
||||
|
||||
Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embeddings у runtime.
|
||||
Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час runtime.
|
||||
|
||||
### 14) Попередження щодо стану каналів
|
||||
### 14) Попередження про стан каналів
|
||||
|
||||
Якщо gateway справний, doctor виконує перевірку стану каналів і повідомляє
|
||||
попередження разом із запропонованими виправленнями.
|
||||
Якщо gateway справний, doctor запускає перевірку стану каналів і повідомляє
|
||||
попередження з рекомендованими виправленнями.
|
||||
|
||||
### 15) Аудит конфігурації supervisor + відновлення
|
||||
|
||||
Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на
|
||||
наявність відсутніх або застарілих типових значень (наприклад, залежності systemd від network-online та
|
||||
затримки перезапуску). Коли він знаходить невідповідність, то рекомендує оновлення і може
|
||||
переписати service file/task відповідно до поточних типових значень.
|
||||
Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на наявність
|
||||
відсутніх або застарілих типових значень (наприклад, залежностей systemd network-online і
|
||||
затримки перезапуску). Коли він виявляє невідповідність, то рекомендує оновлення і може
|
||||
перезаписати файл служби/завдання відповідно до поточних типових значень.
|
||||
|
||||
Примітки:
|
||||
|
||||
- `openclaw doctor` запитує підтвердження перед переписуванням конфігурації supervisor.
|
||||
- `openclaw doctor` запитує підтвердження перед перезаписом конфігурації supervisor.
|
||||
- `openclaw doctor --yes` приймає типові запити на відновлення.
|
||||
- `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів.
|
||||
- `openclaw doctor --repair --force` перезаписує власні конфігурації supervisor.
|
||||
- Якщо token auth потребує token і `gateway.auth.token` керується через SecretRef, встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані відкриті значення token у метаданих середовища служби supervisor.
|
||||
- Якщо token auth потребує token і налаштований token SecretRef не може бути розв’язаний, doctor блокує шлях install/repair і надає практичні інструкції.
|
||||
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує install/repair, доки режим не буде явно встановлено.
|
||||
- Для Linux user-systemd units перевірки розбіжностей token у doctor тепер включають як джерела `Environment=`, так і `EnvironmentFile=` під час порівняння метаданих auth служби.
|
||||
- Ви завжди можете примусово переписати все через `openclaw gateway install --force`.
|
||||
- `openclaw doctor --repair --force` перезаписує користувацькі конфігурації supervisor.
|
||||
- Якщо автентифікація токеном потребує токена, а `gateway.auth.token` керується через SecretRef, doctor під час встановлення/відновлення служби перевіряє SecretRef, але не зберігає розв’язані значення токена відкритим текстом у метаданих середовища служби supervisor.
|
||||
- Якщо автентифікація токеном потребує токена, а налаштований токен SecretRef не розв’язано, doctor блокує шлях встановлення/відновлення і надає практичні рекомендації.
|
||||
- Якщо одночасно налаштовано `gateway.auth.token` і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки режим явно не буде встановлено.
|
||||
- Для користувацьких unit systemd у Linux перевірки дрейфу токена в doctor тепер включають і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби.
|
||||
- Ви завжди можете примусово виконати повний перезапис через `openclaw gateway install --force`.
|
||||
|
||||
### 16) Runtime gateway + діагностика портів
|
||||
### 16) Діагностика runtime gateway + порту
|
||||
|
||||
Doctor перевіряє runtime служби (PID, статус останнього завершення) і попереджає, коли
|
||||
службу встановлено, але вона фактично не працює. Він також перевіряє конфлікти
|
||||
на порту gateway (типово `18789`) і повідомляє ймовірні причини (gateway уже запущено, SSH tunnel).
|
||||
Doctor перевіряє runtime служби (PID, останній статус завершення) і попереджає, коли
|
||||
службу встановлено, але вона фактично не запущена. Він також перевіряє конфлікти
|
||||
на порту gateway (типово `18789`) і повідомляє ймовірні причини (gateway уже
|
||||
запущений, SSH-тунель).
|
||||
|
||||
### 17) Найкращі практики runtime gateway
|
||||
|
||||
Doctor попереджає, коли служба gateway працює на Bun або на шляху Node, керованому version manager
|
||||
Doctor попереджає, коли служба gateway працює на Bun або на шляху Node, керованому через version manager
|
||||
(`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node,
|
||||
а шляхи version manager можуть ламатися після оновлень, оскільки служба не
|
||||
завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системну інсталяцію Node, якщо
|
||||
а шляхи через version manager можуть ламатися після оновлень, оскільки служба не
|
||||
завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системну інсталяцію Node, коли
|
||||
вона доступна (Homebrew/apt/choco).
|
||||
|
||||
### 18) Запис конфігурації + метадані wizard
|
||||
|
||||
Doctor зберігає будь-які зміни конфігурації та ставить позначки в метаданих wizard, щоб зафіксувати запуск doctor.
|
||||
Doctor зберігає всі зміни конфігурації і проставляє метадані wizard, щоб зафіксувати
|
||||
запуск doctor.
|
||||
|
||||
### 19) Поради щодо workspace (резервне копіювання + система пам’яті)
|
||||
### 19) Поради щодо робочого простору (резервні копії + система пам’яті)
|
||||
|
||||
Doctor пропонує систему пам’яті для workspace, якщо її немає, і друкує пораду про резервне копіювання,
|
||||
якщо workspace ще не перебуває під git.
|
||||
Doctor пропонує систему пам’яті робочого простору, якщо її немає, і виводить пораду щодо резервного копіювання,
|
||||
якщо робочий простір ще не перебуває під git.
|
||||
|
||||
Див. [/concepts/agent-workspace](/concepts/agent-workspace) для повного посібника зі
|
||||
структури workspace та резервного копіювання через git (рекомендовано приватний GitHub або GitLab).
|
||||
Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace) для повного посібника щодо
|
||||
структури робочого простору та резервного копіювання через git (рекомендовано приватний GitHub або GitLab).
|
||||
|
||||
1555
docs/uk/help/faq.md
1555
docs/uk/help/faq.md
File diff suppressed because it is too large
Load Diff
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- Запуск тестів локально або в CI
|
||||
- Додавання регресій для багів моделі/провайдера
|
||||
- Налагодження поведінки gateway і агента
|
||||
summary: 'Набір для тестування: unit/e2e/live набори, Docker-ранери та що покриває кожен тест'
|
||||
- Локальний запуск тестів або запуск у CI
|
||||
- Додавання регресій для багів моделей/провайдерів
|
||||
- Налагодження поведінки gateway та agent
|
||||
summary: 'Набір для тестування: unit/e2e/live набори, Docker-ранери та що охоплює кожен тест'
|
||||
title: Тестування
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T01:03:06Z"
|
||||
generated_at: "2026-04-06T12:44:31Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: cfa174e565df5fdf957234b7909beaf1304aa026e731cc2c433ca7d931681b56
|
||||
source_hash: b18d68d08b851dea994af250f7cb833a34523601d04fd2f118def9777c961b55
|
||||
source_path: help/testing.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -20,8 +20,8 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не
|
||||
|
||||
Цей документ — посібник «як ми тестуємо»:
|
||||
|
||||
- Що покриває кожен набір (і чого він навмисно _не_ покриває)
|
||||
- Які команди запускати для типових сценаріїв (локально, перед push, налагодження)
|
||||
- Що охоплює кожен набір (і що він навмисно _не_ охоплює)
|
||||
- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження)
|
||||
- Як live-тести знаходять облікові дані та вибирають моделі/провайдерів
|
||||
- Як додавати регресії для реальних проблем моделей/провайдерів
|
||||
|
||||
@ -32,30 +32,30 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не
|
||||
- Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm test`
|
||||
- Швидший локальний запуск повного набору на потужній машині: `pnpm test:max`
|
||||
- Прямий цикл спостереження Vitest (сучасна конфігурація projects): `pnpm test:watch`
|
||||
- Пряме націлення на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`
|
||||
- Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`
|
||||
|
||||
Коли ви торкаєтеся тестів або хочете більше впевненості:
|
||||
Коли ви змінюєте тести або хочете мати більше впевненості:
|
||||
|
||||
- Gate покриття: `pnpm test:coverage`
|
||||
- Набір E2E: `pnpm test:e2e`
|
||||
|
||||
Під час налагодження реальних провайдерів/моделей (потрібні справжні облікові дані):
|
||||
Коли налагоджуєте реальні провайдери/моделі (потрібні реальні облікові дані):
|
||||
|
||||
- Набір live (моделі + gateway tool/image probes): `pnpm test:live`
|
||||
- Live-набір (моделі + gateway tool/image probes): `pnpm test:live`
|
||||
- Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts`
|
||||
|
||||
Порада: коли вам потрібен лише один збійний випадок, краще звузити live-тести через змінні середовища allowlist, описані нижче.
|
||||
Порада: коли вам потрібен лише один проблемний випадок, звужуйте live-тести через змінні середовища allowlist, описані нижче.
|
||||
|
||||
## Набори тестів (що де запускається)
|
||||
|
||||
Сприймайте набори як такі, що мають «зростаючий реалізм» (і зростаючу нестабільність/вартість):
|
||||
Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості):
|
||||
|
||||
### Unit / integration (типово)
|
||||
|
||||
- Команда: `pnpm test`
|
||||
- Конфігурація: нативні Vitest `projects` через `vitest.config.ts`
|
||||
- Файли: core/unit inventories у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` та дозволені `ui` node-тести, охоплені `vitest.unit.config.ts`
|
||||
- Обсяг:
|
||||
- Конфігурація: нативні `projects` Vitest через `vitest.config.ts`
|
||||
- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelisted node-тести `ui`, що охоплюються `vitest.unit.config.ts`
|
||||
- Охоплення:
|
||||
- Чисті unit-тести
|
||||
- Внутрішньопроцесні integration-тести (gateway auth, routing, tooling, parsing, config)
|
||||
- Детерміновані регресії для відомих багів
|
||||
@ -63,37 +63,37 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не
|
||||
- Запускається в CI
|
||||
- Реальні ключі не потрібні
|
||||
- Має бути швидким і стабільним
|
||||
- Примітка про projects:
|
||||
- `pnpm test`, `pnpm test:watch` і `pnpm test:changed` тепер використовують однакову нативну кореневу конфігурацію Vitest `projects`.
|
||||
- Прямі файлові фільтри нативно маршрутизуються через граф кореневого проєкту, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` працює без спеціальної обгортки.
|
||||
- Примітка про вбудований раннер:
|
||||
- Коли ви змінюєте входи виявлення message-tool або контекст runtime compaction,
|
||||
зберігайте покриття на обох рівнях.
|
||||
- Додавайте сфокусовані helper-регресії для чистих меж routing/normalization.
|
||||
- Також підтримуйте здоровими integration-набори вбудованого раннера:
|
||||
- Примітка щодо projects:
|
||||
- `pnpm test`, `pnpm test:watch` і `pnpm test:changed` тепер усі використовують однакову нативну кореневу конфігурацію `projects` Vitest.
|
||||
- Прямі фільтри файлів нативно маршрутизуються через граф кореневого проєкту, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` працює без спеціального обгорткового скрипта.
|
||||
- Примітка щодо embedded runner:
|
||||
- Коли ви змінюєте входи виявлення message-tool або runtime context ущільнення,
|
||||
зберігайте обидва рівні покриття.
|
||||
- Додавайте сфокусовані допоміжні регресії для чистих меж routing/normalization.
|
||||
- Також підтримуйте в здоровому стані integration-набори embedded runner:
|
||||
`src/agents/pi-embedded-runner/compact.hooks.test.ts`,
|
||||
`src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і
|
||||
`src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`.
|
||||
- Ці набори перевіряють, що scoped ids і поведінка compaction усе ще проходять
|
||||
через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є
|
||||
достатньою заміною цих integration-шляхів.
|
||||
- Примітка про pool:
|
||||
- Ці набори перевіряють, що scoped ids і поведінка compaction і далі проходять
|
||||
через реальні шляхи `run.ts` / `compact.ts`; helper-only тести не є
|
||||
достатньою заміною для цих integration-шляхів.
|
||||
- Примітка щодо pool:
|
||||
- Базова конфігурація Vitest тепер типово використовує `threads`.
|
||||
- Спільна конфігурація Vitest також фіксує `isolate: false` і використовує неізольований раннер для кореневих projects, e2e та live конфігурацій.
|
||||
- Коренева гілка UI зберігає свій `jsdom` setup і optimizer, але тепер також працює на спільному неізольованому раннері.
|
||||
- Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у кореневих projects, e2e та live-конфігураціях.
|
||||
- Коренева UI-лінія зберігає свій `jsdom` setup і optimizer, але тепер також працює на спільному non-isolated runner.
|
||||
- `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` з конфігурації projects у кореневому `vitest.config.ts`.
|
||||
- Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8.
|
||||
- Примітка про швидку локальну ітерацію:
|
||||
- Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8.
|
||||
- Примітка щодо швидкої локальної ітерації:
|
||||
- `pnpm test:changed` запускає нативну конфігурацію projects з `--changed origin/main`.
|
||||
- `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму нативну конфігурацію projects, лише з вищим лімітом worker-ів.
|
||||
- Автомасштабування локальних worker-ів тепер навмисно консервативне й також зменшує навантаження, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest типово завдають менше шкоди.
|
||||
- Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб повторні запуски в режимі changed залишалися коректними, коли змінюється wiring тестів.
|
||||
- Конфігурація залишає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання.
|
||||
- Примітка про налагодження продуктивності:
|
||||
- `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпортів і вивід деталізації імпортів.
|
||||
- `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму нативну конфігурацію projects, лише з вищою верхньою межею воркерів.
|
||||
- Автоматичне масштабування локальних воркерів тепер навмисно консервативне і також зменшує навантаження, коли середнє навантаження хоста вже високе, тож кілька паралельних запусків Vitest типово шкодять менше.
|
||||
- Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб повторні запуски в changed-режимі лишалися коректними, коли змінюється тестова обв’язка.
|
||||
- Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання.
|
||||
- Примітка щодо налагодження продуктивності:
|
||||
- `pnpm test:perf:imports` вмикає звітність Vitest про тривалість імпортів і вивід деталізації імпортів.
|
||||
- `pnpm test:perf:imports:changed` обмежує той самий режим профілювання файлами, зміненими відносно `origin/main`.
|
||||
- `pnpm test:perf:profile:main` записує профіль CPU головного потоку для накладних витрат запуску й трансформації Vitest/Vite.
|
||||
- `pnpm test:perf:profile:runner` записує профілі CPU+heap раннера для unit-набору з вимкненим файловим паралелізмом.
|
||||
- `pnpm test:perf:profile:main` записує CPU-профіль головного потоку для витрат на запуск і трансформацію Vitest/Vite.
|
||||
- `pnpm test:perf:profile:runner` записує CPU+heap профілі runner для unit-набору з вимкненим паралелізмом між файлами.
|
||||
|
||||
### E2E (gateway smoke)
|
||||
|
||||
@ -101,36 +101,36 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не
|
||||
- Конфігурація: `vitest.e2e.config.ts`
|
||||
- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts`
|
||||
- Типові параметри runtime:
|
||||
- Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію.
|
||||
- Використовує адаптивну кількість worker-ів (CI: до 2, локально: типово 1).
|
||||
- Типово працює в тихому режимі, щоб зменшити накладні витрати на консольний I/O.
|
||||
- Корисні overrides:
|
||||
- `OPENCLAW_E2E_WORKERS=<n>` щоб примусово задати кількість worker-ів (обмеження — 16).
|
||||
- `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль.
|
||||
- Обсяг:
|
||||
- Наскрізна поведінка gateway з кількома екземплярами
|
||||
- Поверхні WebSocket/HTTP, pairing вузлів і складніший networking
|
||||
- Використовує `threads` Vitest з `isolate: false`, як і решта репозиторію.
|
||||
- Використовує адаптивну кількість воркерів (CI: до 2, локально: 1 за замовчуванням).
|
||||
- Працює в тихому режимі за замовчуванням, щоб зменшити накладні витрати на консольний I/O.
|
||||
- Корисні перевизначення:
|
||||
- `OPENCLAW_E2E_WORKERS=<n>` щоб примусово задати кількість воркерів (обмежено 16).
|
||||
- `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний консольний вивід.
|
||||
- Охоплення:
|
||||
- Наскрізна поведінка multi-instance gateway
|
||||
- Поверхні WebSocket/HTTP, pairing вузлів і важчі мережеві сценарії
|
||||
- Очікування:
|
||||
- Запускається в CI (коли ввімкнено в pipeline)
|
||||
- Реальні ключі не потрібні
|
||||
- Більше рухомих частин, ніж у unit-тестах (може бути повільніше)
|
||||
- Більше рухомих частин, ніж у unit-тестів (може працювати повільніше)
|
||||
|
||||
### E2E: smoke бекенда OpenShell
|
||||
### E2E: smoke для backend OpenShell
|
||||
|
||||
- Команда: `pnpm test:e2e:openshell`
|
||||
- Файл: `test/openshell-sandbox.e2e.test.ts`
|
||||
- Обсяг:
|
||||
- Охоплення:
|
||||
- Запускає ізольований gateway OpenShell на хості через Docker
|
||||
- Створює sandbox із тимчасового локального Dockerfile
|
||||
- Перевіряє бекенд OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec
|
||||
- Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge
|
||||
- Проганяє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec
|
||||
- Перевіряє поведінку remote-canonical filesystem через sandbox fs bridge
|
||||
- Очікування:
|
||||
- Лише opt-in; не входить до типового запуску `pnpm test:e2e`
|
||||
- Потрібен локальний CLI `openshell` і справний Docker daemon
|
||||
- Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує тестовий gateway і sandbox
|
||||
- Корисні overrides:
|
||||
- Потрібні локальний CLI `openshell` і працездатний Docker daemon
|
||||
- Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує test gateway і sandbox
|
||||
- Корисні перевизначення:
|
||||
- `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого e2e-набору
|
||||
- `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб вказати нестандартний бінарний файл CLI або wrapper script
|
||||
- `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний бінарний файл CLI або wrapper script
|
||||
|
||||
### Live (реальні провайдери + реальні моделі)
|
||||
|
||||
@ -138,142 +138,182 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не
|
||||
- Конфігурація: `vitest.live.config.ts`
|
||||
- Файли: `src/**/*.live.test.ts`
|
||||
- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`)
|
||||
- Обсяг:
|
||||
- «Чи цей провайдер/модель справді працює _сьогодні_ з реальними обліковими даними?»
|
||||
- Виявлення змін формату провайдера, особливостей tool-calling, проблем auth і поведінки rate limit
|
||||
- Охоплення:
|
||||
- «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?»
|
||||
- Виявлення змін формату провайдера, особливостей виклику tool, проблем auth і поведінки rate limit
|
||||
- Очікування:
|
||||
- Навмисно не стабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої)
|
||||
- За задумом не є CI-stable (реальні мережі, реальні політики провайдера, квоти, збої)
|
||||
- Коштує грошей / використовує rate limits
|
||||
- Краще запускати звужені підмножини, а не «все»
|
||||
- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі.
|
||||
- Типово live-запуски все ще ізолюють `HOME` і копіюють config/auth матеріали у тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`.
|
||||
- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог.
|
||||
- `pnpm test:live` тепер типово працює в тихішому режимі: зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і приглушує логи bootstrap gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи.
|
||||
- Ротація API-ключів (залежно від провайдера): задайте `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використайте per-live override через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу при відповідях із rate limit.
|
||||
- Live-запуски читають `~/.profile`, щоб підхопити відсутні API-ключі.
|
||||
- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють config/auth material у тимчасовий test home, щоб unit-fixtures не могли змінити ваш реальний `~/.openclaw`.
|
||||
- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише коли навмисно хочете, щоб live-тести використовували вашу реальну домашню директорію.
|
||||
- `pnpm test:live` тепер типово працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але прибирає додаткове повідомлення про `~/.profile` і вимикає журнали bootstrap gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи.
|
||||
- Ротація API-ключів (залежить від провайдера): задайте `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу при відповідях із rate limit.
|
||||
- Вивід прогресу/heartbeat:
|
||||
- Live-набори тепер виводять рядки прогресу в stderr, тому довгі виклики провайдерів помітно активні навіть коли захоплення консолі Vitest тихе.
|
||||
- `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/gateway відразу транслюються під час live-запусків.
|
||||
- Налаштовуйте heartbeat прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`.
|
||||
- Налаштовуйте heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`.
|
||||
- Live-набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдера було видно як активні навіть тоді, коли захоплення консолі Vitest працює тихо.
|
||||
- `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/gateway одразу транслюються під час live-запусків.
|
||||
- Налаштовуйте heartbeats прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`.
|
||||
- Налаштовуйте heartbeats gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`.
|
||||
|
||||
## Який набір запускати?
|
||||
## Який набір мені запускати?
|
||||
|
||||
Скористайтеся цією таблицею рішень:
|
||||
|
||||
- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змін було багато)
|
||||
- Торкаєтеся gateway networking / WS protocol / pairing: додайте `pnpm test:e2e`
|
||||
- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / tool calling: запускайте звужений `pnpm test:live`
|
||||
- Редагуєте логіку/тести: запустіть `pnpm test` (і `pnpm test:coverage`, якщо зміни значні)
|
||||
- Торкаєтеся мережевої логіки gateway / WS protocol / pairing: додайте `pnpm test:e2e`
|
||||
- Налагоджуєте «мій бот не працює» / специфічні для провайдера збої / виклики tool: запустіть звужений `pnpm test:live`
|
||||
|
||||
## Live: перевірка можливостей Android node
|
||||
## Live: sweep можливостей Android node
|
||||
|
||||
- Тест: `src/gateway/android-node.capabilities.live.test.ts`
|
||||
- Скрипт: `pnpm android:test:integration`
|
||||
- Мета: викликати **кожну команду, яку зараз рекламує** підключений Android node, і перевірити поведінку контракту команди.
|
||||
- Обсяг:
|
||||
- Налаштування вручну як передумова (набір не встановлює/не запускає/не pair-ить app).
|
||||
- Валідація `node.invoke` gateway по командах для вибраного Android node.
|
||||
- Обов’язкове попереднє налаштування:
|
||||
- Android app уже підключено й pair-ено з gateway.
|
||||
- App має залишатися на передньому плані.
|
||||
- Права/згоду на захоплення надано для можливостей, які ви очікуєте як успішні.
|
||||
- Необов’язкові overrides цілі:
|
||||
- Мета: викликати **кожну команду, яку зараз оголошує** підключений Android node, і перевірити поведінку контракту команд.
|
||||
- Охоплення:
|
||||
- Попередньо підготовлене/ручне налаштування (набір не встановлює, не запускає і не pair-ить застосунок).
|
||||
- Перевірка `node.invoke` gateway для кожної команди на вибраному Android node.
|
||||
- Потрібне попереднє налаштування:
|
||||
- Android-застосунок уже підключений і pair-ений із gateway.
|
||||
- Застосунок утримується на передньому плані.
|
||||
- Дозволи/підтвердження захоплення надані для можливостей, які ви очікуєте успішно пройти.
|
||||
- Необов’язкові перевизначення цілі:
|
||||
- `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`.
|
||||
- `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`.
|
||||
- Повні деталі налаштування Android: [Android App](/uk/platforms/android)
|
||||
- Повні подробиці налаштування Android: [Android App](/uk/platforms/android)
|
||||
|
||||
## Live: smoke моделей (ключі профілів)
|
||||
## Live: smoke моделей (profile keys)
|
||||
|
||||
Live-тести розділено на два рівні, щоб можна було ізолювати збої:
|
||||
Live-тести поділено на два шари, щоб можна було ізолювати збої:
|
||||
|
||||
- «Direct model» показує, чи провайдер/модель взагалі може відповісти з наданим ключем.
|
||||
- «Direct model» показує, чи взагалі провайдер/модель може відповісти з наданим ключем.
|
||||
- «Gateway smoke» показує, чи працює повний pipeline gateway+agent для цієї моделі (sessions, history, tools, sandbox policy тощо).
|
||||
|
||||
### Рівень 1: Пряме завершення моделі (без gateway)
|
||||
### Шар 1: Пряме завершення моделі (без gateway)
|
||||
|
||||
- Тест: `src/agents/models.profiles.live.test.ts`
|
||||
- Мета:
|
||||
- Перелічити виявлені моделі
|
||||
- Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані
|
||||
- Запустити невелике completion для кожної моделі (і точкові регресії там, де потрібно)
|
||||
- Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані
|
||||
- Виконати невелике completion для кожної моделі (і цільові регресії, де потрібно)
|
||||
- Як увімкнути:
|
||||
- `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму)
|
||||
- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб цей набір справді запускався; інакше він буде пропущений, щоб `pnpm test:live` залишався зосередженим на gateway smoke
|
||||
- `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму)
|
||||
- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запустити цей набір; інакше його буде пропущено, щоб `pnpm test:live` залишався сфокусованим на gateway smoke
|
||||
- Як вибирати моделі:
|
||||
- `OPENCLAW_LIVE_MODELS=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
|
||||
- `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist
|
||||
- `OPENCLAW_LIVE_MODELS=modern` для запуску сучасного allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
|
||||
- `OPENCLAW_LIVE_MODELS=all` — це псевдонім для сучасного allowlist
|
||||
- або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому)
|
||||
- Як вибирати провайдерів:
|
||||
- `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity"` (allowlist через кому)
|
||||
- `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому)
|
||||
- Звідки беруться ключі:
|
||||
- Типово: зі сховища профілів і env fallback-ів
|
||||
- Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів**
|
||||
- За замовчуванням: profile store і резервні варіанти через env
|
||||
- Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store**
|
||||
- Навіщо це існує:
|
||||
- Відокремлює «API провайдера зламане / ключ недійсний» від «pipeline gateway agent зламаний»
|
||||
- Містить невеликі ізольовані регресії (приклад: replay міркувань OpenAI Responses/Codex Responses + потоки tool-call)
|
||||
- Відокремлює «API провайдера зламаний / ключ невалідний» від «pipeline gateway agent зламаний»
|
||||
- Містить малі ізольовані регресії (наприклад: reasoning replay + tool-call flows для OpenAI Responses/Codex Responses)
|
||||
|
||||
### Рівень 2: smoke gateway + dev agent (що насправді робить "@openclaw")
|
||||
### Шар 2: Gateway + smoke dev agent (що насправді робить "@openclaw")
|
||||
|
||||
- Тест: `src/gateway/gateway-models.profiles.live.test.ts`
|
||||
- Мета:
|
||||
- Підняти in-process gateway
|
||||
- Створити/оновити session `agent:dev:*` (override моделі для кожного запуску)
|
||||
- Перебрати моделі з ключами й перевірити:
|
||||
- «змістовну» відповідь (без tools)
|
||||
- що працює реальний виклик інструмента (read probe)
|
||||
- необов’язкові додаткові probe інструментів (exec+read probe)
|
||||
- що регресійні шляхи OpenAI (лише tool-call → follow-up) і далі працюють
|
||||
- Деталі probe (щоб можна було швидко пояснити збої):
|
||||
- `read` probe: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce.
|
||||
- `exec+read` probe: тест просить агента через `exec` записати nonce у тимчасовий файл, а потім через `read` зчитати його назад.
|
||||
- image probe: тест додає згенерований PNG (кіт + випадковий код) і очікує, що модель поверне `cat <CODE>`.
|
||||
- Створити/оновити session `agent:dev:*` (перевизначення моделі для кожного запуску)
|
||||
- Пройтися моделями-з-ключами і перевірити:
|
||||
- «осмислену» відповідь (без tools)
|
||||
- що працює реальний виклик tool (read probe)
|
||||
- необов’язкові додаткові tool probes (exec+read probe)
|
||||
- що шляхи регресії OpenAI (лише tool-call → follow-up) і далі працюють
|
||||
- Подробиці probes (щоб ви могли швидко пояснювати збої):
|
||||
- `read` probe: тест записує nonce-файл у workspace і просить agent виконати `read` цього файла та повернути nonce.
|
||||
- `exec+read` probe: тест просить agent через `exec` записати nonce у тимчасовий файл, а потім через `read` повернути його.
|
||||
- image probe: тест прикріплює згенерований PNG (cat + випадковий код) і очікує, що модель поверне `cat <CODE>`.
|
||||
- Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`.
|
||||
- Як увімкнути:
|
||||
- `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму)
|
||||
- `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму)
|
||||
- Як вибирати моделі:
|
||||
- Типово: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
|
||||
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для modern allowlist
|
||||
- Або задайте `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити набір
|
||||
- Як вибирати провайдерів (уникати «усе з OpenRouter»):
|
||||
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,openai,anthropic,zai,minimax"` (allowlist через кому)
|
||||
- Probe інструментів і зображень у цьому live-тесті завжди ввімкнені:
|
||||
- `read` probe + `exec+read` probe (навантаження на tools)
|
||||
- image probe запускається, коли модель оголошує підтримку image input
|
||||
- Типово: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4)
|
||||
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для сучасного allowlist
|
||||
- Або задайте `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити
|
||||
- Як вибирати провайдерів (уникати «OpenRouter для всього»):
|
||||
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому)
|
||||
- Tool + image probes у цьому live-тесті завжди ввімкнені:
|
||||
- `read` probe + `exec+read` probe (навантаження на tool)
|
||||
- image probe виконується, коли модель оголошує підтримку image input
|
||||
- Потік (на високому рівні):
|
||||
- Тест генерує маленький PNG з «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`)
|
||||
- Тест генерує маленький PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`)
|
||||
- Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "<base64>" }]`
|
||||
- Gateway розбирає attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`)
|
||||
- Вбудований агент пересилає мультимодальне повідомлення користувача моделі
|
||||
- Перевірка: відповідь містить `cat` + код (толерантність до OCR: незначні помилки допускаються)
|
||||
- Embedded agent пересилає multimodal user message до моделі
|
||||
- Перевірка: відповідь містить `cat` + код (OCR tolerance: дрібні помилки дозволені)
|
||||
|
||||
Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте:
|
||||
Порада: щоб побачити, що саме ви можете тестувати на своїй машині (і точні ідентифікатори `provider/model`), виконайте:
|
||||
|
||||
```bash
|
||||
openclaw models list
|
||||
openclaw models list --json
|
||||
```
|
||||
|
||||
## Live: smoke CLI backend (Codex CLI або інші локальні CLI)
|
||||
|
||||
- Тест: `src/gateway/gateway-cli-backend.live.test.ts`
|
||||
- Мета: перевірити pipeline Gateway + agent через локальний CLI backend, не торкаючись вашої типової config.
|
||||
- Увімкнення:
|
||||
- `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму)
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND=1`
|
||||
- Типові значення:
|
||||
- Модель: `codex-cli/gpt-5.4`
|
||||
- Команда: `codex`
|
||||
- Аргументи: `["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]`
|
||||
- Перевизначення (необов’язково):
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"`
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати реальне вкладення-зображення (шляхи вставляються в prompt).
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` щоб передавати шляхи до файлів зображень як аргументи CLI замість вставляння в prompt.
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`) щоб керувати передаванням аргументів зображення, коли задано `IMAGE_ARG`.
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` щоб надіслати другий хід і перевірити resume flow.
|
||||
|
||||
Приклад:
|
||||
|
||||
```bash
|
||||
OPENCLAW_LIVE_CLI_BACKEND=1 \
|
||||
OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4" \
|
||||
pnpm test:live src/gateway/gateway-cli-backend.live.test.ts
|
||||
```
|
||||
|
||||
Рецепт для Docker:
|
||||
|
||||
```bash
|
||||
pnpm test:docker:live-cli-backend
|
||||
```
|
||||
|
||||
Примітки:
|
||||
|
||||
- Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`.
|
||||
- Він запускає smoke live CLI-backend усередині Docker-образу репозиторію від непривілейованого користувача `node`.
|
||||
- Для `codex-cli` він встановлює Linux-пакет `@openai/codex` у кешований префікс із правом запису за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`).
|
||||
|
||||
## Live: smoke ACP bind (`/acp spawn ... --bind here`)
|
||||
|
||||
- Тест: `src/gateway/gateway-acp-bind.live.test.ts`
|
||||
- Мета: перевірити реальний потік conversation-bind ACP із live ACP-агентом:
|
||||
- Мета: перевірити реальний conversation-bind flow ACP із live ACP agent:
|
||||
- надіслати `/acp spawn <agent> --bind here`
|
||||
- прив’язати synthetic розмову message-channel на місці
|
||||
- надіслати звичайний follow-up у цій самій розмові
|
||||
- перевірити, що follow-up потрапляє в transcript прив’язаної ACP-сесії
|
||||
- прив’язати synthetic conversation каналу повідомлень на місці
|
||||
- надіслати звичайне follow-up повідомлення в тій самій conversation
|
||||
- перевірити, що follow-up потрапив у transcript прив’язаної ACP session
|
||||
- Увімкнення:
|
||||
- `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts`
|
||||
- `OPENCLAW_LIVE_ACP_BIND=1`
|
||||
- Типові значення:
|
||||
- ACP-агент: `claude`
|
||||
- Synthetic channel: контекст розмови в стилі Slack DM
|
||||
- ACP agent: `claude`
|
||||
- Synthetic channel: контекст conversation у стилі Slack DM
|
||||
- ACP backend: `acpx`
|
||||
- Overrides:
|
||||
- Перевизначення:
|
||||
- `OPENCLAW_LIVE_ACP_BIND_AGENT=claude`
|
||||
- `OPENCLAW_LIVE_ACP_BIND_AGENT=codex`
|
||||
- `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@<version>'`
|
||||
- Примітки:
|
||||
- Ця доріжка використовує поверхню gateway `chat.send` з admin-only synthetic originating-route fields, щоб тести могли приєднати контекст message-channel без удавання зовнішньої доставки.
|
||||
- Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр агентів плагіна `acpx` для вибраного ACP harness agent.
|
||||
- Ця лінія використовує поверхню `chat.send` gateway з admin-only synthetic полями originating-route, щоб тести могли приєднати контекст message-channel без імітації зовнішньої доставки.
|
||||
- Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent плагіна `acpx` для вибраного ACP harness agent.
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -283,29 +323,29 @@ OPENCLAW_LIVE_ACP_BIND=1 \
|
||||
pnpm test:live src/gateway/gateway-acp-bind.live.test.ts
|
||||
```
|
||||
|
||||
Docker-рецепт:
|
||||
Рецепт для Docker:
|
||||
|
||||
```bash
|
||||
pnpm test:docker:live-acp-bind
|
||||
```
|
||||
|
||||
Примітки щодо Docker:
|
||||
Примітки для Docker:
|
||||
|
||||
- Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`.
|
||||
- Він використовує `~/.profile`, додає відповідні матеріали auth CLI в контейнер, установлює `acpx` у записуваний npm prefix, а потім установлює потрібний live CLI (`@anthropic-ai/claude-code` або `@openai/codex`), якщо його немає.
|
||||
- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env vars провайдера з використаного profile доступними для дочірнього harness CLI.
|
||||
- Він читає `~/.profile`, підготовлює відповідні CLI auth material у контейнері, встановлює `acpx` у npm-префікс із правом запису, а потім за потреби встановлює запитаний live CLI (`@anthropic-ai/claude-code` або `@openai/codex`).
|
||||
- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав доступність змінних середовища провайдера із завантаженого profile для дочірнього harness CLI.
|
||||
|
||||
### Рекомендовані live-рецепти
|
||||
### Рекомендовані рецепти live-запусків
|
||||
|
||||
Вузькі, явні allowlist-и — найшвидші й найменш нестабільні:
|
||||
Вузькі явні allowlist — найшвидші та найменш нестабільні:
|
||||
|
||||
- Одна модель, напряму (без gateway):
|
||||
- Одна модель, direct (без gateway):
|
||||
- `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts`
|
||||
|
||||
- Одна модель, gateway smoke:
|
||||
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
|
||||
|
||||
- Tool calling через кілька провайдерів:
|
||||
- Виклики tool для кількох провайдерів:
|
||||
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
|
||||
|
||||
- Фокус на Google (API-ключ Gemini + Antigravity):
|
||||
@ -315,17 +355,21 @@ pnpm test:docker:live-acp-bind
|
||||
Примітки:
|
||||
|
||||
- `google/...` використовує Gemini API (API-ключ).
|
||||
- `google-antigravity/...` використовує міст Antigravity OAuth (agent endpoint у стилі Cloud Code Assist).
|
||||
- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint agent у стилі Cloud Code Assist).
|
||||
- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окремі auth та особливості tooling).
|
||||
- Gemini API проти Gemini CLI:
|
||||
- API: OpenClaw викликає розміщений Google Gemini API через HTTP (auth через API-ключ / profile); саме це більшість користувачів мають на увазі під «Gemini».
|
||||
- CLI: OpenClaw виконує локальний бінарний файл `gemini`; він має власний auth і може поводитися інакше (streaming/tool support/version skew).
|
||||
|
||||
## Live: матриця моделей (що ми покриваємо)
|
||||
|
||||
Фіксованого «списку моделей CI» немає (live — opt-in), але це **рекомендовані** моделі, які варто регулярно покривати на dev-машині з ключами.
|
||||
Немає фіксованого «списку моделей CI» (live є opt-in), але ось **рекомендовані** моделі, які варто регулярно покривати на машині розробника з ключами.
|
||||
|
||||
### Сучасний smoke-набір (tool calling + image)
|
||||
### Сучасний набір smoke (виклик tool + image)
|
||||
|
||||
Це запуск «типових моделей», який ми очікуємо підтримувати в робочому стані:
|
||||
Це запуск «поширених моделей», який ми очікуємо підтримувати працездатним:
|
||||
|
||||
- OpenAI (не Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`)
|
||||
- OpenAI (не-Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`)
|
||||
- OpenAI Codex: `openai-codex/gpt-5.4`
|
||||
- Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`)
|
||||
- Google (Gemini API): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x)
|
||||
@ -333,12 +377,12 @@ pnpm test:docker:live-acp-bind
|
||||
- Z.AI (GLM): `zai/glm-4.7`
|
||||
- MiniMax: `minimax/MiniMax-M2.7`
|
||||
|
||||
Запустити gateway smoke з tools + image:
|
||||
Запуск gateway smoke з tools + image:
|
||||
`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
|
||||
|
||||
### Базовий рівень: tool calling (Read + необов’язковий Exec)
|
||||
### Базовий рівень: виклик tool (Read + необов’язковий Exec)
|
||||
|
||||
Виберіть принаймні одну модель з кожного сімейства провайдерів:
|
||||
Виберіть щонайменше одну модель на сімейство провайдерів:
|
||||
|
||||
- OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`)
|
||||
- Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`)
|
||||
@ -346,75 +390,75 @@ pnpm test:docker:live-acp-bind
|
||||
- Z.AI (GLM): `zai/glm-4.7`
|
||||
- MiniMax: `minimax/MiniMax-M2.7`
|
||||
|
||||
Необов’язкове додаткове покриття (було б добре мати):
|
||||
Необов’язкове додаткове покриття (корисно мати):
|
||||
|
||||
- xAI: `xai/grok-4` (або найновіша доступна)
|
||||
- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яку у вас ввімкнено)
|
||||
- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас ввімкнено)
|
||||
- Cerebras: `cerebras/`… (якщо у вас є доступ)
|
||||
- LM Studio: `lmstudio/`… (локально; tool calling залежить від режиму API)
|
||||
- LM Studio: `lmstudio/`… (локально; виклик tools залежить від режиму API)
|
||||
|
||||
### Vision: надсилання зображення (attachment → мультимодальне повідомлення)
|
||||
### Vision: надсилання image (вкладення → multimodal message)
|
||||
|
||||
Додайте щонайменше одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI варіанти з підтримкою vision тощо), щоб перевірити image probe.
|
||||
Додайте щонайменше одну модель із підтримкою image до `OPENCLAW_LIVE_GATEWAY_MODELS` (варіанти Claude/Gemini/OpenAI з підтримкою vision тощо), щоб прогнати image probe.
|
||||
|
||||
### Aggregators / альтернативні gateway
|
||||
### Агрегатори / альтернативні gateway
|
||||
|
||||
Якщо у вас увімкнено ключі, ми також підтримуємо тестування через:
|
||||
Якщо у вас увімкнені ключі, ми також підтримуємо тестування через:
|
||||
|
||||
- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image)
|
||||
- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`)
|
||||
|
||||
Інші провайдери, які можна включити до live-матриці (якщо у вас є облікові дані/config):
|
||||
Більше провайдерів, які можна включити до live-матриці (якщо у вас є облікові дані/config):
|
||||
|
||||
- Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot`
|
||||
- Через `models.providers` (custom endpoints): `minimax` (cloud/API), а також будь-який сумісний із OpenAI/Anthropic proxy (LM Studio, vLLM, LiteLLM тощо)
|
||||
- Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot`
|
||||
- Через `models.providers` (custom endpoints): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-compatible proxy (LM Studio, vLLM, LiteLLM тощо)
|
||||
|
||||
Порада: не намагайтеся жорстко зашивати в документації «усі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс ключі, які доступні.
|
||||
Порада: не намагайтеся жорстко фіксувати «всі моделі» в документації. Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс доступні ключі.
|
||||
|
||||
## Облікові дані (ніколи не комітьте)
|
||||
|
||||
Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки:
|
||||
|
||||
- Якщо CLI працює, live-тести мають знаходити ті самі ключі.
|
||||
- Якщо CLI працює, live-тести мають знайти ті самі ключі.
|
||||
- Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі.
|
||||
|
||||
- Профілі auth на рівні агента: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (саме це означають «ключі профілів» у live-тестах)
|
||||
- Профілі auth на agent: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (це й означає «profile keys» у live-тестах)
|
||||
- Config: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`)
|
||||
- Застарілий каталог стану: `~/.openclaw/credentials/` (копіюється в staged live home, якщо присутній, але це не основне сховище ключів профілів)
|
||||
- Локальні live-запуски типово копіюють активний config, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні CLI auth-каталоги в тимчасовий test home; overrides шляху `agents.*.workspace` / `agentDir` у цьому staged config прибираються, щоб probes не торкалися вашого реального host workspace.
|
||||
- Директорія legacy state: `~/.openclaw/credentials/` (копіюється в staged live home, якщо присутня, але це не основне сховище profile-key)
|
||||
- Локальні live-запуски типово копіюють активну config, файли `auth-profiles.json` для кожного agent, legacy `credentials/` і підтримувані зовнішні директорії auth CLI у тимчасовий test home; перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються з цієї staged config, щоб probes не працювали у вашому реальному host workspace.
|
||||
|
||||
Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер).
|
||||
Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або скористайтеся Docker-ранерами нижче (вони можуть монтувати `~/.profile` в контейнер).
|
||||
|
||||
## Live Deepgram (аудіотранскрипція)
|
||||
## Deepgram live (транскрипція аудіо)
|
||||
|
||||
- Тест: `src/media-understanding/providers/deepgram/audio.live.test.ts`
|
||||
- Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts`
|
||||
|
||||
## Live BytePlus coding plan
|
||||
## BytePlus coding plan live
|
||||
|
||||
- Тест: `src/agents/byteplus.live.test.ts`
|
||||
- Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts`
|
||||
- Необов’язковий override моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest`
|
||||
- Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest`
|
||||
|
||||
## Live ComfyUI workflow media
|
||||
## ComfyUI workflow media live
|
||||
|
||||
- Тест: `extensions/comfy/comfy.live.test.ts`
|
||||
- Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts`
|
||||
- Обсяг:
|
||||
- Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate`
|
||||
- Охоплення:
|
||||
- Проганяє вбудовані шляхи comfy для image, video і `music_generate`
|
||||
- Пропускає кожну можливість, якщо `models.providers.comfy.<capability>` не налаштовано
|
||||
- Корисно після змін у поданні workflow comfy, polling, downloads або реєстрації plugin
|
||||
- Корисно після змін у надсиланні workflow comfy, polling, downloads або реєстрації plugin
|
||||
|
||||
## Live генерація зображень
|
||||
## Live для генерації зображень
|
||||
|
||||
- Тест: `src/image-generation/runtime.live.test.ts`
|
||||
- Команда: `pnpm test:live src/image-generation/runtime.live.test.ts`
|
||||
- Обсяг:
|
||||
- Перелічує кожен зареєстрований plugin провайдера генерації зображень
|
||||
- Завантажує відсутні env vars провайдера з вашого login shell (`~/.profile`) перед probe
|
||||
- Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не перекривали реальні shell credentials
|
||||
- Пропускає провайдерів без придатного auth/profile/model
|
||||
- Запускає стандартні варіанти генерації зображень через спільну runtime capability:
|
||||
- Охоплення:
|
||||
- Перелічує кожен зареєстрований plugin-провайдер генерації зображень
|
||||
- Завантажує відсутні provider env vars із вашого login shell (`~/.profile`) перед probes
|
||||
- Типово використовує live/env API-ключі раніше за збережені auth profiles, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані
|
||||
- Пропускає провайдери без придатного auth/profile/model
|
||||
- Проганяє стандартні варіанти генерації зображень через спільну runtime capability:
|
||||
- `google:flash-generate`
|
||||
- `google:pro-generate`
|
||||
- `google:pro-edit`
|
||||
@ -427,17 +471,17 @@ Live-тести знаходять облікові дані так само, я
|
||||
- `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"`
|
||||
- `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"`
|
||||
- Необов’язкова поведінка auth:
|
||||
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати env-only overrides
|
||||
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища profiles і ігнорувати перевизначення лише через env
|
||||
|
||||
## Live генерація музики
|
||||
## Live для генерації музики
|
||||
|
||||
- Тест: `extensions/music-generation-providers.live.test.ts`
|
||||
- Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
|
||||
- Обсяг:
|
||||
- Перевіряє спільний вбудований шлях провайдера генерації музики
|
||||
- Охоплення:
|
||||
- Проганяє спільний вбудований шлях провайдера генерації музики
|
||||
- Наразі покриває Google і MiniMax
|
||||
- Завантажує env vars провайдера з вашого login shell (`~/.profile`) перед probe
|
||||
- Пропускає провайдерів без придатного auth/profile/model
|
||||
- Завантажує provider env vars із вашого login shell (`~/.profile`) перед probes
|
||||
- Пропускає провайдери без придатного auth/profile/model
|
||||
- Необов’язкове звуження:
|
||||
- `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
|
||||
- `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"`
|
||||
@ -446,179 +490,180 @@ Live-тести знаходять облікові дані так само, я
|
||||
|
||||
Ці Docker-ранери поділяються на дві групи:
|
||||
|
||||
- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний їм profile-key live-файл усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний каталог config і workspace (і використовуючи `~/.profile`, якщо змонтовано). Відповідні локальні entrypoint-и: `test:live:models-profiles` і `test:live:gateway-profiles`.
|
||||
- Docker-ранери live типово використовують менший smoke-ліміт, щоб повний Docker-sweep залишався практичним:
|
||||
- Ранери для live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл із profile-key усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний config dir і workspace (а також читають `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoints — `test:live:models-profiles` і `test:live:gateway-profiles`.
|
||||
- Docker-ранери для live-запусків типово використовують меншу межу smoke, щоб повний Docker sweep залишався практичним:
|
||||
`test:docker:live-models` типово використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а
|
||||
`test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`,
|
||||
`test:docker:live-gateway` типово використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`,
|
||||
`OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`,
|
||||
`OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і
|
||||
`OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначте ці env vars, коли
|
||||
вам навмисно потрібне більший вичерпний scan.
|
||||
- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-доріжок live.
|
||||
- Контейнерні smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` запускають один або кілька реальних контейнерів і перевіряють integration-шляхи вищого рівня.
|
||||
`OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли
|
||||
вам явно потрібне ширше вичерпне сканування.
|
||||
- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для двох Docker-ліній live.
|
||||
- Контейнерні smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` піднімають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня.
|
||||
|
||||
Ранери Docker для live-моделей також bind-mount-ять лише потрібні CLI auth homes (або всі підтримувані, якщо запуск не звужений), а потім копіюють їх у home контейнера перед запуском, щоб зовнішній CLI OAuth міг оновлювати токени без змін у host auth store:
|
||||
Docker-ранери для live-моделей також bind-mount лише потрібні домівки auth CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у домашню директорію контейнера перед запуском, щоб зовнішній OAuth CLI міг оновлювати токени, не змінюючи auth store на хості:
|
||||
|
||||
- Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`)
|
||||
- Smoke ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`)
|
||||
- ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`)
|
||||
- CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`)
|
||||
- Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`)
|
||||
- Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`)
|
||||
- Майстер onboarding (TTY, повний scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`)
|
||||
- Open WebUI live smoke: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`)
|
||||
- Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`)
|
||||
- Мережа gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`)
|
||||
- MCP channel bridge (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`)
|
||||
- Plugins (smoke встановлення + псевдонім `/plugin` + семантика restart для Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`)
|
||||
- Міст каналу MCP (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`)
|
||||
- Plugins (smoke інсталяції + псевдонім `/plugin` + семантика restart для бандла Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`)
|
||||
|
||||
Ранери Docker для live-моделей також bind-mount-ять поточний checkout лише для читання і
|
||||
стейджать його у тимчасовий workdir усередині контейнера. Це зберігає runtime
|
||||
образ компактним, але водночас дає запускати Vitest точно на вашому локальному source/config.
|
||||
Крок staging пропускає великі локальні кеші та build-артефакти app, як-от
|
||||
`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для app каталоги `.build` або
|
||||
виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання
|
||||
артефактів, специфічних для машини.
|
||||
Docker-ранери для live-моделей також монтують поточний checkout лише для читання і
|
||||
розміщують його в тимчасовому workdir усередині контейнера. Це зберігає runtime
|
||||
image компактним і водночас дає змогу запускати Vitest точно по вашому локальному source/config.
|
||||
Під час підготовки пропускаються великі локальні кеші й артефакти збірки застосунків, як-от
|
||||
`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні директорії виводу `.build` або
|
||||
Gradle, тож Docker live-запуски не витрачають хвилини на копіювання
|
||||
машинно-специфічних артефактів.
|
||||
Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes gateway не запускали
|
||||
реальні воркери каналів Telegram/Discord тощо всередині контейнера.
|
||||
`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте
|
||||
`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити покриття gateway
|
||||
live із цієї Docker-доріжки.
|
||||
`test:docker:live-models` усе одно запускає `pnpm test:live`, тож також передавайте
|
||||
`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити gateway
|
||||
live-покриття з цієї Docker-лінії.
|
||||
`test:docker:openwebui` — це smoke сумісності вищого рівня: він запускає
|
||||
контейнер gateway OpenClaw з увімкненими HTTP endpoint-ами, сумісними з OpenAI,
|
||||
контейнер gateway OpenClaw з увімкненими OpenAI-compatible HTTP endpoints,
|
||||
запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через
|
||||
Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає
|
||||
реальний chat request через proxy `/api/chat/completions` в Open WebUI.
|
||||
Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися витягнути
|
||||
образ Open WebUI, а Open WebUI може потребувати завершити власне cold-start налаштування.
|
||||
Ця доріжка очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE`
|
||||
(типово `~/.profile`) — основний спосіб надати його у Dockerized-запусках.
|
||||
Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model":
|
||||
реальний chat request через проксі `/api/chat/completions` Open WebUI.
|
||||
Перший запуск може бути помітно повільнішим, тому що Docker може знадобитися завантажити
|
||||
образ Open WebUI, а самому Open WebUI — завершити холодний старт.
|
||||
Для цієї лінії потрібен придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE`
|
||||
(типово `~/.profile`) — основний спосіб надати його в Dockerized-запусках.
|
||||
Успішні запуски виводять невеликий JSON-пейлоад на кшталт `{ "ok": true, "model":
|
||||
"openclaw/default", ... }`.
|
||||
`test:docker:mcp-channels` навмисно детермінований і не потребує
|
||||
реального акаунта Telegram, Discord або iMessage. Він запускає seeded контейнер Gateway,
|
||||
стартує другий контейнер, який піднімає `openclaw mcp serve`, а потім
|
||||
перевіряє виявлення маршрутизованих розмов, читання transcript, metadata вкладень,
|
||||
поведінку live event queue, маршрутизацію outbound send, а також сповіщення про канал +
|
||||
дозволи у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень
|
||||
напряму аналізує сирі stdio MCP frames, тож smoke перевіряє те, що
|
||||
міст справді випромінює, а не лише те, що випадково показує певний client SDK.
|
||||
реального облікового запису Telegram, Discord чи iMessage. Він піднімає seeded Gateway
|
||||
контейнер, запускає другий контейнер, який стартує `openclaw mcp serve`, а потім
|
||||
перевіряє виявлення conversation через routing, читання transcript, metadata вкладень,
|
||||
поведінку live event queue, routing вихідного надсилання і channel- та
|
||||
permission-сповіщення в стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень
|
||||
інспектує raw stdio MCP frames напряму, тож smoke перевіряє саме те, що
|
||||
міст реально випромінює, а не лише те, що вміє показати конкретний клієнтський SDK.
|
||||
|
||||
Ручний smoke plain-language thread ACP (не CI):
|
||||
Ручний smoke plain-language thread для ACP (не CI):
|
||||
|
||||
- `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...`
|
||||
- Залишайте цей скрипт для сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його.
|
||||
- Зберігайте цей скрипт для workflow регресії/налагодження. Він може знову знадобитися для перевірки routing ACP thread, тому не видаляйте його.
|
||||
|
||||
Корисні env vars:
|
||||
|
||||
- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw`
|
||||
- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace`
|
||||
- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і використовується перед запуском тестів
|
||||
- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установлень CLI усередині Docker
|
||||
- Зовнішні CLI auth-каталоги/файли в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів
|
||||
- Типові каталоги: `.minimax`
|
||||
- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і читається перед запуском тестів
|
||||
- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установок CLI усередині Docker
|
||||
- Зовнішні auth dirs/files CLI у `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів
|
||||
- Типові директорії: `.minimax`
|
||||
- Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json`
|
||||
- Для звужених запусків провайдерів монтуються лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS`
|
||||
- Звужені запуски провайдерів монтують лише потрібні директорії/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS`
|
||||
- Можна перевизначити вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex`
|
||||
- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` щоб звузити запуск
|
||||
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` щоб фільтрувати провайдерів у контейнері
|
||||
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані беруться зі сховища профілів (а не з env)
|
||||
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб гарантувати, що облікові дані беруться зі сховища profiles (а не з env)
|
||||
- `OPENCLAW_OPENWEBUI_MODEL=...` щоб вибрати модель, яку gateway показує для smoke Open WebUI
|
||||
- `OPENCLAW_OPENWEBUI_PROMPT=...` щоб перевизначити prompt перевірки nonce, який використовується для smoke Open WebUI
|
||||
- `OPENCLAW_OPENWEBUI_PROMPT=...` щоб перевизначити prompt з перевіркою nonce, який використовує smoke Open WebUI
|
||||
- `OPENWEBUI_IMAGE=...` щоб перевизначити закріплений тег образу Open WebUI
|
||||
|
||||
## Перевірка документації
|
||||
|
||||
Запускайте перевірки docs після редагування документації: `pnpm check:docs`.
|
||||
Запускайте повну перевірку якорів Mintlify, коли потрібні також перевірки заголовків на сторінці: `pnpm docs:check-links:anchors`.
|
||||
Після редагування документації запускайте перевірки документації: `pnpm check:docs`.
|
||||
Запускайте повну перевірку якорів Mintlify, коли вам також потрібна перевірка заголовків на сторінці: `pnpm docs:check-links:anchors`.
|
||||
|
||||
## Офлайн-регресія (безпечна для CI)
|
||||
|
||||
Це регресії «реального pipeline» без реальних провайдерів:
|
||||
|
||||
- Tool calling gateway (mock OpenAI, реальний gateway + agent loop): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop")
|
||||
- Gateway wizard (WS `wizard.start`/`wizard.next`, записує config + примусове auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config")
|
||||
- Виклик tools gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop")
|
||||
- Майстер gateway (WS `wizard.start`/`wizard.next`, запис config + примусовий auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config")
|
||||
|
||||
## Оцінювання надійності агентів (Skills)
|
||||
## Оцінювання надійності agent (Skills)
|
||||
|
||||
У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агентів»:
|
||||
У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності agent»:
|
||||
|
||||
- Mock tool-calling через реальний gateway + agent loop (`src/gateway/gateway.test.ts`).
|
||||
- Наскрізні потоки wizard, які перевіряють wiring сесій і вплив config (`src/gateway/gateway.test.ts`).
|
||||
- Mock tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`).
|
||||
- Наскрізні wizard flows, що перевіряють wiring session і ефекти config (`src/gateway/gateway.test.ts`).
|
||||
|
||||
Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)):
|
||||
|
||||
- **Прийняття рішень:** коли Skills перелічено в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)?
|
||||
- **Відповідність вимогам:** чи читає агент `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи?
|
||||
- **Контракти робочого процесу:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox.
|
||||
- **Decisioning:** коли Skills перелічені в prompt, чи вибирає agent правильний skill (або уникає нерелевантних)?
|
||||
- **Compliance:** чи читає agent `SKILL.md` перед використанням і чи дотримується потрібних кроків/аргументів?
|
||||
- **Workflow contracts:** багатокрокові сценарії, що перевіряють порядок tool, перенесення history session і межі sandbox.
|
||||
|
||||
Майбутні evals мають передусім залишатися детермінованими:
|
||||
Майбутні evals спершу мають залишатися детермінованими:
|
||||
|
||||
- Раннер сценаріїв, що використовує mock-провайдери для перевірки викликів tools + порядку, читання skill-файлів і wiring сесій.
|
||||
- Сценарний runner з mock-провайдерами для перевірки викликів tool + порядку, читання skill-файлів і wiring session.
|
||||
- Невеликий набір сценаріїв, сфокусованих на skills (використовувати чи уникати, gating, prompt injection).
|
||||
- Необов’язкові live evals (opt-in, env-gated) — лише після того, як буде готовий безпечний для CI набір.
|
||||
- Необов’язкові live evals (opt-in, із керуванням через env) лише після того, як безпечний для CI набір буде на місці.
|
||||
|
||||
## Контрактні тести (форма plugin і channel)
|
||||
## Contract tests (форма plugin і channel)
|
||||
|
||||
Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму
|
||||
контракту інтерфейсу. Вони перебирають усі виявлені plugins і запускають набір
|
||||
перевірок форми та поведінки. Типова unit-доріжка `pnpm test` навмисно
|
||||
пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди окремо,
|
||||
Contract tests перевіряють, що кожен зареєстрований plugin і channel відповідає
|
||||
своєму interface contract. Вони проходять по всіх знайдених plugins і запускають набір
|
||||
перевірок форми та поведінки. Типова unit-лінія `pnpm test` навмисно
|
||||
пропускає ці спільні seam- і smoke-файли; запускайте команди contract явно,
|
||||
коли торкаєтеся спільних поверхонь channel або provider.
|
||||
|
||||
### Команди
|
||||
|
||||
- Усі контракти: `pnpm test:contracts`
|
||||
- Лише контракти channel: `pnpm test:contracts:channels`
|
||||
- Лише контракти provider: `pnpm test:contracts:plugins`
|
||||
- Усі contracts: `pnpm test:contracts`
|
||||
- Лише contracts channel: `pnpm test:contracts:channels`
|
||||
- Лише contracts provider: `pnpm test:contracts:plugins`
|
||||
|
||||
### Контракти channel
|
||||
### Contracts channel
|
||||
|
||||
Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`:
|
||||
|
||||
- **plugin** - Базова форма plugin (id, name, capabilities)
|
||||
- **setup** - Контракт майстра налаштування
|
||||
- **session-binding** - Поведінка прив’язки сесії
|
||||
- **setup** - Contract майстра setup
|
||||
- **session-binding** - Поведінка прив’язування session
|
||||
- **outbound-payload** - Структура payload повідомлення
|
||||
- **inbound** - Обробка вхідних повідомлень
|
||||
- **actions** - Обробники дій channel
|
||||
- **threading** - Обробка thread ID
|
||||
- **directory** - API каталогу/реєстру
|
||||
- **group-policy** - Застосування групових політик
|
||||
- **directory** - API directory/roster
|
||||
- **group-policy** - Застосування group policy
|
||||
|
||||
### Контракти статусу provider
|
||||
### Contracts status провайдера
|
||||
|
||||
Розташовані в `src/plugins/contracts/*.contract.test.ts`.
|
||||
|
||||
- **status** - Probe-и статусу channel
|
||||
- **registry** - Форма реєстру plugin
|
||||
- **status** - Status probes каналу
|
||||
- **registry** - Форма registry plugin
|
||||
|
||||
### Контракти provider
|
||||
### Contracts provider
|
||||
|
||||
Розташовані в `src/plugins/contracts/*.contract.test.ts`:
|
||||
|
||||
- **auth** - Контракт потоку auth
|
||||
- **auth** - Contract потоку auth
|
||||
- **auth-choice** - Вибір/selection auth
|
||||
- **catalog** - API каталогу моделей
|
||||
- **discovery** - Виявлення plugin
|
||||
- **loader** - Завантаження plugin
|
||||
- **runtime** - Runtime provider
|
||||
- **shape** - Форма/інтерфейс plugin
|
||||
- **wizard** - Майстер налаштування
|
||||
- **shape** - Форма/interface plugin
|
||||
- **wizard** - Майстер setup
|
||||
|
||||
### Коли запускати
|
||||
|
||||
- Після зміни exports або subpath-ів plugin-sdk
|
||||
- Після зміни exports або subpaths у plugin-sdk
|
||||
- Після додавання або зміни channel чи provider plugin
|
||||
- Після рефакторингу реєстрації plugin або discovery
|
||||
- Після рефакторингу реєстрації або виявлення plugin
|
||||
|
||||
Контрактні тести запускаються в CI й не потребують реальних API-ключів.
|
||||
Contract tests запускаються в CI і не потребують реальних API-ключів.
|
||||
|
||||
## Додавання регресій (рекомендації)
|
||||
|
||||
Коли ви виправляєте проблему провайдера/моделі, виявлену в live:
|
||||
|
||||
- Якщо можливо, додавайте безпечну для CI регресію (mock/stub провайдера або фіксацію точної трансформації форми запиту)
|
||||
- Якщо це за своєю природою лише live-випадок (rate limits, політики auth), тримайте live-тест вузьким і opt-in через env vars
|
||||
- Намагайтеся націлюватися на найменший рівень, який ловить баг:
|
||||
- баг конвертації/replay запиту провайдера → тест direct models
|
||||
- Додайте безпечну для CI регресію, якщо це можливо (mock/stub провайдера або захоплення точної трансформації форми запиту)
|
||||
- Якщо це за своєю природою лише live-проблема (rate limits, політики auth), залишайте live-тест вузьким і opt-in через env vars
|
||||
- Намагайтеся націлюватися на найменший шар, який виявляє баг:
|
||||
- баг перетворення/повторення запиту провайдера → direct models test
|
||||
- баг pipeline gateway session/history/tool → gateway live smoke або безпечний для CI gateway mock test
|
||||
- Захисна умова обходу SecretRef:
|
||||
- `src/secrets/exec-secret-ref-id-parity.test.ts` виводить по одній sampled target для кожного класу SecretRef з metadata реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec ids відхиляються.
|
||||
- Якщо ви додаєте нове сімейство цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target ids, щоб нові класи не можна було тихо пропустити.
|
||||
- Захисне правило обходу SecretRef:
|
||||
- `src/secrets/exec-secret-ref-id-parity.test.ts` виводить по одній вибраній цілі на клас SecretRef з metadata registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec ids відхиляються.
|
||||
- Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -2,61 +2,62 @@
|
||||
read_when:
|
||||
- Ви хочете створити новий plugin для OpenClaw
|
||||
- Вам потрібен швидкий старт для розробки plugin
|
||||
- Ви додаєте новий канал, провайдера, інструмент або іншу можливість до OpenClaw
|
||||
- Ви додаєте до OpenClaw новий канал, провайдера, інструмент або іншу можливість
|
||||
sidebarTitle: Getting Started
|
||||
summary: Створіть свій перший plugin для OpenClaw за лічені хвилини
|
||||
title: Створення Plugins
|
||||
title: Розробка Plugins
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T00:52:25Z"
|
||||
generated_at: "2026-04-06T12:43:45Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 9be344cb300ecbcba08e593a95bcc93ab16c14b28a0ff0c29b26b79d8249146c
|
||||
source_hash: 509c1f5abe1a0a74966054ed79b71a1a7ee637a43b1214c424acfe62ddf48eef
|
||||
source_path: plugins/building-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Створення Plugins
|
||||
# Розробка Plugins
|
||||
|
||||
Plugins розширюють OpenClaw новими можливостями: канали, провайдери моделей,
|
||||
мовлення, транскрипція в реальному часі, голос у реальному часі, розуміння медіа, генерація зображень,
|
||||
генерація відео, отримання вебсторінок, вебпошук, інструменти агента або будь-яка
|
||||
комбінація.
|
||||
мовлення, транскрипція в реальному часі, голос у реальному часі, розуміння
|
||||
медіа, генерація зображень, генерація відео, web fetch, web search, інструменти
|
||||
агента або будь-яка комбінація цього.
|
||||
|
||||
Вам не потрібно додавати свій plugin до репозиторію OpenClaw. Опублікуйте його в
|
||||
[ClawHub](/uk/tools/clawhub) або npm, а користувачі встановлять його за допомогою
|
||||
`openclaw plugins install <package-name>`. OpenClaw спочатку пробує ClawHub, а потім
|
||||
автоматично переходить до npm.
|
||||
`openclaw plugins install <package-name>`. OpenClaw спочатку намагається знайти
|
||||
його в ClawHub, а потім автоматично переходить до npm.
|
||||
|
||||
## Передумови
|
||||
|
||||
- Node >= 22 і менеджер пакетів (npm або pnpm)
|
||||
- Знайомство з TypeScript (ESM)
|
||||
- Для plugin у репозиторії: клонований репозиторій і виконано `pnpm install`
|
||||
- Для plugin у репозиторії: клонований репозиторій і виконаний `pnpm install`
|
||||
|
||||
## Який тип plugin?
|
||||
## Який саме plugin?
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Channel plugin" icon="messages-square" href="/uk/plugins/sdk-channel-plugins">
|
||||
Підключає OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо)
|
||||
<Card title="Plugin каналу" icon="messages-square" href="/uk/plugins/sdk-channel-plugins">
|
||||
Підключіть OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо)
|
||||
</Card>
|
||||
<Card title="Provider plugin" icon="cpu" href="/uk/plugins/sdk-provider-plugins">
|
||||
Додає провайдера моделей (LLM, проксі або власну кінцеву точку)
|
||||
<Card title="Plugin провайдера" icon="cpu" href="/uk/plugins/sdk-provider-plugins">
|
||||
Додайте провайдера моделей (LLM, проксі або користувацьку кінцеву точку)
|
||||
</Card>
|
||||
<Card title="Tool / hook plugin" icon="wrench">
|
||||
Реєструє інструменти агента, хуки подій або сервіси — продовжуйте нижче
|
||||
<Card title="Plugin інструмента / hook" icon="wrench">
|
||||
Зареєструйте інструменти агента, hooks подій або сервіси — продовжуйте нижче
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Якщо channel plugin є необов'язковим і може бути не встановлений під час
|
||||
Якщо plugin каналу є необов’язковим і може бути не встановлений під час
|
||||
onboarding/налаштування, використовуйте `createOptionalChannelSetupSurface(...)` з
|
||||
`openclaw/plugin-sdk/channel-setup`. Він створює пару адаптера налаштування та майстра,
|
||||
яка повідомляє про вимогу встановлення і блокує реальний запис конфігурації,
|
||||
доки plugin не буде встановлено.
|
||||
`openclaw/plugin-sdk/channel-setup`. Він створює пару адаптер налаштування +
|
||||
майстер, яка повідомляє про вимогу встановлення й безпечно блокує реальний запис
|
||||
конфігурації, доки plugin не буде встановлено.
|
||||
|
||||
## Швидкий старт: tool plugin
|
||||
## Швидкий старт: plugin інструмента
|
||||
|
||||
У цьому прикладі створюється мінімальний plugin, який реєструє інструмент агента. Для channel
|
||||
і provider plugins є окремі посібники, посилання на які наведено вище.
|
||||
У цьому прикладі створюється мінімальний plugin, який реєструє інструмент
|
||||
агента. Для plugin каналів і провайдерів є окремі посібники за посиланнями
|
||||
вище.
|
||||
|
||||
<Steps>
|
||||
<Step title="Створіть пакет і маніфест">
|
||||
@ -93,9 +94,9 @@ onboarding/налаштування, використовуйте `createOptiona
|
||||
```
|
||||
</CodeGroup>
|
||||
|
||||
Кожному plugin потрібен маніфест, навіть без конфігурації. Дивіться
|
||||
[Manifest](/uk/plugins/manifest) для повної схеми. Канонічні фрагменти для публікації в ClawHub
|
||||
розміщено в `docs/snippets/plugin-publish/`.
|
||||
Кожному plugin потрібен маніфест, навіть без конфігурації. Повну схему див.
|
||||
у [Manifest](/uk/plugins/manifest). Канонічні фрагменти для публікації в ClawHub
|
||||
містяться в `docs/snippets/plugin-publish/`.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -123,15 +124,16 @@ onboarding/налаштування, використовуйте `createOptiona
|
||||
});
|
||||
```
|
||||
|
||||
`definePluginEntry` призначений для plugins, які не є каналами. Для каналів використовуйте
|
||||
`defineChannelPluginEntry` — див. [Channel Plugins](/uk/plugins/sdk-channel-plugins).
|
||||
Повний список параметрів точки входу див. у [Entry Points](/uk/plugins/sdk-entrypoints).
|
||||
`definePluginEntry` використовується для plugin, які не є каналами. Для
|
||||
каналів використовуйте `defineChannelPluginEntry` — див.
|
||||
[Channel Plugins](/uk/plugins/sdk-channel-plugins). Повний перелік параметрів
|
||||
точки входу див. у [Entry Points](/uk/plugins/sdk-entrypoints).
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Протестуйте та опублікуйте">
|
||||
<Step title="Протестуйте й опублікуйте">
|
||||
|
||||
**Зовнішні plugins:** виконайте перевірку та опублікуйте через ClawHub, потім встановіть:
|
||||
**Зовнішні plugins:** перевірте й опублікуйте через ClawHub, потім установіть:
|
||||
|
||||
```bash
|
||||
clawhub package publish your-org/your-plugin --dry-run
|
||||
@ -139,8 +141,8 @@ onboarding/налаштування, використовуйте `createOptiona
|
||||
openclaw plugins install clawhub:@myorg/openclaw-my-plugin
|
||||
```
|
||||
|
||||
OpenClaw також перевіряє ClawHub перед npm для звичайних специфікацій пакетів, як-от
|
||||
`@myorg/openclaw-my-plugin`.
|
||||
OpenClaw також перевіряє ClawHub перед npm для звичайних специфікацій
|
||||
пакетів, таких як `@myorg/openclaw-my-plugin`.
|
||||
|
||||
**Plugins у репозиторії:** розміщуйте їх у дереві робочого простору bundled plugin — вони виявляються автоматично.
|
||||
|
||||
@ -155,10 +157,11 @@ onboarding/налаштування, використовуйте `createOptiona
|
||||
|
||||
Один plugin може зареєструвати будь-яку кількість можливостей через об’єкт `api`:
|
||||
|
||||
| Можливість | Метод реєстрації | Детальний посібник |
|
||||
| ---------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------ |
|
||||
| Текстовий inference (LLM) | `api.registerProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins) |
|
||||
| Канал / обмін повідомленнями | `api.registerChannel(...)` | [Channel Plugins](/uk/plugins/sdk-channel-plugins) |
|
||||
| Можливість | Метод реєстрації | Детальний посібник |
|
||||
| ---------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------- |
|
||||
| Текстовий inference (LLM) | `api.registerProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins) |
|
||||
| Бекенд CLI inference | `api.registerCliBackend(...)` | [CLI Backends](/gateway/cli-backends) |
|
||||
| Канал / обмін повідомленнями | `api.registerChannel(...)` | [Channel Plugins](/uk/plugins/sdk-channel-plugins) |
|
||||
| Мовлення (TTS/STT) | `api.registerSpeechProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
@ -166,43 +169,49 @@ onboarding/налаштування, використовуйте `createOptiona
|
||||
| Генерація зображень | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Генерація музики | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Генерація відео | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Отримання вебсторінок | `api.registerWebFetchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Вебпошук | `api.registerWebSearchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Інструменти агента | `api.registerTool(...)` | Нижче |
|
||||
| Власні команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
|
||||
| Хуки подій | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
|
||||
| HTTP-маршрути | `api.registerHttpRoute(...)` | [Internals](/uk/plugins/architecture#gateway-http-routes) |
|
||||
| Підкоманди CLI | `api.registerCli(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
|
||||
| Web fetch | `api.registerWebFetchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Web search | `api.registerWebSearchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
|
||||
| Інструменти агента | `api.registerTool(...)` | Нижче |
|
||||
| Користувацькі команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
|
||||
| Hooks подій | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
|
||||
| HTTP-маршрути | `api.registerHttpRoute(...)` | [Internals](/uk/plugins/architecture#gateway-http-routes) |
|
||||
| Підкоманди CLI | `api.registerCli(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
|
||||
|
||||
Повний API реєстрації див. у [SDK Overview](/uk/plugins/sdk-overview#registration-api).
|
||||
|
||||
Якщо ваш plugin реєструє власні методи gateway RPC, використовуйте для них
|
||||
префікс, специфічний для plugin. Простори назв адміністрування ядра (`config.*`,
|
||||
Якщо ваш plugin реєструє користувацькі методи gateway RPC, залишайте їх у
|
||||
префіксі, специфічному для plugin. Простори імен адміністрування ядра (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди
|
||||
прив’язуються до `operator.admin`, навіть якщо plugin запитує вужчу область доступу.
|
||||
зіставляються з `operator.admin`, навіть якщо plugin запитує вужчу область
|
||||
доступу.
|
||||
|
||||
Семантика guard для hook, про яку варто пам’ятати:
|
||||
Варто пам’ятати про семантику захисту hooks:
|
||||
|
||||
- `before_tool_call`: `{ block: true }` є остаточним рішенням і зупиняє обробники з нижчим пріоритетом.
|
||||
- `before_tool_call`: `{ block: false }` вважається відсутністю рішення.
|
||||
- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента та запитує схвалення користувача через накладення схвалення exec, кнопки Telegram, інтеракції Discord або команду `/approve` у будь-якому каналі.
|
||||
- `before_install`: `{ block: true }` є остаточним рішенням і зупиняє обробники з нижчим пріоритетом.
|
||||
- `before_install`: `{ block: false }` вважається відсутністю рішення.
|
||||
- `message_sending`: `{ cancel: true }` є остаточним рішенням і зупиняє обробники з нижчим пріоритетом.
|
||||
- `message_sending`: `{ cancel: false }` вважається відсутністю рішення.
|
||||
- `before_tool_call`: `{ block: true }` є термінальним рішенням і зупиняє обробники з нижчим пріоритетом.
|
||||
- `before_tool_call`: `{ block: false }` розглядається як відсутність рішення.
|
||||
- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує схвалення користувача через накладку схвалення exec, кнопки Telegram, інтеракції Discord або команду `/approve` на будь-якому каналі.
|
||||
- `before_install`: `{ block: true }` є термінальним рішенням і зупиняє обробники з нижчим пріоритетом.
|
||||
- `before_install`: `{ block: false }` розглядається як відсутність рішення.
|
||||
- `message_sending`: `{ cancel: true }` є термінальним рішенням і зупиняє обробники з нижчим пріоритетом.
|
||||
- `message_sending`: `{ cancel: false }` розглядається як відсутність рішення.
|
||||
|
||||
Команда `/approve` обробляє і схвалення exec, і схвалення plugin з обмеженим fallback: коли ідентифікатор схвалення exec не знайдено, OpenClaw повторно пробує той самий ідентифікатор через схвалення plugin. Переспрямування схвалень plugin можна налаштувати окремо через `approvals.plugin` у конфігурації.
|
||||
Команда `/approve` обробляє і схвалення exec, і схвалення plugin із обмеженим
|
||||
fallback: коли ідентифікатор схвалення exec не знайдено, OpenClaw повторно
|
||||
пробує той самий ідентифікатор через схвалення plugin. Переспрямування
|
||||
схвалення plugin можна налаштувати окремо через `approvals.plugin` у конфігурації.
|
||||
|
||||
Якщо власній логіці схвалення потрібно виявляти цей самий випадок обмеженого fallback,
|
||||
використовуйте `isApprovalNotFoundError` з `openclaw/plugin-sdk/error-runtime`,
|
||||
замість ручного зіставлення рядків про завершення строку дії схвалення.
|
||||
Якщо користувацька логіка схвалення має виявляти цей самий випадок обмеженого
|
||||
fallback, використовуйте `isApprovalNotFoundError` з
|
||||
`openclaw/plugin-sdk/error-runtime` замість ручного зіставлення рядків
|
||||
про завершення строку дії схвалення.
|
||||
|
||||
Докладніше див. у [семантиці рішень hook в SDK Overview](/uk/plugins/sdk-overview#hook-decision-semantics).
|
||||
Докладніше див. у [SDK Overview hook decision semantics](/uk/plugins/sdk-overview#hook-decision-semantics).
|
||||
|
||||
## Реєстрація інструментів агента
|
||||
|
||||
Інструменти — це типізовані функції, які може викликати LLM. Вони можуть бути обов’язковими (завжди
|
||||
доступними) або необов’язковими (увімкнення користувачем):
|
||||
Інструменти — це типізовані функції, які може викликати LLM. Вони можуть бути
|
||||
обов’язковими (завжди доступними) або необов’язковими (користувач вмикає їх за
|
||||
бажанням):
|
||||
|
||||
```typescript
|
||||
register(api) {
|
||||
@ -239,13 +248,13 @@ register(api) {
|
||||
}
|
||||
```
|
||||
|
||||
- Назви інструментів не повинні конфліктувати з інструментами ядра (конфліктні пропускаються)
|
||||
- Використовуйте `optional: true` для інструментів із побічними ефектами або додатковими вимогами до двійкових файлів
|
||||
- Користувачі можуть увімкнути всі інструменти з plugin, додавши ідентифікатор plugin до `tools.allow`
|
||||
- Назви інструментів не повинні конфліктувати з інструментами ядра (конфлікти пропускаються)
|
||||
- Використовуйте `optional: true` для інструментів із побічними ефектами або додатковими вимогами до бінарних файлів
|
||||
- Користувачі можуть увімкнути всі інструменти plugin, додавши ідентифікатор plugin до `tools.allow`
|
||||
|
||||
## Угоди щодо імпорту
|
||||
## Правила імпорту
|
||||
|
||||
Завжди імпортуйте з цільових шляхів `openclaw/plugin-sdk/<subpath>`:
|
||||
Завжди імпортуйте з вузькоспрямованих шляхів `openclaw/plugin-sdk/<subpath>`:
|
||||
|
||||
```typescript
|
||||
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
|
||||
@ -257,70 +266,72 @@ import { ... } from "openclaw/plugin-sdk";
|
||||
|
||||
Повний довідник підшляхів див. у [SDK Overview](/uk/plugins/sdk-overview).
|
||||
|
||||
Усередині вашого plugin використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для
|
||||
У межах вашого plugin використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для
|
||||
внутрішніх імпортів — ніколи не імпортуйте власний plugin через його шлях SDK.
|
||||
|
||||
Для provider plugins зберігайте допоміжні функції, специфічні для провайдера, у цих barrel-файлах
|
||||
кореня пакета, якщо тільки межа не є справді універсальною. Поточні bundled приклади:
|
||||
Для plugin провайдерів зберігайте допоміжні функції, специфічні для провайдера,
|
||||
у цих barrel-файлах на рівні кореня пакета, якщо лише цей шов не є справді
|
||||
загальним. Поточні bundled-приклади:
|
||||
|
||||
- Anthropic: обгортки потоків Claude і helper-функції для `service_tier` / beta
|
||||
- OpenAI: builder-и провайдерів, helper-и моделей за замовчуванням, провайдери реального часу
|
||||
- OpenRouter: builder провайдера плюс helper-и для onboarding/конфігурації
|
||||
- Anthropic: обгортки потоків Claude і допоміжні функції `service_tier` / beta
|
||||
- OpenAI: збирачі провайдерів, допоміжні функції моделей за замовчуванням, провайдери realtime
|
||||
- OpenRouter: збирач провайдера плюс допоміжні функції onboarding/конфігурації
|
||||
|
||||
Якщо helper корисний лише в межах одного bundled provider package, залишайте його на цій
|
||||
межі кореня пакета замість перенесення до `openclaw/plugin-sdk/*`.
|
||||
Якщо допоміжна функція корисна лише в межах одного bundled-пакета провайдера,
|
||||
залишайте її на цьому шві рівня кореня пакета замість того, щоб переносити її в
|
||||
`openclaw/plugin-sdk/*`.
|
||||
|
||||
Деякі згенеровані helper-межі `openclaw/plugin-sdk/<bundled-id>` усе ще існують для
|
||||
підтримки bundled plugin і сумісності, наприклад
|
||||
`plugin-sdk/feishu-setup` або `plugin-sdk/zalo-setup`. Вважайте їх зарезервованими
|
||||
поверхнями, а не типовим шаблоном для нових сторонніх plugins.
|
||||
Деякі згенеровані шви допоміжних функцій `openclaw/plugin-sdk/<bundled-id>` усе
|
||||
ще існують для підтримки й сумісності bundled-plugin, наприклад
|
||||
`plugin-sdk/feishu-setup` або `plugin-sdk/zalo-setup`. Сприймайте їх як
|
||||
зарезервовані поверхні, а не як типовий шаблон для нових сторонніх plugins.
|
||||
|
||||
## Контрольний список перед надсиланням
|
||||
|
||||
<Check>**package.json** має правильні метадані `openclaw`</Check>
|
||||
<Check>Маніфест **openclaw.plugin.json** присутній і коректний</Check>
|
||||
<Check>**package.json** містить правильні метадані `openclaw`</Check>
|
||||
<Check>Маніфест **openclaw.plugin.json** присутній і валідний</Check>
|
||||
<Check>Точка входу використовує `defineChannelPluginEntry` або `definePluginEntry`</Check>
|
||||
<Check>Усі імпорти використовують цільові шляхи `plugin-sdk/<subpath>`</Check>
|
||||
<Check>Усі імпорти використовують вузькоспрямовані шляхи `plugin-sdk/<subpath>`</Check>
|
||||
<Check>Внутрішні імпорти використовують локальні модулі, а не self-imports через SDK</Check>
|
||||
<Check>Тести проходять (`pnpm test -- <bundled-plugin-root>/my-plugin/`)</Check>
|
||||
<Check>`pnpm check` проходить (для plugins у репозиторії)</Check>
|
||||
<Check>`pnpm check` проходить (для plugin у репозиторії)</Check>
|
||||
|
||||
## Тестування beta-релізів
|
||||
## Тестування бета-релізів
|
||||
|
||||
1. Стежте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Beta-теги мають вигляд `v2026.3.N-beta.1`. Ви також можете ввімкнути сповіщення для офіційного акаунта OpenClaw у X [@openclaw](https://x.com/openclaw) для анонсів релізів.
|
||||
2. Протестуйте свій plugin на beta-тегу щойно він з’явиться. Вікно до stable-релізу зазвичай триває лише кілька годин.
|
||||
3. Після тестування напишіть у гілці вашого plugin у каналі Discord `plugin-forum`: або `all good`, або що саме зламалося. Якщо у вас ще немає гілки, створіть її.
|
||||
4. Якщо щось зламалося, створіть або оновіть issue з назвою `Beta blocker: <plugin-name> - <summary>` і додайте мітку `beta-blocker`. Додайте посилання на issue у вашу гілку.
|
||||
5. Відкрийте PR до `main` з назвою `fix(<plugin-id>): beta blocker - <summary>` і додайте посилання на issue і в PR, і у вашу гілку в Discord. Учасники не можуть додавати мітки до PR, тому назва є сигналом на боці PR для мейнтейнерів та автоматизації. Blocker-и з PR будуть злиті; blocker-и без PR можуть усе ж потрапити в реліз. Мейнтейнери стежать за цими гілками під час beta-тестування.
|
||||
6. Тиша означає, що все добре. Якщо ви пропустите це вікно, ваш виправлення, ймовірно, потрапить уже в наступний цикл.
|
||||
1. Стежте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Бета-теги мають вигляд `v2026.3.N-beta.1`. Ви також можете ввімкнути сповіщення для офіційного акаунта OpenClaw у X [@openclaw](https://x.com/openclaw) для оголошень про релізи.
|
||||
2. Протестуйте свій plugin на бета-тезі щойно він з’явиться. Вікно до стабільного релізу зазвичай становить лише кілька годин.
|
||||
3. Після тестування напишіть у гілці свого plugin в Discord-каналі `plugin-forum`: або `all good`, або що саме зламалося. Якщо у вас ще немає гілки, створіть її.
|
||||
4. Якщо щось зламалося, створіть або оновіть issue з назвою `Beta blocker: <plugin-name> - <summary>` і застосуйте мітку `beta-blocker`. Додайте посилання на issue у свою гілку.
|
||||
5. Відкрийте PR до `main` з назвою `fix(<plugin-id>): beta blocker - <summary>` і додайте посилання на issue і в PR, і у свою Discord-гілку. Учасники не можуть ставити мітки PR, тому назва є сигналом на боці PR для мейнтейнерів та автоматизації. Blockers із PR зливаються; blockers без PR можуть вийти в реліз попри це. Мейнтейнери стежать за цими гілками під час бета-тестування.
|
||||
6. Відсутність повідомлень означає, що все добре. Якщо ви пропустите це вікно, ваш виправлення, імовірно, потрапить до наступного циклу.
|
||||
|
||||
## Подальші кроки
|
||||
## Наступні кроки
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Channel Plugins" icon="messages-square" href="/uk/plugins/sdk-channel-plugins">
|
||||
Створіть plugin для каналу обміну повідомленнями
|
||||
Створіть plugin каналу обміну повідомленнями
|
||||
</Card>
|
||||
<Card title="Provider Plugins" icon="cpu" href="/uk/plugins/sdk-provider-plugins">
|
||||
Створіть plugin для провайдера моделей
|
||||
Створіть plugin провайдера моделей
|
||||
</Card>
|
||||
<Card title="SDK Overview" icon="book-open" href="/uk/plugins/sdk-overview">
|
||||
Довідник з карти імпортів і API реєстрації
|
||||
Довідник карти імпортів і API реєстрації
|
||||
</Card>
|
||||
<Card title="Runtime Helpers" icon="settings" href="/uk/plugins/sdk-runtime">
|
||||
TTS, пошук, subagent через api.runtime
|
||||
TTS, пошук, підлеглий агент через api.runtime
|
||||
</Card>
|
||||
<Card title="Testing" icon="test-tubes" href="/uk/plugins/sdk-testing">
|
||||
Утиліти та шаблони для тестування
|
||||
Утиліти та шаблони тестування
|
||||
</Card>
|
||||
<Card title="Plugin Manifest" icon="file-json" href="/uk/plugins/manifest">
|
||||
Повний довідник зі схеми маніфесту
|
||||
Повний довідник схеми маніфесту
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Plugin Architecture](/uk/plugins/architecture) — детальний розбір внутрішньої архітектури
|
||||
- [Архітектура plugin](/uk/plugins/architecture) — поглиблений розбір внутрішньої архітектури
|
||||
- [SDK Overview](/uk/plugins/sdk-overview) — довідник Plugin SDK
|
||||
- [Manifest](/uk/plugins/manifest) — формат маніфесту plugin
|
||||
- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення channel plugins
|
||||
- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення provider plugins
|
||||
- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — розробка plugin каналів
|
||||
- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — розробка plugin провайдерів
|
||||
|
||||
@ -1,74 +1,76 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви створюєте plugin для OpenClaw
|
||||
- Вам потрібно постачати схему конфігурації plugin або налагодити помилки валідації plugin
|
||||
summary: Вимоги до маніфесту plugin + JSON Schema (сувора валідація конфігурації)
|
||||
title: Маніфест Plugin
|
||||
- Ви створюєте плагін OpenClaw
|
||||
- Вам потрібно постачати schema конфігурації плагіна або налагодити помилки валідації плагіна
|
||||
summary: Маніфест плагіна + вимоги до JSON schema (сувора валідація конфігурації)
|
||||
title: Маніфест плагіна
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T00:52:57Z"
|
||||
generated_at: "2026-04-06T12:44:47Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f6f915a761cdb5df77eba5d2ccd438c65445bd2ab41b0539d1200e63e8cf2c3a
|
||||
source_hash: 15f70fd171d1aad334f01272e035e9a322a4c5c8a983180e6c38f4298b9e9158
|
||||
source_path: plugins/manifest.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Маніфест plugin (`openclaw.plugin.json`)
|
||||
# Маніфест плагіна (openclaw.plugin.json)
|
||||
|
||||
Ця сторінка стосується лише **нативного маніфесту plugin OpenClaw**.
|
||||
Ця сторінка стосується лише **власного маніфесту плагіна OpenClaw**.
|
||||
|
||||
Сумісні макети bundle описано тут: [Набори plugin](/uk/plugins/bundles).
|
||||
Сумісні макети bundle описано в [Plugin bundles](/uk/plugins/bundles).
|
||||
|
||||
Сумісні формати bundle використовують інші файли маніфесту:
|
||||
|
||||
- bundle Codex: `.codex-plugin/plugin.json`
|
||||
- bundle Claude: `.claude-plugin/plugin.json` або типовий макет компонента Claude
|
||||
- Codex bundle: `.codex-plugin/plugin.json`
|
||||
- Claude bundle: `.claude-plugin/plugin.json` або стандартний макет компонента Claude
|
||||
без маніфесту
|
||||
- bundle Cursor: `.cursor-plugin/plugin.json`
|
||||
- Cursor bundle: `.cursor-plugin/plugin.json`
|
||||
|
||||
OpenClaw також автоматично визначає ці макети bundle, але вони не проходять
|
||||
валідацію за схемою `openclaw.plugin.json`, описаною тут.
|
||||
OpenClaw також автоматично виявляє ці макети bundle, але вони не проходять валідацію
|
||||
за schema `openclaw.plugin.json`, описаною тут.
|
||||
|
||||
Для сумісних bundle OpenClaw зараз читає метадані bundle, а також оголошені
|
||||
корені Skills, корені команд Claude, типові значення `settings.json` bundle Claude,
|
||||
типові значення LSP bundle Claude і підтримувані набори hooks, якщо макет
|
||||
відповідає очікуванням середовища виконання OpenClaw.
|
||||
Для сумісних bundle OpenClaw наразі зчитує метадані bundle разом із оголошеними
|
||||
коренями Skills, коренями команд Claude, типових значеннях Claude bundle `settings.json`,
|
||||
типових значеннях Claude bundle LSP і підтримуваних наборах hook, коли макет відповідає
|
||||
очікуванням середовища виконання OpenClaw.
|
||||
|
||||
Кожен нативний plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у
|
||||
**корені plugin**. OpenClaw використовує цей маніфест, щоб валідувати конфігурацію
|
||||
**без виконання коду plugin**. Відсутні або невалідні маніфести вважаються
|
||||
помилками plugin і блокують валідацію конфігурації.
|
||||
Кожен власний плагін OpenClaw **має** постачатися з файлом `openclaw.plugin.json` у
|
||||
**корені плагіна**. OpenClaw використовує цей маніфест для валідації конфігурації
|
||||
**без виконання коду плагіна**. Відсутні або недійсні маніфести вважаються
|
||||
помилками плагіна і блокують валідацію конфігурації.
|
||||
|
||||
Повний посібник із системи plugin дивіться тут: [Plugins](/uk/tools/plugin).
|
||||
Щодо нативної моделі можливостей і актуальних рекомендацій із зовнішньої сумісності:
|
||||
[Модель можливостей](/uk/plugins/architecture#public-capability-model).
|
||||
Дивіться повний посібник із системи плагінів: [Plugins](/uk/tools/plugin).
|
||||
Для моделі власних можливостей і поточних рекомендацій щодо зовнішньої сумісності:
|
||||
[Capability model](/uk/plugins/architecture#public-capability-model).
|
||||
|
||||
## Що робить цей файл
|
||||
|
||||
`openclaw.plugin.json` — це метадані, які OpenClaw читає перед завантаженням коду
|
||||
вашого plugin.
|
||||
`openclaw.plugin.json` — це метадані, які OpenClaw зчитує перед завантаженням
|
||||
коду вашого плагіна.
|
||||
|
||||
Використовуйте його для:
|
||||
|
||||
- ідентичності plugin
|
||||
- ідентичності плагіна
|
||||
- валідації конфігурації
|
||||
- метаданих auth і онбордингу, які мають бути доступні без запуску середовища виконання plugin
|
||||
- метаданих псевдонімів і автоувімкнення, які мають визначатися до завантаження середовища виконання plugin
|
||||
- скорочених метаданих належності до сімейств моделей, які мають автоматично активувати
|
||||
plugin до завантаження середовища виконання
|
||||
- статичних знімків належності можливостей, що використовуються для сумісної логіки bundled plugin і
|
||||
- метаданих автентифікації та онбордингу, які мають бути доступні без запуску
|
||||
середовища виконання плагіна
|
||||
- метаданих псевдонімів і автоувімкнення, які мають визначатися до завантаження
|
||||
середовища виконання плагіна
|
||||
- метаданих володіння скороченими сімействами моделей, які мають автоматично
|
||||
активувати плагін до завантаження середовища виконання
|
||||
- статичних знімків володіння можливостями, що використовуються для вбудованої compat-обв’язки та
|
||||
покриття контрактів
|
||||
- метаданих конфігурації, специфічних для channel, які мають об’єднуватися в поверхні каталогу та валідації
|
||||
- метаданих конфігурації каналів, специфічних для каналу, які мають зливатися в поверхні каталогу та валідації
|
||||
без завантаження середовища виконання
|
||||
- підказок UI для конфігурації
|
||||
- підказок UI конфігурації
|
||||
|
||||
Не використовуйте його для:
|
||||
|
||||
- реєстрації поведінки середовища виконання
|
||||
- оголошення code entrypoints
|
||||
- оголошення code entrypoint
|
||||
- метаданих встановлення npm
|
||||
|
||||
Для цього призначені код plugin і `package.json`.
|
||||
Для цього призначені код вашого плагіна та `package.json`.
|
||||
|
||||
## Мінімальний приклад
|
||||
|
||||
@ -89,12 +91,13 @@ OpenClaw також автоматично визначає ці макети bu
|
||||
{
|
||||
"id": "openrouter",
|
||||
"name": "OpenRouter",
|
||||
"description": "OpenRouter provider plugin",
|
||||
"description": "Плагін провайдера OpenRouter",
|
||||
"version": "1.0.0",
|
||||
"providers": ["openrouter"],
|
||||
"modelSupport": {
|
||||
"modelPrefixes": ["router-"]
|
||||
},
|
||||
"cliBackends": ["openrouter-cli"],
|
||||
"providerAuthEnvVars": {
|
||||
"openrouter": ["OPENROUTER_API_KEY"]
|
||||
},
|
||||
@ -103,19 +106,19 @@ OpenClaw також автоматично визначає ці макети bu
|
||||
"provider": "openrouter",
|
||||
"method": "api-key",
|
||||
"choiceId": "openrouter-api-key",
|
||||
"choiceLabel": "OpenRouter API key",
|
||||
"choiceLabel": "Ключ API OpenRouter",
|
||||
"groupId": "openrouter",
|
||||
"groupLabel": "OpenRouter",
|
||||
"optionKey": "openrouterApiKey",
|
||||
"cliFlag": "--openrouter-api-key",
|
||||
"cliOption": "--openrouter-api-key <key>",
|
||||
"cliDescription": "OpenRouter API key",
|
||||
"cliDescription": "Ключ API OpenRouter",
|
||||
"onboardingScopes": ["text-inference"]
|
||||
}
|
||||
],
|
||||
"uiHints": {
|
||||
"apiKey": {
|
||||
"label": "API key",
|
||||
"label": "Ключ API",
|
||||
"placeholder": "sk-or-v1-...",
|
||||
"sensitive": true
|
||||
}
|
||||
@ -134,61 +137,62 @@ OpenClaw також автоматично визначає ці макети bu
|
||||
|
||||
## Довідник полів верхнього рівня
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `id` | Так | `string` | Канонічний id plugin. Це id, що використовується в `plugins.entries.<id>`. |
|
||||
| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього plugin. |
|
||||
| `enabledByDefault` | Ні | `true` | Позначає bundled plugin як увімкнений типово. Не вказуйте це поле або встановіть будь-яке значення, відмінне від `true`, щоб plugin був типово вимкнений. |
|
||||
| `legacyPluginIds` | Ні | `string[]` | Застарілі id, що нормалізуються до цього канонічного id plugin. |
|
||||
| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id provider, які мають автоматично вмикати цей plugin, коли auth, конфігурація або посилання на моделі згадують їх. |
|
||||
| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує виключний тип plugin, що використовується `plugins.slots.*`. |
|
||||
| `channels` | Ні | `string[]` | Id channel, що належать цьому plugin. Використовується для виявлення та валідації конфігурації. |
|
||||
| `providers` | Ні | `string[]` | Id provider, що належать цьому plugin. |
|
||||
| `modelSupport` | Ні | `object` | Скорочені метадані сімейств моделей, що належать маніфесту й використовуються для автоматичного завантаження plugin до запуску середовища виконання. |
|
||||
| `providerAuthEnvVars` | Ні | `Record<string, string[]>` | Недорогі метадані env для auth provider, які OpenClaw може перевіряти без завантаження коду plugin. |
|
||||
| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані варіантів auth для селекторів онбордингу, визначення preferred provider і простого зв’язування CLI flags. |
|
||||
| `contracts` | Ні | `object` | Статичний bundled-знімок можливостей для speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і належності tools. |
|
||||
| `channelConfigs` | Ні | `Record<string, object>` | Метадані конфігурації channel, що належать маніфесту та об’єднуються з поверхнями виявлення й валідації до завантаження середовища виконання. |
|
||||
| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня plugin. |
|
||||
| `name` | Ні | `string` | Зрозуміла людині назва plugin. |
|
||||
| `description` | Ні | `string` | Короткий опис, що відображається в поверхнях plugin. |
|
||||
| `version` | Ні | `string` | Інформаційна версія plugin. |
|
||||
| `uiHints` | Ні | `Record<string, object>` | Мітки UI, placeholder-и та підказки чутливості для полів конфігурації. |
|
||||
| Field | Required | Type | What it means |
|
||||
| ----------------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `id` | Yes | `string` | Канонічний id плагіна. Це id, який використовується в `plugins.entries.<id>`. |
|
||||
| `configSchema` | Yes | `object` | Вбудована JSON Schema для конфігурації цього плагіна. |
|
||||
| `enabledByDefault` | No | `true` | Позначає вбудований плагін як увімкнений типово. Пропустіть його або задайте будь-яке значення, відмінне від `true`, щоб залишити плагін вимкненим типово. |
|
||||
| `legacyPluginIds` | No | `string[]` | Застарілі id, які нормалізуються до цього канонічного id плагіна. |
|
||||
| `autoEnableWhenConfiguredProviders` | No | `string[]` | Id провайдерів, які мають автоматично вмикати цей плагін, коли на них посилаються автентифікація, конфігурація або model ref. |
|
||||
| `kind` | No | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип плагіна, який використовується `plugins.slots.*`. |
|
||||
| `channels` | No | `string[]` | Id каналів, якими володіє цей плагін. Використовується для виявлення та валідації конфігурації. |
|
||||
| `providers` | No | `string[]` | Id провайдерів, якими володіє цей плагін. |
|
||||
| `modelSupport` | No | `object` | Метадані скорочених сімейств моделей, що належать маніфесту та використовуються для автоматичного завантаження плагіна до середовища виконання. |
|
||||
| `cliBackends` | No | `string[]` | Id CLI-бекендів inference, якими володіє цей плагін. Використовується для автоактивації під час запуску на основі явних посилань у конфігурації. |
|
||||
| `providerAuthEnvVars` | No | `Record<string, string[]>` | Легкі метадані env автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду плагіна. |
|
||||
| `providerAuthChoices` | No | `object[]` | Легкі метадані варіантів автентифікації для онбординг-пікерів, визначення preferred-provider та простого зв’язування прапорців CLI. |
|
||||
| `contracts` | No | `object` | Статичний знімок вбудованих можливостей для speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. |
|
||||
| `channelConfigs` | No | `Record<string, object>` | Метадані конфігурації каналу, що належать маніфесту та зливаються в поверхні виявлення та валідації до завантаження середовища виконання. |
|
||||
| `skills` | No | `string[]` | Каталоги Skills для завантаження, відносно кореня плагіна. |
|
||||
| `name` | No | `string` | Людинозрозуміла назва плагіна. |
|
||||
| `description` | No | `string` | Короткий опис, який показується в поверхнях плагіна. |
|
||||
| `version` | No | `string` | Інформаційна версія плагіна. |
|
||||
| `uiHints` | No | `Record<string, object>` | Мітки UI, placeholder і підказки щодо чутливості для полів конфігурації. |
|
||||
|
||||
## Довідник `providerAuthChoices`
|
||||
|
||||
Кожен запис `providerAuthChoices` описує один варіант онбордингу або auth.
|
||||
OpenClaw читає це до завантаження середовища виконання provider.
|
||||
Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації.
|
||||
OpenClaw зчитує це до завантаження середовища виконання провайдера.
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| -------------------- | ----------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| `provider` | Так | `string` | Id provider, до якого належить цей варіант. |
|
||||
| `method` | Так | `string` | Id методу auth, за яким виконується маршрутизація. |
|
||||
| `choiceId` | Так | `string` | Стабільний id варіанта auth, що використовується в онбордингу та потоках CLI. |
|
||||
| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. |
|
||||
| `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. |
|
||||
| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних селекторах, керованих асистентом. |
|
||||
| `assistantVisibility`| Ні | `"visible"` \| `"manual-only"` | Приховує варіант у селекторах асистента, але залишає можливість ручного вибору через CLI. |
|
||||
| `deprecatedChoiceIds`| Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів на цей варіант-заміну. |
|
||||
| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. |
|
||||
| `groupLabel` | Ні | `string` | Мітка цієї групи для користувача. |
|
||||
| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. |
|
||||
| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків auth з одним flag. |
|
||||
| `cliFlag` | Ні | `string` | Назва CLI flag, наприклад `--openrouter-api-key`. |
|
||||
| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key <key>`. |
|
||||
| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. |
|
||||
| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. |
|
||||
| Field | Required | Type | What it means |
|
||||
| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `provider` | Yes | `string` | Id провайдера, до якого належить цей варіант. |
|
||||
| `method` | Yes | `string` | Id методу автентифікації, до якого слід маршрутизувати. |
|
||||
| `choiceId` | Yes | `string` | Стабільний id варіанта автентифікації, який використовується в онбордингу та CLI-потоках. |
|
||||
| `choiceLabel` | No | `string` | Мітка для користувача. Якщо пропущено, OpenClaw використовує `choiceId`. |
|
||||
| `choiceHint` | No | `string` | Короткий допоміжний текст для пікера. |
|
||||
| `assistantPriority` | No | `number` | Менші значення сортуються раніше в інтерактивних пікерах, керованих помічником. |
|
||||
| `assistantVisibility` | No | `"visible"` \| `"manual-only"` | Ховає варіант із пікерів помічника, але все ще дозволяє ручний вибір у CLI. |
|
||||
| `deprecatedChoiceIds` | No | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів на цей варіант-заміну. |
|
||||
| `groupId` | No | `string` | Необов’язковий id групи для групування пов’язаних варіантів. |
|
||||
| `groupLabel` | No | `string` | Мітка цієї групи для користувача. |
|
||||
| `groupHint` | No | `string` | Короткий допоміжний текст для групи. |
|
||||
| `optionKey` | No | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. |
|
||||
| `cliFlag` | No | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. |
|
||||
| `cliOption` | No | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key <key>`. |
|
||||
| `cliDescription` | No | `string` | Опис, який використовується в довідці CLI. |
|
||||
| `onboardingScopes` | No | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо пропущено, типово використовується `["text-inference"]`. |
|
||||
|
||||
## Довідник `uiHints`
|
||||
|
||||
`uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу.
|
||||
`uiHints` — це мапа імен полів конфігурації до невеликих підказок рендерингу.
|
||||
|
||||
```json
|
||||
{
|
||||
"uiHints": {
|
||||
"apiKey": {
|
||||
"label": "API key",
|
||||
"help": "Used for OpenRouter requests",
|
||||
"label": "Ключ API",
|
||||
"help": "Використовується для запитів OpenRouter",
|
||||
"placeholder": "sk-or-v1-...",
|
||||
"sensitive": true
|
||||
}
|
||||
@ -196,9 +200,9 @@ OpenClaw читає це до завантаження середовища ви
|
||||
}
|
||||
```
|
||||
|
||||
Кожна підказка поля може містити:
|
||||
Підказка кожного поля може містити:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| Field | Type | What it means |
|
||||
| ------------- | ---------- | --------------------------------------- |
|
||||
| `label` | `string` | Мітка поля для користувача. |
|
||||
| `help` | `string` | Короткий допоміжний текст. |
|
||||
@ -209,8 +213,8 @@ OpenClaw читає це до завантаження середовища ви
|
||||
|
||||
## Довідник `contracts`
|
||||
|
||||
Використовуйте `contracts` лише для статичних метаданих належності можливостей, які OpenClaw може
|
||||
прочитати без імпорту середовища виконання plugin.
|
||||
Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може
|
||||
зчитати без імпортування середовища виконання плагіна.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -228,23 +232,23 @@ OpenClaw читає це до завантаження середовища ви
|
||||
}
|
||||
```
|
||||
|
||||
Кожен список необов’язковий:
|
||||
Кожен список є необов’язковим:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| -------------------------------- | ---------- | ----------------------------------------------------------- |
|
||||
| `speechProviders` | `string[]` | Id provider speech, що належать цьому plugin. |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | Id provider realtime-transcription, що належать цьому plugin. |
|
||||
| `realtimeVoiceProviders` | `string[]` | Id provider realtime-voice, що належать цьому plugin. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | Id provider media-understanding, що належать цьому plugin. |
|
||||
| `imageGenerationProviders` | `string[]` | Id provider image-generation, що належать цьому plugin. |
|
||||
| `videoGenerationProviders` | `string[]` | Id provider video-generation, що належать цьому plugin. |
|
||||
| `webFetchProviders` | `string[]` | Id provider web-fetch, що належать цьому plugin. |
|
||||
| `webSearchProviders` | `string[]` | Id provider web-search, що належать цьому plugin. |
|
||||
| `tools` | `string[]` | Назви agent tools, що належать цьому plugin для перевірок bundled-контрактів. |
|
||||
| Field | Type | What it means |
|
||||
| -------------------------------- | ---------- | -------------------------------------------------------------- |
|
||||
| `speechProviders` | `string[]` | Id провайдерів speech, якими володіє цей плагін. |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | Id провайдерів realtime-transcription, якими володіє цей плагін. |
|
||||
| `realtimeVoiceProviders` | `string[]` | Id провайдерів realtime-voice, якими володіє цей плагін. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | Id провайдерів media-understanding, якими володіє цей плагін. |
|
||||
| `imageGenerationProviders` | `string[]` | Id провайдерів image-generation, якими володіє цей плагін. |
|
||||
| `videoGenerationProviders` | `string[]` | Id провайдерів video-generation, якими володіє цей плагін. |
|
||||
| `webFetchProviders` | `string[]` | Id провайдерів web-fetch, якими володіє цей плагін. |
|
||||
| `webSearchProviders` | `string[]` | Id провайдерів web-search, якими володіє цей плагін. |
|
||||
| `tools` | `string[]` | Назви інструментів агента, якими володіє цей плагін, для перевірок вбудованих контрактів. |
|
||||
|
||||
## Довідник `channelConfigs`
|
||||
|
||||
Використовуйте `channelConfigs`, коли plugin channel потребує недорогих метаданих конфігурації до
|
||||
Використовуйте `channelConfigs`, коли плагіну каналу потрібні легкі метадані конфігурації до
|
||||
завантаження середовища виконання.
|
||||
|
||||
```json
|
||||
@ -260,32 +264,32 @@ OpenClaw читає це до завантаження середовища ви
|
||||
},
|
||||
"uiHints": {
|
||||
"homeserverUrl": {
|
||||
"label": "Homeserver URL",
|
||||
"label": "URL homeserver",
|
||||
"placeholder": "https://matrix.example.com"
|
||||
}
|
||||
},
|
||||
"label": "Matrix",
|
||||
"description": "Matrix homeserver connection",
|
||||
"description": "Підключення до homeserver Matrix",
|
||||
"preferOver": ["matrix-legacy"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Кожен запис channel може містити:
|
||||
Кожен запис каналу може містити:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
|
||||
| `schema` | `object` | JSON Schema для `channels.<id>`. Обов’язкова для кожного оголошеного запису конфігурації channel. |
|
||||
| `uiHints` | `Record<string, object>` | Необов’язкові мітки UI/placeholder-и/підказки чутливості для цього розділу конфігурації channel. |
|
||||
| `label` | `string` | Мітка channel, що об’єднується з поверхнями вибору та перевірки, коли метадані середовища виконання ще не готові. |
|
||||
| `description` | `string` | Короткий опис channel для поверхонь перевірки та каталогу. |
|
||||
| `preferOver` | `string[]` | Застарілі або нижчого пріоритету id plugin, які цей channel має випереджати в поверхнях вибору. |
|
||||
| Field | Type | What it means |
|
||||
| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
|
||||
| `schema` | `object` | JSON Schema для `channels.<id>`. Обов’язкове для кожного оголошеного запису конфігурації каналу. |
|
||||
| `uiHints` | `Record<string, object>` | Необов’язкові мітки UI/placeholder/підказки щодо чутливості для цього розділу конфігурації каналу. |
|
||||
| `label` | `string` | Мітка каналу, що зливається в поверхні пікера та inspect, коли метадані середовища виконання ще не готові. |
|
||||
| `description` | `string` | Короткий опис каналу для поверхонь inspect і каталогу. |
|
||||
| `preferOver` | `string[]` | Id застарілих або менш пріоритетних плагінів, які цей канал має випереджати в поверхнях вибору. |
|
||||
|
||||
## Довідник `modelSupport`
|
||||
|
||||
Використовуйте `modelSupport`, коли OpenClaw має визначати ваш plugin provider за
|
||||
скороченими id моделей, як-от `gpt-5.4` або `claude-sonnet-4.6`, до завантаження середовища виконання plugin.
|
||||
Використовуйте `modelSupport`, коли OpenClaw має визначати ваш плагін провайдера з
|
||||
коротких id моделей, таких як `gpt-5.4` або `claude-sonnet-4.6`, до завантаження середовища виконання плагіна.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -296,76 +300,76 @@ OpenClaw читає це до завантаження середовища ви
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw застосовує такий пріоритет:
|
||||
OpenClaw застосовує таку пріоритетність:
|
||||
|
||||
- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать власнику
|
||||
- `modelPatterns` мають вищий пріоритет, ніж `modelPrefixes`
|
||||
- якщо збігаються один небандлований plugin і один bundled plugin, перемагає небандлований
|
||||
plugin
|
||||
- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть provider
|
||||
- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать відповідному плагіну
|
||||
- `modelPatterns` мають вищий пріоритет за `modelPrefixes`
|
||||
- якщо збігаються один невбудований плагін і один вбудований плагін, перемагає невбудований
|
||||
плагін
|
||||
- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкаже провайдера
|
||||
|
||||
Поля:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| --------------- | ---------- | -------------------------------------------------------------------------------- |
|
||||
| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими id моделей. |
|
||||
| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими id моделей після видалення суфікса профілю. |
|
||||
| Field | Type | What it means |
|
||||
| --------------- | ---------- | ------------------------------------------------------------------------------- |
|
||||
| `modelPrefixes` | `string[]` | Префікси, які перевіряються через `startsWith` для скорочених id моделей. |
|
||||
| `modelPatterns` | `string[]` | Джерела regex, які зіставляються зі скороченими id моделей після видалення суфікса профілю. |
|
||||
|
||||
Застарілі ключі можливостей верхнього рівня не рекомендуються до використання. Використайте `openclaw doctor --fix`, щоб
|
||||
Застарілі ключі можливостей верхнього рівня не рекомендовані. Використовуйте `openclaw doctor --fix`, щоб
|
||||
перемістити `speechProviders`, `realtimeTranscriptionProviders`,
|
||||
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
|
||||
`imageGenerationProviders`, `videoGenerationProviders`,
|
||||
`webFetchProviders` і `webSearchProviders` до `contracts`; звичайне
|
||||
`webFetchProviders` і `webSearchProviders` у `contracts`; звичайне
|
||||
завантаження маніфесту більше не трактує ці поля верхнього рівня як
|
||||
належність можливостей.
|
||||
володіння можливостями.
|
||||
|
||||
## Маніфест і `package.json`
|
||||
## Маніфест і package.json
|
||||
|
||||
Ці два файли виконують різні завдання:
|
||||
Ці два файли виконують різні ролі:
|
||||
|
||||
| Файл | Для чого використовувати |
|
||||
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів auth і підказки UI, які мають існувати до запуску коду plugin |
|
||||
| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для entrypoints, обмежень встановлення, налаштування або метаданих каталогу |
|
||||
| File | Use it for |
|
||||
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду плагіна |
|
||||
| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для entrypoint, обмежень встановлення, налаштування або метаданих каталогу |
|
||||
|
||||
Якщо ви не впевнені, куди має належати певний фрагмент метаданих, користуйтеся таким правилом:
|
||||
Якщо ви не впевнені, де має бути певний фрагмент метаданих, використовуйте таке правило:
|
||||
|
||||
- якщо OpenClaw повинен знати це до завантаження коду plugin, помістіть це в `openclaw.plugin.json`
|
||||
- якщо це стосується пакування, entry files або поведінки встановлення npm, помістіть це в `package.json`
|
||||
- якщо OpenClaw має знати про нього до завантаження коду плагіна, помістіть його в `openclaw.plugin.json`
|
||||
- якщо це стосується пакування, вхідних файлів або поведінки встановлення npm, помістіть це в `package.json`
|
||||
|
||||
### Поля `package.json`, які впливають на виявлення
|
||||
### Поля package.json, які впливають на виявлення
|
||||
|
||||
Деякі метадані plugin до запуску середовища виконання навмисно розміщені в `package.json` у блоці
|
||||
Деякі метадані плагіна для етапу до середовища виконання навмисно зберігаються в `package.json` у блоці
|
||||
`openclaw`, а не в `openclaw.plugin.json`.
|
||||
|
||||
Важливі приклади:
|
||||
|
||||
| Поле | Що воно означає |
|
||||
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.extensions` | Оголошує нативні entrypoints plugin. |
|
||||
| `openclaw.setupEntry` | Легковажний entrypoint лише для налаштування, який використовується під час онбордингу та відкладеного запуску channel. |
|
||||
| `openclaw.channel` | Недорогі метадані каталогу channel, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. |
|
||||
| `openclaw.channel.configuredState` | Недорогі метадані перевірки налаштованого стану, які можуть відповісти на питання "чи вже існує налаштування лише через env?" без завантаження повного середовища виконання channel. |
|
||||
| `openclaw.channel.persistedAuthState` | Недорогі метадані перевірки збереженого auth, які можуть відповісти на питання "чи вже є активний вхід?" без завантаження повного середовища виконання channel. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення bundled plugin і externally published plugin. |
|
||||
| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
|
||||
| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw з використанням нижньої межі semver, наприклад `>=2026.3.22`. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення bundled plugin, коли конфігурація невалідна. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для налаштування завантажуватися до повного plugin channel під час запуску. |
|
||||
| Field | What it means |
|
||||
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.extensions` | Оголошує власні entrypoint плагіна. |
|
||||
| `openclaw.setupEntry` | Легкий entrypoint лише для налаштування, який використовується під час онбордингу та відкладеного запуску каналу. |
|
||||
| `openclaw.channel` | Легкі метадані каталогу каналів, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. |
|
||||
| `openclaw.channel.configuredState` | Легкі метадані перевірки configured-state, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного середовища виконання каналу. |
|
||||
| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки persisted-auth, які можуть відповісти на запитання «чи вже щось увійшло в систему?» без завантаження повного середовища виконання каналу. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих плагінів. |
|
||||
| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
|
||||
| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw, із нижньою межею semver, наприклад `>=2026.3.22`. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення вбудованого плагіна, коли конфігурація недійсна. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для налаштування завантажуватися до повного плагіна каналу під час запуску. |
|
||||
|
||||
`openclaw.install.minHostVersion` застосовується під час встановлення та
|
||||
завантаження реєстру маніфесту. Невалідні значення відхиляються; новіші, але валідні
|
||||
значення пропускають plugin на старіших хостах.
|
||||
завантаження реєстру маніфестів. Недійсні значення відхиляються; новіші, але коректні значення пропускають
|
||||
плагін на старіших хостах.
|
||||
|
||||
`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке призначення. Воно
|
||||
не робить довільно зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє потокам встановлення
|
||||
відновлюватися після конкретних застарілих збоїв оновлення bundled plugin, наприклад
|
||||
відсутнього шляху до bundled plugin або застарілого запису `channels.<id>` для того самого
|
||||
bundled plugin. Не пов’язані помилки конфігурації все одно блокують встановлення і направляють операторів
|
||||
не робить довільні зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє
|
||||
потокам встановлення відновлюватися після певних застарілих збоїв оновлення вбудованих плагінів, таких як
|
||||
відсутній шлях до вбудованого плагіна або застарілий запис `channels.<id>` для цього самого
|
||||
вбудованого плагіна. Непов’язані помилки конфігурації й далі блокують встановлення та спрямовують операторів
|
||||
до `openclaw doctor --fix`.
|
||||
|
||||
`openclaw.channel.persistedAuthState` — це метадані package для маленького
|
||||
модуля перевірки:
|
||||
`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля
|
||||
перевірки:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -381,13 +385,13 @@ bundled plugin. Не пов’язані помилки конфігурації
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте це, коли потокам setup, doctor або configured-state потрібна недорога
|
||||
перевірка auth у форматі yes/no до завантаження повного plugin channel. Цільовий export має бути невеликою
|
||||
функцією, яка читає лише збережений стан; не маршрутизуйте її через повний
|
||||
barrel середовища виконання channel.
|
||||
Використовуйте це, коли потокам setup, doctor або configured-state потрібна легка
|
||||
yes/no перевірка автентифікації до завантаження повного плагіна каналу. Цільовий експорт має бути невеликою
|
||||
функцією, яка зчитує лише збережений стан; не маршрутизуйте її через повний barrel середовища виконання
|
||||
каналу.
|
||||
|
||||
`openclaw.channel.configuredState` має таку саму форму для недорогих перевірок
|
||||
налаштованого стану лише через env:
|
||||
`openclaw.channel.configuredState` має ту саму форму для легких перевірок
|
||||
configured-state лише через env:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -403,59 +407,59 @@ barrel середовища виконання channel.
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте це, коли channel може визначити налаштований стан із env або інших малих
|
||||
неruntime-джерел. Якщо перевірка потребує повного розв’язання конфігурації або реального
|
||||
середовища виконання channel, залиште цю логіку в hook `config.hasConfiguredState`
|
||||
plugin.
|
||||
Використовуйте це, коли канал може визначити configured-state через env або інші малі
|
||||
невиконувані входи. Якщо перевірці потрібне повне визначення конфігурації або реальне
|
||||
середовище виконання каналу, залиште цю логіку в hook `config.hasConfiguredState`
|
||||
плагіна.
|
||||
|
||||
## Вимоги до JSON Schema
|
||||
|
||||
- **Кожен plugin повинен містити JSON Schema**, навіть якщо він не приймає конфігурацію.
|
||||
- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`).
|
||||
- Схеми валідуються під час читання/запису конфігурації, а не під час виконання.
|
||||
- **Кожен плагін має постачати JSON Schema**, навіть якщо він не приймає конфігурацію.
|
||||
- Порожня schema прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`).
|
||||
- Schema проходять валідацію під час читання/запису конфігурації, а не під час виконання.
|
||||
|
||||
## Поведінка валідації
|
||||
|
||||
- Невідомі ключі `channels.*` є **помилками**, якщо тільки id channel не оголошено
|
||||
маніфестом plugin.
|
||||
- Невідомі ключі `channels.*` є **помилками**, якщо тільки id каналу не оголошено
|
||||
маніфестом плагіна.
|
||||
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` і `plugins.slots.*`
|
||||
повинні посилатися на **виявлювані** id plugin. Невідомі id є **помилками**.
|
||||
- Якщо plugin встановлено, але має зламаний або відсутній маніфест чи схему,
|
||||
валідація завершується помилкою, а Doctor повідомляє про помилку plugin.
|
||||
- Якщо конфігурація plugin існує, але plugin **вимкнено**, конфігурація зберігається,
|
||||
а в Doctor і журналах відображається **попередження**.
|
||||
мають посилатися на **виявлювані** id плагінів. Невідомі id є **помилками**.
|
||||
- Якщо плагін встановлено, але його маніфест або schema зламані чи відсутні,
|
||||
валідація завершується помилкою, і Doctor повідомляє про помилку плагіна.
|
||||
- Якщо конфігурація плагіна існує, але плагін **вимкнено**, конфігурація зберігається, і
|
||||
в Doctor + логах показується **попередження**.
|
||||
|
||||
Повну схему `plugins.*` дивіться в [Довіднику з конфігурації](/uk/gateway/configuration).
|
||||
Дивіться [Configuration reference](/uk/gateway/configuration), щоб переглянути повну schema `plugins.*`.
|
||||
|
||||
## Примітки
|
||||
|
||||
- Маніфест **обов’язковий для нативних plugin OpenClaw**, включно із завантаженням із локальної файлової системи.
|
||||
- Середовище виконання, як і раніше, завантажує модуль plugin окремо; маніфест призначений лише для
|
||||
- Маніфест **обов’язковий для власних плагінів OpenClaw**, зокрема для локальних завантажень із файлової системи.
|
||||
- Середовище виконання й далі завантажує модуль плагіна окремо; маніфест використовується лише для
|
||||
виявлення + валідації.
|
||||
- Нативні маніфести розбираються за допомогою JSON5, тому коментарі, завершаючі коми та
|
||||
ключі без лапок допускаються, якщо фінальне значення все одно є object.
|
||||
- Власні маніфести розбираються за допомогою JSON5, тож коментарі, кінцеві коми та
|
||||
ключі без лапок приймаються, якщо фінальне значення все ще є об’єктом.
|
||||
- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте додавання
|
||||
власних ключів верхнього рівня сюди.
|
||||
- `providerAuthEnvVars` — це недорогий шлях метаданих для перевірок auth, валідації маркерів env
|
||||
та подібних поверхонь auth provider, які не повинні запускати середовище виконання plugin
|
||||
- `providerAuthEnvVars` — це легкий шлях метаданих для перевірок автентифікації, валідації
|
||||
env-маркерів і подібних поверхонь автентифікації провайдера, які не повинні запускати середовище виконання плагіна
|
||||
лише для перевірки назв env.
|
||||
- `providerAuthChoices` — це недорогий шлях метаданих для селекторів варіантів auth,
|
||||
визначення `--auth-choice`, мапінгу preferred provider і простої реєстрації CLI flags
|
||||
для онбордингу до завантаження середовища виконання provider. Метадані wizard середовища виконання,
|
||||
що потребують коду provider, дивіться в
|
||||
[Hooks середовища виконання provider](/uk/plugins/architecture#provider-runtime-hooks).
|
||||
- Виключні типи plugin вибираються через `plugins.slots.*`.
|
||||
- `providerAuthChoices` — це легкий шлях метаданих для пікерів варіантів автентифікації,
|
||||
визначення `--auth-choice`, мапінгу preferred-provider і простої реєстрації прапорців CLI
|
||||
до завантаження середовища виконання провайдера. Для метаданих wizard у середовищі виконання,
|
||||
яким потрібен код провайдера, дивіться
|
||||
[Provider runtime hooks](/uk/plugins/architecture#provider-runtime-hooks).
|
||||
- Ексклюзивні типи плагінів вибираються через `plugins.slots.*`.
|
||||
- `kind: "memory"` вибирається через `plugins.slots.memory`.
|
||||
- `kind: "context-engine"` вибирається через `plugins.slots.contextEngine`
|
||||
(типово: вбудований `legacy`).
|
||||
- `channels`, `providers` і `skills` можна не вказувати, якщо
|
||||
plugin їх не потребує.
|
||||
- Якщо ваш plugin залежить від нативних модулів, задокументуйте кроки збирання та будь-які
|
||||
вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts`
|
||||
- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо
|
||||
плагіну вони не потрібні.
|
||||
- Якщо ваш плагін залежить від власних модулів, задокументуйте кроки збирання та будь-які
|
||||
вимоги до allowlist пакетного менеджера (наприклад, pnpm `allow-build-scripts`
|
||||
- `pnpm rebuild <package>`).
|
||||
|
||||
## Пов’язані сторінки
|
||||
## Пов’язане
|
||||
|
||||
- [Створення Plugins](/uk/plugins/building-plugins) — початок роботи з plugins
|
||||
- [Архітектура Plugin](/uk/plugins/architecture) — внутрішня архітектура
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — довідник Plugin SDK
|
||||
- [Building Plugins](/uk/plugins/building-plugins) — початок роботи з плагінами
|
||||
- [Plugin Architecture](/uk/plugins/architecture) — внутрішня архітектура
|
||||
- [SDK Overview](/uk/plugins/sdk-overview) — довідник Plugin SDK
|
||||
|
||||
@ -1,33 +1,33 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібно знати, з якого підшляху SDK імпортувати
|
||||
- Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi
|
||||
- Ви хочете мати довідник для всіх методів реєстрації в OpenClawPluginApi
|
||||
- Ви шукаєте конкретний експорт SDK
|
||||
sidebarTitle: SDK Overview
|
||||
summary: Карта імпортів, довідник API реєстрації та архітектура SDK
|
||||
title: Огляд Plugin SDK
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T12:17:16Z"
|
||||
generated_at: "2026-04-06T12:45:46Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6dfd7a632101c2f6da8ba43b3cb4e673794ebaed00908ae897059fe115782f54
|
||||
source_hash: e045097753f33d13d570f6ce5297d2a7c0f0ad8b31515d0d9021386c8004354c
|
||||
source_path: plugins/sdk-overview.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Огляд Plugin SDK
|
||||
|
||||
Plugin SDK — це типізований контракт між plugins і core. Ця сторінка є
|
||||
довідником щодо **що імпортувати** і **що можна реєструвати**.
|
||||
Plugin SDK — це типізований контракт між plugins і ядром. Ця сторінка є
|
||||
довідником про **що імпортувати** і **що можна зареєструвати**.
|
||||
|
||||
<Tip>
|
||||
**Шукаєте практичний посібник?**
|
||||
- Перший plugin? Почніть із [Getting Started](/uk/plugins/building-plugins)
|
||||
- Channel plugin? Дивіться [Channel Plugins](/uk/plugins/sdk-channel-plugins)
|
||||
- Provider plugin? Дивіться [Provider Plugins](/uk/plugins/sdk-provider-plugins)
|
||||
- Plugin каналу? Див. [Channel Plugins](/uk/plugins/sdk-channel-plugins)
|
||||
- Plugin провайдера? Див. [Provider Plugins](/uk/plugins/sdk-provider-plugins)
|
||||
</Tip>
|
||||
|
||||
## Угода щодо імпорту
|
||||
## Правило імпорту
|
||||
|
||||
Завжди імпортуйте з конкретного підшляху:
|
||||
|
||||
@ -36,318 +36,318 @@ 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`
|
||||
для ширшої узагальненої поверхні та спільних допоміжних функцій, таких як
|
||||
каналів допоміжних функцій точки входу/збирання віддавайте перевагу
|
||||
`openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для
|
||||
ширшої umbrella-поверхні та спільних допоміжних функцій, таких як
|
||||
`buildChannelConfigSchema`.
|
||||
|
||||
Не додавайте і не використовуйте іменовані за provider зручні шари, такі як
|
||||
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
|
||||
Не додавайте і не використовуйте convenience-шви, названі на честь провайдерів,
|
||||
такі як `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
|
||||
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, або
|
||||
допоміжні шари з брендуванням channel. Bundled plugins мають компонувати
|
||||
загальні підшляхи SDK у власних barrels `api.ts` або `runtime-api.ts`, а core
|
||||
має або використовувати ці локальні barrels plugin, або додавати вузький
|
||||
загальний контракт SDK, коли потреба справді є міжканальною.
|
||||
допоміжні шви з брендингом каналів. Bundled plugins мають комбінувати загальні
|
||||
підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а ядро
|
||||
має або використовувати ці plugin-локальні barrel-файли, або додавати вузький
|
||||
загальний контракт SDK, якщо потреба справді є міжканальною.
|
||||
|
||||
Згенерована карта експортів усе ще містить невеликий набір допоміжних шарів
|
||||
Згенерована карта експортів усе ще містить невеликий набір допоміжних швів для
|
||||
bundled-plugin, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
|
||||
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Ці
|
||||
підшляхи існують лише для підтримки bundled-plugin і сумісності; їх навмисно
|
||||
не включено до загальної таблиці нижче, і вони не є рекомендованим шляхом
|
||||
не включено до спільної таблиці нижче, і вони не є рекомендованим шляхом
|
||||
імпорту для нових сторонніх plugins.
|
||||
|
||||
## Довідник підшляхів
|
||||
|
||||
Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список із
|
||||
понад 200 підшляхів знаходиться в `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`.
|
||||
|
||||
Зарезервовані допоміжні підшляхи bundled-plugin усе ще з’являються в цьому
|
||||
згенерованому списку. Розглядайте їх як деталі реалізації або поверхні
|
||||
сумісності, якщо тільки сторінка документації явно не позначає одну з них як
|
||||
публічну.
|
||||
згенерованому списку. Вважайте їх деталями реалізації/поверхнями сумісності,
|
||||
якщо лише якась сторінка документації явно не оголошує один із них публічним.
|
||||
|
||||
### Вхід plugin
|
||||
### Точка входу plugin
|
||||
|
||||
| Subpath | Ключові експорти |
|
||||
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
|
||||
| Підшлях | Ключові експорти |
|
||||
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
|
||||
| `plugin-sdk/config-schema` | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/config-schema` | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Підшляхи каналів">
|
||||
| Subpath | Ключові експорти |
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `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` | Спільні допоміжні функції майстра налаштування, запити allowlist, збирачі статусу налаштування |
|
||||
| `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` | Допоміжні функції для конфігурації та action gate мультиакаунтів, допоміжні функції fallback для акаунта за замовчуванням |
|
||||
| `plugin-sdk/account-core` | Допоміжні функції багатoакаунтної конфігурації/керування обмеженнями дій, допоміжні функції fallback для акаунта за замовчуванням |
|
||||
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні функції нормалізації account-id |
|
||||
| `plugin-sdk/account-resolution` | Допоміжні функції пошуку акаунта + fallback до акаунта за замовчуванням |
|
||||
| `plugin-sdk/account-helpers` | Вузькі допоміжні функції для списку акаунтів/дій із акаунтами |
|
||||
| `plugin-sdk/account-resolution` | Пошук акаунта + допоміжні функції fallback за замовчуванням |
|
||||
| `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 із fallback на bundled contract |
|
||||
| `plugin-sdk/channel-config-schema` | Типи схеми конфігурації каналу |
|
||||
| `plugin-sdk/telegram-command-config` | Допоміжні функції нормалізації/валідації користувацьких команд Telegram із fallback на bundled-contract |
|
||||
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
|
||||
| `plugin-sdk/inbound-envelope` | Спільні допоміжні функції маршрутизації вхідних подій + побудови envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні функції запису й диспетчеризації вхідних повідомлень |
|
||||
| `plugin-sdk/messaging-targets` | Допоміжні функції розбору/зіставлення target |
|
||||
| `plugin-sdk/inbound-envelope` | Спільні допоміжні функції вхідних маршрутів + побудови envelope |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні функції запису й диспетчеризації вхідних подій |
|
||||
| `plugin-sdk/messaging-targets` | Допоміжні функції розбору/зіставлення цілей |
|
||||
| `plugin-sdk/outbound-media` | Спільні допоміжні функції завантаження вихідних медіа |
|
||||
| `plugin-sdk/outbound-runtime` | Допоміжні функції для вихідної ідентичності та send delegate |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Допоміжні функції життєвого циклу та адаптерів thread-binding |
|
||||
| `plugin-sdk/agent-media-payload` | Застарілий builder payload медіа агента |
|
||||
| `plugin-sdk/conversation-runtime` | Допоміжні функції прив’язки conversation/thread, pairing і configured-binding |
|
||||
| `plugin-sdk/outbound-runtime` | Допоміжні функції вихідної ідентичності/делегата надсилання |
|
||||
| `plugin-sdk/thread-bindings-runtime` | Життєвий цикл thread-binding і допоміжні функції адаптера |
|
||||
| `plugin-sdk/agent-media-payload` | Legacy-збирач медіапейлоада агента |
|
||||
| `plugin-sdk/conversation-runtime` | Допоміжні функції прив’язки розмови/thread, pairing і configured-binding |
|
||||
| `plugin-sdk/runtime-config-snapshot` | Допоміжна функція snapshot конфігурації runtime |
|
||||
| `plugin-sdk/runtime-group-policy` | Допоміжні функції визначення policy груп під час runtime |
|
||||
| `plugin-sdk/channel-status` | Спільні допоміжні функції snapshot/summary статусу каналу |
|
||||
| `plugin-sdk/channel-config-primitives` | Вузькі примітиви schema конфігурації каналу |
|
||||
| `plugin-sdk/runtime-group-policy` | Допоміжні функції розв’язання групової політики runtime |
|
||||
| `plugin-sdk/channel-status` | Спільні допоміжні функції snapshot/summary стану каналу |
|
||||
| `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу |
|
||||
| `plugin-sdk/channel-config-writes` | Допоміжні функції авторизації запису конфігурації каналу |
|
||||
| `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти channel plugin |
|
||||
| `plugin-sdk/allowlist-config-edit` | Допоміжні функції редагування/читання конфігурації allowlist |
|
||||
| `plugin-sdk/group-access` | Спільні допоміжні функції рішень щодо доступу груп |
|
||||
| `plugin-sdk/direct-dm` | Спільні допоміжні функції авторизації/захисту direct-DM |
|
||||
| `plugin-sdk/interactive-runtime` | Допоміжні функції нормалізації/зведення payload інтерактивних відповідей |
|
||||
| `plugin-sdk/allowlist-config-edit` | Допоміжні функції читання/редагування конфігурації allowlist |
|
||||
| `plugin-sdk/group-access` | Спільні допоміжні функції рішень щодо групового доступу |
|
||||
| `plugin-sdk/direct-dm` | Спільні допоміжні функції auth/guard для direct-DM |
|
||||
| `plugin-sdk/interactive-runtime` | Допоміжні функції нормалізації/скорочення інтерактивного reply payload |
|
||||
| `plugin-sdk/channel-inbound` | Debounce, зіставлення згадок, допоміжні функції envelope |
|
||||
| `plugin-sdk/channel-send-result` | Типи результатів reply |
|
||||
| `plugin-sdk/channel-send-result` | Типи результату reply |
|
||||
| `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
|
||||
| `plugin-sdk/channel-targets` | Допоміжні функції розбору/зіставлення target |
|
||||
| `plugin-sdk/channel-contract` | Типи контрактів channel |
|
||||
| `plugin-sdk/channel-feedback` | Налаштування feedback/reaction |
|
||||
| `plugin-sdk/channel-targets` | Допоміжні функції розбору/зіставлення цілей |
|
||||
| `plugin-sdk/channel-contract` | Типи контракту каналу |
|
||||
| `plugin-sdk/channel-feedback` | Зв’язування feedback/reaction |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи provider">
|
||||
| Subpath | Ключові експорти |
|
||||
<Accordion title="Підшляхи провайдерів">
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/provider-setup` | Кураторські допоміжні функції налаштування локальних/self-hosted provider |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні функції налаштування self-hosted provider, сумісних з OpenAI |
|
||||
| `plugin-sdk/provider-auth-runtime` | Допоміжні функції визначення API key під час runtime для provider plugins |
|
||||
| `plugin-sdk/provider-auth-api-key` | Допоміжні функції onboarding/profile-write для API key, такі як `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | Стандартний builder auth-result для OAuth |
|
||||
| `plugin-sdk/provider-auth-login` | Спільні допоміжні функції інтерактивного входу для provider plugins |
|
||||
| `plugin-sdk/provider-env-vars` | Допоміжні функції пошуку env vars для авторизації provider |
|
||||
| `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 провайдерів |
|
||||
| `plugin-sdk/provider-auth-api-key` | Допоміжні функції onboarding/запису профілю API-ключа, такі як `upsertApiKeyProfile` |
|
||||
| `plugin-sdk/provider-auth-result` | Стандартний збирач результату OAuth auth |
|
||||
| `plugin-sdk/provider-auth-login` | Спільні допоміжні функції інтерактивного входу для plugin провайдерів |
|
||||
| `plugin-sdk/provider-env-vars` | Допоміжні функції пошуку змінних середовища для auth провайдера |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
|
||||
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні builder-и replay-policy, допоміжні функції endpoint provider і нормалізації 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/capability endpoint provider |
|
||||
| `plugin-sdk/provider-web-fetch` | Допоміжні функції реєстрації/кешування provider web-fetch |
|
||||
| `plugin-sdk/provider-web-search` | Допоміжні функції реєстрації/кешування/конфігурації provider web-search |
|
||||
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика, а також допоміжні функції сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні |
|
||||
| `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`, типи stream wrapper і спільні допоміжні функції wrapper для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
|
||||
| `plugin-sdk/provider-onboard` | Допоміжні функції patch конфігурації onboarding |
|
||||
| `plugin-sdk/provider-onboard` | Допоміжні функції виправлення конфігурації onboarding |
|
||||
| `plugin-sdk/global-singleton` | Допоміжні функції process-local singleton/map/cache |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи авторизації та безпеки">
|
||||
| Subpath | Ключові експорти |
|
||||
<Accordion title="Підшляхи auth і безпеки">
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні функції реєстру команд, допоміжні функції авторизації відправника |
|
||||
| `plugin-sdk/approval-auth-runtime` | Допоміжні функції визначення approver та action-auth у тому ж чаті |
|
||||
| `plugin-sdk/approval-client-runtime` | Допоміжні функції профілю/фільтра native exec approval |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Адаптери native approval capability/delivery |
|
||||
| `plugin-sdk/approval-auth-runtime` | Допоміжні функції розв’язання approver і auth дій у межах того самого чату |
|
||||
| `plugin-sdk/approval-client-runtime` | Допоміжні функції native exec approval profile/filter |
|
||||
| `plugin-sdk/approval-delivery-runtime` | Native-адаптери можливостей/доставки approval |
|
||||
| `plugin-sdk/approval-native-runtime` | Допоміжні функції native approval target + account-binding |
|
||||
| `plugin-sdk/approval-reply-runtime` | Допоміжні функції payload відповіді на approval exec/plugin |
|
||||
| `plugin-sdk/command-auth-native` | Допоміжні функції native command auth + native session-target |
|
||||
| `plugin-sdk/command-detection` | Спільні допоміжні функції визначення команд |
|
||||
| `plugin-sdk/command-surface` | Нормалізація тіла команди та допоміжні функції command-surface |
|
||||
| `plugin-sdk/approval-reply-runtime` | Допоміжні функції reply payload для approval exec/plugin |
|
||||
| `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, external-content і збору секретів |
|
||||
| `plugin-sdk/security-runtime` | Спільні допоміжні функції довіри, обмеження DM, зовнішнього контенту та збирання секретів |
|
||||
| `plugin-sdk/ssrf-policy` | Допоміжні функції allowlist хостів і політики SSRF для приватних мереж |
|
||||
| `plugin-sdk/ssrf-runtime` | Допоміжні функції pinned-dispatcher, fetch із захистом SSRF та політики SSRF |
|
||||
| `plugin-sdk/ssrf-runtime` | Допоміжні функції pinned-dispatcher, fetch із захистом SSRF і політики SSRF |
|
||||
| `plugin-sdk/secret-input` | Допоміжні функції розбору secret input |
|
||||
| `plugin-sdk/webhook-ingress` | Допоміжні функції webhook request/target |
|
||||
| `plugin-sdk/webhook-request-guards` | Допоміжні функції для розміру body request/timeout |
|
||||
| `plugin-sdk/webhook-request-guards` | Допоміжні функції розміру тіла request/тайм-ауту |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи runtime і сховища">
|
||||
| Subpath | Ключові експорти |
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/runtime` | Широка поверхня допоміжних функцій runtime/logging/backup/plugin-install |
|
||||
| `plugin-sdk/runtime-env` | Вузькі допоміжні функції runtime env, logger, timeout, retry і backoff |
|
||||
| `plugin-sdk/runtime` | Широкі допоміжні функції runtime/логування/резервних копій/встановлення plugin |
|
||||
| `plugin-sdk/runtime-env` | Вузькі допоміжні функції env runtime, logger, timeout, retry і backoff |
|
||||
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні допоміжні функції для команд/hook/http/interactive plugin |
|
||||
| `plugin-sdk/hook-runtime` | Спільні допоміжні функції pipeline для webhook/internal hook |
|
||||
| `plugin-sdk/lazy-runtime` | Допоміжні функції lazy import/binding runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Допоміжні функції exec процесів |
|
||||
| `plugin-sdk/cli-runtime` | Допоміжні функції форматування CLI, wait і version |
|
||||
| `plugin-sdk/gateway-runtime` | Допоміжні функції клієнта gateway і patch статусу каналу |
|
||||
| `plugin-sdk/plugin-runtime` | Спільні допоміжні функції plugin command/hook/http/interactive |
|
||||
| `plugin-sdk/hook-runtime` | Спільні допоміжні функції webhook та внутрішнього hook pipeline |
|
||||
| `plugin-sdk/lazy-runtime` | Допоміжні функції lazy-імпорту/binding runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | Допоміжні функції виконання process |
|
||||
| `plugin-sdk/cli-runtime` | Допоміжні функції форматування CLI, очікування та версій |
|
||||
| `plugin-sdk/gateway-runtime` | Допоміжні функції клієнта Gateway і виправлення статусу каналу |
|
||||
| `plugin-sdk/config-runtime` | Допоміжні функції завантаження/запису конфігурації |
|
||||
| `plugin-sdk/telegram-command-config` | Нормалізація назви/опису команд Telegram і перевірки на дублікати/конфлікти, навіть коли поверхня bundled Telegram contract недоступна |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні функції approval exec/plugin, builder-и approval capability, допоміжні функції auth/profile, допоміжні функції native routing/runtime |
|
||||
| `plugin-sdk/reply-runtime` | Спільні допоміжні функції runtime для inbound/reply, chunking, dispatch, heartbeat, planner reply |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції dispatch/finalize reply |
|
||||
| `plugin-sdk/reply-history` | Спільні допоміжні функції коротковіконної history reply, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/telegram-command-config` | Нормалізація імен/описів команд Telegram та перевірки дублікатів/конфліктів, навіть коли bundled Telegram contract surface недоступна |
|
||||
| `plugin-sdk/approval-runtime` | Допоміжні функції approval exec/plugin, збирачі approval-capability, auth/profile, native routing/runtime helpers |
|
||||
| `plugin-sdk/reply-runtime` | Спільні допоміжні функції runtime для inbound/reply, chunking, dispatch, heartbeat, планувальник reply |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції dispatch/finalize для reply |
|
||||
| `plugin-sdk/reply-history` | Спільні допоміжні функції короткого вікна історії reply, такі як `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/state-paths` | Допоміжні функції шляхів до каталогів state/OAuth |
|
||||
| `plugin-sdk/routing` | Допоміжні функції route/session-key/account binding, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` |
|
||||
| `plugin-sdk/status-helpers` | Спільні допоміжні функції summary статусу channel/account, значення runtime-state за замовчуванням і допоміжні функції метаданих issue |
|
||||
| `plugin-sdk/target-resolver-runtime` | Спільні допоміжні функції визначення target |
|
||||
| `plugin-sdk/string-normalization-runtime` | Допоміжні функції нормалізації slug/string |
|
||||
| `plugin-sdk/request-url` | Витягування URL-адрес рядків із fetch/request-like input |
|
||||
| `plugin-sdk/run-command` | Запуск команд із таймером і нормалізованими результатами stdout/stderr |
|
||||
| `plugin-sdk/param-readers` | Загальні читачі параметрів tool/CLI |
|
||||
| `plugin-sdk/tool-send` | Витягування канонічних полів target відправлення з аргументів tool |
|
||||
| `plugin-sdk/temp-path` | Спільні допоміжні функції шляхів до тимчасових завантажень |
|
||||
| `plugin-sdk/logging-core` | Допоміжні функції subsystem logger і redaction |
|
||||
| `plugin-sdk/markdown-table-runtime` | Допоміжні функції режиму таблиць Markdown |
|
||||
| `plugin-sdk/json-store` | Невеликі допоміжні функції читання/запису JSON state |
|
||||
| `plugin-sdk/file-lock` | Допоміжні функції повторно-вхідного file-lock |
|
||||
| `plugin-sdk/persistent-dedupe` | Допоміжні функції дискового dedupe cache |
|
||||
| `plugin-sdk/status-helpers` | Спільні допоміжні функції summary стану каналу/акаунта, типові значення runtime-state і допоміжні функції метаданих issues |
|
||||
| `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` | Витягування канонічних полів цілі надсилання з аргументів інструмента |
|
||||
| `plugin-sdk/temp-path` | Спільні допоміжні функції шляхів тимчасових завантажень |
|
||||
| `plugin-sdk/logging-core` | Допоміжні функції subsystem logger і редагування чутливих даних |
|
||||
| `plugin-sdk/markdown-table-runtime` | Допоміжні функції режиму markdown-таблиць |
|
||||
| `plugin-sdk/json-store` | Невеликі допоміжні функції читання/запису JSON-стану |
|
||||
| `plugin-sdk/file-lock` | Допоміжні функції повторно вхідного file-lock |
|
||||
| `plugin-sdk/persistent-dedupe` | Допоміжні функції disk-backed dedupe cache |
|
||||
| `plugin-sdk/acp-runtime` | Допоміжні функції ACP runtime/session і reply-dispatch |
|
||||
| `plugin-sdk/agent-config-primitives` | Вузькі примітиви schema конфігурації runtime агента |
|
||||
| `plugin-sdk/boolean-param` | Нестрогий читач boolean-параметрів |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Допоміжні функції визначення збігу небезпечних імен |
|
||||
| `plugin-sdk/device-bootstrap` | Допоміжні функції device bootstrap і токенів pairing |
|
||||
| `plugin-sdk/extension-shared` | Спільні примітиви для passive-channel і допоміжні функції статусу |
|
||||
| `plugin-sdk/models-provider-runtime` | Допоміжні функції відповіді `/models` command/provider |
|
||||
| `plugin-sdk/skill-commands-runtime` | Допоміжні функції переліку команд Skills |
|
||||
| `plugin-sdk/native-command-registry` | Допоміжні функції реєстру/build/serialize native commands |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Допоміжні функції визначення endpoint Z.A.I |
|
||||
| `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime агента |
|
||||
| `plugin-sdk/boolean-param` | Зчитувач нечітких boolean-параметрів |
|
||||
| `plugin-sdk/dangerous-name-runtime` | Допоміжні функції розв’язання збігів небезпечних імен |
|
||||
| `plugin-sdk/device-bootstrap` | Допоміжні функції bootstrap пристрою та токенів pairing |
|
||||
| `plugin-sdk/extension-shared` | Спільні примітиви пасивного каналу та допоміжні функції статусу |
|
||||
| `plugin-sdk/models-provider-runtime` | Допоміжні функції команд `/models` і reply провайдера |
|
||||
| `plugin-sdk/skill-commands-runtime` | Допоміжні функції виведення списку skill-команд |
|
||||
| `plugin-sdk/native-command-registry` | Допоміжні функції native command registry/build/serialize |
|
||||
| `plugin-sdk/provider-zai-endpoint` | Допоміжні функції виявлення endpoint Z.AI |
|
||||
| `plugin-sdk/infra-runtime` | Допоміжні функції system event/heartbeat |
|
||||
| `plugin-sdk/collection-runtime` | Невеликі допоміжні функції обмеженого cache |
|
||||
| `plugin-sdk/collection-runtime` | Невеликі допоміжні функції обмеженого кешу |
|
||||
| `plugin-sdk/diagnostic-runtime` | Допоміжні функції діагностичних прапорців і подій |
|
||||
| `plugin-sdk/error-runtime` | Граф помилок, форматування, спільні допоміжні функції класифікації помилок, `isApprovalNotFoundError` |
|
||||
| `plugin-sdk/fetch-runtime` | Допоміжні функції wrapped fetch, proxy і pinned lookup |
|
||||
| `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` | Запит до каталогу на основі config/dedup |
|
||||
| `plugin-sdk/retry-runtime` | Допоміжні функції конфігурації retry і виконавця retry |
|
||||
| `plugin-sdk/agent-runtime` | Допоміжні функції dir/identity/workspace агента |
|
||||
| `plugin-sdk/directory-runtime` | Запит/дедуплікація каталогів на основі конфігурації |
|
||||
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи можливостей і тестування">
|
||||
| Subpath | Ключові експорти |
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/media-runtime` | Спільні допоміжні функції fetch/transform/store медіа плюс builder-и payload медіа |
|
||||
| `plugin-sdk/media-generation-runtime` | Спільні допоміжні функції failover для генерації медіа, вибір candidate і повідомлення про відсутню модель |
|
||||
| `plugin-sdk/media-understanding` | Типи provider для розуміння медіа плюс експорти допоміжних функцій для provider для зображень/аудіо |
|
||||
| `plugin-sdk/text-runtime` | Спільні допоміжні функції для text/markdown/logging, такі як видалення видимого асистенту тексту, рендеринг/chunking/table helpers markdown, redaction helpers, directive-tag helpers і safe-text utilities |
|
||||
| `plugin-sdk/media-runtime` | Спільні допоміжні функції fetch/transform/store медіа плюс збирачі media payload |
|
||||
| `plugin-sdk/media-generation-runtime` | Спільні допоміжні функції failover генерації медіа, вибору кандидатів і повідомлень про відсутню модель |
|
||||
| `plugin-sdk/media-understanding` | Типи провайдера розуміння медіа плюс експорти допоміжних функцій зображень/аудіо для провайдерів |
|
||||
| `plugin-sdk/text-runtime` | Спільні допоміжні функції тексту/markdown/логування, такі як видалення видимого для асистента тексту, рендер/chunking/table helpers для markdown, допоміжні функції редагування чутливих даних, тегів директив і safe-text utilities |
|
||||
| `plugin-sdk/text-chunking` | Допоміжна функція chunking вихідного тексту |
|
||||
| `plugin-sdk/speech` | Типи speech provider плюс експорти допоміжних функцій для provider для directive, registry і validation |
|
||||
| `plugin-sdk/speech-core` | Спільні типи speech provider, registry, directive і допоміжні функції normalізації |
|
||||
| `plugin-sdk/realtime-transcription` | Типи provider для realtime transcription і допоміжні функції registry |
|
||||
| `plugin-sdk/realtime-voice` | Типи provider для realtime voice і допоміжні функції registry |
|
||||
| `plugin-sdk/image-generation` | Типи provider для генерації зображень |
|
||||
| `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, failover, auth і допоміжні функції registry |
|
||||
| `plugin-sdk/music-generation` | Типи provider/request/result для генерації музики |
|
||||
| `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні функції failover, пошуку provider і розбору model-ref |
|
||||
| `plugin-sdk/video-generation` | Типи provider/request/result для генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні функції failover, пошуку provider і розбору model-ref |
|
||||
| `plugin-sdk/webhook-targets` | Допоміжні функції реєстру webhook target і встановлення route |
|
||||
| `plugin-sdk/speech` | Типи speech-провайдера плюс експорти допоміжних функцій директив, реєстру та валідації для провайдерів |
|
||||
| `plugin-sdk/speech-core` | Спільні типи speech-провайдера, реєстр, директиви та допоміжні функції нормалізації |
|
||||
| `plugin-sdk/realtime-transcription` | Типи провайдера транскрипції в реальному часі та допоміжні функції реєстру |
|
||||
| `plugin-sdk/realtime-voice` | Типи провайдера голосу в реальному часі та допоміжні функції реєстру |
|
||||
| `plugin-sdk/image-generation` | Типи провайдера генерації зображень |
|
||||
| `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, failover, auth і допоміжні функції реєстру |
|
||||
| `plugin-sdk/music-generation` | Типи провайдера/запиту/результату генерації музики |
|
||||
| `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні функції failover, пошуку провайдера та розбору model-ref |
|
||||
| `plugin-sdk/video-generation` | Типи провайдера/запиту/результату генерації відео |
|
||||
| `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні функції failover, пошуку провайдера та розбору model-ref |
|
||||
| `plugin-sdk/webhook-targets` | Допоміжні функції реєстру webhook target і встановлення маршрутів |
|
||||
| `plugin-sdk/webhook-path` | Допоміжні функції нормалізації шляху webhook |
|
||||
| `plugin-sdk/web-media` | Спільні допоміжні функції завантаження віддалених/локальних медіа |
|
||||
| `plugin-sdk/zod` | Повторно експортований `zod` для споживачів plugin SDK |
|
||||
| `plugin-sdk/zod` | Повторний експорт `zod` для користувачів Plugin SDK |
|
||||
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи memory">
|
||||
| Subpath | Ключові експорти |
|
||||
<Accordion title="Підшляхи пам’яті">
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `plugin-sdk/memory-core` | Допоміжна поверхня bundled memory-core для manager/config/file/CLI helpers |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Runtime facade індексування/пошуку memory |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine memory host |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Експорти embedding engine memory host |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine memory host |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine memory host |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Допоміжні функції multimodal memory host |
|
||||
| `plugin-sdk/memory-core-host-query` | Допоміжні функції query memory host |
|
||||
| `plugin-sdk/memory-core-host-secret` | Допоміжні функції secret memory host |
|
||||
| `plugin-sdk/memory-core-host-events` | Допоміжні функції журналу подій memory host |
|
||||
| `plugin-sdk/memory-core-host-status` | Допоміжні функції status memory host |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні функції CLI runtime memory host |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Допоміжні функції core runtime memory host |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Допоміжні функції file/runtime memory host |
|
||||
| `plugin-sdk/memory-host-core` | Нейтральний до вендора alias для допоміжних функцій core runtime memory host |
|
||||
| `plugin-sdk/memory-host-events` | Нейтральний до вендора alias для допоміжних функцій журналу подій memory host |
|
||||
| `plugin-sdk/memory-host-files` | Нейтральний до вендора alias для допоміжних функцій file/runtime memory host |
|
||||
| `plugin-sdk/memory-host-markdown` | Спільні допоміжні функції managed-markdown для plugins, суміжних із memory |
|
||||
| `plugin-sdk/memory-host-search` | Активна runtime facade memory для доступу до search-manager |
|
||||
| `plugin-sdk/memory-host-status` | Нейтральний до вендора alias для допоміжних функцій status memory host |
|
||||
| `plugin-sdk/memory-lancedb` | Допоміжна поверхня bundled memory-lancedb |
|
||||
| `plugin-sdk/memory-core` | Поверхня допоміжних функцій bundled memory-core для менеджера/конфігурації/файлів/CLI |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Runtime-фасад індексації/пошуку в пам’яті |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста пам’яті |
|
||||
| `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` | Допоміжні функції multimodal хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-query` | Допоміжні функції запитів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-secret` | Допоміжні функції секретів хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-events` | Допоміжні функції журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-status` | Допоміжні функції статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні функції runtime CLI хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Допоміжні функції core runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Допоміжні функції файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-core` | Вендорно-нейтральний псевдонім для допоміжних функцій core runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-events` | Вендорно-нейтральний псевдонім для допоміжних функцій журналу подій хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-files` | Вендорно-нейтральний псевдонім для допоміжних функцій файлів/runtime хоста пам’яті |
|
||||
| `plugin-sdk/memory-host-markdown` | Спільні допоміжні функції керованого markdown для plugins, суміжних із пам’яттю |
|
||||
| `plugin-sdk/memory-host-search` | Активний runtime-фасад пам’яті для доступу до search-manager |
|
||||
| `plugin-sdk/memory-host-status` | Вендорно-нейтральний псевдонім для допоміжних функцій статусу хоста пам’яті |
|
||||
| `plugin-sdk/memory-lancedb` | Поверхня допоміжних функцій bundled memory-lancedb |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Зарезервовані підшляхи bundled-helper">
|
||||
| Family | Поточні підшляхи | Призначення |
|
||||
| Сімейство | Поточні підшляхи | Призначення |
|
||||
| --- | --- | --- |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні функції підтримки bundled browser plugin (`browser-support` залишається barrel сумісності) |
|
||||
| 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 surface bundled Matrix |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Допоміжна/runtime surface bundled LINE |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Допоміжна surface bundled IRC |
|
||||
| Channel-specific helpers | `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` | Шари сумісності/допоміжні шари bundled channel |
|
||||
| Auth/plugin-specific helpers | `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` | Допоміжні шари bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` |
|
||||
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні функції підтримки bundled browser plugin (`browser-support` лишається barrel-файлом сумісності) |
|
||||
| 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 bundled Matrix |
|
||||
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних функцій/runtime bundled LINE |
|
||||
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних функцій bundled 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` | Шви сумісності/допоміжні шви bundled-каналів |
|
||||
| Допоміжні функції для 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` | Допоміжні шви bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## API реєстрації
|
||||
|
||||
Callback `register(api)` отримує об’єкт `OpenClawPluginApi` із такими
|
||||
Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими
|
||||
методами:
|
||||
|
||||
### Реєстрація можливостей
|
||||
|
||||
| Method | Що реєструє |
|
||||
| ------------------------------------------------ | ------------------------------- |
|
||||
| `api.registerProvider(...)` | Текстове виведення (LLM) |
|
||||
| Метод | Що реєструє |
|
||||
| ----------------------------------------------- | ------------------------------- |
|
||||
| `api.registerProvider(...)` | Текстовий inference (LLM) |
|
||||
| `api.registerCliBackend(...)` | Локальний backend CLI inference |
|
||||
| `api.registerChannel(...)` | Канал обміну повідомленнями |
|
||||
| `api.registerSpeechProvider(...)` | Text-to-speech / STT synthesis |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція realtime |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Двобічні голосові сесії realtime |
|
||||
| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT |
|
||||
| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі |
|
||||
| `api.registerRealtimeVoiceProvider(...)` | Двосторонні голосові сесії в реальному часі |
|
||||
| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео |
|
||||
| `api.registerImageGenerationProvider(...)` | Генерація зображень |
|
||||
| `api.registerMusicGenerationProvider(...)` | Генерація музики |
|
||||
| `api.registerVideoGenerationProvider(...)` | Генерація відео |
|
||||
| `api.registerWebFetchProvider(...)` | Provider для web fetch / scrape |
|
||||
| `api.registerWebSearchProvider(...)` | Пошук у вебі |
|
||||
| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape |
|
||||
| `api.registerWebSearchProvider(...)` | Web search |
|
||||
|
||||
### Інструменти та команди
|
||||
|
||||
| Method | Що реєструє |
|
||||
| ------------------------------- | -------------------------------------------- |
|
||||
| Метод | Що реєструє |
|
||||
| ------------------------------ | -------------------------------------------- |
|
||||
| `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) |
|
||||
| `api.registerCommand(def)` | Користувацька команда (обходить LLM) |
|
||||
| `api.registerCommand(def)` | Користувацьку команду (в оминання LLM) |
|
||||
|
||||
### Інфраструктура
|
||||
|
||||
| Method | Що реєструє |
|
||||
| ---------------------------------------------- | -------------------------------------- |
|
||||
| `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)` | Інтерактивний обробник |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із memory |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний corpus пошуку/читання memory |
|
||||
| Метод | Що реєструє |
|
||||
| --------------------------------------------- | ------------------------------------ |
|
||||
| `api.registerHook(events, handler, opts?)` | Hook події |
|
||||
| `api.registerHttpRoute(params)` | HTTP-ендпойнт Gateway |
|
||||
| `api.registerGatewayMethod(name, handler)` | Метод Gateway RPC |
|
||||
| `api.registerCli(registrar, opts?)` | Підкоманду CLI |
|
||||
| `api.registerService(service)` | Фоновий сервіс |
|
||||
| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник |
|
||||
| `api.registerMemoryPromptSupplement(builder)` | Додатковий розділ prompt, суміжний із пам’яттю |
|
||||
| `api.registerMemoryCorpusSupplement(adapter)` | Додатковий корпус пошуку/читання пам’яті |
|
||||
|
||||
Зарезервовані простори імен адміністратора core (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) завжди залишаються `operator.admin`, навіть якщо plugin намагається призначити
|
||||
вужчу область gateway method. Віддавайте перевагу префіксам, специфічним для plugin, для
|
||||
методів, що належать plugin.
|
||||
Зарезервовані простори імен адміністрування ядра (`config.*`, `exec.approvals.*`,
|
||||
`wizard.*`, `update.*`) завжди залишаються `operator.admin`, навіть якщо plugin
|
||||
намагається призначити методу gateway вужчу область доступу. Для методів, що
|
||||
належать plugin, віддавайте перевагу специфічним для plugin префіксам.
|
||||
|
||||
### Метадані реєстрації CLI
|
||||
|
||||
`api.registerCli(registrar, opts?)` приймає два види метаданих верхнього рівня:
|
||||
`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня:
|
||||
|
||||
- `commands`: явні корені команд, якими володіє registrar
|
||||
- `descriptors`: дескриптори команд на етапі парсингу, що використовуються для
|
||||
довідки кореневого CLI, маршрутизації та відкладеної реєстрації CLI plugin
|
||||
- `descriptors`: дескриптори команд на етапі парсингу, що використовуються для кореневої довідки CLI, маршрутизації та лінивої реєстрації CLI plugin
|
||||
|
||||
Якщо ви хочете, щоб команда plugin залишалася ліниво завантажуваною у звичайному
|
||||
шляху кореневого CLI, надайте `descriptors`, які покривають кожен корінь
|
||||
команди верхнього рівня, відкритий цим registrar.
|
||||
Якщо ви хочете, щоб команда plugin залишалася ліниво завантажуваною в
|
||||
звичайному кореневому шляху CLI, надайте `descriptors`, які охоплюють кожен
|
||||
корінь команди верхнього рівня, що експонується цим registrar.
|
||||
|
||||
```typescript
|
||||
api.registerCli(
|
||||
@ -359,7 +359,7 @@ api.registerCli(
|
||||
descriptors: [
|
||||
{
|
||||
name: "matrix",
|
||||
description: "Керування акаунтами Matrix, верифікацією, пристроями та станом профілю",
|
||||
description: "Manage Matrix accounts, verification, devices, and profile state",
|
||||
hasSubcommands: true,
|
||||
},
|
||||
],
|
||||
@ -367,113 +367,122 @@ api.registerCli(
|
||||
);
|
||||
```
|
||||
|
||||
Використовуйте лише `commands` тільки тоді, коли вам не потрібна лінива
|
||||
реєстрація кореневого CLI. Цей eager-шлях сумісності все ще підтримується,
|
||||
але він не встановлює placeholders на основі descriptors для лінивого
|
||||
завантаження під час парсингу.
|
||||
Використовуйте лише `commands`, якщо вам не потрібна лінива реєстрація кореня
|
||||
CLI. Цей eager-шлях сумісності все ще підтримується, але він не встановлює
|
||||
placeholder-и на основі descriptor для лінивого завантаження під час парсингу.
|
||||
|
||||
### Реєстрація CLI backend
|
||||
|
||||
`api.registerCliBackend(...)` дає plugin змогу володіти типовою конфігурацією
|
||||
локального backend AI CLI, такого як `codex-cli`.
|
||||
|
||||
- `id` backend стає префіксом провайдера в model ref, наприклад `codex-cli/gpt-5`.
|
||||
- `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.<id>`.
|
||||
- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.<id>` поверх типової конфігурації plugin перед запуском CLI.
|
||||
- Використовуйте `normalizeConfig`, коли backend потребує сумісних переписувань після злиття (наприклад, для нормалізації старих форм прапорців).
|
||||
|
||||
### Ексклюзивні слоти
|
||||
|
||||
| Method | Що реєструє |
|
||||
| ------------------------------------------ | ----------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | Context engine (одночасно активний лише один) |
|
||||
| `api.registerMemoryPromptSection(builder)` | Builder розділу prompt memory |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush для memory |
|
||||
| `api.registerMemoryRuntime(runtime)` | Адаптер runtime memory |
|
||||
| Метод | Що реєструє |
|
||||
| ----------------------------------------- | ----------------------------------- |
|
||||
| `api.registerContextEngine(id, factory)` | Рушій контексту (одночасно активний лише один) |
|
||||
| `api.registerMemoryPromptSection(builder)` | Збирач розділу prompt пам’яті |
|
||||
| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану flush пам’яті |
|
||||
| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті |
|
||||
|
||||
### Адаптери embedding для memory
|
||||
### Адаптери embedding пам’яті
|
||||
|
||||
| Method | Що реєструє |
|
||||
| ---------------------------------------------- | ------------------------------------------------ |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding для memory для активного plugin |
|
||||
| Метод | Що реєструє |
|
||||
| --------------------------------------------- | -------------------------------------------- |
|
||||
| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного plugin |
|
||||
|
||||
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` і
|
||||
`registerMemoryRuntime` є ексклюзивними для plugins memory.
|
||||
- `registerMemoryEmbeddingProvider` дозволяє активному plugin memory реєструвати один
|
||||
або кілька id адаптерів embedding (наприклад `openai`, `gemini` або
|
||||
custom id, визначений plugin).
|
||||
- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і
|
||||
`agents.defaults.memorySearch.fallback`, визначається відносно цих
|
||||
зареєстрованих id адаптерів.
|
||||
`registerMemoryRuntime` є ексклюзивними для plugins пам’яті.
|
||||
- `registerMemoryEmbeddingProvider` дає активному plugin пам’яті змогу
|
||||
реєструвати один або більше id адаптерів embedding (наприклад `openai`,
|
||||
`gemini` або користувацький id, визначений plugin).
|
||||
- Конфігурація користувача, як-от `agents.defaults.memorySearch.provider` і
|
||||
`agents.defaults.memorySearch.fallback`, зіставляється з цими
|
||||
зареєстрованими id адаптерів.
|
||||
|
||||
### Події та життєвий цикл
|
||||
|
||||
| Method | Що робить |
|
||||
| -------------------------------------------- | -------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Типізований hook життєвого циклу |
|
||||
| `api.onConversationBindingResolved(handler)` | Callback прив’язки conversation |
|
||||
| Метод | Що робить |
|
||||
| ------------------------------------------- | ---------------------------- |
|
||||
| `api.on(hookName, handler, opts?)` | Типізований lifecycle 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, ... }` є термінальним. Щойно будь-який обробник бере dispatch на себе, обробники з нижчим пріоритетом і стандартний шлях dispatch моделі пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: false }` розглядається як відсутність рішення (так само, як і пропуск `cancel`), а не як перевизначення.
|
||||
- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_tool_call`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як і пропущений `block`), а не як перевизначення.
|
||||
- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
|
||||
- `before_install`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як і пропущений `block`), а не як перевизначення.
|
||||
- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник перехоплює dispatch, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
|
||||
- `message_sending`: повернення `{ cancel: false }` розглядається як відсутність рішення (так само, як і пропущений `cancel`), а не як перевизначення.
|
||||
|
||||
### Поля об’єкта API
|
||||
|
||||
| Field | Type | Опис |
|
||||
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | ID plugin |
|
||||
| `api.name` | `string` | Відображувана назва |
|
||||
| `api.version` | `string?` | Версія plugin (необов’язково) |
|
||||
| `api.description` | `string?` | Опис plugin (необов’язково) |
|
||||
| `api.source` | `string` | Шлях до джерела plugin |
|
||||
| `api.rootDir` | `string?` | Кореневий каталог plugin (необов’язково) |
|
||||
| `api.config` | `OpenClawConfig` | Поточний snapshot конфігурації (активний snapshot 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` | Визначення шляху відносно кореня plugin |
|
||||
| Поле | Тип | Опис |
|
||||
| ----------------------- | ------------------------- | -------------------------------------------------------------------------------------------------- |
|
||||
| `api.id` | `string` | Ідентифікатор plugin |
|
||||
| `api.name` | `string` | Відображувана назва |
|
||||
| `api.version` | `string?` | Версія plugin (необов’язково) |
|
||||
| `api.description` | `string?` | Опис plugin (необов’язково) |
|
||||
| `api.source` | `string` | Шлях до джерела plugin |
|
||||
| `api.rootDir` | `string?` | Кореневий каталог plugin (необов’язково) |
|
||||
| `api.config` | `OpenClawConfig` | Поточний snapshot конфігурації (активний snapshot runtime у пам’яті, коли доступний) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Конфігурація, специфічна для plugin, з `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [Runtime helpers](/uk/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | Logger з областю видимості (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування до повного entry |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Розв’язує шлях відносно кореня plugin |
|
||||
|
||||
## Угода щодо внутрішніх модулів
|
||||
## Внутрішня угода для модулів
|
||||
|
||||
Усередині свого plugin використовуйте локальні barrel-файли для внутрішніх імпортів:
|
||||
У межах вашого plugin використовуйте локальні barrel-файли для внутрішніх імпортів:
|
||||
|
||||
```
|
||||
my-plugin/
|
||||
api.ts # Публічні експорти для зовнішніх споживачів
|
||||
runtime-api.ts # Лише внутрішні експорти runtime
|
||||
runtime-api.ts # Лише внутрішні runtime-експорти
|
||||
index.ts # Точка входу plugin
|
||||
setup-entry.ts # Полегшений entry лише для налаштування (необов’язково)
|
||||
setup-entry.ts # Полегшена точка входу лише для налаштування (необов’язково)
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/<your-plugin>`
|
||||
з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або
|
||||
у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або
|
||||
`./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт.
|
||||
</Warning>
|
||||
|
||||
Facade-loaded публічні поверхні bundled plugin (`api.ts`, `runtime-api.ts`,
|
||||
`index.ts`, `setup-entry.ts` та подібні публічні entry-файли) тепер надають
|
||||
перевагу активному snapshot конфігурації runtime, коли OpenClaw уже запущено.
|
||||
Якщо snapshot runtime ще не існує, вони використовують fallback до визначеного
|
||||
на диску файлу конфігурації.
|
||||
`index.ts`, `setup-entry.ts` та подібні публічні файли входу) тепер віддають
|
||||
перевагу активному snapshot конфігурації runtime, якщо OpenClaw уже запущено.
|
||||
Якщо snapshot runtime ще не існує, вони використовують fallback до розв’язаного
|
||||
файла конфігурації на диску.
|
||||
|
||||
Provider plugins також можуть відкривати вузький локальний barrel контракту plugin,
|
||||
коли допоміжна функція навмисно є специфічною для provider і поки що не належить
|
||||
до загального підшляху SDK. Поточний bundled-приклад: provider Anthropic тримає
|
||||
свої допоміжні функції потоку Claude у власному публічному шарі `api.ts` / `contract-api.ts`
|
||||
замість просування логіки beta-header Anthropic і `service_tier` у загальний
|
||||
контракт `plugin-sdk/*`.
|
||||
Plugins провайдерів також можуть експортувати вузький plugin-локальний contract
|
||||
barrel, коли допоміжна функція навмисно є специфічною для провайдера і поки що
|
||||
не належить до загального підшляху SDK. Поточний bundled-приклад: провайдер
|
||||
Anthropic зберігає свої допоміжні функції потоків Claude у власному публічному
|
||||
шві `api.ts` / `contract-api.ts` замість перенесення логіки Anthropic beta-header
|
||||
і `service_tier` до загального контракту `plugin-sdk/*`.
|
||||
|
||||
Інші поточні bundled-приклади:
|
||||
|
||||
- `@openclaw/openai-provider`: `api.ts` експортує builder-и provider,
|
||||
допоміжні функції моделей за замовчуванням і builder-и provider realtime
|
||||
- `@openclaw/openrouter-provider`: `api.ts` експортує builder provider, а також
|
||||
допоміжні функції onboarding/config
|
||||
- `@openclaw/openai-provider`: `api.ts` експортує builder-и провайдерів,
|
||||
допоміжні функції моделей за замовчуванням і builder-и realtime-провайдерів
|
||||
- `@openclaw/openrouter-provider`: `api.ts` експортує builder провайдера та
|
||||
допоміжні функції onboarding/конфігурації
|
||||
|
||||
<Warning>
|
||||
Production-код extension також має уникати імпортів
|
||||
`openclaw/plugin-sdk/<other-plugin>`. Якщо допоміжна функція справді спільна,
|
||||
перенесіть її до нейтрального підшляху SDK, наприклад
|
||||
`openclaw/plugin-sdk/<other-plugin>`. Якщо допоміжна функція справді є
|
||||
спільною, перенесіть її до нейтрального підшляху SDK, такого як
|
||||
`openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої
|
||||
поверхні, орієнтованої на capability, замість жорсткого зв’язування двох plugins.
|
||||
capability-орієнтованої поверхні, замість жорсткого зв’язування двох plugins.
|
||||
</Warning>
|
||||
|
||||
## Пов’язане
|
||||
@ -482,5 +491,5 @@ Provider plugins також можуть відкривати вузький л
|
||||
- [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) — поглиблена архітектура та модель можливостей
|
||||
- [SDK Migration](/uk/plugins/sdk-migration) — міграція з застарілих поверхонь
|
||||
- [Plugin Internals](/uk/plugins/architecture) — поглиблена архітектура і модель можливостей
|
||||
|
||||
@ -1,30 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви створюєте новий плагін постачальника моделей
|
||||
- Ви хочете додати сумісний з OpenAI проксі або власну LLM до OpenClaw
|
||||
- Вам потрібно зрозуміти автентифікацію постачальників, каталоги та runtime-хуки
|
||||
- Ви хочете додати OpenAI-сумісний проксі або власну LLM до OpenClaw
|
||||
- Вам потрібно зрозуміти автентифікацію постачальника, каталоги та runtime hooks
|
||||
sidebarTitle: Provider Plugins
|
||||
summary: Покроковий посібник зі створення плагіна постачальника моделей для OpenClaw
|
||||
title: Створення плагінів постачальників
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T12:29:08Z"
|
||||
generated_at: "2026-04-06T12:45:52Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 21c888a988f6128f2c77b73ee4962ae7ad7b8a6c1b7d302610788c81ad25b0db
|
||||
source_hash: 89e7402742c87cb31265db1d98b34ca17ba57ad1c61952fa8c7da834306986f5
|
||||
source_path: plugins/sdk-provider-plugins.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Створення плагінів постачальників
|
||||
|
||||
У цьому посібнику розглянуто створення плагіна постачальника, який додає
|
||||
постачальника моделей (LLM) до OpenClaw. Наприкінці у вас буде постачальник із каталогом моделей,
|
||||
автентифікацією за API-ключем і динамічним визначенням моделей.
|
||||
Цей посібник пояснює, як створити плагін постачальника, який додає до OpenClaw
|
||||
постачальника моделей (LLM). Наприкінці у вас буде постачальник із каталогом моделей,
|
||||
автентифікацією через API key і динамічним визначенням моделей.
|
||||
|
||||
<Info>
|
||||
Якщо ви раніше не створювали жодного плагіна OpenClaw, спочатку прочитайте
|
||||
[Getting Started](/uk/plugins/building-plugins), щоб ознайомитися з базовою структурою
|
||||
пакета та налаштуванням маніфесту.
|
||||
Якщо ви ще не створювали жодного плагіна OpenClaw, спочатку прочитайте
|
||||
[Початок роботи](/uk/plugins/building-plugins) для базової структури пакета
|
||||
та налаштування маніфесту.
|
||||
</Info>
|
||||
|
||||
## Покроковий розбір
|
||||
@ -88,10 +88,10 @@ x-i18n:
|
||||
|
||||
Маніфест оголошує `providerAuthEnvVars`, щоб OpenClaw міг виявляти
|
||||
облікові дані без завантаження runtime вашого плагіна. `modelSupport` є необов’язковим
|
||||
і дозволяє OpenClaw автоматично завантажувати ваш плагін постачальника за скороченими ідентифікаторами моделей,
|
||||
такими як `acme-large`, ще до появи runtime-хуків. Якщо ви публікуєте
|
||||
і дозволяє OpenClaw автоматично завантажувати ваш плагін постачальника за скороченими ID моделей
|
||||
на кшталт `acme-large` ще до появи runtime hooks. Якщо ви публікуєте
|
||||
постачальника в ClawHub, поля `openclaw.compat` і `openclaw.build`
|
||||
є обов’язковими в `package.json`.
|
||||
у `package.json` є обов’язковими.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -171,9 +171,9 @@ x-i18n:
|
||||
`openclaw onboard --acme-ai-api-key <key>` і вибрати
|
||||
`acme-ai/acme-large` як свою модель.
|
||||
|
||||
Для вбудованих постачальників, які реєструють лише одного текстового постачальника з
|
||||
автентифікацією за API-ключем плюс один runtime на основі каталогу, краще використовувати вужчий хелпер
|
||||
`defineSingleProviderPluginEntry(...)`:
|
||||
Для вбудованих постачальників, які реєструють лише одного текстового постачальника з автентифікацією через API key
|
||||
і одним runtime на основі каталогу, надавайте перевагу вужчому
|
||||
хелперу `defineSingleProviderPluginEntry(...)`:
|
||||
|
||||
```typescript
|
||||
import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry";
|
||||
@ -208,25 +208,24 @@ x-i18n:
|
||||
});
|
||||
```
|
||||
|
||||
Якщо ваш потік автентифікації також має змінювати `models.providers.*`, псевдоніми та
|
||||
модель агента за замовчуванням під час онбордингу, використовуйте preset-хелпери з
|
||||
Якщо вашому потоку автентифікації також потрібно змінювати `models.providers.*`, псевдоніми та
|
||||
типову модель агента під час onboarding, використовуйте preset-хелпери з
|
||||
`openclaw/plugin-sdk/provider-onboard`. Найвужчі хелпери:
|
||||
`createDefaultModelPresetAppliers(...)`,
|
||||
`createDefaultModelsPresetAppliers(...)` і
|
||||
`createModelCatalogPresetAppliers(...)`.
|
||||
|
||||
Коли нативна кінцева точка постачальника підтримує потокові блоки usage у
|
||||
звичайному транспорті `openai-completions`, віддавайте перевагу спільним хелперам каталогу з
|
||||
`openclaw/plugin-sdk/provider-catalog-shared`, а не жорстко прописаним
|
||||
перевіркам ідентифікатора постачальника. `supportsNativeStreamingUsageCompat(...)` і
|
||||
`applyProviderNativeStreamingUsageCompat(...)` визначають підтримку за мапою можливостей
|
||||
кінцевої точки, тож нативні кінцеві точки у стилі Moonshot/DashScope також
|
||||
зможуть підключатися, навіть якщо плагін використовує власний ідентифікатор постачальника.
|
||||
Коли нативний endpoint постачальника підтримує streamed usage blocks на
|
||||
звичайному транспорті `openai-completions`, надавайте перевагу спільним хелперам каталогів із
|
||||
`openclaw/plugin-sdk/provider-catalog-shared` замість жорстко закодованих перевірок `provider-id`. Функції
|
||||
`supportsNativeStreamingUsageCompat(...)` і
|
||||
`applyProviderNativeStreamingUsageCompat(...)` визначають підтримку за мапою можливостей endpoint, тож
|
||||
нативні endpoint у стилі Moonshot/DashScope також можуть підключатися, навіть якщо плагін використовує власний `provider id`.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте динамічне визначення моделей">
|
||||
Якщо ваш постачальник приймає довільні ідентифікатори моделей (наприклад, проксі або маршрутизатор),
|
||||
Якщо ваш постачальник приймає довільні ID моделей (наприклад, проксі або маршрутизатор),
|
||||
додайте `resolveDynamicModel`:
|
||||
|
||||
```typescript
|
||||
@ -249,16 +248,16 @@ x-i18n:
|
||||
```
|
||||
|
||||
Якщо для визначення потрібен мережевий виклик, використовуйте `prepareDynamicModel` для асинхронного
|
||||
прогрівання — після його завершення `resolveDynamicModel` виконується знову.
|
||||
попереднього прогріву — після його завершення `resolveDynamicModel` буде запущено знову.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте runtime-хуки (за потреби)">
|
||||
Більшості постачальників потрібні лише `catalog` + `resolveDynamicModel`. Додавайте хуки
|
||||
поступово, у міру того як це потрібно вашому постачальнику.
|
||||
<Step title="Додайте runtime hooks (за потреби)">
|
||||
Більшості постачальників потрібні лише `catalog` + `resolveDynamicModel`. Додавайте hooks
|
||||
поступово, у міру того як цього вимагатиме ваш постачальник.
|
||||
|
||||
Спільні builder-хелпери тепер охоплюють найпоширеніші сімейства replay/tool-compat,
|
||||
тому плагінам зазвичай не потрібно вручну підключати кожен хук окремо:
|
||||
Спільні builder-хелпери тепер охоплюють найтиповіші сімейства replay/tool-compat,
|
||||
тому плагінам зазвичай не потрібно вручну підключати кожен hook окремо:
|
||||
|
||||
```typescript
|
||||
import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared";
|
||||
@ -282,15 +281,15 @@ x-i18n:
|
||||
|
||||
| Family | Що воно підключає |
|
||||
| --- | --- |
|
||||
| `openai-compatible` | Спільна політика replay у стилі OpenAI для транспортів, сумісних з OpenAI, включно з санітизацією ідентифікаторів викликів інструментів, виправленнями порядку assistant-first і загальною валідацією Gemini-turn там, де вона потрібна транспорту |
|
||||
| `anthropic-by-model` | Політика replay з урахуванням Claude, що обирається за `modelId`, тому транспорти Anthropic-message отримують очищення thinking-блоків, специфічне для Claude, лише коли визначена модель справді є ідентифікатором Claude |
|
||||
| `google-gemini` | Нативна політика replay для Gemini плюс bootstrap-санітизація replay і режим tagged reasoning-output |
|
||||
| `passthrough-gemini` | Санітизація thought-signature Gemini для моделей Gemini, що працюють через сумісні з OpenAI проксі-транспорти; не вмикає нативну валідацію replay Gemini або bootstrap-перезаписування |
|
||||
| `hybrid-anthropic-openai` | Гібридна політика для постачальників, які поєднують поверхні моделей Anthropic-message і OpenAI-compatible в одному плагіні; необов’язкове відкидання thinking-блоків лише для Claude залишається обмеженим стороною Anthropic |
|
||||
| `openai-compatible` | Спільна політика replay у стилі OpenAI для OpenAI-сумісних транспортів, включно з очищенням tool-call-id, виправленням порядку assistant-first і загальною перевіркою Gemini-turn там, де цього потребує транспорт |
|
||||
| `anthropic-by-model` | Політика replay з урахуванням Claude, що вибирається за `modelId`, тож транспорти Anthropic-message отримують очищення thinking-block, специфічне для Claude, лише коли визначена модель дійсно має Claude id |
|
||||
| `google-gemini` | Нативна політика replay Gemini плюс санітизація bootstrap replay і режим tagged reasoning-output |
|
||||
| `passthrough-gemini` | Санітизація thought-signature Gemini для моделей Gemini, що працюють через OpenAI-сумісні проксі-транспорти; не вмикає нативну перевірку replay Gemini або переписування bootstrap |
|
||||
| `hybrid-anthropic-openai` | Гібридна політика для постачальників, які поєднують поверхні моделей Anthropic-message і OpenAI-compatible в одному плагіні; необов’язкове відкидання thinking-block лише для Claude залишається обмеженим стороною Anthropic |
|
||||
|
||||
Реальні вбудовані приклади:
|
||||
|
||||
- `google`: `google-gemini`
|
||||
- `google` і `google-gemini-cli`: `google-gemini`
|
||||
- `openrouter`, `kilocode`, `opencode` і `opencode-go`: `passthrough-gemini`
|
||||
- `amazon-bedrock` і `anthropic-vertex`: `anthropic-by-model`
|
||||
- `minimax`: `hybrid-anthropic-openai`
|
||||
@ -300,17 +299,17 @@ x-i18n:
|
||||
|
||||
| Family | Що воно підключає |
|
||||
| --- | --- |
|
||||
| `google-thinking` | Нормалізація payload thinking Gemini у спільному stream-шляху |
|
||||
| `kilocode-thinking` | Обгортка reasoning Kilo у спільному proxy stream-шляху, де `kilo/auto` та непідтримувані proxy reasoning id пропускають інжектований thinking |
|
||||
| `moonshot-thinking` | Мапінг бінарного payload native-thinking Moonshot з config + рівня `/think` |
|
||||
| `minimax-fast-mode` | Перезапис моделі fast-mode MiniMax у спільному stream-шляху |
|
||||
| `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: attribution-заголовки, `/fast`/`serviceTier`, деталізація тексту, нативний вебпошук Codex, формування payload для сумісності reasoning і керування контекстом Responses |
|
||||
| `openrouter-thinking` | Обгортка reasoning OpenRouter для proxy-маршрутів, із централізованою обробкою пропусків для непідтримуваних моделей/`auto` |
|
||||
| `tool-stream-default-on` | Увімкнена за замовчуванням обгортка `tool_stream` для постачальників на кшталт Z.AI, які хочуть потокову передачу інструментів, якщо її не вимкнено явно |
|
||||
| `google-thinking` | Нормалізація payload thinking Gemini на спільному stream-шляху |
|
||||
| `kilocode-thinking` | Обгортка reasoning Kilo на спільному proxy stream-шляху, де `kilo/auto` і непідтримувані proxy reasoning id пропускають інжектований thinking |
|
||||
| `moonshot-thinking` | Відображення бінарного payload native-thinking Moonshot з конфігурації + рівня `/think` |
|
||||
| `minimax-fast-mode` | Переписування моделі MiniMax fast-mode на спільному stream-шляху |
|
||||
| `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: attribution headers, `/fast`/`serviceTier`, text verbosity, нативний вебпошук Codex, формування payload для reasoning-compat і керування контекстом Responses |
|
||||
| `openrouter-thinking` | Обгортка reasoning OpenRouter для proxy-маршрутів, з централізованою обробкою пропусків для непідтримуваних моделей/`auto` |
|
||||
| `tool-stream-default-on` | Обгортка `tool_stream`, увімкнена типово, для постачальників на кшталт Z.AI, яким потрібен streaming інструментів, якщо його явно не вимкнено |
|
||||
|
||||
Реальні вбудовані приклади:
|
||||
|
||||
- `google`: `google-thinking`
|
||||
- `google` і `google-gemini-cli`: `google-thinking`
|
||||
- `kilocode`: `kilocode-thinking`
|
||||
- `moonshot`: `moonshot-thinking`
|
||||
- `minimax` і `minimax-portal`: `minimax-fast-mode`
|
||||
@ -319,8 +318,8 @@ x-i18n:
|
||||
- `zai`: `tool-stream-default-on`
|
||||
|
||||
`openclaw/plugin-sdk/provider-model-shared` також експортує enum сімейств replay
|
||||
плюс спільні хелпери, з яких ці сімейства побудовані. Поширені публічні
|
||||
експорти включають:
|
||||
плюс спільні хелпери, з яких ці сімейства побудовані. Поширені публічні експорти
|
||||
включають:
|
||||
|
||||
- `ProviderReplayFamily`
|
||||
- `buildProviderReplayFamilyHooks(...)`
|
||||
@ -328,13 +327,13 @@ x-i18n:
|
||||
`buildAnthropicReplayPolicyForModel(...)`,
|
||||
`buildGoogleGeminiReplayPolicy(...)` і
|
||||
`buildHybridAnthropicOrOpenAIReplayPolicy(...)`
|
||||
- хелпери replay для Gemini, такі як `sanitizeGoogleGeminiReplayHistory(...)`
|
||||
- хелпери replay Gemini, такі як `sanitizeGoogleGeminiReplayHistory(...)`
|
||||
і `resolveTaggedReasoningOutputMode()`
|
||||
- хелпери кінцевих точок/моделей, такі як `resolveProviderEndpoint(...)`,
|
||||
- хелпери endpoint/model, такі як `resolveProviderEndpoint(...)`,
|
||||
`normalizeProviderId(...)`, `normalizeGooglePreviewModelId(...)` і
|
||||
`normalizeNativeXaiModelId(...)`
|
||||
|
||||
`openclaw/plugin-sdk/provider-stream` надає і builder сімейств, і
|
||||
`openclaw/plugin-sdk/provider-stream` надає і builder сімейства, і
|
||||
публічні wrapper-хелпери, які ці сімейства повторно використовують. Поширені публічні експорти
|
||||
включають:
|
||||
|
||||
@ -354,45 +353,45 @@ x-i18n:
|
||||
приклад: `@openclaw/anthropic-provider` експортує
|
||||
`wrapAnthropicProviderStream`, `resolveAnthropicBetas`,
|
||||
`resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і
|
||||
низькорівневі builder-и обгорток Anthropic зі свого публічного seam `api.ts` /
|
||||
низькорівневі builder-и обгорток Anthropic зі свого публічного шва `api.ts` /
|
||||
`contract-api.ts`. Ці хелпери залишаються специфічними для Anthropic, оскільки
|
||||
також кодують обробку Claude OAuth beta і gating `context1m`.
|
||||
вони також кодують обробку Claude OAuth beta і gating `context1m`.
|
||||
|
||||
Інші вбудовані постачальники також тримають специфічні для транспорту обгортки локально, коли
|
||||
цю поведінку неможливо чисто поділити між сімействами. Поточний приклад: вбудований
|
||||
Інші вбудовані постачальники також залишають transport-специфічні обгортки локальними, коли
|
||||
цю поведінку неможливо чисто розділити між сімействами. Поточний приклад: вбудований
|
||||
плагін xAI зберігає нативне формування xAI Responses у власному
|
||||
`wrapStreamFn`, включно з перезаписуванням псевдонімів `/fast`, `tool_stream`
|
||||
за замовчуванням, очищенням непідтримуваних strict-tool і видаленням payload reasoning,
|
||||
специфічного для xAI.
|
||||
`wrapStreamFn`, включно з переписуванням псевдонімів `/fast`, типовим `tool_stream`,
|
||||
очищенням непідтримуваних strict-tool і видаленням reasoning-payload,
|
||||
специфічним для xAI.
|
||||
|
||||
`openclaw/plugin-sdk/provider-tools` наразі надає одне спільне
|
||||
сімейство tool-schema плюс спільні хелпери schema/compat:
|
||||
|
||||
- `ProviderToolCompatFamily` документує наявний сьогодні інвентар спільних сімейств.
|
||||
- `buildProviderToolCompatFamilyHooks("gemini")` підключає очищення Gemini schema
|
||||
- `ProviderToolCompatFamily` документує наявний перелік спільних сімейств.
|
||||
- `buildProviderToolCompatFamilyHooks("gemini")` підключає очищення схем Gemini
|
||||
+ діагностику для постачальників, яким потрібні безпечні для Gemini схеми інструментів.
|
||||
- `normalizeGeminiToolSchemas(...)` і `inspectGeminiToolSchemas(...)`
|
||||
є базовими публічними Gemini schema-хелперами.
|
||||
- `resolveXaiModelCompatPatch()` повертає вбудований compat-патч xAI:
|
||||
`toolSchemaProfile: "xai"`, непідтримувані ключові слова schema, нативну підтримку
|
||||
`web_search` і декодування аргументів викликів інструментів із HTML-сутностями.
|
||||
- `applyXaiModelCompat(model)` застосовує той самий compat-патч xAI до
|
||||
визначеної моделі, перш ніж вона потрапить до runner-а.
|
||||
— це базові публічні хелпери схем Gemini.
|
||||
- `resolveXaiModelCompatPatch()` повертає вбудований compat patch xAI:
|
||||
`toolSchemaProfile: "xai"`, непідтримувані ключові слова схеми, нативну
|
||||
підтримку `web_search` і декодування HTML-entity аргументів виклику інструментів.
|
||||
- `applyXaiModelCompat(model)` застосовує той самий compat patch xAI до
|
||||
визначеної моделі до того, як вона потрапить до runner.
|
||||
|
||||
Реальний вбудований приклад: плагін xAI використовує `normalizeResolvedModel` плюс
|
||||
`contributeResolvedModelCompat`, щоб зберегти метадані compat у власності
|
||||
постачальника, а не жорстко прописувати правила xAI в core.
|
||||
`contributeResolvedModelCompat`, щоб ці compat-метадані залишалися у
|
||||
власності постачальника, а не були жорстко закодовані в core.
|
||||
|
||||
Той самий шаблон на рівні кореня пакета також лежить в основі інших вбудованих постачальників:
|
||||
Такий самий шаблон package-root також підтримує інші вбудовані постачальники:
|
||||
|
||||
- `@openclaw/openai-provider`: `api.ts` експортує builder-и постачальника,
|
||||
хелпери моделі за замовчуванням і builder-и realtime-постачальника
|
||||
хелпери типових моделей і builder-и realtime provider
|
||||
- `@openclaw/openrouter-provider`: `api.ts` експортує builder
|
||||
постачальника плюс хелпери онбордингу/конфігурації
|
||||
постачальника плюс хелпери onboarding/config
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Обмін токенів">
|
||||
Для постачальників, яким потрібен обмін токенів перед кожним викликом inference:
|
||||
<Tab title="Обмін токенами">
|
||||
Для постачальників, яким потрібен обмін токенами перед кожним викликом inference:
|
||||
|
||||
```typescript
|
||||
prepareRuntimeAuth: async (ctx) => {
|
||||
@ -406,7 +405,7 @@ x-i18n:
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Користувацькі заголовки">
|
||||
Для постачальників, яким потрібні користувацькі заголовки запитів або зміни тіла запиту:
|
||||
Для постачальників, яким потрібні користувацькі заголовки запиту або модифікації тіла:
|
||||
|
||||
```typescript
|
||||
// wrapStreamFn returns a StreamFn derived from ctx.streamFn
|
||||
@ -424,8 +423,8 @@ x-i18n:
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Ідентичність нативного транспорту">
|
||||
Для постачальників, яким потрібні нативні заголовки або метадані запитів/сесій на
|
||||
узагальнених HTTP- або WebSocket-транспортах:
|
||||
Для постачальників, яким потрібні нативні заголовки або метадані запиту/сесії в
|
||||
універсальних HTTP- або WebSocket-транспортах:
|
||||
|
||||
```typescript
|
||||
resolveTransportTurnState: (ctx) => ({
|
||||
@ -445,8 +444,8 @@ x-i18n:
|
||||
}),
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Usage і білінг">
|
||||
Для постачальників, які надають дані usage/білінгу:
|
||||
<Tab title="Використання і білінг">
|
||||
Для постачальників, які надають дані про використання/білінг:
|
||||
|
||||
```typescript
|
||||
resolveUsageAuth: async (ctx) => {
|
||||
@ -460,75 +459,75 @@ x-i18n:
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Accordion title="Усі доступні хуки постачальника">
|
||||
OpenClaw викликає хуки в такому порядку. Більшість постачальників використовують лише 2-3:
|
||||
<Accordion title="Усі доступні hooks постачальника">
|
||||
OpenClaw викликає hooks у такому порядку. Більшість постачальників використовують лише 2–3:
|
||||
|
||||
| # | Hook | Коли використовувати |
|
||||
| --- | --- | --- |
|
||||
| 1 | `catalog` | Каталог моделей або значення `baseUrl` за замовчуванням |
|
||||
| 2 | `applyConfigDefaults` | Глобальні значення за замовчуванням, що належать постачальнику, під час materialization конфігурації |
|
||||
| 3 | `normalizeModelId` | Очищення застарілих/preview псевдонімів ідентифікаторів моделей перед пошуком |
|
||||
| 4 | `normalizeTransport` | Очищення `api` / `baseUrl` для сімейства постачальника перед загальним складанням моделі |
|
||||
| 1 | `catalog` | Каталог моделей або типові значення `base URL` |
|
||||
| 2 | `applyConfigDefaults` | Глобальні типові значення, що належать постачальнику, під час матеріалізації конфігурації |
|
||||
| 3 | `normalizeModelId` | Очищення псевдонімів застарілих/preview model id перед пошуком |
|
||||
| 4 | `normalizeTransport` | Очищення `api` / `baseUrl` сімейства постачальника перед загальним складанням моделі |
|
||||
| 5 | `normalizeConfig` | Нормалізація конфігурації `models.providers.<id>` |
|
||||
| 6 | `applyNativeStreamingUsageCompat` | Перезаписування native streaming-usage compat для config-постачальників |
|
||||
| 7 | `resolveConfigApiKey` | Визначення автентифікації за env-marker, що належить постачальнику |
|
||||
| 8 | `resolveSyntheticAuth` | Синтетична автентифікація local/self-hosted або на основі config |
|
||||
| 9 | `shouldDeferSyntheticProfileAuth` | Опустити синтетичні placeholder-и збереженого профілю нижче за env/config auth |
|
||||
| 10 | `resolveDynamicModel` | Приймати довільні ідентифікатори моделей upstream |
|
||||
| 6 | `applyNativeStreamingUsageCompat` | Переписування native streaming-usage compat для config providers |
|
||||
| 7 | `resolveConfigApiKey` | Визначення автентифікації env-marker, що належить постачальнику |
|
||||
| 8 | `resolveSyntheticAuth` | Синтетична автентифікація для локального/self-hosted або конфігураційного сценарію |
|
||||
| 9 | `shouldDeferSyntheticProfileAuth` | Зниження пріоритету синтетичних placeholder-ів збереженого профілю відносно env/config auth |
|
||||
| 10 | `resolveDynamicModel` | Приймати довільні upstream model ID |
|
||||
| 11 | `prepareDynamicModel` | Асинхронне отримання метаданих перед визначенням |
|
||||
| 12 | `normalizeResolvedModel` | Перезаписування транспорту перед runner-ом |
|
||||
| 12 | `normalizeResolvedModel` | Переписування транспорту перед runner |
|
||||
|
||||
Примітки щодо runtime fallback:
|
||||
|
||||
- `normalizeConfig` спочатку перевіряє відповідного постачальника, а потім інші
|
||||
плагіни постачальників, здатні обробляти хуки, доки один із них справді не змінить конфігурацію.
|
||||
Якщо жоден хук постачальника не перепише підтримуваний запис конфігурації сімейства Google,
|
||||
усе одно буде застосовано вбудований нормалізатор конфігурації Google.
|
||||
- `resolveConfigApiKey` використовує хук постачальника, якщо він наданий. Вбудований
|
||||
- `normalizeConfig` спочатку перевіряє відповідний постачальник, а потім інші
|
||||
плагіни постачальників, здатні працювати з hooks, доки хтось із них справді не змінить конфігурацію.
|
||||
Якщо жоден provider hook не перепише підтримуваний запис конфігурації сімейства Google,
|
||||
усе одно застосовується вбудований normalizer конфігурації Google.
|
||||
- `resolveConfigApiKey` використовує hook постачальника, якщо він доступний. Вбудований
|
||||
шлях `amazon-bedrock` також має тут вбудований resolver AWS env-marker,
|
||||
хоча runtime-автентифікація Bedrock досі використовує стандартний
|
||||
AWS SDK chain.
|
||||
навіть попри те, що runtime auth Bedrock і далі використовує типовий
|
||||
ланцюжок AWS SDK.
|
||||
| 13 | `contributeResolvedModelCompat` | Compat-прапорці для вендорських моделей за іншим сумісним транспортом |
|
||||
| 14 | `capabilities` | Застарілий статичний набір можливостей; лише для сумісності |
|
||||
| 15 | `normalizeToolSchemas` | Очищення схеми інструментів, що належить постачальнику, перед реєстрацією |
|
||||
| 16 | `inspectToolSchemas` | Діагностика схем інструментів, що належить постачальнику |
|
||||
| 17 | `resolveReasoningOutputMode` | Контракт reasoning-output: tagged чи native |
|
||||
| 18 | `prepareExtraParams` | Параметри запиту за замовчуванням |
|
||||
| 14 | `capabilities` | Застарілий статичний контейнер можливостей; лише для сумісності |
|
||||
| 15 | `normalizeToolSchemas` | Очищення tool-schema, що належить постачальнику, перед реєстрацією |
|
||||
| 16 | `inspectToolSchemas` | Діагностика tool-schema, що належить постачальнику |
|
||||
| 17 | `resolveReasoningOutputMode` | Tagged vs native контракт reasoning-output |
|
||||
| 18 | `prepareExtraParams` | Типові параметри запиту |
|
||||
| 19 | `createStreamFn` | Повністю користувацький транспорт StreamFn |
|
||||
| 20 | `wrapStreamFn` | Користувацькі обгортки заголовків/тіла в стандартному stream-шляху |
|
||||
| 20 | `wrapStreamFn` | Користувацькі обгортки заголовків/тіла на звичайному stream-шляху |
|
||||
| 21 | `resolveTransportTurnState` | Нативні заголовки/метадані для кожного turn |
|
||||
| 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сесії WS / охолодження |
|
||||
| 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сесії WS/cool-down |
|
||||
| 23 | `formatApiKey` | Користувацька форма runtime-токена |
|
||||
| 24 | `refreshOAuth` | Користувацьке оновлення OAuth |
|
||||
| 25 | `buildAuthDoctorHint` | Підказка щодо виправлення автентифікації |
|
||||
| 26 | `matchesContextOverflowError` | Виявлення переповнення, що належить постачальнику |
|
||||
| 25 | `buildAuthDoctorHint` | Рекомендації для відновлення автентифікації |
|
||||
| 26 | `matchesContextOverflowError` | Визначення переповнення контексту, що належить постачальнику |
|
||||
| 27 | `classifyFailoverReason` | Класифікація rate-limit/overload, що належить постачальнику |
|
||||
| 28 | `isCacheTtlEligible` | Gating TTL кешу prompt-ів |
|
||||
| 28 | `isCacheTtlEligible` | Gating TTL кешу prompt |
|
||||
| 29 | `buildMissingAuthMessage` | Користувацька підказка про відсутню автентифікацію |
|
||||
| 30 | `suppressBuiltInModel` | Приховати застарілі рядки upstream |
|
||||
| 31 | `augmentModelCatalog` | Синтетичні рядки для прямої сумісності вперед |
|
||||
| 32 | `isBinaryThinking` | Бінарне thinking увімк./вимк. |
|
||||
| 30 | `suppressBuiltInModel` | Приховати застарілі upstream-рядки |
|
||||
| 31 | `augmentModelCatalog` | Синтетичні рядки forward-compat |
|
||||
| 32 | `isBinaryThinking` | Бінарний thinking увімк./вимк. |
|
||||
| 33 | `supportsXHighThinking` | Підтримка reasoning `xhigh` |
|
||||
| 34 | `resolveDefaultThinkingLevel` | Політика `/think` за замовчуванням |
|
||||
| 34 | `resolveDefaultThinkingLevel` | Типова політика `/think` |
|
||||
| 35 | `isModernModelRef` | Відповідність live/smoke моделей |
|
||||
| 36 | `prepareRuntimeAuth` | Обмін токенів перед inference |
|
||||
| 37 | `resolveUsageAuth` | Користувацький розбір облікових даних usage |
|
||||
| 38 | `fetchUsageSnapshot` | Користувацька кінцева точка usage |
|
||||
| 36 | `prepareRuntimeAuth` | Обмін токенами перед inference |
|
||||
| 37 | `resolveUsageAuth` | Користувацький розбір облікових даних використання |
|
||||
| 38 | `fetchUsageSnapshot` | Користувацький endpoint використання |
|
||||
| 39 | `createEmbeddingProvider` | Адаптер embedding, що належить постачальнику, для memory/search |
|
||||
| 40 | `buildReplayPolicy` | Користувацька політика replay/compaction транскрипту |
|
||||
| 41 | `sanitizeReplayHistory` | Перезаписування replay, специфічні для постачальника, після загального очищення |
|
||||
| 42 | `validateReplayTurns` | Сувора валідація replay-turn перед вбудованим runner-ом |
|
||||
| 43 | `onModelSelected` | Зворотний виклик після вибору моделі (наприклад, telemetry) |
|
||||
| 40 | `buildReplayPolicy` | Користувацька політика replay/compaction для транскриптів |
|
||||
| 41 | `sanitizeReplayHistory` | Специфічні для постачальника переписування replay після загального очищення |
|
||||
| 42 | `validateReplayTurns` | Сувора перевірка replay-turn перед вбудованим runner |
|
||||
| 43 | `onModelSelected` | Зворотний виклик після вибору моделі (наприклад, телеметрія) |
|
||||
|
||||
Примітка щодо налаштування prompt-ів:
|
||||
Примітка щодо налаштування prompt:
|
||||
|
||||
- `resolveSystemPromptContribution` дозволяє постачальнику інжектувати
|
||||
cache-aware підказки системного prompt-а для сімейства моделей. Віддавайте йому перевагу перед
|
||||
cache-aware рекомендації для system prompt для сімейства моделей. Надавайте перевагу цьому hook над
|
||||
`before_prompt_build`, коли поведінка належить одному сімейству постачальника/моделі
|
||||
і має зберігати стабільний/динамічний поділ кешу.
|
||||
|
||||
Детальні описи та приклади з реального світу дивіться у
|
||||
[Internals: Provider Runtime Hooks](/uk/plugins/architecture#provider-runtime-hooks).
|
||||
Докладні описи й реальні приклади див. у
|
||||
[Внутрішні механізми: runtime hooks постачальника](/uk/plugins/architecture#provider-runtime-hooks).
|
||||
</Accordion>
|
||||
|
||||
</Step>
|
||||
@ -645,15 +644,15 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw класифікує це як плагін **hybrid-capability**. Це
|
||||
OpenClaw класифікує це як плагін **гібридних можливостей**. Це
|
||||
рекомендований шаблон для корпоративних плагінів (один плагін на вендора). Див.
|
||||
[Internals: Capability Ownership](/uk/plugins/architecture#capability-ownership-model).
|
||||
[Внутрішні механізми: модель володіння можливостями](/uk/plugins/architecture#capability-ownership-model).
|
||||
|
||||
Для генерації відео віддавайте перевагу показаній вище структурі можливостей, що враховує режими:
|
||||
`generate`, `imageToVideo` і `videoToVideo`. Старіші пласкі поля, такі
|
||||
Для генерації відео надавайте перевагу показаній вище структурі можливостей з урахуванням режимів:
|
||||
`generate`, `imageToVideo` і `videoToVideo`. Старі пласкі поля, такі
|
||||
як `maxInputImages`, `maxInputVideos` і `maxDurationSeconds`, усе ще працюють
|
||||
як агреговані резервні обмеження, але вони не можуть так само чисто описувати
|
||||
обмеження для окремих режимів або вимкнені режими трансформації.
|
||||
як сукупні резервні ліміти, але не можуть так чисто описувати обмеження для окремих режимів або
|
||||
вимкнені режими перетворення.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -694,14 +693,14 @@ x-i18n:
|
||||
|
||||
## Публікація в ClawHub
|
||||
|
||||
Плагіни постачальників публікуються так само, як і будь-які інші зовнішні кодові плагіни:
|
||||
Плагіни постачальників публікуються так само, як і будь-який інший зовнішній кодовий плагін:
|
||||
|
||||
```bash
|
||||
clawhub package publish your-org/your-plugin --dry-run
|
||||
clawhub package publish your-org/your-plugin
|
||||
```
|
||||
|
||||
Не використовуйте тут застарілий псевдонім публікації лише для Skills; пакети плагінів повинні використовувати
|
||||
Не використовуйте тут застарілий псевдонім публікації лише для Skills; пакети плагінів мають використовувати
|
||||
`clawhub package publish`.
|
||||
|
||||
## Структура файлів
|
||||
@ -716,21 +715,21 @@ clawhub package publish your-org/your-plugin
|
||||
└── usage.ts # Usage endpoint (optional)
|
||||
```
|
||||
|
||||
## Довідка щодо порядку каталогу
|
||||
## Довідник порядку каталогу
|
||||
|
||||
`catalog.order` визначає, коли ваш каталог зливається відносно вбудованих
|
||||
`catalog.order` керує тим, коли ваш каталог об’єднується відносно вбудованих
|
||||
постачальників:
|
||||
|
||||
| Order | Коли | Випадок використання |
|
||||
| --------- | ------------- | ---------------------------------------------- |
|
||||
| `simple` | Перший прохід | Звичайні постачальники з API-ключем |
|
||||
| `profile` | Після simple | Постачальники, прив’язані до профілів автентифікації |
|
||||
| `paired` | Після profile | Синтез кількох пов’язаних записів |
|
||||
| `late` | Останній прохід | Перевизначення наявних постачальників (перемагає при конфлікті) |
|
||||
| Order | Коли | Варіант використання |
|
||||
| --------- | ------------- | ----------------------------------------------- |
|
||||
| `simple` | Перший прохід | Звичайні постачальники з API key |
|
||||
| `profile` | Після simple | Постачальники, що залежать від auth profiles |
|
||||
| `paired` | Після profile | Синтез кількох пов’язаних записів |
|
||||
| `late` | Останній прохід | Перевизначення наявних постачальників (виграє при конфлікті) |
|
||||
|
||||
## Подальші кроки
|
||||
## Наступні кроки
|
||||
|
||||
- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — якщо ваш плагін також надає канал
|
||||
- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — якщо ваш плагін також надає канал
|
||||
- [SDK Runtime](/uk/plugins/sdk-runtime) — хелпери `api.runtime` (TTS, search, subagent)
|
||||
- [SDK Overview](/uk/plugins/sdk-overview) — повний довідник з імпорту subpath
|
||||
- [Plugin Internals](/uk/plugins/architecture#provider-runtime-hooks) — деталі хуків і вбудовані приклади
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпорту subpath
|
||||
- [Внутрішні механізми плагінів](/uk/plugins/architecture#provider-runtime-hooks) — деталі hooks і приклади вбудованих реалізацій
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете використовувати моделі Anthropic в OpenClaw
|
||||
summary: Використання Anthropic Claude через API-ключі в OpenClaw
|
||||
summary: Використовуйте Anthropic Claude через API-ключі в OpenClaw
|
||||
title: Anthropic
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T18:13:54Z"
|
||||
generated_at: "2026-04-06T12:45:07Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: bbc6c4938674aedf20ff944bc04e742c9a7e77a5ff10ae4f95b5718504c57c2d
|
||||
source_hash: 6af35571debf5889b63e3b4f6a05aa4e046f39740287e6e1c492916ca00df44b
|
||||
source_path: providers/anthropic.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -15,29 +15,29 @@ x-i18n:
|
||||
# Anthropic (Claude)
|
||||
|
||||
Anthropic створює сімейство моделей **Claude** і надає доступ через API.
|
||||
У OpenClaw нове налаштування Anthropic має використовувати API-ключ. Наявні застарілі
|
||||
профілі токенів Anthropic і далі враховуються під час виконання, якщо вони вже
|
||||
У OpenClaw для нового налаштування Anthropic слід використовувати API-ключ. Наявні legacy
|
||||
профілі токенів Anthropic і далі підтримуються під час виконання, якщо вони вже
|
||||
налаштовані.
|
||||
|
||||
<Warning>
|
||||
Для Anthropic в OpenClaw розподіл білінгу такий:
|
||||
Для Anthropic в OpenClaw розподіл оплати такий:
|
||||
|
||||
- **Anthropic API key**: звичайний білінг Anthropic API.
|
||||
- **Anthropic API key**: звичайна оплата Anthropic API.
|
||||
- **Claude subscription auth всередині OpenClaw**: Anthropic повідомила користувачам OpenClaw
|
||||
**4 квітня 2026 року о 12:00 PT / 8:00 PM BST**, що це вважається
|
||||
використанням стороннього harness і вимагає **Extra Usage** (pay-as-you-go,
|
||||
оплачується окремо від підписки).
|
||||
**4 квітня 2026 року о 12:00 PT / 20:00 BST**, що це вважається
|
||||
використанням стороннього harness і вимагає **Extra Usage** (оплата за фактом використання,
|
||||
виставляється окремо від підписки).
|
||||
|
||||
Наші локальні відтворення підтверджують цей розподіл:
|
||||
Наші локальні відтворення підтверджують цей поділ:
|
||||
|
||||
- прямий `claude -p` усе ще може працювати
|
||||
- `claude -p --append-system-prompt ...` може активувати перевірку Extra Usage, коли
|
||||
- `claude -p --append-system-prompt ...` може активувати захист Extra Usage, коли
|
||||
prompt ідентифікує OpenClaw
|
||||
- той самий system prompt у стилі OpenClaw **не** відтворює блокування на шляху
|
||||
Anthropic SDK + `ANTHROPIC_API_KEY`
|
||||
- той самий системний prompt у стилі OpenClaw **не** відтворює блокування на
|
||||
шляху Anthropic SDK + `ANTHROPIC_API_KEY`
|
||||
|
||||
Тож практичне правило таке: **Anthropic API key або Claude subscription з
|
||||
Extra Usage**. Якщо вам потрібен найочевидніший production-шлях, використовуйте Anthropic API
|
||||
Extra Usage**. Якщо вам потрібен найзрозуміліший production-шлях, використовуйте Anthropic API
|
||||
key.
|
||||
|
||||
Поточна публічна документація Anthropic:
|
||||
@ -48,17 +48,18 @@ key.
|
||||
- [Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
|
||||
- [Using Claude Code with your Team or Enterprise plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)
|
||||
|
||||
Якщо вам потрібен найзрозуміліший шлях білінгу, натомість використовуйте Anthropic API key.
|
||||
Якщо вам потрібен найзрозуміліший шлях оплати, натомість використовуйте Anthropic API
|
||||
key.
|
||||
OpenClaw також підтримує інші варіанти у стилі підписки, зокрема [OpenAI
|
||||
Codex](/providers/openai), [Qwen Cloud Coding Plan](/providers/qwen),
|
||||
[MiniMax Coding Plan](/providers/minimax) і [Z.AI / GLM Coding
|
||||
Plan](/providers/glm).
|
||||
Codex](/uk/providers/openai), [Qwen Cloud Coding Plan](/uk/providers/qwen),
|
||||
[MiniMax Coding Plan](/uk/providers/minimax) і [Z.AI / GLM Coding
|
||||
Plan](/uk/providers/glm).
|
||||
</Warning>
|
||||
|
||||
## Варіант A: Anthropic API key
|
||||
|
||||
**Найкраще для:** стандартного доступу до API та білінгу на основі використання.
|
||||
Створіть свій API-ключ у Anthropic Console.
|
||||
**Найкраще для:** стандартного доступу до API та оплати за використання.
|
||||
Створіть свій API key у Anthropic Console.
|
||||
|
||||
### Налаштування CLI
|
||||
|
||||
@ -70,7 +71,7 @@ openclaw onboard
|
||||
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
|
||||
```
|
||||
|
||||
### Фрагмент конфігурації Anthropic
|
||||
### Фрагмент config Anthropic
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -81,20 +82,20 @@ openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
|
||||
|
||||
## Типові параметри thinking (Claude 4.6)
|
||||
|
||||
- Для моделей Anthropic Claude 4.6 в OpenClaw за замовчуванням використовується `adaptive` thinking, якщо не задано явний рівень thinking.
|
||||
- Ви можете перевизначити це для окремого повідомлення (`/think:<level>`) або в параметрах моделі:
|
||||
- Для моделей Anthropic Claude 4.6 в OpenClaw за замовчуванням використовується `adaptive` thinking, якщо явно не задано рівень thinking.
|
||||
- Ви можете перевизначити його для кожного повідомлення (`/think:<level>`) або в params моделі:
|
||||
`agents.defaults.models["anthropic/<model>"].params.thinking`.
|
||||
- Пов’язана документація Anthropic:
|
||||
- [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking)
|
||||
- [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)
|
||||
|
||||
## Швидкий режим (Anthropic API)
|
||||
## Fast mode (Anthropic API)
|
||||
|
||||
Спільний перемикач `/fast` в OpenClaw також підтримує прямий публічний трафік Anthropic, включно із запитами з auth через API-key та OAuth, надісланими до `api.anthropic.com`.
|
||||
Спільний перемикач `/fast` в OpenClaw також підтримує прямий публічний трафік Anthropic, включно із запитами, автентифікованими через API key і OAuth, що надсилаються до `api.anthropic.com`.
|
||||
|
||||
- `/fast on` відповідає `service_tier: "auto"`
|
||||
- `/fast off` відповідає `service_tier: "standard_only"`
|
||||
- Значення конфігурації за замовчуванням:
|
||||
- Типове значення в config:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -113,22 +114,22 @@ openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
|
||||
Важливі обмеження:
|
||||
|
||||
- OpenClaw додає рівні сервісу Anthropic лише для прямих запитів до `api.anthropic.com`. Якщо ви маршрутизуєте `anthropic/*` через proxy або gateway, `/fast` не змінює `service_tier`.
|
||||
- Явні параметри моделі Anthropic `serviceTier` або `service_tier` мають пріоритет над типовим значенням `/fast`, якщо задано обидва.
|
||||
- Anthropic повідомляє про фактичний рівень у відповіді в полі `usage.service_tier`. Для облікових записів без доступної місткості Priority Tier значення `service_tier: "auto"` усе одно може звестися до `standard`.
|
||||
- Явно задані params моделі Anthropic `serviceTier` або `service_tier` мають пріоритет над типовою поведінкою `/fast`, якщо задано обидва параметри.
|
||||
- Anthropic повідомляє фактичний рівень у відповіді в полі `usage.service_tier`. Для облікових записів без доступної ємності Priority Tier значення `service_tier: "auto"` усе одно може зводитися до `standard`.
|
||||
|
||||
## Кешування prompt (Anthropic API)
|
||||
|
||||
OpenClaw підтримує можливість кешування prompt від Anthropic. Це **лише для API**; застаріла auth через токен Anthropic не враховує налаштування кешу.
|
||||
OpenClaw підтримує функцію кешування prompt від Anthropic. Це **лише API**; legacy Anthropic token auth не враховує параметри кешу.
|
||||
|
||||
### Конфігурація
|
||||
|
||||
Використовуйте параметр `cacheRetention` у конфігурації моделі:
|
||||
Використовуйте параметр `cacheRetention` у config моделі:
|
||||
|
||||
| Значення | Тривалість кешу | Опис |
|
||||
| ------- | --------------- | ---- |
|
||||
| Value | Тривалість кешу | Опис |
|
||||
| ------- | --------------- | ------------------------ |
|
||||
| `none` | Без кешування | Вимкнути кешування prompt |
|
||||
| `short` | 5 хвилин | Значення за замовчуванням для auth через API Key |
|
||||
| `long` | 1 година | Розширений кеш |
|
||||
| `short` | 5 хвилин | Типово для auth через API Key |
|
||||
| `long` | 1 година | Розширений кеш |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -144,13 +145,13 @@ OpenClaw підтримує можливість кешування prompt ві
|
||||
}
|
||||
```
|
||||
|
||||
### Значення за замовчуванням
|
||||
### Типові значення
|
||||
|
||||
Під час використання автентифікації через Anthropic API Key OpenClaw автоматично застосовує `cacheRetention: "short"` (кеш на 5 хвилин) для всіх моделей Anthropic. Ви можете перевизначити це, явно задавши `cacheRetention` у своїй конфігурації.
|
||||
Під час використання автентифікації через Anthropic API Key OpenClaw автоматично застосовує `cacheRetention: "short"` (5-хвилинний кеш) для всіх моделей Anthropic. Ви можете перевизначити це, явно задавши `cacheRetention` у своїй config.
|
||||
|
||||
### Перевизначення cacheRetention для окремих агентів
|
||||
### Перевизначення `cacheRetention` для окремого agent
|
||||
|
||||
Використовуйте параметри на рівні моделі як базовий варіант, а потім перевизначайте конкретних агентів через `agents.list[].params`.
|
||||
Використовуйте params на рівні моделі як базовий рівень, а потім перевизначайте конкретних agent через `agents.list[].params`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -159,34 +160,34 @@ OpenClaw підтримує можливість кешування prompt ві
|
||||
model: { primary: "anthropic/claude-opus-4-6" },
|
||||
models: {
|
||||
"anthropic/claude-opus-4-6": {
|
||||
params: { cacheRetention: "long" }, // базове значення для більшості агентів
|
||||
params: { cacheRetention: "long" }, // baseline for most agents
|
||||
},
|
||||
},
|
||||
},
|
||||
list: [
|
||||
{ id: "research", default: true },
|
||||
{ id: "alerts", params: { cacheRetention: "none" } }, // перевизначення лише для цього агента
|
||||
{ id: "alerts", params: { cacheRetention: "none" } }, // override for this agent only
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Порядок злиття конфігурації для параметрів, пов’язаних із кешем:
|
||||
Порядок злиття config для параметрів, пов’язаних із кешем:
|
||||
|
||||
1. `agents.defaults.models["provider/model"].params`
|
||||
2. `agents.list[].params` (відповідний `id`, перевизначення за ключем)
|
||||
|
||||
Це дозволяє одному агенту зберігати довгоживучий кеш, тоді як інший агент на тій самій моделі вимикає кешування, щоб уникнути витрат на запис для імпульсного трафіку або трафіку з низьким повторним використанням.
|
||||
Це дає змогу одному agent зберігати довготривалий кеш, а іншому agent на тій самій моделі вимикати кешування, щоб уникнути витрат на запис для імпульсного трафіку або трафіку з низьким повторним використанням.
|
||||
|
||||
### Примітки щодо Bedrock Claude
|
||||
|
||||
- Моделі Anthropic Claude у Bedrock (`amazon-bedrock/*anthropic.claude*`) приймають наскрізну передачу `cacheRetention`, якщо її налаштовано.
|
||||
- Для моделей Bedrock, які не є Anthropic, під час виконання примусово встановлюється `cacheRetention: "none"`.
|
||||
- Розумні типові значення Anthropic API-key також задають `cacheRetention: "short"` для посилань на моделі Claude-on-Bedrock, якщо явне значення не встановлено.
|
||||
- Моделі Anthropic Claude на Bedrock (`amazon-bedrock/*anthropic.claude*`) приймають наскрізну передачу `cacheRetention`, якщо це налаштовано.
|
||||
- Для моделей Bedrock не від Anthropic під час виконання примусово встановлюється `cacheRetention: "none"`.
|
||||
- Розумні типові значення Anthropic API-key також встановлюють `cacheRetention: "short"` для посилань на моделі Claude-on-Bedrock, якщо явне значення не задано.
|
||||
|
||||
## Вікно контексту 1M (бета Anthropic)
|
||||
|
||||
Вікно контексту 1M від Anthropic є бета-можливістю з обмеженим доступом. У OpenClaw увімкніть його для окремої моделі
|
||||
Вікно контексту Anthropic 1M доступне лише в beta. У OpenClaw його можна ввімкнути для кожної моделі окремо
|
||||
через `params.context1m: true` для підтримуваних моделей Opus/Sonnet.
|
||||
|
||||
```json5
|
||||
@ -203,73 +204,75 @@ OpenClaw підтримує можливість кешування prompt ві
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw зіставляє це з `anthropic-beta: context-1m-2025-08-07` у запитах
|
||||
OpenClaw відображає це в `anthropic-beta: context-1m-2025-08-07` у запитах
|
||||
Anthropic.
|
||||
|
||||
Це активується лише тоді, коли `params.context1m` явно встановлено в `true` для
|
||||
цієї моделі.
|
||||
|
||||
Вимога: Anthropic має дозволяти використання довгого контексту для цих облікових даних
|
||||
(зазвичай білінг через API key або шлях Claude-login / застарілу auth через токен в OpenClaw
|
||||
(зазвичай це оплата через API key або шлях Claude-login / legacy token auth у OpenClaw
|
||||
з увімкненим Extra Usage). Інакше Anthropic повертає:
|
||||
`HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
|
||||
|
||||
Примітка: наразі Anthropic відхиляє бета-запити `context-1m-*` при використанні
|
||||
застарілої auth через токен Anthropic (`sk-ant-oat-*`). Якщо ви налаштуєте
|
||||
`context1m: true` з цим застарілим режимом auth, OpenClaw запише попередження в журнал і
|
||||
Примітка: наразі Anthropic відхиляє beta-запити `context-1m-*` під час використання
|
||||
legacy Anthropic token auth (`sk-ant-oat-*`). Якщо ви налаштуєте
|
||||
`context1m: true` з цим legacy режимом auth, OpenClaw запише попередження в журнал і
|
||||
повернеться до стандартного вікна контексту, пропустивши beta-заголовок context1m,
|
||||
але зберігши потрібні beta-параметри OAuth.
|
||||
зберігши при цьому обов’язкові OAuth beta.
|
||||
|
||||
## Видалено: бекенд Claude CLI
|
||||
## Видалено: backend Claude CLI
|
||||
|
||||
Вбудований бекенд Anthropic `claude-cli` було видалено.
|
||||
Вбудований backend Anthropic `claude-cli` було видалено.
|
||||
|
||||
- У повідомленні Anthropic від 4 квітня 2026 року сказано, що трафік Claude-login, ініційований OpenClaw,
|
||||
є використанням стороннього harness і вимагає **Extra Usage**.
|
||||
- Наші локальні відтворення також показують, що прямий
|
||||
`claude -p --append-system-prompt ...` може натрапити на ту саму перевірку, коли
|
||||
`claude -p --append-system-prompt ...` може наштовхуватися на той самий захист, коли
|
||||
доданий prompt ідентифікує OpenClaw.
|
||||
- Та сама форма system prompt у стилі OpenClaw не викликає цю перевірку на
|
||||
- Той самий системний prompt у стилі OpenClaw не активує цей захист на
|
||||
шляху Anthropic SDK + `ANTHROPIC_API_KEY`.
|
||||
- Для трафіку Anthropic в OpenClaw використовуйте API-ключі Anthropic.
|
||||
- Для трафіку Anthropic в OpenClaw використовуйте Anthropic API keys.
|
||||
- Якщо вам потрібен локальний резервний runtime на основі CLI, використовуйте інший підтримуваний CLI backend,
|
||||
наприклад Codex CLI. Див. [/gateway/cli-backends](/gateway/cli-backends).
|
||||
|
||||
## Примітки
|
||||
|
||||
- Публічна документація Anthropic для Claude Code усе ще описує пряме використання CLI, зокрема
|
||||
- Публічна документація Anthropic для Claude Code усе ще описує пряме використання CLI, наприклад
|
||||
`claude -p`, але окреме повідомлення Anthropic для користувачів OpenClaw каже, що
|
||||
шлях Claude-login у **OpenClaw** є використанням стороннього harness і вимагає
|
||||
**Extra Usage** (pay-as-you-go, що оплачується окремо від підписки).
|
||||
**Extra Usage** (оплата за фактом використання, окремо від підписки).
|
||||
Наші локальні відтворення також показують, що прямий
|
||||
`claude -p --append-system-prompt ...` може натрапити на ту саму перевірку, коли
|
||||
доданий prompt ідентифікує OpenClaw, тоді як та сама форма prompt не
|
||||
відтворює це на шляху Anthropic SDK + `ANTHROPIC_API_KEY`. Для production ми
|
||||
натомість рекомендуємо Anthropic API-ключі.
|
||||
- Anthropic setup-token знову доступний в OpenClaw як застарілий/ручний шлях. Повідомлення Anthropic щодо білінгу для OpenClaw усе ще застосовується, тож використовуйте його з розумінням того, що Anthropic вимагає **Extra Usage** для цього шляху.
|
||||
- Деталі auth і правила повторного використання наведено в [/concepts/oauth](/uk/concepts/oauth).
|
||||
`claude -p --append-system-prompt ...` може наштовхуватися на той самий захист, коли
|
||||
доданий prompt ідентифікує OpenClaw, тоді як той самий формат prompt не
|
||||
відтворюється на шляху Anthropic SDK + `ANTHROPIC_API_KEY`. Для production ми
|
||||
натомість рекомендуємо Anthropic API keys.
|
||||
- setup-token Anthropic знову доступний в OpenClaw як legacy/manual шлях. Повідомлення Anthropic про оплату, специфічне для OpenClaw, і далі застосовується, тож використовуйте його з розумінням, що Anthropic вимагає **Extra Usage** для цього шляху.
|
||||
- Подробиці auth і правила повторного використання наведені в [/concepts/oauth](/uk/concepts/oauth).
|
||||
|
||||
## Усунення несправностей
|
||||
## Усунення проблем
|
||||
|
||||
**Помилки 401 / токен раптово став недійсним**
|
||||
**Помилки 401 / токен раптово став невалідним**
|
||||
|
||||
- Застаріла auth через токен Anthropic може завершитися або бути відкликаною.
|
||||
- Legacy Anthropic token auth може завершитися або бути відкликаним.
|
||||
- Для нового налаштування перейдіть на Anthropic API key.
|
||||
|
||||
**Не знайдено API key для provider "anthropic"**
|
||||
**Не знайдено API key для провайдера "anthropic"**
|
||||
|
||||
- Auth є **для кожного агента окремо**. Нові агенти не успадковують ключі головного агента.
|
||||
- Повторно запустіть онбординг для цього агента або налаштуйте API key на host
|
||||
- Auth є **для кожного agent окремо**. Нові agent не успадковують ключі головного agent.
|
||||
- Повторно запустіть onboarding для цього agent або налаштуйте API key на хості
|
||||
gateway, а потім перевірте через `openclaw models status`.
|
||||
|
||||
**Не знайдено облікові дані для профілю `anthropic:default`**
|
||||
**Не знайдено облікових даних для profile `anthropic:default`**
|
||||
|
||||
- Запустіть `openclaw models status`, щоб побачити, який профіль auth активний.
|
||||
- Повторно запустіть онбординг або налаштуйте API key для цього шляху профілю.
|
||||
- Запустіть `openclaw models status`, щоб побачити, який auth profile активний.
|
||||
- Повторно запустіть onboarding або налаштуйте API key для цього шляху profile.
|
||||
|
||||
**Немає доступного профілю auth (усі в cooldown/unavailable)**
|
||||
**Немає доступного auth profile (усі в cooldown/недоступні)**
|
||||
|
||||
- Перевірте `openclaw models status --json` для `auth.unusableProfiles`.
|
||||
- Cooldown через обмеження швидкості Anthropic може бути прив’язаний до моделі, тож сусідня модель Anthropic
|
||||
все ще може бути придатною до використання, навіть якщо поточна перебуває в cooldown.
|
||||
- Додайте ще один профіль Anthropic або дочекайтеся завершення cooldown.
|
||||
- Перевірте `openclaw models status --json` на `auth.unusableProfiles`.
|
||||
- Cooldown rate limit Anthropic може бути прив’язаним до моделі, тож споріднена модель Anthropic
|
||||
усе ще може бути придатною, навіть коли поточна перебуває в cooldown.
|
||||
- Додайте ще один profile Anthropic або дочекайтеся завершення cooldown.
|
||||
|
||||
Докладніше: [/gateway/troubleshooting](/uk/gateway/troubleshooting) і [/help/faq](/help/faq).
|
||||
Більше: [/gateway/troubleshooting](/uk/gateway/troubleshooting) і [/help/faq](/uk/help/faq).
|
||||
|
||||
@ -1,37 +1,38 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете використовувати моделі Google Gemini з OpenClaw
|
||||
- Вам потрібен потік автентифікації за ключем API
|
||||
summary: Налаштування Google Gemini (ключ API, генерація зображень, розуміння медіа, вебпошук)
|
||||
- Вам потрібен потік автентифікації через API-ключ або OAuth
|
||||
summary: Налаштування Google Gemini (API-ключ + OAuth, генерація зображень, розуміння медіа, вебпошук)
|
||||
title: Google (Gemini)
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T00:51:57Z"
|
||||
generated_at: "2026-04-06T12:44:57Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 358d33a68275b01ebd916a3621dd651619cb9a1d062e2fb6196a7f3c501c015a
|
||||
source_hash: 36cc7c7d8d19f6d4a3fb223af36c8402364fc309d14ffe922bd004203ceb1754
|
||||
source_path: providers/google.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Google (Gemini)
|
||||
|
||||
Плагін Google надає доступ до моделей Gemini через Google AI Studio, а також до
|
||||
генерації зображень, розуміння медіа (зображення/аудіо/відео) і вебпошуку через
|
||||
Плагін Google надає доступ до моделей Gemini через Google AI Studio, а також
|
||||
до генерації зображень, розуміння медіа (зображення/аудіо/відео) і вебпошуку через
|
||||
Gemini Grounding.
|
||||
|
||||
- Провайдер: `google`
|
||||
- Постачальник: `google`
|
||||
- Автентифікація: `GEMINI_API_KEY` або `GOOGLE_API_KEY`
|
||||
- API: Google Gemini API
|
||||
- Альтернативний постачальник: `google-gemini-cli` (OAuth)
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
1. Установіть ключ API:
|
||||
1. Задайте API-ключ:
|
||||
|
||||
```bash
|
||||
openclaw onboard --auth-choice gemini-api-key
|
||||
```
|
||||
|
||||
2. Установіть модель за замовчуванням:
|
||||
2. Задайте типову модель:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -52,6 +53,46 @@ openclaw onboard --non-interactive \
|
||||
--gemini-api-key "$GEMINI_API_KEY"
|
||||
```
|
||||
|
||||
## OAuth (Gemini CLI)
|
||||
|
||||
Альтернативний постачальник `google-gemini-cli` використовує PKCE OAuth замість API-
|
||||
ключа. Це неофіційна інтеграція; деякі користувачі повідомляють про обмеження
|
||||
облікового запису. Використовуйте на власний ризик.
|
||||
|
||||
- Типова модель: `google-gemini-cli/gemini-3.1-pro-preview`
|
||||
- Псевдонім: `gemini-cli`
|
||||
- Обов'язкова передумова для встановлення: локальний Gemini CLI, доступний як `gemini`
|
||||
- Homebrew: `brew install gemini-cli`
|
||||
- npm: `npm install -g @google/gemini-cli`
|
||||
- Вхід:
|
||||
|
||||
```bash
|
||||
openclaw models auth login --provider google-gemini-cli --set-default
|
||||
```
|
||||
|
||||
Змінні середовища:
|
||||
|
||||
- `OPENCLAW_GEMINI_OAUTH_CLIENT_ID`
|
||||
- `OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET`
|
||||
|
||||
(Або варіанти `GEMINI_CLI_*`.)
|
||||
|
||||
Якщо запити Gemini CLI OAuth не працюють після входу, задайте
|
||||
`GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на gateway host і
|
||||
повторіть спробу.
|
||||
|
||||
Якщо вхід завершується помилкою до початку потоку в браузері, переконайтеся, що локальна команда `gemini`
|
||||
встановлена й присутня в `PATH`. OpenClaw підтримує як встановлення через Homebrew,
|
||||
так і глобальні встановлення npm, зокрема поширені Windows/npm-схеми.
|
||||
|
||||
Примітки щодо використання Gemini CLI JSON:
|
||||
|
||||
- Текст відповіді береться з поля CLI JSON `response`.
|
||||
- Дані використання резервно беруться з `stats`, коли CLI залишає `usage` порожнім.
|
||||
- `stats.cached` нормалізується в OpenClaw `cacheRead`.
|
||||
- Якщо `stats.input` відсутній, OpenClaw виводить вхідні токени з
|
||||
`stats.input_tokens - stats.cached`.
|
||||
|
||||
## Можливості
|
||||
|
||||
| Можливість | Підтримується |
|
||||
@ -60,22 +101,22 @@ openclaw onboard --non-interactive \
|
||||
| Генерація зображень | Так |
|
||||
| Генерація музики | Так |
|
||||
| Розуміння зображень | Так |
|
||||
| Транскрибування аудіо | Так |
|
||||
| Транскрипція аудіо | Так |
|
||||
| Розуміння відео | Так |
|
||||
| Вебпошук (Grounding) | Так |
|
||||
| Мислення/міркування | Так (Gemini 3.1+) |
|
||||
| Thinking/reasoning | Так (Gemini 3.1+) |
|
||||
|
||||
## Пряме повторне використання кешу Gemini
|
||||
|
||||
Для прямих запусків Gemini API (`api: "google-generative-ai"`) OpenClaw тепер
|
||||
передає налаштований дескриптор `cachedContent` у запити до Gemini.
|
||||
передає налаштований дескриптор `cachedContent` у запити Gemini.
|
||||
|
||||
- Налаштовуйте параметри для окремої моделі або глобально за допомогою
|
||||
`cachedContent` або застарілого `cached_content`
|
||||
- Налаштуйте параметри для окремої моделі або глобально через
|
||||
`cachedContent` або застарілий `cached_content`
|
||||
- Якщо присутні обидва, пріоритет має `cachedContent`
|
||||
- Приклад значення: `cachedContents/prebuilt-context`
|
||||
- Використання Gemini cache-hit нормалізується в OpenClaw як `cacheRead` з
|
||||
вхідного `cachedContentTokenCount`
|
||||
- Використання потрапляння в кеш Gemini нормалізується в OpenClaw `cacheRead` з
|
||||
upstream `cachedContentTokenCount`
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -97,18 +138,19 @@ openclaw onboard --non-interactive \
|
||||
|
||||
## Генерація зображень
|
||||
|
||||
Вбудований провайдер генерації зображень `google` за замовчуванням використовує
|
||||
Вбудований постачальник генерації зображень `google` типово використовує
|
||||
`google/gemini-3.1-flash-image-preview`.
|
||||
|
||||
- Також підтримує `google/gemini-3-pro-image-preview`
|
||||
- Генерація: до 4 зображень на запит
|
||||
- Генерація: до 4 зображень за запит
|
||||
- Режим редагування: увімкнено, до 5 вхідних зображень
|
||||
- Керування геометрією: `size`, `aspectRatio` і `resolution`
|
||||
|
||||
Генерація зображень, розуміння медіа та Gemini Grounding усе ще використовують
|
||||
ідентифікатор провайдера `google`.
|
||||
Постачальник `google-gemini-cli`, доступний лише через OAuth, — це окрема
|
||||
поверхня текстового inference. Генерація зображень, розуміння медіа та Gemini Grounding залишаються
|
||||
на ідентифікаторі постачальника `google`.
|
||||
|
||||
Щоб використовувати Google як провайдера зображень за замовчуванням:
|
||||
Щоб використовувати Google як типовий постачальник зображень:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -122,20 +164,20 @@ openclaw onboard --non-interactive \
|
||||
}
|
||||
```
|
||||
|
||||
Див. [Генерація зображень](/uk/tools/image-generation), щоб дізнатися про спільні
|
||||
параметри інструмента, вибір провайдера та поведінку аварійного перемикання.
|
||||
Див. [Image Generation](/uk/tools/image-generation) щодо спільних параметрів
|
||||
інструмента, вибору постачальника та поведінки резервного перемикання.
|
||||
|
||||
## Генерація відео
|
||||
|
||||
Вбудований плагін `google` також реєструє генерацію відео через спільний
|
||||
інструмент `video_generate`.
|
||||
|
||||
- Модель відео за замовчуванням: `google/veo-3.1-fast-generate-preview`
|
||||
- Режими: text-to-video, image-to-video і потоки з одним еталонним відео
|
||||
- Типова відеомодель: `google/veo-3.1-fast-generate-preview`
|
||||
- Режими: text-to-video, image-to-video і потоки з одним референсним відео
|
||||
- Підтримує `aspectRatio`, `resolution` і `audio`
|
||||
- Поточне обмеження тривалості: **від 4 до 8 секунд**
|
||||
|
||||
Щоб використовувати Google як провайдера відео за замовчуванням:
|
||||
Щоб використовувати Google як типовий постачальник відео:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -149,22 +191,22 @@ openclaw onboard --non-interactive \
|
||||
}
|
||||
```
|
||||
|
||||
Див. [Генерація відео](/uk/tools/video-generation), щоб дізнатися про спільні
|
||||
параметри інструмента, вибір провайдера та поведінку аварійного перемикання.
|
||||
Див. [Video Generation](/uk/tools/video-generation) щодо спільних параметрів
|
||||
інструмента, вибору постачальника та поведінки резервного перемикання.
|
||||
|
||||
## Генерація музики
|
||||
|
||||
Вбудований плагін `google` також реєструє генерацію музики через спільний
|
||||
інструмент `music_generate`.
|
||||
|
||||
- Модель музики за замовчуванням: `google/lyria-3-clip-preview`
|
||||
- Типова музична модель: `google/lyria-3-clip-preview`
|
||||
- Також підтримує `google/lyria-3-pro-preview`
|
||||
- Керування запитом: `lyrics` і `instrumental`
|
||||
- Формат виводу: `mp3` за замовчуванням, а також `wav` для `google/lyria-3-pro-preview`
|
||||
- Еталонні вхідні дані: до 10 зображень
|
||||
- Запуски на основі сесій відокремлюються через спільний потік завдань/стану, включно з `action: "status"`
|
||||
- Керування промптом: `lyrics` і `instrumental`
|
||||
- Формат виводу: типово `mp3`, а також `wav` для `google/lyria-3-pro-preview`
|
||||
- Референсні входи: до 10 зображень
|
||||
- Запуски з підтримкою сесії від'єднуються через спільний потік завдання/статусу, включно з `action: "status"`
|
||||
|
||||
Щоб використовувати Google як музичного провайдера за замовчуванням:
|
||||
Щоб використовувати Google як типовий постачальник музики:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -178,8 +220,8 @@ openclaw onboard --non-interactive \
|
||||
}
|
||||
```
|
||||
|
||||
Див. [Генерація музики](/uk/tools/music-generation), щоб дізнатися про спільні
|
||||
параметри інструмента, вибір провайдера та поведінку аварійного перемикання.
|
||||
Див. [Music Generation](/uk/tools/music-generation) щодо спільних параметрів
|
||||
інструмента, вибору постачальника та поведінки резервного перемикання.
|
||||
|
||||
## Примітка щодо середовища
|
||||
|
||||
|
||||
@ -1,27 +1,27 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете вибрати постачальника моделей
|
||||
- Ви хочете швидкі приклади налаштування автентифікації LLM і вибору моделі
|
||||
summary: Постачальники моделей (LLM), які підтримує OpenClaw
|
||||
title: Швидкий старт для постачальника моделей
|
||||
- Ви хочете вибрати провайдера моделі
|
||||
- Вам потрібні швидкі приклади налаштування автентифікації LLM і вибору моделі
|
||||
summary: Провайдери моделей (LLM), які підтримує OpenClaw
|
||||
title: Швидкий старт провайдерів моделей
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T00:47:22Z"
|
||||
generated_at: "2026-04-06T12:44:59Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c0314fb1c754171e5fc252d30f7ba9bb6acdbb978d97e9249264d90351bac2e7
|
||||
source_hash: 500191bfe853241096f97928ced2327a13b6f7f62003cb7452b24886c272e6ba
|
||||
source_path: providers/models.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Постачальники моделей
|
||||
# Провайдери моделей
|
||||
|
||||
OpenClaw може використовувати багато постачальників LLM. Виберіть одного, пройдіть автентифікацію, а потім встановіть типову
|
||||
модель як `provider/model`.
|
||||
OpenClaw може використовувати багато провайдерів LLM. Виберіть одного, пройдіть автентифікацію, а потім задайте типову
|
||||
модель у форматі `provider/model`.
|
||||
|
||||
## Швидкий старт (два кроки)
|
||||
|
||||
1. Пройдіть автентифікацію у постачальника (зазвичай через `openclaw onboard`).
|
||||
2. Встановіть типову модель:
|
||||
1. Пройдіть автентифікацію у провайдера (зазвичай через `openclaw onboard`).
|
||||
2. Задайте типову модель:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -29,18 +29,18 @@ OpenClaw може використовувати багато постачаль
|
||||
}
|
||||
```
|
||||
|
||||
## Підтримувані постачальники (стартовий набір)
|
||||
## Підтримувані провайдери (стартовий набір)
|
||||
|
||||
- [Alibaba Model Studio](/uk/providers/alibaba)
|
||||
- [Anthropic (API + Claude CLI)](/uk/providers/anthropic)
|
||||
- [Amazon Bedrock](/uk/providers/bedrock)
|
||||
- [BytePlus (міжнародний)](/uk/concepts/model-providers#byteplus-international)
|
||||
- [Chutes](/uk/providers/chutes)
|
||||
- [ComfyUI](/providers/comfy)
|
||||
- [ComfyUI](/uk/providers/comfy)
|
||||
- [Cloudflare AI Gateway](/uk/providers/cloudflare-ai-gateway)
|
||||
- [fal](/uk/providers/fal)
|
||||
- [Fireworks](/uk/providers/fireworks)
|
||||
- [Моделі GLM](/uk/providers/glm)
|
||||
- [GLM models](/uk/providers/glm)
|
||||
- [MiniMax](/uk/providers/minimax)
|
||||
- [Mistral](/uk/providers/mistral)
|
||||
- [Moonshot AI (Kimi + Kimi Coding)](/uk/providers/moonshot)
|
||||
@ -57,10 +57,10 @@ OpenClaw може використовувати багато постачаль
|
||||
- [xAI](/uk/providers/xai)
|
||||
- [Z.AI](/uk/providers/zai)
|
||||
|
||||
## Додаткові варіанти вбудованих постачальників
|
||||
## Додаткові варіанти вбудованих провайдерів
|
||||
|
||||
- `anthropic-vertex` - неявна підтримка Anthropic у Google Vertex, коли доступні облікові дані Vertex; окремий вибір автентифікації під час онбордингу не потрібен
|
||||
- `anthropic-vertex` - неявна підтримка Anthropic у Google Vertex, коли доступні облікові дані Vertex; окремий варіант автентифікації для онбордингу не потрібен
|
||||
- `copilot-proxy` - локальний міст VS Code Copilot Proxy; використовуйте `openclaw onboard --auth-choice copilot-proxy`
|
||||
- `google-gemini-cli` - неофіційний OAuth-потік Gemini CLI; потребує локально встановленого `gemini` (`brew install gemini-cli` або `npm install -g @google/gemini-cli`); типова модель `google-gemini-cli/gemini-3.1-pro-preview`; використовуйте `openclaw onboard --auth-choice google-gemini-cli` або `openclaw models auth login --provider google-gemini-cli --set-default`
|
||||
|
||||
Повний каталог постачальників (xAI, Groq, Mistral тощо) і розширене налаштування
|
||||
дивіться в розділі [Постачальники моделей](/uk/concepts/model-providers).
|
||||
Повний каталог провайдерів (xAI, Groq, Mistral тощо) і розширену конфігурацію дивіться в [Model providers](/uk/concepts/model-providers).
|
||||
|
||||
@ -1,32 +1,32 @@
|
||||
---
|
||||
read_when:
|
||||
- Потрібно налагодити ідентифікатори сесій, JSONL транскрипту або поля в sessions.json
|
||||
- Ви змінюєте поведінку автоущільнення або додаєте службові дії “перед ущільненням”
|
||||
- Вам потрібно налагодити ідентифікатори сесій, JSONL транскриптів або поля sessions.json
|
||||
- Ви змінюєте поведінку автокомпакції або додаєте господарські дії «перед компакцією»
|
||||
- Ви хочете реалізувати скидання пам’яті або тихі системні ходи
|
||||
summary: 'Глибокий розбір: сховище сесій і транскрипти, життєвий цикл та внутрішні механізми (авто)ущільнення'
|
||||
title: Глибокий розбір керування сесіями
|
||||
summary: 'Поглиблений розбір: сховище сесій і транскрипти, життєвий цикл та внутрішня логіка (авто)компакції'
|
||||
title: Поглиблений розбір керування сесіями
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T18:49:16Z"
|
||||
generated_at: "2026-04-06T12:45:52Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e0d8c2d30be773eac0424f7a4419ab055fdd50daac8bc654e7d250c891f2c3b8
|
||||
source_hash: e379d624dd7808d3af25ed011079268ce6a9da64bb3f301598884ad4c46ab091
|
||||
source_path: reference/session-management-compaction.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Керування сесіями та ущільнення (глибокий розбір)
|
||||
# Керування сесіями та компакція (поглиблений розбір)
|
||||
|
||||
У цьому документі пояснюється, як OpenClaw керує сесіями наскрізно:
|
||||
|
||||
- **Маршрутизація сесій** (як вхідні повідомлення зіставляються з `sessionKey`)
|
||||
- **Сховище сесій** (`sessions.json`) і що воно відстежує
|
||||
- **Збереження транскрипту** (`*.jsonl`) та його структура
|
||||
- **Гігієна транскрипту** (виправлення для конкретних провайдерів перед запусками)
|
||||
- **Збереження транскриптів** (`*.jsonl`) та їхня структура
|
||||
- **Гігієна транскриптів** (виправлення, специфічні для постачальника, перед запусками)
|
||||
- **Обмеження контексту** (вікно контексту проти відстежуваних токенів)
|
||||
- **Ущільнення** (ручне + автоущільнення) і куди підключати роботу перед ущільненням
|
||||
- **Тихі службові дії** (наприклад, запис пам’яті, який не повинен створювати видимий для користувача вивід)
|
||||
- **Компакція** (ручна + автокомпакція) і куди підключати логіку перед компакцією
|
||||
- **Тихі господарські дії** (наприклад, записи в пам’ять, які не повинні створювати видимий користувачу вивід)
|
||||
|
||||
Якщо спочатку потрібен огляд вищого рівня, почніть із:
|
||||
Якщо вам спочатку потрібен огляд вищого рівня, почніть із:
|
||||
|
||||
- [/concepts/session](/uk/concepts/session)
|
||||
- [/concepts/compaction](/uk/concepts/compaction)
|
||||
@ -39,32 +39,32 @@ x-i18n:
|
||||
|
||||
## Джерело істини: Gateway
|
||||
|
||||
OpenClaw спроєктовано навколо єдиного **процесу Gateway**, який володіє станом сесій.
|
||||
OpenClaw спроєктовано навколо одного **процесу Gateway**, який володіє станом сесій.
|
||||
|
||||
- Інтерфейси (macOS app, веб-інтерфейс Control UI, TUI) мають запитувати в Gateway списки сесій і кількість токенів.
|
||||
- У віддаленому режимі файли сесій розміщені на віддаленому хості; “перевірка локальних файлів на Mac” не покаже те, що використовує Gateway.
|
||||
- Інтерфейси користувача (macOS app, web Control UI, TUI) повинні запитувати Gateway щодо списків сесій і кількості токенів.
|
||||
- У віддаленому режимі файли сесій розміщені на віддаленому хості; «перевірка локальних файлів Mac» не покаже те, що використовує Gateway.
|
||||
|
||||
---
|
||||
|
||||
## Два шари збереження
|
||||
## Два рівні збереження
|
||||
|
||||
OpenClaw зберігає сесії у двох шарах:
|
||||
OpenClaw зберігає сесії у двох рівнях:
|
||||
|
||||
1. **Сховище сесій (`sessions.json`)**
|
||||
- Мапа ключ/значення: `sessionKey -> SessionEntry`
|
||||
- Маленьке, змінюване, безпечно редагувати (або видаляти записи)
|
||||
- Відстежує метадані сесії (поточний id сесії, останню активність, перемикачі, лічильники токенів тощо)
|
||||
- Невелике, змінюване, безпечне для редагування (або видалення записів)
|
||||
- Відстежує метадані сесії (поточний ідентифікатор сесії, останню активність, перемикачі, лічильники токенів тощо)
|
||||
|
||||
2. **Транскрипт (`<sessionId>.jsonl`)**
|
||||
- Транскрипт лише з додаванням записів із деревоподібною структурою (записи мають `id` + `parentId`)
|
||||
- Зберігає фактичну розмову + виклики інструментів + зведення ущільнення
|
||||
- Транскрипт із дописуванням у кінець і деревоподібною структурою (записи мають `id` + `parentId`)
|
||||
- Зберігає фактичну розмову + виклики інструментів + підсумки компакції
|
||||
- Використовується для відновлення контексту моделі для майбутніх ходів
|
||||
|
||||
---
|
||||
|
||||
## Розташування на диску
|
||||
|
||||
Для кожного агента, на хості Gateway:
|
||||
Для кожного агента на хості Gateway:
|
||||
|
||||
- Сховище: `~/.openclaw/agents/<agentId>/sessions/sessions.json`
|
||||
- Транскрипти: `~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl`
|
||||
@ -76,25 +76,25 @@ OpenClaw визначає ці шляхи через `src/config/sessions.ts`.
|
||||
|
||||
## Обслуговування сховища та контроль диска
|
||||
|
||||
Збереження сесій має автоматичні механізми обслуговування (`session.maintenance`) для `sessions.json` і артефактів транскриптів:
|
||||
Збереження сесій має автоматичні засоби обслуговування (`session.maintenance`) для `sessions.json` і артефактів транскриптів:
|
||||
|
||||
- `mode`: `warn` (типово) або `enforce`
|
||||
- `pruneAfter`: поріг віку застарілих записів для очищення (типово `30d`)
|
||||
- `maxEntries`: обмеження кількості записів у `sessions.json` (типово `500`)
|
||||
- `rotateBytes`: ротація `sessions.json`, коли файл стає завеликим (типово `10mb`)
|
||||
- `resetArchiveRetention`: термін зберігання архівів транскриптів `*.reset.<timestamp>` (типово: такий самий, як `pruneAfter`; `false` вимикає очищення)
|
||||
- `maxDiskBytes`: необов’язковий бюджет каталогу sessions на диску
|
||||
- `rotateBytes`: ротація `sessions.json`, якщо файл завеликий (типово `10mb`)
|
||||
- `resetArchiveRetention`: строк зберігання архівів транскриптів `*.reset.<timestamp>` (типово: той самий, що й `pruneAfter`; `false` вимикає очищення)
|
||||
- `maxDiskBytes`: необов’язковий бюджет каталогу сесій на диску
|
||||
- `highWaterBytes`: необов’язкова ціль після очищення (типово `80%` від `maxDiskBytes`)
|
||||
|
||||
Порядок примусового очищення для бюджету диска (`mode: "enforce"`):
|
||||
Порядок застосування політики очищення бюджету диска (`mode: "enforce"`):
|
||||
|
||||
1. Спочатку видалити найстаріші архівовані або осиротілі артефакти транскриптів.
|
||||
2. Якщо все ще вище за ціль, витіснити найстаріші записи сесій і їхні файли транскриптів.
|
||||
3. Продовжувати, доки використання не стане на рівні або нижче `highWaterBytes`.
|
||||
1. Спочатку видаляються найстаріші архівовані або осиротілі артефакти транскриптів.
|
||||
2. Якщо використання все ще вище цілі, витісняються найстаріші записи сесій та їхні файли транскриптів.
|
||||
3. Процес триває, доки використання не стане меншим або рівним `highWaterBytes`.
|
||||
|
||||
У режимі `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,13 +118,13 @@ 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>`
|
||||
- Webhook: `hook:<uuid>` (якщо не перевизначено)
|
||||
|
||||
Канонічні правила задокументовано в [/concepts/session](/uk/concepts/session).
|
||||
Канонічні правила описано в [/concepts/session](/uk/concepts/session).
|
||||
|
||||
---
|
||||
|
||||
@ -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,99 +147,100 @@ openclaw sessions cleanup --enforce
|
||||
|
||||
Тип значення сховища — `SessionEntry` у `src/config/sessions.ts`.
|
||||
|
||||
Ключові поля (не вичерпний список):
|
||||
Ключові поля (не вичерпно):
|
||||
|
||||
- `sessionId`: поточний id транскрипту (ім’я файлу виводиться з нього, якщо не задано `sessionFile`)
|
||||
- `updatedAt`: мітка часу останньої активності
|
||||
- `sessionFile`: необов’язкове явне перевизначення шляху транскрипту
|
||||
- `chatType`: `direct | group | room` (допомагає інтерфейсам і політиці надсилання)
|
||||
- `sessionId`: поточний ідентифікатор транскрипту (ім’я файла виводиться з нього, якщо не задано `sessionFile`)
|
||||
- `updatedAt`: час останньої активності
|
||||
- `sessionFile`: необов’язкове явне перевизначення шляху до транскрипту
|
||||
- `chatType`: `direct | group | room` (допомагає UI і політиці надсилання)
|
||||
- `provider`, `subject`, `room`, `space`, `displayName`: метадані для позначення груп/каналів
|
||||
- Перемикачі:
|
||||
- `thinkingLevel`, `verboseLevel`, `reasoningLevel`, `elevatedLevel`
|
||||
- `sendPolicy` (перевизначення для конкретної сесії)
|
||||
- `sendPolicy` (перевизначення для окремої сесії)
|
||||
- Вибір моделі:
|
||||
- `providerOverride`, `modelOverride`, `authProfileOverride`
|
||||
- Лічильники токенів (best-effort / залежать від провайдера):
|
||||
- Лічильники токенів (best-effort / залежать від постачальника):
|
||||
- `inputTokens`, `outputTokens`, `totalTokens`, `contextTokens`
|
||||
- `compactionCount`: скільки разів автоущільнення завершувалося для цього ключа сесії
|
||||
- `memoryFlushAt`: мітка часу останнього скидання пам’яті перед ущільненням
|
||||
- `memoryFlushCompactionCount`: лічильник ущільнень, коли востаннє виконувався flush
|
||||
- `compactionCount`: скільки разів автокомпакція завершувалась для цього ключа сесії
|
||||
- `memoryFlushAt`: часовий штамп останнього скидання пам’яті перед компакцією
|
||||
- `memoryFlushCompactionCount`: лічильник компакції на момент останнього скидання
|
||||
|
||||
Сховище безпечно редагувати, але Gateway є джерелом істини: під час виконання сесій він може переписувати або повторно гідратувати записи.
|
||||
Сховище можна безпечно редагувати, але Gateway є джерелом істини: під час роботи сесій він може переписувати або перевідновлювати записи.
|
||||
|
||||
---
|
||||
|
||||
## Структура транскрипту (`*.jsonl`)
|
||||
|
||||
Транскриптами керує `SessionManager` з `@mariozechner/pi-coding-agent`.
|
||||
Транскриптами керує `SessionManager` із `@mariozechner/pi-coding-agent`.
|
||||
|
||||
Файл має формат JSONL:
|
||||
|
||||
- Перший рядок: заголовок сесії (`type: "session"`, містить `id`, `cwd`, `timestamp`, необов’язковий `parentSession`)
|
||||
- Перший рядок: заголовок сесії (`type: "session"`, містить `id`, `cwd`, `timestamp`, необов’язково `parentSession`)
|
||||
- Далі: записи сесії з `id` + `parentId` (дерево)
|
||||
|
||||
Помітні типи записів:
|
||||
|
||||
- `message`: повідомлення user/assistant/toolResult
|
||||
- `custom_message`: повідомлення, інжектовані розширенням, які _потрапляють_ у контекст моделі (можуть бути приховані від UI)
|
||||
- `custom`: стан розширення, який _не потрапляє_ у контекст моделі
|
||||
- `compaction`: збережене зведення ущільнення з `firstKeptEntryId` і `tokensBefore`
|
||||
- `branch_summary`: збережене зведення під час навігації гілкою дерева
|
||||
- `message`: повідомлення користувача/асистента/toolResult
|
||||
- `custom_message`: повідомлення, вставлені розширенням, які _входять_ у контекст моделі (можуть бути приховані від UI)
|
||||
- `custom`: стан розширення, який _не входить_ у контекст моделі
|
||||
- `compaction`: збережений підсумок компакції з `firstKeptEntryId` і `tokensBefore`
|
||||
- `branch_summary`: збережений підсумок під час навігації гілкою дерева
|
||||
|
||||
OpenClaw навмисно **не** “виправляє” транскрипти; Gateway використовує `SessionManager` для їх читання/запису.
|
||||
OpenClaw навмисно **не** «виправляє» транскрипти; Gateway використовує `SessionManager` для їх читання/запису.
|
||||
|
||||
---
|
||||
|
||||
## Вікна контексту проти відстежуваних токенів
|
||||
|
||||
Важливі два різні поняття:
|
||||
Мають значення два різні поняття:
|
||||
|
||||
1. **Вікно контексту моделі**: жорстке обмеження для кожної моделі (токени, видимі моделі)
|
||||
2. **Лічильники сховища сесій**: ковзна статистика, що записується в `sessions.json` (використовується для /status і панелей)
|
||||
1. **Вікно контексту моделі**: жорстке обмеження для моделі (токени, видимі моделі)
|
||||
2. **Лічильники сховища сесій**: ковзна статистика, яка записується в `sessions.json` (використовується для /status і панелей)
|
||||
|
||||
Якщо ви налаштовуєте обмеження:
|
||||
Якщо ви налаштовуєте ліміти:
|
||||
|
||||
- Вікно контексту береться з каталогу моделей (і може бути перевизначене через конфігурацію).
|
||||
- `contextTokens` у сховищі — це оцінка/значення звітності під час виконання; не сприймайте його як сувору гарантію.
|
||||
- `contextTokens` у сховищі — це оцінка/звітне значення під час виконання; не сприймайте його як сувору гарантію.
|
||||
|
||||
Докладніше див. у [/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 зберігає цей очікувальний блок інструмента й лишає непідсумований хвіст
|
||||
недоторканим.
|
||||
- Перервані/помилкові блоки викликів інструментів не утримують відкритим очікувальний поділ.
|
||||
|
||||
---
|
||||
|
||||
## Коли відбувається автоущільнення (середовище Pi)
|
||||
## Коли відбувається автокомпакція (середовище виконання Pi)
|
||||
|
||||
У вбудованому агенті Pi автоущільнення спрацьовує у двох випадках:
|
||||
У вбудованому агенті Pi автокомпакція спрацьовує у двох випадках:
|
||||
|
||||
1. **Відновлення після переповнення**: модель повертає помилку переповнення контексту
|
||||
(`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 +250,13 @@ exceeded` та подібні варіанти, характерні для ко
|
||||
- `contextWindow` — це вікно контексту моделі
|
||||
- `reserveTokens` — це запас токенів, зарезервований для промптів + наступного виводу моделі
|
||||
|
||||
Це семантика середовища Pi (OpenClaw споживає події, але коли ущільнювати, вирішує Pi).
|
||||
Це семантика середовища виконання Pi (OpenClaw споживає події, але саме Pi вирішує, коли виконувати компакцію).
|
||||
|
||||
---
|
||||
|
||||
## Налаштування ущільнення (`reserveTokens`, `keepRecentTokens`)
|
||||
## Налаштування компакції (`reserveTokens`, `keepRecentTokens`)
|
||||
|
||||
Налаштування ущільнення Pi зберігаються в налаштуваннях Pi:
|
||||
Налаштування компакції Pi живуть у налаштуваннях Pi:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -267,14 +268,14 @@ exceeded` та подібні варіанти, характерні для ко
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw також застосовує мінімальний захисний поріг для вбудованих запусків:
|
||||
OpenClaw також забезпечує мінімальний поріг безпеки для вбудованих запусків:
|
||||
|
||||
- Якщо `compaction.reserveTokens < reserveTokensFloor`, OpenClaw підвищує значення.
|
||||
- Якщо `compaction.reserveTokens < reserveTokensFloor`, OpenClaw збільшує його.
|
||||
- Типовий поріг — `20000` токенів.
|
||||
- Установіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути цей поріг.
|
||||
- Якщо значення вже вище, OpenClaw залишає його без змін.
|
||||
- Встановіть `agents.defaults.compaction.reserveTokensFloor: 0`, щоб вимкнути цей поріг.
|
||||
- Якщо значення вже вище, OpenClaw не змінює його.
|
||||
|
||||
Чому: залишити достатньо запасу для багатокрокових “службових” дій (наприклад, записів пам’яті), перш ніж ущільнення стане неминучим.
|
||||
Навіщо: залишити достатньо запасу для багатокрокових «господарських» дій (наприклад, записів у пам’ять), перш ніж компакція стане неминучою.
|
||||
|
||||
Реалізація: `ensurePiCompactionReserveTokens()` у `src/agents/pi-settings.ts`
|
||||
(викликається з `src/agents/pi-embedded-runner.ts`).
|
||||
@ -283,46 +284,46 @@ OpenClaw також застосовує мінімальний захисний
|
||||
|
||||
## Поверхні, видимі користувачу
|
||||
|
||||
Ви можете спостерігати ущільнення і стан сесії через:
|
||||
Ви можете спостерігати компакцію та стан сесії через:
|
||||
|
||||
- `/status` (у будь-якому чаті сесії)
|
||||
- `/status` (у будь-якій сесії чату)
|
||||
- `openclaw status` (CLI)
|
||||
- `openclaw sessions` / `sessions --json`
|
||||
- Режим verbose: `🧹 Auto-compaction complete` + кількість ущільнень
|
||||
- Режим verbose: `🧹 Auto-compaction complete` + кількість компакцій
|
||||
|
||||
---
|
||||
|
||||
## Тихі службові дії (`NO_REPLY`)
|
||||
## Тихі господарські дії (`NO_REPLY`)
|
||||
|
||||
OpenClaw підтримує “тихі” ходи для фонових завдань, де користувач не повинен бачити проміжний вивід.
|
||||
OpenClaw підтримує «тихі» ходи для фонових завдань, коли користувач не повинен бачити проміжний вивід.
|
||||
|
||||
Умова:
|
||||
Домовленість:
|
||||
|
||||
- Асистент починає свій вивід з точного тихого токена `NO_REPLY` /
|
||||
`no_reply`, щоб позначити “не доставляти відповідь користувачу”.
|
||||
- OpenClaw прибирає/приглушує це на рівні доставки.
|
||||
- Приглушення точного тихого токена нечутливе до регістру, тож `NO_REPLY` і
|
||||
`no_reply` обидва зараховуються, коли весь payload — це лише тихий токен.
|
||||
- Це лише для справді фонових ходів/ходів без доставки; це не скорочений шлях
|
||||
для звичайних практичних запитів користувача.
|
||||
- Асистент починає свій вивід із точного тихого токена `NO_REPLY` /
|
||||
`no_reply`, щоб позначити «не доставляти відповідь користувачу».
|
||||
- OpenClaw видаляє/пригнічує це на рівні доставки.
|
||||
- Пригнічення точного тихого токена не залежить від регістру, тож `NO_REPLY` і
|
||||
`no_reply` обидва враховуються, коли весь payload — це лише тихий токен.
|
||||
- Це призначено лише для справді фонових/безвідповідних ходів; це не скорочення
|
||||
для звичайних дієвих запитів користувача.
|
||||
|
||||
Починаючи з `2026.1.10`, OpenClaw також приглушує **чернетковий/набірний стримінг**, коли
|
||||
частковий чанк починається з `NO_REPLY`, щоб тихі операції не видавали частковий
|
||||
Починаючи з `2026.1.10`, OpenClaw також пригнічує **чернетковий/набірний streaming**, коли
|
||||
частковий фрагмент починається з `NO_REPLY`, щоб тихі операції не розкривали частковий
|
||||
вивід посеред ходу.
|
||||
|
||||
---
|
||||
|
||||
## "Скидання пам’яті" перед ущільненням (реалізовано)
|
||||
## «Скидання пам’яті» перед компакцією (реалізовано)
|
||||
|
||||
Мета: перед тим як відбудеться автоущільнення, виконати тихий агентний хід, який записує стійкий
|
||||
стан на диск (наприклад, `memory/YYYY-MM-DD.md` у робочому просторі агента), щоб ущільнення не могло
|
||||
Мета: перед тим як відбудеться автокомпакція, виконати тихий агентний хід, який запише стійкий
|
||||
стан на диск (наприклад, `memory/YYYY-MM-DD.md` у робочому просторі агента), щоб компакція не могла
|
||||
стерти критичний контекст.
|
||||
|
||||
OpenClaw використовує підхід **flush до порога**:
|
||||
OpenClaw використовує підхід **скидання перед порогом**:
|
||||
|
||||
1. Відстежувати використання контексту сесії.
|
||||
2. Коли воно перетинає “м’який поріг” (нижчий за поріг ущільнення Pi), виконати тиху
|
||||
директиву “запиши пам’ять зараз” для агента.
|
||||
2. Коли воно перетинає «м’який поріг» (нижче за поріг компакції Pi), виконати тиху
|
||||
інструкцію «запиши пам’ять зараз» для агента.
|
||||
3. Використовувати точний тихий токен `NO_REPLY` / `no_reply`, щоб користувач
|
||||
нічого не бачив.
|
||||
|
||||
@ -330,29 +331,29 @@ OpenClaw використовує підхід **flush до порога**:
|
||||
|
||||
- `enabled` (типово: `true`)
|
||||
- `softThresholdTokens` (типово: `4000`)
|
||||
- `prompt` (повідомлення user для ходу flush)
|
||||
- `systemPrompt` (додатковий системний промпт, який додається для ходу flush)
|
||||
- `prompt` (повідомлення користувача для ходу скидання)
|
||||
- `systemPrompt` (додатковий системний промпт, який додається для ходу скидання)
|
||||
|
||||
Примітки:
|
||||
|
||||
- Типові значення prompt/system prompt містять підказку `NO_REPLY` для приглушення
|
||||
- Типові `prompt`/`systemPrompt` містять підказку `NO_REPLY` для пригнічення
|
||||
доставки.
|
||||
- Flush виконується один раз за цикл ущільнення (відстежується в `sessions.json`).
|
||||
- Flush виконується лише для вбудованих сесій Pi.
|
||||
- Flush пропускається, коли робочий простір сесії доступний лише для читання (`workspaceAccess: "ro"` або `"none"`).
|
||||
- Див. [Memory](/uk/concepts/memory) щодо структури файлів робочого простору та шаблонів запису.
|
||||
- Скидання виконується один раз за цикл компакції (відстежується в `sessions.json`).
|
||||
- Скидання виконується лише для вбудованих сесій Pi (бекенди CLI його пропускають).
|
||||
- Скидання пропускається, коли робочий простір сесії доступний лише для читання (`workspaceAccess: "ro"` або `"none"`).
|
||||
- Схему файлів робочого простору та шаблони запису див. у [Memory](/uk/concepts/memory).
|
||||
|
||||
Pi також надає хук `session_before_compact` в API розширень, але логіка flush в OpenClaw
|
||||
сьогодні живе на боці Gateway.
|
||||
Pi також надає хук `session_before_compact` в API розширення, але логіка
|
||||
скидання в OpenClaw сьогодні живе на боці Gateway.
|
||||
|
||||
---
|
||||
|
||||
## Контрольний список усунення несправностей
|
||||
## Контрольний список для усунення несправностей
|
||||
|
||||
- Неправильний ключ сесії? Почніть із [/concepts/session](/uk/concepts/session) і перевірте `sessionKey` у `/status`.
|
||||
- Невідповідність між сховищем і транскриптом? Перевірте хост Gateway і шлях до сховища з `openclaw status`.
|
||||
- Спам ущільненням? Перевірте:
|
||||
- Невідповідність сховища й транскрипту? Перевірте хост Gateway і шлях до сховища з `openclaw status`.
|
||||
- Спам компакції? Перевірте:
|
||||
- вікно контексту моделі (замале)
|
||||
- налаштування ущільнення (`reserveTokens` завелике для вікна моделі може спричиняти раніше ущільнення)
|
||||
- роздуття tool-result: увімкніть/налаштуйте очищення сесії
|
||||
- Тихі ходи протікають? Переконайтеся, що відповідь починається з `NO_REPLY` (нечутливий до регістру точний токен) і що у вас збірка, яка містить виправлення приглушення стримінгу.
|
||||
- налаштування компакції (`reserveTokens`, завелике для вікна моделі, може спричиняти раннішу компакцію)
|
||||
- роздування через tool-result: увімкніть/налаштуйте обрізання сесії
|
||||
- Протікають тихі ходи? Переконайтеся, що відповідь починається з `NO_REPLY` (точний токен без урахування регістру) і що ви використовуєте збірку, яка містить виправлення пригнічення streaming.
|
||||
|
||||
@ -1,229 +1,233 @@
|
||||
---
|
||||
read_when:
|
||||
- Запуск harness-оточень для кодування через ACP
|
||||
- Налаштування прив’язаних до розмови сеансів ACP у каналах обміну повідомленнями
|
||||
- Прив’язування розмови в каналі повідомлень до постійного сеансу ACP
|
||||
- Усунення несправностей бекенду ACP і підключення плагінів
|
||||
- Керування командами /acp з чату
|
||||
summary: Використовуйте сеанси середовища виконання ACP для Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP та інших агентів harness
|
||||
title: Агенти ACP
|
||||
- Запуск coding harness через ACP
|
||||
- Налаштування ACP-сеансів, прив’язаних до розмови, у каналах обміну повідомленнями
|
||||
- Прив’язка розмови в каналі повідомлень до постійного ACP-сеансу
|
||||
- Усунення неполадок бекенду ACP і обв’язки плагіна
|
||||
- Керування командами /acp із чату
|
||||
summary: Використовуйте сеанси середовища виконання ACP для Codex, Claude Code, Cursor, Gemini CLI, OpenClaw ACP та інших harness-агентів
|
||||
title: ACP Agents
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T18:49:57Z"
|
||||
generated_at: "2026-04-06T12:47:45Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 302f3fe25b1ffe0576592b6e0ad9e8a5781fa5702b31d508d9ba8908f7df33bd
|
||||
source_hash: fb651ab39b05e537398623ee06cb952a5a07730fc75d3f7e0de20dd3128e72c6
|
||||
source_path: tools/acp-agents.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Агенти ACP
|
||||
# ACP-агенти
|
||||
|
||||
Сеанси [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають змогу OpenClaw запускати зовнішні harness-оточення для кодування (наприклад Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX-harness-оточення) через плагін бекенду 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-бекенду.
|
||||
|
||||
Якщо ви попросите OpenClaw звичайною мовою «запусти це в Codex» або «запусти Claude Code у гілці», OpenClaw має спрямувати цей запит до середовища виконання ACP (а не до нативного середовища виконання субагента). Кожен запуск сеансу ACP відстежується як [фонове завдання](/uk/automation/tasks).
|
||||
Якщо ви просите OpenClaw звичайною мовою «запусти це в Codex» або «запусти Claude Code у треді», OpenClaw має спрямувати цей запит до середовища виконання ACP (а не до власного середовища виконання sub-agent). Кожен запуск ACP-сеансу відстежується як [фонове завдання](/uk/automation/tasks).
|
||||
|
||||
Якщо ви хочете, щоб Codex або Claude Code підключалися як зовнішній MCP-клієнт безпосередньо
|
||||
до наявних розмов у каналах OpenClaw, використовуйте [`openclaw mcp serve`](/cli/mcp)
|
||||
замість ACP.
|
||||
до наявних розмов у каналах OpenClaw, використовуйте
|
||||
[`openclaw mcp serve`](/cli/mcp) замість ACP.
|
||||
|
||||
## Яку сторінку мені потрібно?
|
||||
## Яка сторінка мені потрібна?
|
||||
|
||||
Поруч є три поверхні, які легко сплутати:
|
||||
|
||||
| Ви хочете... | Використовуйте це | Примітки |
|
||||
| --------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| Запускати 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 |
|
||||
| You want to... | Use this | Notes |
|
||||
| ---------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
||||
| Запускати Codex, Claude Code, Gemini CLI або інший зовнішній harness _через_ OpenClaw | Ця сторінка: ACP Agents | Сеанси, прив’язані до чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, елементи керування runtime |
|
||||
| Відкрити сеанс OpenClaw Gateway _як_ ACP-сервер для редактора або клієнта | [`openclaw acp`](/cli/acp) | Режим bridge. IDE/клієнт спілкується з OpenClaw через ACP по stdio/WebSocket |
|
||||
| Повторно використовувати локальний AI CLI як лише текстову резервну модель | [CLI Backends](/gateway/cli-backends) | Це не ACP. Немає інструментів OpenClaw, немає елементів керування ACP, немає середовища виконання harness |
|
||||
|
||||
## Це працює одразу після встановлення?
|
||||
## Чи працює це одразу після встановлення?
|
||||
|
||||
Зазвичай так.
|
||||
|
||||
- Нові встановлення тепер постачаються з увімкненим за замовчуванням вбудованим плагіном середовища виконання `acpx`.
|
||||
- Вбудований плагін `acpx` віддає перевагу своєму локально закріпленому бінарному файлу `acpx`.
|
||||
- Під час запуску OpenClaw перевіряє цей бінарний файл і за потреби самостійно його відновлює.
|
||||
- Вбудований плагін `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 на цьому хості.
|
||||
|
||||
## Швидкий операторський потік
|
||||
## Швидкий операторський сценарій
|
||||
|
||||
Використовуйте це, якщо вам потрібна практична інструкція для `/acp`:
|
||||
Використовуйте це, якщо вам потрібен практичний runbook для `/acp`:
|
||||
|
||||
1. Запустіть сеанс:
|
||||
1. Створіть сеанс:
|
||||
- `/acp spawn codex --bind here`
|
||||
- `/acp spawn codex --mode persistent --thread auto`
|
||||
2. Працюйте в прив’язаній розмові або гілці (або явно вкажіть ключ цього сеансу).
|
||||
2. Працюйте у прив’язаній розмові або треді (або явно вкажіть ключ цього сеансу).
|
||||
3. Перевірте стан середовища виконання:
|
||||
- `/acp status`
|
||||
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 у гілці й тримай його зосередженим».
|
||||
- «Виконай це як одноразовий сеанс Claude Code ACP і підсумуй результат».
|
||||
- «Прив’яжи цей чат iMessage до Codex і зберігай наступні повідомлення в тому самому робочому просторі».
|
||||
- «Використай Gemini CLI для цього завдання в гілці, а потім зберігай наступні повідомлення в цій самій гілці».
|
||||
- «Прив’яжи цей Discord-канал до Codex».
|
||||
- «Запусти тут постійний сеанс Codex у треді та тримай його сфокусованим».
|
||||
- «Запусти це як одноразовий ACP-сеанс Claude Code і підсумуй результат».
|
||||
- «Прив’яжи цей чат iMessage до Codex і зберігай наступні звернення в тому самому workspace».
|
||||
- «Використай 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 проти sub-agents
|
||||
|
||||
Використовуйте ACP, коли потрібне зовнішнє середовище виконання harness. Використовуйте субагентів, коли потрібні делеговані запуски OpenClaw.
|
||||
Використовуйте ACP, коли вам потрібне зовнішнє середовище виконання harness. Використовуйте sub-agents, коли вам потрібні делеговані запуски, власні для OpenClaw.
|
||||
|
||||
| Область | Сеанс ACP | Запуск субагента |
|
||||
| ------------- | -------------------------------------- | ----------------------------------- |
|
||||
| Середовище виконання | Плагін бекенду ACP (наприклад acpx) | Нативне середовище виконання субагента OpenClaw |
|
||||
| Ключ сеансу | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
|
||||
| Основні команди | `/acp ...` | `/subagents ...` |
|
||||
| Інструмент запуску | `sessions_spawn` with `runtime:"acp"` | `sessions_spawn` (середовище виконання за замовчуванням) |
|
||||
| Area | ACP session | Sub-agent run |
|
||||
| ------------- | ------------------------------------- | ---------------------------------------- |
|
||||
| Runtime | Плагін ACP-бекенду (наприклад acpx) | Власне середовище виконання sub-agent OpenClaw |
|
||||
| Session key | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
|
||||
| Main commands | `/acp ...` | `/subagents ...` |
|
||||
| Spawn tool | `sessions_spawn` with `runtime:"acp"` | `sessions_spawn` (runtime за замовчуванням) |
|
||||
|
||||
Див. також [Субагенти](/uk/tools/subagents).
|
||||
Дивіться також [Sub-agents](/uk/tools/subagents).
|
||||
|
||||
## Як ACP запускає Claude Code
|
||||
|
||||
Для Claude Code через ACP стек такий:
|
||||
|
||||
1. Площина керування сеансом OpenClaw ACP
|
||||
1. Керувальна площина ACP-сеансів OpenClaw
|
||||
2. вбудований плагін середовища виконання `acpx`
|
||||
3. адаптер Claude ACP
|
||||
4. механізм середовища виконання/сеансу на боці Claude
|
||||
4. механізм runtime/session на боці Claude
|
||||
|
||||
Важлива відмінність:
|
||||
|
||||
- ACP Claude — це сеанс harness з елементами керування ACP, відновленням сеансу, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/гілки.
|
||||
Для операторів практичне правило таке:
|
||||
- ACP Claude — це сеанс harness з елементами керування ACP, відновленням сеансу, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/треда.
|
||||
- CLI-бекенди — це окремі локальні резервні середовища виконання лише для тексту. Дивіться [CLI Backends](/gateway/cli-backends).
|
||||
|
||||
- якщо потрібні `/acp spawn`, сеанси з прив’язкою, елементи керування середовищем виконання або постійна робота harness — використовуйте ACP
|
||||
Для операторів практичне правило таке:
|
||||
|
||||
- потрібні `/acp spawn`, сеанси з прив’язкою, елементи керування runtime або постійна робота harness: використовуйте ACP
|
||||
- потрібен простий локальний резервний текстовий шлях через сирий CLI: використовуйте CLI-бекенди
|
||||
|
||||
## Прив’язані сеанси
|
||||
|
||||
### Прив’язки до поточної розмови
|
||||
|
||||
Використовуйте `/acp spawn <harness> --bind here`, коли хочете, щоб поточна розмова стала довговічним робочим простором ACP без створення дочірньої гілки.
|
||||
Використовуйте `/acp spawn <harness> --bind here`, коли хочете, щоб поточна розмова стала довготривалим ACP-workspace без створення дочірнього треда.
|
||||
|
||||
Поведінка:
|
||||
|
||||
- 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.
|
||||
- Середовище виконання ACP все одно може мати власну робочу директорію (`cwd`) або робочий простір на диску, яким керує бекенд. Цей робочий простір середовища виконання є окремим від поверхні чату й не означає створення нової гілки повідомлень.
|
||||
- Якщо ви запускаєте інший ACP-агент і не передаєте `--cwd`, OpenClaw за замовчуванням успадковує робочий простір **цільового агента**, а не запитувача.
|
||||
- Якщо цей успадкований шлях до робочого простору відсутній (`ENOENT`/`ENOTDIR`), OpenClaw повертається до стандартного cwd бекенду замість того, щоб мовчки повторно використати неправильне дерево.
|
||||
- Якщо успадкований робочий простір існує, але доступ до нього неможливий (наприклад `EACCES`), запуск повертає реальну помилку доступу замість відкидання `cwd`.
|
||||
- `--bind here` все ще може створити новий ACP-сеанс, якщо ви запускаєте нову роботу.
|
||||
- `--bind here` сам по собі не створює дочірній Discord-тред або тему Telegram.
|
||||
- Середовище виконання ACP все ще може мати власний робочий каталог (`cwd`) або workspace на диску, керований бекендом. Цей workspace runtime відокремлений від поверхні чату і не означає створення нового треда повідомлень.
|
||||
- Якщо ви запускаєте інший ACP-агент і не передаєте `--cwd`, OpenClaw типово успадковує workspace **цільового агента**, а не агента-запитувача.
|
||||
- Якщо цей успадкований шлях до workspace відсутній (`ENOENT`/`ENOTDIR`), OpenClaw повертається до типового `cwd` бекенду замість того, щоб мовчки повторно використовувати неправильне дерево.
|
||||
- Якщо успадкований workspace існує, але до нього немає доступу (наприклад `EACCES`), spawn повертає реальну помилку доступу замість пропуску `cwd`.
|
||||
|
||||
Ментальна модель:
|
||||
|
||||
- поверхня чату: де люди продовжують спілкуватися (`канал Discord`, `тема Telegram`, `чат iMessage`)
|
||||
- сеанс ACP: довговічний стан середовища виконання Codex/Claude/Gemini, до якого OpenClaw спрямовує запити
|
||||
- дочірня гілка/тема: необов’язкова додаткова поверхня повідомлень, що створюється лише через `--thread ...`
|
||||
- робочий простір середовища виконання: розташування у файловій системі, де працює harness (`cwd`, checkout репозиторію, робочий простір бекенду)
|
||||
- поверхня чату: де люди продовжують спілкуватися (`Discord channel`, `Telegram topic`, `iMessage chat`)
|
||||
- ACP-сеанс: довготривалий стан runtime Codex/Claude/Gemini, до якого маршрутизує OpenClaw
|
||||
- дочірній тред/тема: необов’язкова додаткова поверхня повідомлень, що створюється лише через `--thread ...`
|
||||
- workspace runtime: розташування у файловій системі, де працює harness (`cwd`, checkout репозиторію, workspace бекенду)
|
||||
|
||||
Приклади:
|
||||
|
||||
- `/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, а не каналу. Ви можете повторно використовувати або замінювати стан середовища виконання, не змінюючи поточну поверхню чату.
|
||||
- `--bind here` і `--thread ...` взаємовиключні у `/acp spawn`.
|
||||
- У Discord `--bind here` прив’язує поточний канал або тред на місці. `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірній тред для `--thread auto|here`.
|
||||
- Якщо активний канал не надає ACP-прив’язок до поточної розмови, OpenClaw повертає чітке повідомлення про непідтримуваність.
|
||||
- `resume` і питання «новий сеанс» — це питання ACP-сеансу, а не каналу. Ви можете повторно використовувати або замінювати стан runtime без зміни поточної поверхні чату.
|
||||
|
||||
### Сеанси з прив’язкою до гілки
|
||||
### Сеанси, прив’язані до тредів
|
||||
|
||||
Коли для адаптера каналу ввімкнено прив’язки до гілок, сеанси ACP можна прив’язувати до гілок:
|
||||
Коли для адаптера каналу увімкнено прив’язки до тредів, ACP-сеанси можна прив’язувати до тредів:
|
||||
|
||||
- OpenClaw прив’язує гілку до цільового сеансу ACP.
|
||||
- Наступні повідомлення в цій гілці спрямовуються до прив’язаного сеансу ACP.
|
||||
- Вивід ACP доставляється назад у ту саму гілку.
|
||||
- Розфокусування, закриття, архівування, тайм-аут бездіяльності або завершення max-age прибирає прив’язку.
|
||||
- OpenClaw прив’язує тред до цільового ACP-сеансу.
|
||||
- Наступні повідомлення в цьому треді маршрутизуються до прив’язаного ACP-сеансу.
|
||||
- Вивід ACP доставляється назад у той самий тред.
|
||||
- Розфокусування/закриття/архівація/тайм-аут бездіяльності або завершення максимального віку видаляє прив’язку.
|
||||
|
||||
Підтримка прив’язки до гілки залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки до гілки, OpenClaw повертає зрозуміле повідомлення про непідтримку/недоступність.
|
||||
Підтримка прив’язки до тредів залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки до тредів, OpenClaw повертає чітке повідомлення про непідтримуваність/недоступність.
|
||||
|
||||
Необхідні прапорці функцій для ACP із прив’язкою до гілки:
|
||||
Потрібні feature flags для ACP, прив’язаного до тредів:
|
||||
|
||||
- `acp.enabled=true`
|
||||
- `acp.dispatch.enabled` увімкнено за замовчуванням (встановіть `false`, щоб призупинити диспетчеризацію ACP)
|
||||
- Увімкнено прапорець запуску ACP у гілках адаптера каналу (залежить від адаптера)
|
||||
- `acp.dispatch.enabled` увімкнено за замовчуванням (задайте `false`, щоб призупинити ACP-dispatch)
|
||||
- Увімкнено прапорець spawn ACP-сеансів для тредів адаптера каналу (залежить від адаптера)
|
||||
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
|
||||
|
||||
### Канали з підтримкою гілок
|
||||
### Канали з підтримкою тредів
|
||||
|
||||
- Будь-який адаптер каналу, який надає можливість прив’язки сеансу/гілки.
|
||||
- Будь-який адаптер каналу, який надає можливість прив’язки сеансу/треда.
|
||||
- Поточна вбудована підтримка:
|
||||
- гілки/канали Discord
|
||||
- теми Telegram (форумні теми в групах/супергрупах і DM-теми)
|
||||
- Канали-плагіни можуть додавати підтримку через той самий інтерфейс прив’язки.
|
||||
- Discord threads/channels
|
||||
- Telegram topics (теми форуму в групах/supergroups і DM topics)
|
||||
- Канали плагінів можуть додавати підтримку через той самий інтерфейс прив’язки.
|
||||
|
||||
## Налаштування для конкретних каналів
|
||||
|
||||
Для неепізодичних робочих процесів налаштуйте постійні ACP-прив’язки в записах верхнього рівня `bindings[]`.
|
||||
Для неепізодичних workflow налаштовуйте постійні ACP-прив’язки у верхньорівневих записах `bindings[]`.
|
||||
|
||||
### Модель прив’язки
|
||||
|
||||
- `bindings[].type="acp"` позначає постійну ACP-прив’язку розмови.
|
||||
- `bindings[].type="acp"` позначає постійну 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:*`.
|
||||
- Discord channel or thread: `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
|
||||
- Telegram forum topic: `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
|
||||
- BlueBubbles DM/group chat: `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Для стабільних групових прив’язок надавайте перевагу `chat_id:*` або `chat_identifier:*`.
|
||||
- iMessage DM/group chat: `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
Для стабільних групових прив’язок надавайте перевагу `chat_id:*`.
|
||||
- `bindings[].agentId` — це id агента OpenClaw-власника.
|
||||
- Необов’язкові перевизначення ACP містяться в `bindings[].acp`:
|
||||
- Необов’язкові перевизначення 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`)
|
||||
@ -231,11 +235,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`)
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -319,18 +323,18 @@ x-i18n:
|
||||
|
||||
Поведінка:
|
||||
|
||||
- OpenClaw гарантує, що налаштований сеанс ACP існує до початку використання.
|
||||
- Повідомлення в цьому каналі або темі спрямовуються до налаштованого сеансу ACP.
|
||||
- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ сеансу ACP на місці.
|
||||
- Тимчасові прив’язки середовища виконання (наприклад створені потоками фокусування на гілці) усе ще застосовуються, де вони є.
|
||||
- Для міжагентних запусків ACP без явного `cwd` OpenClaw успадковує робочий простір цільового агента з конфігурації агента.
|
||||
- Відсутні успадковані шляхи до робочого простору призводять до повернення до стандартного cwd бекенду; невідсутні помилки доступу повертаються як помилки запуску.
|
||||
- OpenClaw гарантує, що налаштований ACP-сеанс існує до використання.
|
||||
- Повідомлення в цьому каналі або темі маршрутизуються до налаштованого ACP-сеансу.
|
||||
- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ ACP-сеансу на місці.
|
||||
- Тимчасові прив’язки runtime (наприклад створені потоками фокусування на треді) усе ще застосовуються там, де вони присутні.
|
||||
- Для міжагентних ACP-запусків без явного `cwd` OpenClaw успадковує workspace цільового агента з конфігурації агента.
|
||||
- Відсутні успадковані шляхи до workspace повертаються до типового `cwd` бекенду; помилки доступу для наявних шляхів повертаються як помилки spawn.
|
||||
|
||||
## Запуск сеансів ACP (інтерфейси)
|
||||
## Запуск ACP-сеансів (інтерфейси)
|
||||
|
||||
### Із `sessions_spawn`
|
||||
|
||||
Використовуйте `runtime: "acp"`, щоб запустити сеанс ACP із ходу агента або виклику інструмента.
|
||||
Використовуйте `runtime: "acp"`, щоб запустити ACP-сеанс із ходу агента або виклику інструмента.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -344,29 +348,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` (обов’язково): початковий prompt, надісланий ACP-сеансу.
|
||||
- `runtime` (обов’язково для ACP): має бути `"acp"`.
|
||||
- `agentId` (необов’язково): id цільового harness ACP. Якщо не вказано, використовується `acp.defaultAgent`, якщо налаштовано.
|
||||
- `thread` (необов’язково, за замовчуванням `false`): запитати потік прив’язки до гілки там, де це підтримується.
|
||||
- `mode` (необов’язково): `run` (одноразовий) або `session` (постійний).
|
||||
- за замовчуванням використовується `run`
|
||||
- якщо `thread: true` і mode не вказано, OpenClaw може за замовчуванням використовувати постійну поведінку залежно від шляху середовища виконання
|
||||
- `agentId` (необов’язково): id цільового ACP-harness. Якщо задано, використовується `acp.defaultAgent`.
|
||||
- `thread` (необов’язково, типово `false`): запитати потік прив’язки до треда, де це підтримується.
|
||||
- `mode` (необов’язково): `run` (одноразово) або `session` (постійно).
|
||||
- типове значення — `run`
|
||||
- якщо `thread: true` і mode пропущено, OpenClaw може типово вибрати постійну поведінку залежно від шляху runtime
|
||||
- `mode: "session"` вимагає `thread: true`
|
||||
- `cwd` (необов’язково): запитувана робоча директорія середовища виконання (перевіряється політикою бекенду/середовища виконання). Якщо не вказано, під час запуску ACP успадковується робочий простір цільового агента, якщо він налаштований; відсутні успадковані шляхи повертаються до стандартних параметрів бекенду, а реальні помилки доступу повертаються.
|
||||
- `label` (необов’язково): операторська мітка, що використовується в тексті сеансу/банера.
|
||||
- `resumeSessionId` (необов’язково): відновити наявний сеанс ACP замість створення нового. Агент відтворює свою історію розмов через `session/load`. Вимагає `runtime: "acp"`.
|
||||
- `streamTo` (необов’язково): `"parent"` передає підсумки прогресу початкового запуску ACP назад до сеансу-запитувача як системні події.
|
||||
- За наявності прийнятні відповіді включають `streamLogPath`, який вказує на JSONL-журнал у межах сеансу (`<sessionId>.acp-stream.jsonl`), який можна відстежувати для повної історії ретрансляції.
|
||||
- `cwd` (необов’язково): запитаний робочий каталог runtime (валідується політикою бекенду/runtime). Якщо пропущено, ACP spawn успадковує workspace цільового агента, коли його налаштовано; відсутні успадковані шляхи повертаються до типових значень бекенду, а реальні помилки доступу повертаються.
|
||||
- `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
|
||||
{
|
||||
@ -377,32 +381,32 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Типові сценарії використання:
|
||||
Поширені сценарії використання:
|
||||
|
||||
- Передати сеанс Codex з ноутбука на телефон — попросіть агента продовжити з того місця, де ви зупинилися
|
||||
- Продовжити сеанс кодування, який ви почали інтерактивно в CLI, а тепер хочете виконувати безголово через агента
|
||||
- Відновити роботу, яку перервав перезапуск gateway або тайм-аут бездіяльності
|
||||
- Передати сеанс Codex із ноутбука на телефон — попросіть агента продовжити там, де ви зупинилися
|
||||
- Продовжити coding-сеанс, який ви почали інтерактивно в CLI, а тепер запускаєте безголово через агента
|
||||
- Підхопити роботу, яку перервав перезапуск gateway або тайм-аут бездіяльності
|
||||
|
||||
Примітки:
|
||||
|
||||
- `resumeSessionId` вимагає `runtime: "acp"` — повертає помилку, якщо використовується із середовищем виконання субагента.
|
||||
- `resumeSessionId` відновлює історію вхідної ACP-розмови; `thread` і `mode` як і раніше застосовуються звичайним чином до нового сеансу OpenClaw, який ви створюєте, тож `mode: "session"` усе ще вимагає `thread: true`.
|
||||
- Цільовий агент має підтримувати `session/load` (Codex і Claude Code це підтримують).
|
||||
- Якщо id сеансу не знайдено, запуск завершиться зрозумілою помилкою — без тихого повернення до нового сеансу.
|
||||
- `resumeSessionId` вимагає `runtime: "acp"` — повертає помилку, якщо використовується із середовищем виконання sub-agent.
|
||||
- `resumeSessionId` відновлює історію розмови upstream ACP; `thread` і `mode` усе ще застосовуються звичайним чином до нового сеансу OpenClaw, який ви створюєте, тому `mode: "session"` усе ще вимагає `thread: true`.
|
||||
- Цільовий агент має підтримувати `session/load` (Codex і Claude Code підтримують).
|
||||
- Якщо id сеансу не знайдено, spawn завершується чіткою помилкою — без тихого переходу до нового сеансу.
|
||||
|
||||
### Операторський smoke test
|
||||
|
||||
Використовуйте це після розгортання gateway, коли потрібна швидка жива перевірка того, що запуск ACP
|
||||
справді працює наскрізь, а не лише проходить модульні тести.
|
||||
Використовуйте це після розгортання gateway, коли хочете швидко перевірити вживу, що ACP spawn
|
||||
справді працює наскрізно, а не просто проходить unit-тести.
|
||||
|
||||
Рекомендований бар’єр перевірки:
|
||||
Рекомендований gate:
|
||||
|
||||
1. Перевірте версію/коміт розгорнутого gateway на цільовому хості.
|
||||
2. Підтвердьте, що розгорнуте джерело містить прийняття лінійності ACP у
|
||||
2. Підтвердьте, що розгорнуте джерело містить прийняття lineage ACP у
|
||||
`src/gateway/sessions-patch.ts` (`subagent:* or acp:* sessions`).
|
||||
3. Відкрийте тимчасовий сеанс мосту ACPX до живого агента (наприклад
|
||||
3. Відкрийте тимчасовий bridge-сеанс ACPX до живого агента (наприклад
|
||||
`razor(main)` на `jpclawhq`).
|
||||
4. Попросіть цього агента викликати `sessions_spawn` із:
|
||||
4. Попросіть цього агента викликати `sessions_spawn` з:
|
||||
- `runtime: "acp"`
|
||||
- `agentId: "codex"`
|
||||
- `mode: "run"`
|
||||
@ -411,9 +415,9 @@ x-i18n:
|
||||
- `accepted=yes`
|
||||
- реальний `childSessionKey`
|
||||
- відсутність помилки валідатора
|
||||
6. Приберіть тимчасовий сеанс мосту ACPX.
|
||||
6. Приберіть тимчасовий bridge-сеанс ACPX.
|
||||
|
||||
Приклад промпту для живого агента:
|
||||
Приклад prompt для живого агента:
|
||||
|
||||
```text
|
||||
Use the sessions_spawn tool now with runtime: "acp", agentId: "codex", and mode: "run".
|
||||
@ -423,25 +427,25 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
|
||||
Примітки:
|
||||
|
||||
- Для цього smoke test використовуйте `mode: "run"`, якщо тільки ви навмисно не тестуєте
|
||||
постійні сеанси ACP із прив’язкою до гілки.
|
||||
- Не вимагайте `streamTo: "parent"` для базового бар’єра. Цей шлях залежить від
|
||||
можливостей запитувача/сеансу й є окремою інтеграційною перевіркою.
|
||||
- Розглядайте тестування `mode: "session"` із прив’язкою до гілки як другу, ширшу інтеграційну
|
||||
перевірку з реальної гілки Discord або теми Telegram.
|
||||
- Залишайте цей smoke test у режимі `mode: "run"`, якщо лише ви не тестуєте навмисно
|
||||
постійні ACP-сеанси, прив’язані до тредів.
|
||||
- Не вимагайте `streamTo: "parent"` для базового gate. Цей шлях залежить від
|
||||
можливостей запитувача/сеансу і є окремою інтеграційною перевіркою.
|
||||
- Розглядайте тестування `mode: "session"`, прив’язаного до треда, як другий, багатший інтеграційний
|
||||
прохід із реального Discord-треда або Telegram topic.
|
||||
|
||||
## Сумісність із sandbox
|
||||
|
||||
Наразі сеанси ACP працюють у середовищі виконання хоста, а не всередині sandbox OpenClaw.
|
||||
ACP-сеанси наразі працюють у runtime хоста, а не всередині sandbox OpenClaw.
|
||||
|
||||
Поточні обмеження:
|
||||
|
||||
- Якщо сеанс-запитувач ізольований sandbox, запуски ACP блокуються як для `sessions_spawn({ runtime: "acp" })`, так і для `/acp spawn`.
|
||||
- Якщо сеанс-запитувач sandboxed, 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` із `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`
|
||||
|
||||
@ -454,7 +458,7 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
/acp spawn codex --thread here
|
||||
```
|
||||
|
||||
Основні прапорці:
|
||||
Ключові прапорці:
|
||||
|
||||
- `--mode persistent|oneshot`
|
||||
- `--bind here|off`
|
||||
@ -462,7 +466,7 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
- `--cwd <absolute-path>`
|
||||
- `--label <name>`
|
||||
|
||||
Див. [Слеш-команди](/uk/tools/slash-commands).
|
||||
Дивіться [Slash Commands](/uk/tools/slash-commands).
|
||||
|
||||
## Визначення цілі сеансу
|
||||
|
||||
@ -471,49 +475,49 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
Порядок визначення:
|
||||
|
||||
1. Явний аргумент цілі (або `--session` для `/acp steer`)
|
||||
- спочатку пробує ключ
|
||||
- спочатку пробує key
|
||||
- потім session id у форматі UUID
|
||||
- потім мітку
|
||||
2. Прив’язка поточної гілки (якщо ця розмова/гілка прив’язана до сеансу ACP)
|
||||
3. Резервний варіант: поточний сеанс запитувача
|
||||
- потім label
|
||||
2. Поточна прив’язка треда (якщо ця розмова/тред прив’язані до ACP-сеансу)
|
||||
3. Резервний варіант — поточний сеанс запитувача
|
||||
|
||||
Прив’язки до поточної розмови та прив’язки до гілки беруть участь у кроці 2.
|
||||
І прив’язки до поточної розмови, і прив’язки до треда беруть участь у кроці 2.
|
||||
|
||||
Якщо жодної цілі не вдається визначити, OpenClaw повертає зрозумілу помилку (`Unable to resolve session target: ...`).
|
||||
Якщо ціль не вдається визначити, OpenClaw повертає чітку помилку (`Unable to resolve session target: ...`).
|
||||
|
||||
## Режими прив’язки під час запуску
|
||||
## Режими прив’язки spawn
|
||||
|
||||
`/acp spawn` підтримує `--bind here|off`.
|
||||
|
||||
| Режим | Поведінка |
|
||||
| ------ | ---------------------------------------------------------------------- |
|
||||
| `here` | Прив’язати поточну активну розмову на місці; помилка, якщо її немає. |
|
||||
| `off` | Не створювати прив’язку до поточної розмови. |
|
||||
| Mode | Behavior |
|
||||
| ------ | ------------------------------------------------------------------- |
|
||||
| `here` | Прив’язати поточну активну розмову на місці; завершити помилкою, якщо активної немає. |
|
||||
| `off` | Не створювати прив’язку до поточної розмови. |
|
||||
|
||||
Примітки:
|
||||
|
||||
- `--bind here` — найпростіший операторський шлях для «зробити цей канал або чат підкріпленим Codex».
|
||||
- `--bind here` не створює дочірню гілку.
|
||||
- `--bind here` доступний лише в каналах, які підтримують прив’язку до поточної розмови.
|
||||
- `--bind here` — найпростіший операторський шлях для сценарію «зроби цей канал або чат з підтримкою Codex».
|
||||
- `--bind here` не створює дочірній тред.
|
||||
- `--bind here` доступний лише в каналах, які надають підтримку прив’язки до поточної розмови.
|
||||
- `--bind` і `--thread` не можна поєднувати в одному виклику `/acp spawn`.
|
||||
|
||||
## Режими гілок під час запуску
|
||||
## Режими тредів spawn
|
||||
|
||||
`/acp spawn` підтримує `--thread auto|here|off`.
|
||||
|
||||
| Режим | Поведінка |
|
||||
| ------ | ---------------------------------------------------------------------------------------------------- |
|
||||
| `auto` | В активній гілці: прив’язати цю гілку. Поза гілкою: створити/прив’язати дочірню гілку, якщо це підтримується. |
|
||||
| `here` | Вимагає поточної активної гілки; помилка, якщо ви не в гілці. |
|
||||
| `off` | Без прив’язки. Сеанс запускається без прив’язки. |
|
||||
| Mode | Behavior |
|
||||
| ------ | --------------------------------------------------------------------------------------------------------- |
|
||||
| `auto` | У активному треді: прив’язати цей тред. Поза тредом: створити/прив’язати дочірній тред, якщо це підтримується. |
|
||||
| `here` | Вимагати поточний активний тред; завершити помилкою, якщо ви не в треді. |
|
||||
| `off` | Без прив’язки. Сеанс запускається без прив’язки. |
|
||||
|
||||
Примітки:
|
||||
|
||||
- На поверхнях без підтримки прив’язки до гілки поведінка за замовчуванням фактично дорівнює `off`.
|
||||
- Запуск із прив’язкою до гілки вимагає підтримки політики каналу:
|
||||
- На поверхнях без прив’язки до тредів типова поведінка фактично дорівнює `off`.
|
||||
- Spawn із прив’язкою до треда потребує підтримки політики каналу:
|
||||
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
|
||||
- Використовуйте `--bind here`, якщо хочете закріпити поточну розмову без створення дочірньої гілки.
|
||||
- Використовуйте `--bind here`, якщо хочете закріпити поточну розмову без створення дочірнього треда.
|
||||
|
||||
## Елементи керування ACP
|
||||
|
||||
@ -535,49 +539,49 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
- `/acp doctor`
|
||||
- `/acp install`
|
||||
|
||||
`/acp status` показує ефективні параметри середовища виконання і, за наявності, ідентифікатори сеансів як на рівні середовища виконання, так і на рівні бекенду.
|
||||
`/acp status` показує ефективні параметри runtime і, коли доступно, ідентифікатори сеансу як на рівні runtime, так і на рівні бекенду.
|
||||
|
||||
Деякі елементи керування залежать від можливостей бекенду. Якщо бекенд не підтримує певний елемент керування, OpenClaw повертає зрозумілу помилку про непідтримуваний елемент керування.
|
||||
Деякі елементи керування залежать від можливостей бекенду. Якщо бекенд не підтримує певний елемент керування, OpenClaw повертає чітку помилку unsupported-control.
|
||||
|
||||
## Книга рецептів для команд 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` | Показує бекенд, режим, стан, параметри середовища виконання, можливості. | `/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` |
|
||||
| Command | What it does | Example |
|
||||
| -------------------- | ---------------------------------------------------- | ------------------------------------------------------------- |
|
||||
| `/acp spawn` | Створити ACP-сеанс; необов’язкова поточна прив’язка або прив’язка до треда. | `/acp spawn codex --bind here --cwd /repo` |
|
||||
| `/acp cancel` | Скасувати хід у процесі для цільового сеансу. | `/acp cancel agent:codex:acp:<uuid>` |
|
||||
| `/acp steer` | Надіслати інструкцію 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` | Задати тайм-аут 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 sessions` читає сховище для поточного прив’язаного сеансу або сеансу запитувача. Команди, які приймають токени `session-key`, `session-id` або `session-label`, визначають цілі через виявлення сеансів gateway, включно з користувацькими коренями `session.store` для окремих агентів.
|
||||
|
||||
## Відображення параметрів середовища виконання
|
||||
## Відображення параметрів runtime
|
||||
|
||||
`/acp` має зручні команди та загальний сеттер.
|
||||
`/acp` має зручні команди і загальний setter.
|
||||
|
||||
Еквівалентні операції:
|
||||
|
||||
- `/acp model <id>` відповідає ключу конфігурації середовища виконання `model`.
|
||||
- `/acp permissions <profile>` відповідає ключу конфігурації середовища виконання `approval_policy`.
|
||||
- `/acp timeout <seconds>` відповідає ключу конфігурації середовища виконання `timeout`.
|
||||
- `/acp cwd <path>` безпосередньо оновлює перевизначення cwd середовища виконання.
|
||||
- `/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` очищає всі перевизначення середовища виконання для цільового сеансу.
|
||||
- Особливий випадок: `key=cwd` використовує шлях перевизначення `cwd`.
|
||||
- `/acp reset-options` очищає всі перевизначення runtime для цільового сеансу.
|
||||
|
||||
## Підтримка harness acpx (поточна)
|
||||
## Підтримка harness в acpx (поточна)
|
||||
|
||||
Поточні вбудовані псевдоніми harness acpx:
|
||||
Поточні вбудовані псевдоніми harness в acpx:
|
||||
|
||||
- `claude`
|
||||
- `codex`
|
||||
@ -594,20 +598,20 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
- `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>`, але цей сирий обхідний шлях є функцією CLI acpx (а не звичайним шляхом `agentId` в OpenClaw).
|
||||
Пряме використання CLI acpx також може націлюватися на довільні адаптери через `--agent <command>`, але цей сирий escape hatch є можливістю CLI acpx (а не звичайного шляху OpenClaw `agentId`).
|
||||
|
||||
## Необхідна конфігурація
|
||||
## Потрібна конфігурація
|
||||
|
||||
Базова конфігурація ACP:
|
||||
Базова конфігурація ACP core:
|
||||
|
||||
```json5
|
||||
{
|
||||
acp: {
|
||||
enabled: true,
|
||||
// Необов’язково. За замовчуванням true; встановіть false, щоб призупинити диспетчеризацію ACP, зберігши елементи керування /acp.
|
||||
// Необов’язково. Типове значення — true; задайте false, щоб призупинити ACP-dispatch, зберігши елементи керування /acp.
|
||||
dispatch: { enabled: true },
|
||||
backend: "acpx",
|
||||
defaultAgent: "codex",
|
||||
@ -639,7 +643,7 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
}
|
||||
```
|
||||
|
||||
Конфігурація прив’язки до гілок залежить від адаптера каналу. Приклад для Discord:
|
||||
Конфігурація прив’язки до тредів залежить від адаптера каналу. Приклад для Discord:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -661,18 +665,18 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
}
|
||||
```
|
||||
|
||||
Якщо запуск ACP із прив’язкою до гілки не працює, спочатку перевірте прапорець функції адаптера:
|
||||
Якщо запуск ACP із прив’язкою до треда не працює, спочатку перевірте feature flag адаптера:
|
||||
|
||||
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
|
||||
Прив’язки до поточної розмови не потребують створення дочірньої гілки. Вони потребують активного контексту розмови й адаптера каналу, який надає ACP-прив’язки розмов.
|
||||
Прив’язки до поточної розмови не потребують створення дочірнього треда. Вони потребують активного контексту розмови та адаптера каналу, який надає ACP-прив’язки до розмов.
|
||||
|
||||
Див. [Довідник із конфігурації](/uk/gateway/configuration-reference).
|
||||
Дивіться [Configuration Reference](/uk/gateway/configuration-reference).
|
||||
|
||||
## Налаштування плагіна для бекенду acpx
|
||||
|
||||
Нові встановлення постачаються з увімкненим за замовчуванням вбудованим плагіном
|
||||
середовища виконання `acpx`, тому ACP зазвичай працює без ручного кроку встановлення плагіна.
|
||||
середовища виконання `acpx`, тож ACP зазвичай працює без ручного встановлення плагіна.
|
||||
|
||||
Почніть із:
|
||||
|
||||
@ -681,34 +685,34 @@ Then report only: accepted=<yes/no>; childSessionKey=<value or none>; error=<exa
|
||||
```
|
||||
|
||||
Якщо ви вимкнули `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. Очікувана версія за замовчуванням відповідає закріпленню розширення.
|
||||
3. Під час запуску реєстрація бекенду ACP одразу позначається як not-ready.
|
||||
4. Фонове завдання ensure перевіряє `acpx --version`.
|
||||
5. Якщо локальний бінарний файл плагіна відсутній або не збігається за версією, виконується:
|
||||
1. Типова команда — локальний для плагіна `node_modules/.bin/acpx` у пакеті плагіна ACPX.
|
||||
2. Очікувана версія типово дорівнює pin розширення.
|
||||
3. Під час запуску ACP-бекенд негайно реєструється як not-ready.
|
||||
4. Фонове ensure-завдання перевіряє `acpx --version`.
|
||||
5. Якщо локальний для плагіна бінарник відсутній або не збігається, виконується:
|
||||
`npm install --omit=dev --no-save acpx@<pinned>` і повторна перевірка.
|
||||
|
||||
Ви можете перевизначити команду/версію в конфігурації плагіна:
|
||||
@ -731,28 +735,28 @@ openclaw plugins install ./path/to/local/acpx-plugin
|
||||
|
||||
Примітки:
|
||||
|
||||
- `command` приймає абсолютний шлях, відносний шлях або ім’я команди (`acpx`).
|
||||
- Відносні шляхи визначаються від директорії робочого простору OpenClaw.
|
||||
- `expectedVersion: "any"` вимикає сувору перевірку відповідності версії.
|
||||
- Коли `command` вказує на користувацький бінарний файл/шлях, автоматичне локальне встановлення плагіна вимикається.
|
||||
- Запуск OpenClaw залишається неблокувальним, поки триває фонова перевірка стану бекенду.
|
||||
- `command` приймає абсолютний шлях, відносний шлях або назву команди (`acpx`).
|
||||
- Відносні шляхи визначаються від каталогу workspace OpenClaw.
|
||||
- `expectedVersion: "any"` вимикає сувору перевірку збігу версій.
|
||||
- Коли `command` вказує на користувацький бінарник/шлях, автоматичне встановлення локального для плагіна пакета вимикається.
|
||||
- Запуск OpenClaw залишається неблокувальним, поки виконується перевірка стану бекенду.
|
||||
|
||||
Див. [Плагіни](/uk/tools/plugin).
|
||||
Дивіться [Plugins](/uk/tools/plugin).
|
||||
|
||||
### Автоматичне встановлення залежностей
|
||||
|
||||
Коли ви встановлюєте OpenClaw глобально через `npm install -g openclaw`, залежності
|
||||
середовища виконання acpx (платформозалежні бінарні файли) встановлюються автоматично
|
||||
через хук postinstall. Якщо автоматичне встановлення завершується помилкою, gateway все одно запускається
|
||||
Коли ви встановлюєте OpenClaw глобально через `npm install -g openclaw`, runtime-залежності acpx
|
||||
(бінарники для конкретної платформи) встановлюються автоматично
|
||||
через postinstall-hook. Якщо автоматичне встановлення завершується невдачею, gateway все одно запускається
|
||||
нормально і повідомляє про відсутню залежність через `openclaw acp doctor`.
|
||||
|
||||
### MCP-міст інструментів плагіна
|
||||
### Міст MCP для інструментів плагіна
|
||||
|
||||
За замовчуванням сеанси ACPX **не** відкривають зареєстровані плагінами OpenClaw інструменти
|
||||
для ACP-harness-оточення.
|
||||
Типово сеанси ACPX **не** відкривають інструменти, зареєстровані плагінами OpenClaw, для
|
||||
ACP-harness.
|
||||
|
||||
Якщо ви хочете, щоб ACP-агенти, такі як Codex або Claude Code, могли викликати встановлені
|
||||
інструменти плагінів OpenClaw, такі як збереження/отримання пам’яті, увімкніть спеціальний міст:
|
||||
інструменти плагінів OpenClaw, наприклад memory recall/store, увімкніть спеціальний міст:
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
|
||||
@ -760,79 +764,78 @@ openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
|
||||
|
||||
Що це робить:
|
||||
|
||||
- Вбудовує в bootstrap сеансу ACPX вбудований MCP-сервер з назвою `openclaw-plugin-tools`.
|
||||
- Відкриває інструменти плагінів, уже зареєстровані встановленими та ввімкненими
|
||||
плагінами OpenClaw.
|
||||
- Робить цю функцію явною і вимкненою за замовчуванням.
|
||||
- Впроваджує вбудований MCP-сервер з назвою `openclaw-plugin-tools` у bootstrap
|
||||
сеансу ACPX.
|
||||
- Відкриває інструменти плагінів, уже зареєстровані встановленими та увімкненими плагінами OpenClaw.
|
||||
- Залишає цю можливість явною і вимкненою за замовчуванням.
|
||||
|
||||
Примітки щодо безпеки й довіри:
|
||||
Примітки щодо безпеки та довіри:
|
||||
|
||||
- Це розширює поверхню інструментів ACP-harness-оточення.
|
||||
- Це розширює поверхню інструментів ACP-harness.
|
||||
- ACP-агенти отримують доступ лише до інструментів плагінів, які вже активні в gateway.
|
||||
- Розглядайте це як ту саму межу довіри, що й дозвіл цим плагінам виконуватися
|
||||
у самому OpenClaw.
|
||||
- Перевіряйте встановлені плагіни перед увімкненням цієї функції.
|
||||
- Сприймайте це як ту саму межу довіри, що й дозвіл цим плагінам виконуватися всередині самого OpenClaw.
|
||||
- Перегляньте встановлені плагіни перед увімкненням.
|
||||
|
||||
Користувацькі `mcpServers` і надалі працюють як раніше. Вбудований міст інструментів плагінів є
|
||||
додатковою зручною функцією за явним увімкненням, а не заміною загальної конфігурації MCP-сервера.
|
||||
Користувацькі `mcpServers` і надалі працюють як раніше. Вбудований міст plugin-tools —
|
||||
це додаткова зручність за явною згодою, а не заміна загальної конфігурації MCP-сервера.
|
||||
|
||||
## Конфігурація дозволів
|
||||
## Налаштування дозволів
|
||||
|
||||
Сеанси ACP працюють неінтерактивно — TTY для схвалення або відхилення запитів дозволів на запис у файли й виконання shell-команд немає. Плагін acpx надає два ключі конфігурації, які керують обробкою дозволів:
|
||||
ACP-сеанси працюють неінтерактивно — TTY для схвалення або відхилення запитів на дозвіл запису файлів і виконання shell-команд немає. Плагін acpx надає два ключі конфігурації, які визначають, як обробляються дозволи:
|
||||
|
||||
Ці дозволи harness ACPX відокремлені від схвалень exec в OpenClaw і відокремлені від прапорців обходу постачальника в бекендах CLI, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний перемикач на рівні harness для сеансів ACP.
|
||||
Ці дозволи ACPX harness відокремлені від схвалень exec у OpenClaw і відокремлені від vendor-прапорців обходу в CLI-бекендах, таких як Claude CLI `--permission-mode bypassPermissions`. ACPX `approve-all` — це аварійний перемикач на рівні harness для ACP-сеансів.
|
||||
|
||||
### `permissionMode`
|
||||
|
||||
Керує тим, які операції агент harness може виконувати без запиту.
|
||||
|
||||
| Значення | Поведінка |
|
||||
| --------------- | -------------------------------------------------------- |
|
||||
| `approve-all` | Автоматично схвалює всі записи у файли та shell-команди. |
|
||||
| `approve-reads` | Автоматично схвалює лише читання; запис і exec вимагають запитів. |
|
||||
| `deny-all` | Відхиляє всі запити дозволів. |
|
||||
| Value | Behavior |
|
||||
| --------------- | ---------------------------------------------------------------- |
|
||||
| `approve-all` | Автоматично схвалювати всі записи файлів і shell-команди. |
|
||||
| `approve-reads` | Автоматично схвалювати лише читання; запис і exec потребують запитів. |
|
||||
| `deny-all` | Відхиляти всі запити на дозвіл. |
|
||||
|
||||
### `nonInteractivePermissions`
|
||||
|
||||
Керує тим, що відбувається, коли мав би з’явитися запит на дозвіл, але інтерактивний TTY недоступний (а для сеансів ACP це завжди так).
|
||||
Керує тим, що відбувається, коли мав би з’явитися запит на дозвіл, але інтерактивний TTY недоступний (а для ACP-сеансів це завжди так).
|
||||
|
||||
| Значення | Поведінка |
|
||||
| -------- | ---------------------------------------------------------------- |
|
||||
| `fail` | Перервати сеанс з `AcpRuntimeError`. **(за замовчуванням)** |
|
||||
| `deny` | Мовчки відхилити дозвіл і продовжити роботу (плавна деградація). |
|
||||
| Value | Behavior |
|
||||
| ------ | ------------------------------------------------------------- |
|
||||
| `fail` | Перервати сеанс з `AcpRuntimeError`. **(типово)** |
|
||||
| `deny` | Мовчки відхилити дозвіл і продовжити роботу (graceful degradation). |
|
||||
|
||||
### Конфігурація
|
||||
|
||||
Налаштовується через конфігурацію плагіна:
|
||||
Задається через конфігурацію плагіна:
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
|
||||
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
|
||||
```
|
||||
|
||||
Після зміни цих значень перезапустіть gateway.
|
||||
Перезапустіть 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)` | Диспетчеризацію зі звичайних повідомлень у гілках вимкнено. | Встановіть `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`; вручну завершіть завислі процеси. |
|
||||
| Symptom | Likely cause | Fix |
|
||||
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `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: ...` | Неправильний токен key/id/label. | Виконайте `/acp sessions`, скопіюйте точний key/label і повторіть. |
|
||||
| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, до якої можна прив’язати. | Перейдіть у цільовий чат/канал і повторіть, або використайте spawn без прив’язки. |
|
||||
| `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 runtime працює на хості; сеанс-запитувач працює в sandbox. | Використовуйте `runtime="subagent"` із sandboxed-сеансів або запускайте ACP spawn із сеансу без sandbox. |
|
||||
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для runtime ACP було запитано `sandbox="require"`. | Використовуйте `runtime="subagent"` для обов’язкового sandboxing або 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](#permission-configuration). |
|
||||
| ACP session fails early with little output | Запити на дозволи блокуються через `permissionMode`/`nonInteractivePermissions`. | Перевірте логи gateway на `AcpRuntimeError`. Для повних дозволів задайте `permissionMode=approve-all`; для graceful degradation задайте `nonInteractivePermissions=deny`. |
|
||||
| ACP session stalls indefinitely after completing work | Процес harness завершився, але ACP-сеанс не повідомив про завершення. | Відстежуйте через `ps aux \| grep acpx`; вручну завершіть застарілі процеси. |
|
||||
|
||||
Loading…
Reference in New Issue
Block a user