From 79f02727c3bc989526fc4bc0173149891e3dee35 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 28 Apr 2026 00:39:06 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/concepts/memory-builtin.md | 101 +-- docs/uk/concepts/model-providers.md | 373 +++++------ docs/uk/help/testing-live.md | 472 +++++++------- docs/uk/platforms/mac/peekaboo.md | 62 +- docs/uk/plugins/codex-computer-use.md | 271 ++++---- docs/uk/plugins/codex-harness.md | 645 +++++++++---------- docs/uk/plugins/compatibility.md | 152 ++--- docs/uk/plugins/hooks.md | 242 +++---- docs/uk/plugins/memory-lancedb.md | 141 +++-- docs/uk/plugins/sdk-channel-plugins.md | 422 ++++++------- docs/uk/plugins/sdk-migration.md | 830 +++++++++++++------------ docs/uk/plugins/sdk-subpaths.md | 502 +++++++-------- docs/uk/plugins/sdk-testing.md | 206 +++--- docs/uk/providers/deepinfra.md | 90 +++ docs/uk/providers/models.md | 23 +- docs/uk/reference/api-usage-costs.md | 146 ++--- docs/uk/reference/memory-config.md | 422 ++++++------- docs/uk/reference/test.md | 104 ++-- docs/uk/tools/image-generation.md | 273 ++++---- docs/uk/tools/media-overview.md | 161 ++--- docs/uk/tools/tts.md | 554 ++++++++--------- docs/uk/tools/video-generation.md | 360 +++++------ 22 files changed, 3437 insertions(+), 3115 deletions(-) create mode 100644 docs/uk/providers/deepinfra.md diff --git a/docs/uk/concepts/memory-builtin.md b/docs/uk/concepts/memory-builtin.md index 05bda9a5a..217fe65cd 100644 --- a/docs/uk/concepts/memory-builtin.md +++ b/docs/uk/concepts/memory-builtin.md @@ -1,32 +1,32 @@ --- read_when: - - Ви хочете зрозуміти стандартний бекенд пам’яті + - Ви хочете зрозуміти типовий бекенд пам’яті - Ви хочете налаштувати провайдерів ембедингів або гібридний пошук -summary: Стандартний бекенд пам’яті на основі SQLite з пошуком за ключовими словами, векторним і гібридним пошуком +summary: Типовий бекенд пам’яті на основі SQLite з пошуком за ключовими словами, векторним і гібридним пошуком title: Вбудований рушій пам’яті x-i18n: - generated_at: "2026-04-27T12:49:12Z" + generated_at: "2026-04-28T00:34:00Z" model: gpt-5.4 provider: openai - source_hash: 6b7893109f933b8130b4c4a3b0fd5be705dd92891d27deb37be1e677a0ee268e + source_hash: aa1597a9a49a6f1124cedf49f6f5a4c336f76dd5998ced246affb9c2e8171f05 source_path: concepts/memory-builtin.md workflow: 15 --- -Вбудований рушій — це стандартний бекенд пам’яті. Він зберігає ваш індекс пам’яті -в окремій для кожного агента базі даних SQLite і не потребує додаткових залежностей для початку роботи. +Вбудований рушій є типовим бекендом пам’яті. Він зберігає ваш індекс пам’яті в +окремій базі даних SQLite для кожного агента й не потребує додаткових залежностей для початку роботи. ## Що він надає - **Пошук за ключовими словами** через повнотекстове індексування FTS5 (оцінювання BM25). - **Векторний пошук** через ембединги від будь-якого підтримуваного провайдера. -- **Гібридний пошук**, що поєднує обидва підходи для найкращих результатів. -- **Підтримка CJK** через триграмну токенізацію для китайської, японської та корейської мов. -- **Прискорення sqlite-vec** для векторних запитів у базі даних (необов’язково). +- **Гібридний пошук**, який поєднує обидва підходи для найкращих результатів. +- **Підтримку CJK** через триграмну токенізацію для китайської, японської та корейської мов. +- **Прискорення sqlite-vec** для векторних запитів усередині бази даних (необов’язково). ## Початок роботи -Якщо у вас є API-ключ для OpenAI, Gemini, Voyage або Mistral, вбудований +Якщо у вас є API-ключ для OpenAI, Gemini, Voyage, Mistral або DeepInfra, вбудований рушій автоматично виявить його та ввімкне векторний пошук. Конфігурація не потрібна. Щоб явно вказати провайдера: @@ -43,10 +43,10 @@ x-i18n: } ``` -Без провайдера ембедингів буде доступний лише пошук за ключовими словами. +Без провайдера ембедингів доступний лише пошук за ключовими словами. -Щоб примусово використовувати вбудований локальний провайдер ембедингів, установіть необов’язковий -пакет середовища виконання `node-llama-cpp` поруч з OpenClaw, а потім укажіть `local.modelPath` +Щоб примусово використовувати вбудованого локального провайдера ембедингів, встановіть необов’язковий +пакет середовища виконання `node-llama-cpp` поруч із OpenClaw, а потім укажіть `local.modelPath` на файл GGUF: ```json5 @@ -67,55 +67,56 @@ x-i18n: ## Підтримувані провайдери ембедингів -| Провайдер | ID | Автовиявлення | Примітки | -| --------- | --------- | ------------- | ----------------------------------- | -| OpenAI | `openai` | Так | Типово: `text-embedding-3-small` | -| Gemini | `gemini` | Так | Підтримує мультимодальність (зображення + аудіо) | -| Voyage | `voyage` | Так | | -| Mistral | `mistral` | Так | | -| Ollama | `ollama` | Ні | Локальний, потрібно вказати явно | -| Local | `local` | Так (першим) | Необов’язкове середовище виконання `node-llama-cpp` | +| Провайдер | ID | Автоматичне виявлення | Примітки | +| --------- | ----------- | --------------------- | ----------------------------------- | +| OpenAI | `openai` | Так | Типово: `text-embedding-3-small` | +| Gemini | `gemini` | Так | Підтримує мультимодальність (зображення + аудіо) | +| Voyage | `voyage` | Так | | +| Mistral | `mistral` | Так | | +| DeepInfra | `deepinfra` | Так | Типово: `BAAI/bge-m3` | +| Ollama | `ollama` | Ні | Локальний, потрібно вказати явно | +| Local | `local` | Так (першим) | Необов’язкове середовище виконання `node-llama-cpp` | -Автовиявлення вибирає першого провайдера, для якого вдається знайти API-ключ, у -наведеному порядку. Установіть `memorySearch.provider`, щоб перевизначити це. +Автоматичне виявлення вибирає першого провайдера, для якого вдається визначити API-ключ, у +показаному порядку. Щоб перевизначити це, установіть `memorySearch.provider`. ## Як працює індексування -OpenClaw індексує `MEMORY.md` і `memory/*.md` у чанки (~400 токенів із -перекриттям 80 токенів) і зберігає їх в окремій для кожного агента базі даних SQLite. +OpenClaw індексує `MEMORY.md` і `memory/*.md` на фрагменти (~400 токенів з +перекриттям у 80 токенів) і зберігає їх в окремій базі даних SQLite для кожного агента. - **Розташування індексу:** `~/.openclaw/memory/.sqlite` - **Обслуговування сховища:** побічні файли SQLite WAL обмежуються періодичними - checkpoint-ами та checkpoint-ами під час завершення роботи. -- **Відстеження файлів:** зміни у файлах пам’яті запускають відкладене повторне індексування (1,5 с). -- **Автоматичне повторне індексування:** коли змінюється провайдер ембедингів, модель або конфігурація чанкування, - увесь індекс автоматично перебудовується. -- **Повторне індексування за запитом:** `openclaw memory index --force` + та завершальними checkpoint. +- **Спостереження за файлами:** зміни у файлах пам’яті запускають відкладене повторне індексування (1,5 с). +- **Автоматичне повторне індексування:** коли змінюється провайдер ембедингів, модель або конфігурація фрагментації, + весь індекс автоматично перебудовується. +- **Повторне індексування на вимогу:** `openclaw memory index --force` -Ви також можете індексувати файли Markdown поза робочим простором за допомогою +Ви також можете індексувати файли Markdown поза межами робочого простору за допомогою `memorySearch.extraPaths`. Див. [довідник із конфігурації](/uk/reference/memory-config#additional-memory-paths). ## Коли використовувати -Вбудований рушій — правильний вибір для більшості користувачів: +Вбудований рушій є правильним вибором для більшості користувачів: - Працює одразу без додаткових залежностей. - Добре обробляє пошук за ключовими словами та векторний пошук. - Підтримує всіх провайдерів ембедингів. -- Гібридний пошук поєднує найкраще з обох підходів до отримання даних. +- Гібридний пошук поєднує найкраще з обох підходів до пошуку. Розгляньте перехід на [QMD](/uk/concepts/memory-qmd), якщо вам потрібні reranking, query -expansion або якщо ви хочете індексувати каталоги поза робочим простором. +expansion або якщо ви хочете індексувати каталоги поза межами робочого простору. -Розгляньте [Honcho](/uk/concepts/memory-honcho), якщо вам потрібна міжсеансна пам’ять з +Розгляньте [Honcho](/uk/concepts/memory-honcho), якщо вам потрібна пам’ять між сесіями з автоматичним моделюванням користувача. -## Усунення проблем +## Усунення несправностей -**Пошук у пам’яті вимкнено?** Перевірте `openclaw memory status`. Якщо жодного провайдера не -виявлено, явно вкажіть його або додайте API-ключ. +**Пошук у пам’яті вимкнено?** Перевірте `openclaw memory status`. Якщо провайдера не +виявлено, укажіть його явно або додайте API-ключ. **Локального провайдера не виявлено?** Переконайтеся, що локальний шлях існує, і виконайте: @@ -124,25 +125,25 @@ openclaw memory status --deep --agent main openclaw memory index --force --agent main ``` -І окремі команди CLI, і Gateway використовують той самий ідентифікатор провайдера `local`. +Як окремі команди CLI, так і Gateway використовують той самий ідентифікатор провайдера `local`. Якщо для провайдера встановлено `auto`, локальні ембединги розглядаються першими лише тоді, коли `memorySearch.local.modelPath` вказує на наявний локальний файл. -**Застарілі результати?** Виконайте `openclaw memory index --force`, щоб перебудувати індекс. Засіб -відстеження в рідкісних крайових випадках може пропустити зміни. +**Застарілі результати?** Виконайте `openclaw memory index --force`, щоб перебудувати індекс. Спостерігач +може пропустити зміни в рідкісних крайових випадках. -**sqlite-vec не завантажується?** OpenClaw автоматично повертається до внутрішньопроцесної косинусної подібності. -Перевірте журнали, щоб дізнатися про конкретну помилку завантаження. +**sqlite-vec не завантажується?** OpenClaw автоматично повертається до косинусної подібності +в межах процесу. Перевірте журнали для конкретної помилки завантаження. ## Конфігурація -Щоб дізнатися про налаштування провайдера ембедингів, налаштування гібридного пошуку (ваги, MMR, часовий -спад), пакетне індексування, мультимодальну пам’ять, sqlite-vec, додаткові шляхи та всі -інші параметри конфігурації, див. -[довідник із конфігурації Memory](/uk/reference/memory-config). +Налаштування провайдера ембедингів, тонке налаштування гібридного пошуку (ваги, MMR, часовий +спад), пакетне індексування, мультимодальна пам’ять, sqlite-vec, додаткові шляхи та всі +інші параметри конфігурації див. у +[довіднику з конфігурації пам’яті](/uk/reference/memory-config). -## Пов’язано +## Пов’язане -- [Огляд Memory](/uk/concepts/memory) -- [Пошук у Memory](/uk/concepts/memory-search) +- [Огляд пам’яті](/uk/concepts/memory) +- [Пошук у пам’яті](/uk/concepts/memory-search) - [Active Memory](/uk/concepts/active-memory) diff --git a/docs/uk/concepts/model-providers.md b/docs/uk/concepts/model-providers.md index 5316f5514..e31ada1f8 100644 --- a/docs/uk/concepts/model-providers.md +++ b/docs/uk/concepts/model-providers.md @@ -1,61 +1,61 @@ --- read_when: - - Вам потрібна довідка з налаштування моделей для кожного провайдера окремо - - Вам потрібні приклади конфігурацій або команди онбордингу CLI для провайдерів моделей + - Вам потрібен довідник із налаштування моделей для кожного постачальника окремо + - Ви хочете приклади конфігурацій або команд онбордингу CLI для постачальників моделей sidebarTitle: Model providers -summary: Огляд провайдерів моделей із прикладами конфігурацій і потоками CLI -title: Провайдери моделей +summary: Огляд постачальників моделей із прикладами конфігурацій + потоками CLI +title: Постачальники моделей x-i18n: - generated_at: "2026-04-27T12:49:31Z" + generated_at: "2026-04-28T00:34:00Z" model: gpt-5.4 provider: openai - source_hash: 6b2390b0dc98ba26d5be02ee5b7b3189536912726f4fadd2e43fe62d66ff3643 + source_hash: 0fc7c5ba37f321906ec06733fb9c20ea346014279563db5dc6b723dc3c0cdd23 source_path: concepts/model-providers.md workflow: 15 --- -Довідка для **провайдерів LLM/моделей** (а не каналів чату на кшталт WhatsApp/Telegram). Правила вибору моделей дивіться в [Моделі](/uk/concepts/models). +Довідник для **постачальників LLM/моделей** (а не чат-каналів на кшталт WhatsApp/Telegram). Правила вибору моделей див. у [Models](/uk/concepts/models). ## Швидкі правила - - Посилання на моделі використовують формат `provider/model` (приклад: `opencode/claude-opus-4-6`). - - `agents.defaults.models` працює як список дозволених моделей, якщо заданий. + - Посилання на моделі використовують `provider/model` (приклад: `opencode/claude-opus-4-6`). + - `agents.defaults.models` працює як список дозволених значень, якщо його задано. - Допоміжні команди CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. - - `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` задають типові значення на рівні провайдера; `models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` перевизначають їх для окремої моделі. - - Правила резервного перемикання, перевірки cooldown і збереження перевизначень сесії: [Model failover](/uk/concepts/model-failover). + - `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` задають типові значення на рівні постачальника; `models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` перевизначають їх для окремої моделі. + - Правила резервного перемикання, cooldown-проби та збереження перевизначень сесії див. у [Model failover](/uk/concepts/model-failover). - + Маршрути сімейства OpenAI залежать від префікса: - - `openai/` використовує прямий провайдер OpenAI з API-ключем у Pi. - - `openai-codex/` використовує Codex OAuth у Pi. + - `openai/` використовує прямого постачальника API-ключів OpenAI у PI. + - `openai-codex/` використовує Codex OAuth у PI. - `openai/` разом із `agents.defaults.agentRuntime.id: "codex"` використовує нативний app-server harness Codex. - Дивіться [OpenAI](/uk/providers/openai) і [Codex harness](/uk/plugins/codex-harness). Якщо розділення провайдера/середовища виконання викликає плутанину, спочатку прочитайте [Середовища виконання агентів](/uk/concepts/agent-runtimes). + Див. [OpenAI](/uk/providers/openai) і [Codex harness](/uk/plugins/codex-harness). Якщо поділ постачальника/середовища виконання заплутує, спочатку прочитайте [Agent runtimes](/uk/concepts/agent-runtimes). - Автоматичне ввімкнення Plugin дотримується тієї самої межі: `openai-codex/` належить до Plugin OpenAI, тоді як Plugin Codex вмикається через `agentRuntime.id: "codex"` або застарілі посилання `codex/`. + Автоматичне ввімкнення Plugin дотримується тієї самої межі: `openai-codex/` належить Plugin OpenAI, тоді як Plugin Codex вмикається через `agentRuntime.id: "codex"` або застарілі посилання `codex/`. - GPT-5.5 доступна через `openai/gpt-5.5` для прямого трафіку з API-ключем, `openai-codex/gpt-5.5` у Pi для Codex OAuth і нативний app-server harness Codex, коли встановлено `agentRuntime.id: "codex"`. + GPT-5.5 доступна через `openai/gpt-5.5` для прямого трафіку з API-ключем, `openai-codex/gpt-5.5` у PI для Codex OAuth, а також через нативний app-server harness Codex, коли задано `agentRuntime.id: "codex"`. - Середовища виконання CLI використовують те саме розділення: вибирайте канонічні посилання на моделі, як-от `anthropic/claude-*`, `google/gemini-*` або `openai/gpt-*`, а потім установлюйте `agents.defaults.agentRuntime.id` у `claude-cli`, `google-gemini-cli` або `codex-cli`, коли вам потрібен локальний бекенд CLI. + Середовища виконання CLI використовують той самий поділ: вибирайте канонічні посилання на моделі, як-от `anthropic/claude-*`, `google/gemini-*` або `openai/gpt-*`, а потім задайте `agents.defaults.agentRuntime.id` як `claude-cli`, `google-gemini-cli` або `codex-cli`, якщо вам потрібен локальний бекенд CLI. - Застарілі посилання `claude-cli/*`, `google-gemini-cli/*` і `codex-cli/*` мігрують назад до канонічних посилань провайдерів, а середовище виконання записується окремо. + Застарілі посилання `claude-cli/*`, `google-gemini-cli/*` і `codex-cli/*` мігрують назад до канонічних посилань постачальників, а середовище виконання записується окремо. -## Поведінка провайдера, що належить Plugin +## Поведінка постачальників, якою володіє Plugin -Більшість логіки, специфічної для провайдера, живе в Plugin провайдерів (`registerProvider(...)`), тоді як OpenClaw зберігає загальний цикл інференсу. Plugins відповідають за онбординг, каталоги моделей, зіставлення змінних середовища автентифікації, нормалізацію транспорту/конфігурації, очищення схем інструментів, класифікацію резервного перемикання, оновлення OAuth, звітність про використання, профілі мислення/міркування тощо. +Більшість логіки, специфічної для постачальників, живе в Plugin постачальників (`registerProvider(...)`), тоді як OpenClaw зберігає узагальнений цикл інференсу. Plugins відповідають за онбординг, каталоги моделей, зіставлення auth env-var, нормалізацію транспорту/конфігурації, очищення схем інструментів, класифікацію резервного перемикання, оновлення OAuth, звітування про використання, профілі thinking/reasoning тощо. -Повний список хуків provider-SDK і приклади вбудованих Plugins наведено в [Provider plugins](/uk/plugins/sdk-provider-plugins). Провайдер, якому потрібен повністю кастомний виконавець запитів, — це окрема, глибша поверхня розширення. +Повний список хуків SDK постачальників і прикладів вбудованих Plugins наведено в [Provider plugins](/uk/plugins/sdk-provider-plugins). Постачальник, якому потрібен повністю кастомний виконавець запитів, використовує окрему, глибшу поверхню розширення. -`capabilities` середовища виконання провайдера — це спільні метадані виконавця (сімейство провайдера, особливості транскрипту/інструментів, підказки для транспорту/кешу). Це не те саме, що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє Plugin (текстовий інференс, мовлення тощо). +`capabilities` середовища виконання постачальника — це спільні метадані раннера (сімейство постачальника, особливості transcript/tooling, підказки для transport/cache). Це не те саме, що [public capability model](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє Plugin (текстовий інференс, мовлення тощо). ## Ротація API-ключів @@ -64,42 +64,42 @@ x-i18n: Налаштуйте кілька ключів через: - - `OPENCLAW_LIVE__KEY` (єдине живе перевизначення, найвищий пріоритет) - - `_API_KEYS` (список через кому або крапку з комою) + - `OPENCLAW_LIVE__KEY` (одне live-перевизначення, найвищий пріоритет) + - `_API_KEYS` (список, розділений комами або крапками з комою) - `_API_KEY` (основний ключ) - `_API_KEY_*` (нумерований список, наприклад `_API_KEY_1`) - Для провайдерів Google `GOOGLE_API_KEY` також включається як резервний варіант. Порядок вибору ключів зберігає пріоритет і прибирає дублікати значень. + Для постачальників Google також як резервне значення використовується `GOOGLE_API_KEY`. Порядок вибору ключів зберігає пріоритет і усуває дублікати значень. - - Запити повторюються з наступним ключем лише у відповідь на обмеження швидкості (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання). - - Збої, не пов’язані з обмеженням швидкості, завершуються негайно; ротація ключів не виконується. - - Коли всі кандидатні ключі не спрацювали, повертається фінальна помилка з останньої спроби. + - Запити повторюються з наступним ключем лише у відповідь на rate-limit (наприклад, `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання). + - Збої, не пов’язані з rate-limit, завершуються одразу; ротація ключів не виконується. + - Коли всі можливі ключі завершуються помилкою, повертається фінальна помилка з останньої спроби. -## Вбудовані провайдери (каталог pi-ai) +## Вбудовані постачальники (каталог pi-ai) -OpenClaw постачається з каталогом pi‑ai. Ці провайдери **не** потребують конфігурації `models.providers`; достатньо налаштувати автентифікацію та вибрати модель. +OpenClaw постачається з каталогом pi‑ai. Для цих постачальників **не потрібна** конфігурація `models.providers`; просто налаштуйте auth і виберіть модель. ### OpenAI -- Провайдер: `openai` -- Автентифікація: `OPENAI_API_KEY` +- Постачальник: `openai` +- Auth: `OPENAI_API_KEY` - Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення) - Приклади моделей: `openai/gpt-5.5`, `openai/gpt-5.4-mini` - Перевіряйте доступність облікового запису/моделі за допомогою `openclaw models list --provider openai`, якщо конкретне встановлення або API-ключ поводиться інакше. - CLI: `openclaw onboard --auth-choice openai-api-key` -- Типовий транспорт — `auto` (спочатку WebSocket, резервно SSE) +- Типовий transport — `auto` (спочатку WebSocket, із резервним переходом на SSE) - Перевизначення для окремої моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- Розігрівання OpenAI Responses WebSocket типово ввімкнене через `params.openaiWsWarmup` (`true`/`false`) +- Прогрівання OpenAI Responses WebSocket типово ввімкнене через `params.openaiWsWarmup` (`true`/`false`) - Пріоритетну обробку OpenAI можна ввімкнути через `agents.defaults.models["openai/"].params.serviceTier` -- `/fast` і `params.fastMode` зіставляють прямі запити Responses `openai/*` із `service_tier=priority` на `api.openai.com` -- Використовуйте `params.serviceTier`, якщо вам потрібен явно заданий рівень замість спільного перемикача `/fast` -- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не до загальних OpenAI-сумісних проксі -- Нативні маршрути OpenAI також зберігають `store` Responses, підказки кешу промптів і формування payload OpenAI reasoning-compat; проксі-маршрути цього не роблять -- `openai/gpt-5.3-codex-spark` навмисно приглушено в OpenClaw, оскільки живі запити OpenAI API його відхиляють, а поточний каталог Codex його не надає +- `/fast` і `params.fastMode` напряму зіставляють запити Responses `openai/*` з `service_tier=priority` на `api.openai.com` +- Використовуйте `params.serviceTier`, якщо вам потрібен явний tier замість спільного перемикача `/fast` +- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не до загальних OpenAI-сумісних proxy +- Нативні маршрути OpenAI також зберігають `store` із Responses, підказки prompt-cache і формування payload для сумісності з OpenAI reasoning; proxy-маршрути цього не роблять +- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, оскільки live-запити до OpenAI API його відхиляють, а поточний каталог Codex його не показує ```json5 { @@ -109,16 +109,16 @@ OpenClaw постачається з каталогом pi‑ai. Ці прова ### Anthropic -- Провайдер: `anthropic` -- Автентифікація: `ANTHROPIC_API_KEY` +- Постачальник: `anthropic` +- Auth: `ANTHROPIC_API_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`) -- Бажана конфігурація Claude CLI зберігає канонічне посилання на модель і вибирає бекенд CLI окремо: `anthropic/claude-opus-4-7` з `agents.defaults.agentRuntime.id: "claude-cli"`. Застарілі посилання `claude-cli/claude-opus-4-7` усе ще працюють для сумісності. +- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком з API-ключем та OAuth-автентифікацією, що надсилається на `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) +- Рекомендована конфігурація Claude CLI зберігає канонічне посилання на модель і окремо вибирає CLI-бекенд: `anthropic/claude-opus-4-7` з `agents.defaults.agentRuntime.id: "claude-cli"`. Застарілі посилання `claude-cli/claude-opus-4-7` усе ще працюють для сумісності. -Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. Токен налаштування Anthropic усе ще доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли це можливо. +Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI і використання `claude -p` дозволеними для цієї інтеграції, якщо Anthropic не опублікує нову політику. Токен налаштування Anthropic і далі доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли це можливо. ```json5 @@ -129,22 +129,22 @@ OpenClaw постачається з каталогом pi‑ai. Ці прова ### OpenAI Codex OAuth -- Провайдер: `openai-codex` -- Автентифікація: OAuth (ChatGPT) +- Постачальник: `openai-codex` +- Auth: OAuth (ChatGPT) - Посилання на модель PI: `openai-codex/gpt-5.5` -- Посилання нативного app-server harness Codex: `openai/gpt-5.5` з `agents.defaults.agentRuntime.id: "codex"` +- Посилання на нативний app-server harness Codex: `openai/gpt-5.5` з `agents.defaults.agentRuntime.id: "codex"` - Документація нативного app-server harness Codex: [Codex harness](/uk/plugins/codex-harness) - Застарілі посилання на моделі: `codex/gpt-*` -- Межа Plugin: `openai-codex/*` завантажує Plugin OpenAI; нативний Plugin app-server Codex вибирається лише через середовище виконання Codex harness або застарілі посилання `codex/*`. +- Межа Plugin: `openai-codex/*` завантажує Plugin OpenAI; нативний Plugin app-server Codex вибирається лише середовищем виконання Codex harness або застарілими посиланнями `codex/*`. - CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex` -- Типовий транспорт — `auto` (спочатку WebSocket, резервно SSE) +- Типовий transport — `auto` (спочатку WebSocket, із резервним переходом на SSE) - Перевизначення для окремої моделі PI через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) - `params.serviceTier` також передається в нативних запитах Codex Responses (`chatgpt.com/backend-api`) -- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) додаються лише до нативного трафіку Codex на `chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних проксі +- Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) додаються лише до нативного трафіку Codex на `chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних proxy - Використовує той самий перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` -- `openai-codex/gpt-5.5` використовує нативний для каталогу Codex `contextWindow = 400000` і типове для середовища виконання `contextTokens = 272000`; перевизначайте ліміт середовища виконання через `models.providers.openai-codex.models[].contextTokens` -- Примітка щодо політики: OpenAI Codex OAuth явно підтримується для зовнішніх інструментів/робочих процесів, як-от OpenClaw. -- Використовуйте `openai-codex/gpt-5.5`, якщо вам потрібен маршрут Codex OAuth/підписки; використовуйте `openai/gpt-5.5`, якщо ваші налаштування API-ключа та локальний каталог відкривають маршрут публічного API. +- `openai-codex/gpt-5.5` використовує нативні значення каталогу Codex `contextWindow = 400000` і типове для середовища виконання `contextTokens = 272000`; перевизначайте ліміт середовища виконання через `models.providers.openai-codex.models[].contextTokens` +- Примітка щодо політики: OpenAI Codex OAuth явно підтримується для зовнішніх інструментів/робочих процесів, таких як OpenClaw. +- Використовуйте `openai-codex/gpt-5.5`, коли вам потрібен маршрут Codex OAuth/підписки; використовуйте `openai/gpt-5.5`, коли ваше налаштування API-ключа та локальний каталог відкривають публічний маршрут API. ```json5 { @@ -164,7 +164,7 @@ OpenClaw постачається з каталогом pi‑ai. Ці прова } ``` -### Інші розміщені варіанти у стилі підписки +### Інші розміщені варіанти в стилі підписки @@ -174,15 +174,15 @@ OpenClaw постачається з каталогом pi‑ai. Ці прова OAuth плану MiniMax Coding або доступ за API-ключем. - Поверхня провайдера Qwen Cloud плюс зіставлення кінцевих точок Alibaba DashScope і Coding Plan. + Поверхня постачальника Qwen Cloud, а також зіставлення кінцевих точок Alibaba DashScope і Coding Plan. ### OpenCode -- Автентифікація: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`) -- Провайдер середовища виконання Zen: `opencode` -- Провайдер середовища виконання Go: `opencode-go` +- Auth: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`) +- Постачальник середовища виконання Zen: `opencode` +- Постачальник середовища виконання Go: `opencode-go` - Приклади моделей: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.6` - CLI: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go` @@ -194,22 +194,22 @@ OpenClaw постачається з каталогом pi‑ai. Ці прова ### 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` (одне перевизначення) +- Постачальник: `google` +- Auth: `GEMINI_API_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` +- Сумісність: застарілу конфігурацію OpenClaw з `google/gemini-3.1-flash-preview` нормалізовано до `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` -- Мислення: `/think adaptive` використовує динамічне мислення Google. Gemini 3/3.1 не мають фіксованого `thinkingLevel`; Gemini 2.5 надсилає `thinkingBudget: -1`. -- Прямі запуски Gemini також приймають `agents.defaults.models["google/"].params.cachedContent` (або застаріле `cached_content`) для передавання нативного дескриптора провайдера `cachedContents/...`; влучання в кеш Gemini відображаються як OpenClaw `cacheRead` +- Thinking: `/think adaptive` використовує динамічне thinking Google. Gemini 3/3.1 не мають фіксованого `thinkingLevel`; Gemini 2.5 надсилає `thinkingBudget: -1`. +- Прямі запуски Gemini також приймають `agents.defaults.models["google/"].params.cachedContent` (або застарілий `cached_content`) для передавання нативного дескриптора постачальника `cachedContents/...`; потрапляння в кеш Gemini відображаються як OpenClaw `cacheRead` ### Google Vertex і Gemini CLI -- Провайдери: `google-vertex`, `google-gemini-cli` -- Автентифікація: Vertex використовує gcloud ADC; Gemini CLI використовує свій потік OAuth +- Постачальники: `google-vertex`, `google-gemini-cli` +- Auth: Vertex використовує gcloud ADC; Gemini CLI використовує свій потік OAuth -Gemini CLI OAuth в OpenClaw — це неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. +Gemini CLI OAuth в OpenClaw — це неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікових записів Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. Gemini CLI OAuth постачається як частина вбудованого Plugin `google`. @@ -239,11 +239,11 @@ Gemini CLI OAuth постачається як частина вбудовано openclaw models auth login --provider google-gemini-cli --set-default ``` - Модель за замовчуванням: `google-gemini-cli/gemini-3-flash-preview`. Вам **не потрібно** вставляти client id або secret у `openclaw.json`. Потік входу CLI зберігає токени в профілях автентифікації на хості gateway. + Типова модель: `google-gemini-cli/gemini-3-flash-preview`. Ви **не** вставляєте client id або secret у `openclaw.json`. Потік входу CLI зберігає токени в auth profiles на хості gateway. - - Якщо після входу запити завершуються помилкою, установіть `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway. + + Якщо після входу запити завершуються помилкою, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway. @@ -251,96 +251,97 @@ JSON-відповіді Gemini CLI розбираються з `response`; да ### Z.AI (GLM) -- Провайдер: `zai` -- Автентифікація: `ZAI_API_KEY` +- Постачальник: `zai` +- Auth: `ZAI_API_KEY` - Приклад моделі: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - Аліаси: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*` - - `zai-api-key` автоматично виявляє відповідну кінцеву точку 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 -- Провайдер: `vercel-ai-gateway` -- Автентифікація: `AI_GATEWAY_API_KEY` +- Постачальник: `vercel-ai-gateway` +- Auth: `AI_GATEWAY_API_KEY` - Приклади моделей: `vercel-ai-gateway/anthropic/claude-opus-4.6`, `vercel-ai-gateway/moonshotai/kimi-k2.6` - CLI: `openclaw onboard --auth-choice ai-gateway-api-key` ### Kilo Gateway -- Провайдер: `kilocode` -- Автентифікація: `KILOCODE_API_KEY` +- Постачальник: `kilocode` +- Auth: `KILOCODE_API_KEY` - Приклад моделі: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` - Базова URL-адреса: `https://api.kilo.ai/api/gateway/` -- Статичний резервний каталог постачається з `kilocode/kilo/auto`; живе виявлення через `https://api.kilo.ai/api/gateway/models` може додатково розширити каталог середовища виконання. -- Точна маршрутизація на боці постачальника за `kilocode/kilo/auto` належить Kilo Gateway, а не жорстко закодована в OpenClaw. +- Статичний резервний каталог постачається з `kilocode/kilo/auto`; live-виявлення через `https://api.kilo.ai/api/gateway/models` може додатково розширити каталог середовища виконання. +- Точна маршрутизація вгору за течією для `kilocode/kilo/auto` належить Kilo Gateway, а не жорстко закодована в OpenClaw. -Деталі налаштування дивіться в [/providers/kilocode](/uk/providers/kilocode). +Докладні відомості про налаштування див. у [/providers/kilocode](/uk/providers/kilocode). -### Інші вбудовані Plugin провайдерів +### Інші вбудовані Plugins постачальників -| Провайдер | Id | Змінна середовища для автентифікації | Приклад моделі | -| ----------------------- | -------------------------------- | ---------------------------------------------------------- | ----------------------------------------------- | -| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | -| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | -| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | -| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` | -| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — | -| Groq | `groq` | `GROQ_API_KEY` | — | -| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` або `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | -| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | -| Kimi Coding | `kimi` | `KIMI_API_KEY` або `KIMICODE_API_KEY` | `kimi/kimi-code` | -| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` | -| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` | -| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | -| NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | -| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` | -| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` | -| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` | -| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` | -| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` | -| Venice | `venice` | `VENICE_API_KEY` | — | -| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | -| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | -| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | -| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | +| Постачальник | Id | Auth env | Приклад моделі | +| ----------------------- | -------------------------------- | ------------------------------------------------------------ | ---------------------------------------------- | +| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | +| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | +| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | +| DeepInfra | `deepinfra` | `DEEPINFRA_API_KEY` | `deepinfra/deepseek-ai/DeepSeek-V3.2` | +| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` | +| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — | +| Groq | `groq` | `GROQ_API_KEY` | — | +| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` або `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | +| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | +| Kimi Coding | `kimi` | `KIMI_API_KEY` або `KIMICODE_API_KEY` | `kimi/kimi-code` | +| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` | +| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` | +| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | +| NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | +| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` | +| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` | +| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` | +| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` | +| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` | +| Venice | `venice` | `VENICE_API_KEY` | — | +| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | +| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | +| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | +| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | -#### Важливі особливості +#### Особливості, які варто знати - Застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Посилання DeepSeek, Moonshot і ZAI придатні для TTL кешу в керованому OpenRouter кешуванні промптів, але не отримують маркерів кешу Anthropic. Як проксі-шлях у стилі OpenAI-сумісності, він пропускає формування, притаманне лише нативному OpenAI (`serviceTier`, `store` Responses, підказки кешу промптів, OpenAI reasoning-compat). Посилання на базі Gemini зберігають лише очищення сигнатури думок proxy-Gemini. + Застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Посилання DeepSeek, Moonshot і ZAI мають право на cache-TTL для prompt caching, яким керує OpenRouter, але не отримують маркери кешу Anthropic. Як OpenAI-сумісний шлях у стилі proxy, він пропускає формування, доступне лише для нативного OpenAI (`serviceTier`, `store` у Responses, підказки prompt-cache, сумісність із OpenAI reasoning). Посилання на базі Gemini зберігають лише очищення thought-signature для proxy Gemini. - Посилання на базі Gemini проходять тим самим шляхом очищення proxy-Gemini; `kilocode/kilo/auto` та інші посилання, що не підтримують proxy reasoning, пропускають ін’єкцію proxy reasoning. + Посилання на базі Gemini дотримуються того самого шляху очищення для proxy Gemini; `kilocode/kilo/auto` та інші посилання, які не підтримують reasoning через proxy, пропускають ін’єкцію reasoning для proxy. - Онбординг через API-ключ записує явні визначення чат-моделей M2.7 лише для тексту; розуміння зображень залишається на медіапровайдері `MiniMax-VL-01`, що належить Plugin. + Онбординг за API-ключем записує явні визначення chat-моделей M2.7 лише для тексту; розуміння зображень залишається на медіа-постачальнику `MiniMax-VL-01`, яким володіє Plugin. - Використовує шлях xAI Responses. `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast`. `tool_stream` типово ввімкнений; вимкнення через `agents.defaults.models["xai/"].params.tool_stream=false`. + Використовує шлях xAI Responses. `/fast` або `params.fastMode: true` переписують `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast`. `tool_stream` типово ввімкнено; вимкнення через `agents.defaults.models["xai/"].params.tool_stream=false`. - Постачається як вбудований Plugin провайдера `cerebras`. GLM використовує `zai-glm-4.7`; базова URL-адреса в стилі OpenAI-compatible — `https://api.cerebras.ai/v1`. + Постачається як вбудований Plugin постачальника `cerebras`. GLM використовує `zai-glm-4.7`; OpenAI-сумісна базова URL-адреса — `https://api.cerebras.ai/v1`. -## Провайдери через `models.providers` (кастомні/base URL) +## Постачальники через `models.providers` (custom/base URL) -Використовуйте `models.providers` (або `models.json`), щоб додавати **кастомні** провайдери або OpenAI/Anthropic‑сумісні проксі. +Використовуйте `models.providers` (або `models.json`), щоб додати **custom** постачальників або OpenAI/Anthropic‑сумісні proxy. -Багато з наведених нижче вбудованих Plugin провайдерів уже публікують типовий каталог. Явні записи `models.providers.` використовуйте лише тоді, коли потрібно перевизначити типову base URL, заголовки або список моделей. +Багато з наведених нижче вбудованих Plugins постачальників уже публікують типовий каталог. Явні записи `models.providers.` використовуйте лише тоді, коли хочете перевизначити типову base URL, headers або список моделей. ### Moonshot AI (Kimi) -Moonshot постачається як вбудований Plugin провайдера. Типово використовуйте вбудований провайдер, а явний запис `models.providers.moonshot` додавайте лише тоді, коли потрібно перевизначити базову URL-адресу або метадані моделі: +Moonshot постачається як вбудований Plugin постачальника. Типово використовуйте вбудованого постачальника і додавайте явний запис `models.providers.moonshot` лише тоді, коли потрібно перевизначити базову URL-адресу або метадані моделі: -- Провайдер: `moonshot` -- Автентифікація: `MOONSHOT_API_KEY` +- Постачальник: `moonshot` +- Auth: `MOONSHOT_API_KEY` - Приклад моделі: `moonshot/kimi-k2.6` - CLI: `openclaw onboard --auth-choice moonshot-api-key` або `openclaw onboard --auth-choice moonshot-api-key-cn` -Ідентифікатори моделей Kimi: +Ідентифікатори моделей Kimi K2: [//]: # "moonshot-kimi-k2-model-refs:start" @@ -373,10 +374,10 @@ Moonshot постачається як вбудований Plugin провай ### Kimi coding -Kimi Coding використовує Anthropic-compatible кінцеву точку Moonshot AI: +Kimi Coding використовує Anthropic-сумісну кінцеву точку Moonshot AI: -- Провайдер: `kimi` -- Автентифікація: `KIMI_API_KEY` +- Постачальник: `kimi` +- Auth: `KIMI_API_KEY` - Приклад моделі: `kimi/kimi-code` ```json5 @@ -388,14 +389,14 @@ Kimi Coding використовує Anthropic-compatible кінцеву точ } ``` -Застарілий `kimi/k2p5` усе ще приймається як сумісний id моделі. +Застарілий `kimi/k2p5` і далі приймається як ідентифікатор моделі для сумісності. ### Volcano Engine (Doubao) Volcano Engine (火山引擎) надає доступ до Doubao та інших моделей у Китаї. -- Провайдер: `volcengine` (coding: `volcengine-plan`) -- Автентифікація: `VOLCANO_ENGINE_API_KEY` +- Постачальник: `volcengine` (coding: `volcengine-plan`) +- Auth: `VOLCANO_ENGINE_API_KEY` - Приклад моделі: `volcengine-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice volcengine-api-key` @@ -409,7 +410,7 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши Онбординг типово використовує поверхню coding, але загальний каталог `volcengine/*` реєструється одночасно. -У засобах вибору моделі для онбордингу/налаштування модельний вибір для автентифікації Volcengine віддає перевагу рядкам `volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажені, OpenClaw повертається до нефільтрованого каталогу замість показу порожнього вибору провайдера. +У вибірниках моделей для онбордингу/налаштування вибору auth Volcengine надає перевагу рядкам і `volcengine/*`, і `volcengine-plan/*`. Якщо ці моделі ще не завантажені, OpenClaw повертається до нефільтрованого каталогу, а не показує порожній вибірник у межах постачальника. @@ -419,7 +420,7 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши - `volcengine/glm-4-7-251222` (GLM 4.7) - `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K) - + - `volcengine-plan/ark-code-latest` - `volcengine-plan/doubao-seed-code` - `volcengine-plan/kimi-k2.5` @@ -428,12 +429,12 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши -### BytePlus (International) +### BytePlus (міжнародний) BytePlus ARK надає міжнародним користувачам доступ до тих самих моделей, що й Volcano Engine. -- Провайдер: `byteplus` (coding: `byteplus-plan`) -- Автентифікація: `BYTEPLUS_API_KEY` +- Постачальник: `byteplus` (coding: `byteplus-plan`) +- Auth: `BYTEPLUS_API_KEY` - Приклад моделі: `byteplus-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice byteplus-api-key` @@ -447,7 +448,7 @@ BytePlus ARK надає міжнародним користувачам дост Онбординг типово використовує поверхню coding, але загальний каталог `byteplus/*` реєструється одночасно. -У засобах вибору моделі для онбордингу/налаштування модельний вибір для автентифікації BytePlus віддає перевагу рядкам `byteplus/*` і `byteplus-plan/*`. Якщо ці моделі ще не завантажені, OpenClaw повертається до нефільтрованого каталогу замість показу порожнього вибору провайдера. +У вибірниках моделей для онбордингу/налаштування вибір auth BytePlus надає перевагу рядкам і `byteplus/*`, і `byteplus-plan/*`. Якщо ці моделі ще не завантажені, OpenClaw повертається до нефільтрованого каталогу, а не показує порожній вибірник у межах постачальника. @@ -455,7 +456,7 @@ BytePlus ARK надає міжнародним користувачам дост - `byteplus/kimi-k2-5-260127` (Kimi K2.5) - `byteplus/glm-4-7-251222` (GLM 4.7) - + - `byteplus-plan/ark-code-latest` - `byteplus-plan/doubao-seed-code` - `byteplus-plan/kimi-k2.5` @@ -466,10 +467,10 @@ BytePlus ARK надає міжнародним користувачам дост ### Synthetic -Synthetic надає Anthropic-compatible моделі через провайдер `synthetic`: +Synthetic надає Anthropic-сумісні моделі через постачальника `synthetic`: -- Провайдер: `synthetic` -- Автентифікація: `SYNTHETIC_API_KEY` +- Постачальник: `synthetic` +- Auth: `SYNTHETIC_API_KEY` - Приклад моделі: `synthetic/hf:MiniMaxAI/MiniMax-M2.5` - CLI: `openclaw onboard --auth-choice synthetic-api-key` @@ -494,36 +495,36 @@ Synthetic надає Anthropic-compatible моделі через провайд ### MiniMax -MiniMax налаштовується через `models.providers`, оскільки використовує кастомні кінцеві точки: +MiniMax налаштовується через `models.providers`, оскільки використовує custom-кінцеві точки: - 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_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` +- MiniMax API-ключ (Global): `--auth-choice minimax-global-api` +- MiniMax API-ключ (CN): `--auth-choice minimax-cn-api` +- Auth: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` -Деталі налаштування, параметри моделей і фрагменти конфігурації дивіться в [/providers/minimax](/uk/providers/minimax). +Докладні відомості про налаштування, варіанти моделей і фрагменти конфігурації див. у [/providers/minimax](/uk/providers/minimax). -На Anthropic-compatible шляху потокової передачі MiniMax OpenClaw типово вимикає thinking, якщо ви явно його не встановите, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. +На Anthropic-сумісному шляху потокової передачі MiniMax OpenClaw типово вимикає thinking, якщо ви не задали його явно, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. -Розділення можливостей, що належать Plugin: +Розподіл можливостей, яким володіє Plugin: -- Типові налаштування тексту/чату залишаються на `minimax/MiniMax-M2.7` +- Типові значення для тексту/chat залишаються на `minimax/MiniMax-M2.7` - Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01` -- Розуміння зображень — це `MiniMax-VL-01`, що належить Plugin, на обох шляхах автентифікації MiniMax -- Web search залишається на id провайдера `minimax` +- Розуміння зображень — це `MiniMax-VL-01`, яким володіє Plugin, на обох шляхах auth MiniMax +- Вебпошук залишається на id постачальника `minimax` ### LM Studio -LM Studio постачається як вбудований Plugin провайдера, який використовує нативний API: +LM Studio постачається як вбудований Plugin постачальника, який використовує нативний API: -- Провайдер: `lmstudio` -- Автентифікація: `LM_API_TOKEN` -- Типова базова URL-адреса інференсу: `http://localhost:1234/v1` +- Постачальник: `lmstudio` +- Auth: `LM_API_TOKEN` +- Типова базова URL-адреса для інференсу: `http://localhost:1234/v1` -Потім установіть модель (замініть на один з id, повернутих `http://localhost:1234/api/v1/models`): +Потім задайте модель (замініть на один з id, повернених `http://localhost:1234/api/v1/models`): ```json5 { @@ -533,14 +534,14 @@ LM Studio постачається як вбудований Plugin провай } ``` -OpenClaw використовує нативні `/api/v1/models` і `/api/v1/models/load` LM Studio для виявлення й автозавантаження, а `/v1/chat/completions` — типово для інференсу. Налаштування та усунення проблем дивіться в [/providers/lmstudio](/uk/providers/lmstudio). +OpenClaw використовує нативні для LM Studio `/api/v1/models` і `/api/v1/models/load` для виявлення й автозавантаження, а `/v1/chat/completions` — типово для інференсу. Докладні відомості про налаштування та усунення несправностей див. у [/providers/lmstudio](/uk/providers/lmstudio). ### Ollama -Ollama постачається як вбудований Plugin провайдера і використовує нативний API Ollama: +Ollama постачається як вбудований Plugin постачальника й використовує нативний API Ollama: -- Провайдер: `ollama` -- Автентифікація: не потрібна (локальний сервер) +- Постачальник: `ollama` +- Auth: не потрібен (локальний сервер) - Приклад моделі: `ollama/llama3.3` - Встановлення: [https://ollama.com/download](https://ollama.com/download) @@ -557,23 +558,23 @@ ollama pull llama3.3 } ``` -Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви вмикаєте її через `OLLAMA_API_KEY`, а вбудований Plugin провайдера безпосередньо додає Ollama до `openclaw onboard` і засобу вибору моделі. Онбординг, локальний/хмарний режим і кастомну конфігурацію дивіться в [/providers/ollama](/uk/providers/ollama). +Ollama виявляється локально за адресою `http://127.0.0.1:11434`, якщо ви виконаєте opt-in через `OLLAMA_API_KEY`, а вбудований Plugin постачальника додає Ollama безпосередньо до `openclaw onboard` і до вибірника моделей. Докладні відомості про онбординг, хмарний/локальний режим і custom-конфігурацію див. у [/providers/ollama](/uk/providers/ollama). ### vLLM -vLLM постачається як вбудований Plugin провайдера для локальних/self-hosted OpenAI-compatible серверів: +vLLM постачається як вбудований Plugin постачальника для локальних/self-hosted OpenAI-сумісних серверів: -- Провайдер: `vllm` -- Автентифікація: необов’язкова (залежить від вашого сервера) -- Типова базова URL-адреса: `http://127.0.0.1:8000/v1` +- Постачальник: `vllm` +- Auth: необов’язковий (залежить від вашого сервера) +- Типова base URL: `http://127.0.0.1:8000/v1` -Щоб увімкнути автовиявлення локально (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації): +Щоб локально виконати opt-in для автовиявлення (підійде будь-яке значення, якщо ваш сервер не вимагає auth): ```bash export VLLM_API_KEY="vllm-local" ``` -Потім установіть модель (замініть на один з id, повернутих `/v1/models`): +Потім задайте модель (замініть на один з id, повернених `/v1/models`): ```json5 { @@ -583,23 +584,23 @@ export VLLM_API_KEY="vllm-local" } ``` -Докладніше дивіться в [/providers/vllm](/uk/providers/vllm). +Докладні відомості див. у [/providers/vllm](/uk/providers/vllm). ### SGLang -SGLang постачається як вбудований Plugin провайдера для швидких self-hosted OpenAI-compatible серверів: +SGLang постачається як вбудований Plugin постачальника для швидких self-hosted OpenAI-сумісних серверів: -- Провайдер: `sglang` -- Автентифікація: необов’язкова (залежить від вашого сервера) -- Типова базова URL-адреса: `http://127.0.0.1:30000/v1` +- Постачальник: `sglang` +- Auth: необов’язковий (залежить від вашого сервера) +- Типова base URL: `http://127.0.0.1:30000/v1` -Щоб увімкнути автовиявлення локально (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації): +Щоб локально виконати opt-in для автовиявлення (підійде будь-яке значення, якщо ваш сервер не вимагає auth): ```bash export SGLANG_API_KEY="sglang-local" ``` -Потім установіть модель (замініть на один з id, повернутих `/v1/models`): +Потім задайте модель (замініть на один з id, повернених `/v1/models`): ```json5 { @@ -609,11 +610,11 @@ export SGLANG_API_KEY="sglang-local" } ``` -Докладніше дивіться в [/providers/sglang](/uk/providers/sglang). +Докладні відомості див. у [/providers/sglang](/uk/providers/sglang). -### Локальні проксі (LM Studio, vLLM, LiteLLM тощо) +### Локальні proxy (LM Studio, vLLM, LiteLLM тощо) -Приклад (OpenAI-compatible): +Приклад (OpenAI‑сумісний): ```json5 { @@ -649,7 +650,7 @@ export SGLANG_API_KEY="sglang-local" - Для кастомних провайдерів `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими. Якщо їх не вказано, OpenClaw типово використовує: + Для custom-постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими. Якщо їх пропущено, OpenClaw типово використовує: - `reasoning: false` - `input: ["text"]` @@ -657,17 +658,17 @@ export SGLANG_API_KEY="sglang-local" - `contextWindow: 200000` - `maxTokens: 8192` - Рекомендація: указуйте явні значення, які відповідають обмеженням вашого проксі/моделі. + Рекомендація: задавайте явні значення, що відповідають обмеженням вашого proxy/моделі. - - - Для `api: "openai-completions"` на ненативних кінцевих точках (будь-яка непорожня `baseUrl`, вузол якої не `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникати помилок 400 від провайдера для непідтримуваних ролей `developer`. - - Проксі-маршрути у стилі OpenAI-compatible також пропускають формування запитів, притаманне лише нативному OpenAI: без `service_tier`, без `store` Responses, без `store` Completions, без підказок кешу промптів, без формування payload OpenAI reasoning-compat і без прихованих заголовків атрибуції OpenClaw. - - Для проксі Completions у стилі OpenAI-compatible, яким потрібні поля, специфічні для постачальника, установіть `agents.defaults.models["provider/model"].params.extra_body` (або `extraBody`), щоб додати додатковий JSON до вихідного тіла запиту. - - Для керування chat template у vLLM установіть `agents.defaults.models["provider/model"].params.chat_template_kwargs`. Вбудований Plugin vLLM автоматично надсилає `enable_thinking: false` і `force_nonempty_content: true` для `vllm/nemotron-3-*`, коли в сесії вимкнено рівень thinking. - - Для повільних локальних моделей або віддалених хостів LAN/tailnet установіть `models.providers..timeoutSeconds`. Це розширює обробку HTTP-запитів моделі провайдера, включно з підключенням, заголовками, потоковою передачею тіла та загальним abort захищеного fetch, не збільшуючи тайм-аут усього середовища виконання агента. - - Якщо `baseUrl` порожній або не вказаний, OpenClaw зберігає типову поведінку OpenAI (яка зводиться до `api.openai.com`). - - З міркувань безпеки явне `compat.supportsDeveloperRole: true` все одно перевизначається на ненативних кінцевих точках `openai-completions`. + + - Для `api: "openai-completions"` на ненативних кінцевих точках (будь-який непорожній `baseUrl`, у якого host не `api.openai.com`) OpenClaw примусово задає `compat.supportsDeveloperRole: false`, щоб уникнути помилок 400 від постачальника для непідтримуваних ролей `developer`. + - Маршрути OpenAI-сумісних proxy у стилі proxy також пропускають формування запитів, доступне лише для нативного OpenAI: без `service_tier`, без `store` у Responses, без `store` у Completions, без підказок prompt-cache, без формування payload для сумісності з OpenAI reasoning і без прихованих заголовків атрибуції OpenClaw. + - Для OpenAI-сумісних proxy Completions, яким потрібні поля, специфічні для постачальника, задайте `agents.defaults.models["provider/model"].params.extra_body` (або `extraBody`), щоб об’єднати додатковий JSON у вихідне тіло запиту. + - Для керування `chat_template` у vLLM задайте `agents.defaults.models["provider/model"].params.chat_template_kwargs`. Вбудований Plugin vLLM автоматично надсилає `enable_thinking: false` і `force_nonempty_content: true` для `vllm/nemotron-3-*`, коли рівень thinking у сесії вимкнено. + - Для повільних локальних моделей або віддалених хостів у LAN/tailnet задайте `models.providers..timeoutSeconds`. Це подовжує обробку HTTP-запитів моделі постачальника, включно з підключенням, заголовками, потоковою передачею тіла та загальним guarded-fetch abort, не збільшуючи при цьому timeout усього середовища виконання агента. + - Якщо `baseUrl` порожній або не заданий, OpenClaw зберігає типову поведінку OpenAI (яка вказує на `api.openai.com`). + - З міркувань безпеки явне `compat.supportsDeveloperRole: true` усе одно перевизначається на ненативних кінцевих точках `openai-completions`. @@ -679,11 +680,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -Дивіться також: [Configuration](/uk/gateway/configuration) для повних прикладів конфігурації. +Див. також: [Configuration](/uk/gateway/configuration) для повних прикладів конфігурації. ## Пов’язане -- [Довідка з конфігурації](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей +- [Configuration reference](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей - [Model failover](/uk/concepts/model-failover) — ланцюжки резервного перемикання та поведінка повторних спроб -- [Моделі](/uk/concepts/models) — конфігурація моделей і аліаси -- [Провайдери](/uk/providers) — окремі посібники з налаштування провайдерів +- [Models](/uk/concepts/models) — конфігурація моделей і аліаси +- [Providers](/uk/providers) — посібники з налаштування для кожного постачальника окремо diff --git a/docs/uk/help/testing-live.md b/docs/uk/help/testing-live.md index a9ce9874b..0fda579ef 100644 --- a/docs/uk/help/testing-live.md +++ b/docs/uk/help/testing-live.md @@ -1,35 +1,35 @@ --- read_when: - - Запуск живих smoke-тестів для матриці моделей / бекендів CLI / ACP / медіапровайдерів - - Налагодження визначення облікових даних для живих тестів - - Додавання нового живого тесту для конкретного провайдера + - Запуск smoke-тестів live-матриці моделей / бекенду CLI / ACP / медіапровайдерів + - Налагодження визначення облікових даних live-тестів + - Додавання нового live-тесту, специфічного для провайдера sidebarTitle: Live tests -summary: 'Живі тести (з доступом до мережі): матриця моделей, бекенди CLI, ACP, медіапровайдери, облікові дані' -title: 'Тестування: живі набори тестів' +summary: 'Live (мережеві) тести: матриця моделей, бекенди CLI, ACP, медіапровайдери, облікові дані' +title: 'Тестування: live-набори тестів' x-i18n: - generated_at: "2026-04-27T06:26:00Z" + generated_at: "2026-04-28T00:34:02Z" model: gpt-5.4 provider: openai - source_hash: 9a512bf4344cdb429e8adba822d6499c0f0e6b2fbc05f1eae98d29ebd75923e3 + source_hash: 9db18fe515b823a73e1fccf06c9de1899000700eba9d4972506d35d25b9c4a2f source_path: help/testing-live.md workflow: 15 --- -Щоб дізнатися про швидкий старт, QA runners, модульні/інтеграційні набори тестів і сценарії Docker, див. -[Testing](/uk/help/testing). Ця сторінка описує **живі** (з доступом до мережі) набори тестів: -матрицю моделей, бекенди CLI, ACP і живі тести медіапровайдерів, а також -роботу з обліковими даними. +Для швидкого старту, раннерів QA, наборів unit/integration тестів і Docker-процесів див. +[Тестування](/uk/help/testing). Ця сторінка охоплює **live** (мережеві) набори тестів: +матрицю моделей, бекенди CLI, ACP і live-тести медіапровайдерів, а також +обробку облікових даних. -## Живі тести: локальні smoke-команди профілю +## Live: команди локального smoke-тесту профілю -Перед одноразовими живими перевірками виконайте `source ~/.profile`, щоб ключі провайдерів і локальні шляхи інструментів -відповідали вашій оболонці: +Виконайте `source ~/.profile` перед разовими live-перевірками, щоб ключі +провайдерів і шляхи до локальних інструментів відповідали вашій оболонці: ```bash source ~/.profile ``` -Безпечний smoke-тест медіа: +Безпечний медіа-smoke-тест: ```bash pnpm openclaw infer tts convert --local --json \ @@ -37,43 +37,43 @@ pnpm openclaw infer tts convert --local --json \ --output /tmp/openclaw-live-smoke.mp3 ``` -Безпечний smoke-тест готовності до голосового виклику: +Безпечний smoke-тест готовності голосового виклику: ```bash pnpm openclaw voicecall setup --json pnpm openclaw voicecall smoke --to "+15555550123" ``` -`voicecall smoke` — це dry run, якщо також не вказано `--yes`. Використовуйте `--yes` лише тоді, -коли ви свідомо хочете здійснити реальний повідомлювальний виклик. Для Twilio, Telnyx і -Plivo успішна перевірка готовності потребує публічного URL Webhook; лише локальні +`voicecall smoke` — це dry run, якщо також не вказано `--yes`. Використовуйте `--yes`, лише +коли ви свідомо хочете здійснити реальний сповіщувальний дзвінок. Для Twilio, Telnyx і +Plivo успішна перевірка готовності потребує публічної URL-адреси Webhook; лише локальні резервні варіанти loopback/private навмисно відхиляються. -## Живі тести: перевірка можливостей Android Node +## Live: перевірка можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яка зараз оголошена** підключеним Android Node, і перевірити поведінку контракту команд. -- Область: - - Попередньо підготовлене/ручне налаштування (набір тестів не встановлює/не запускає/не виконує pairing застосунку). - - Перевірка `node.invoke` Gateway для вибраного Android Node по командах. +- Мета: викликати **кожну команду, яку наразі оголошує** підключений Android Node, і перевірити поведінку контракту команд. +- Обсяг: + - Попередньо підготовлене/ручне налаштування (набір тестів не встановлює, не запускає й не спаровує застосунок). + - Перевірка `node.invoke` у Gateway для вибраного Android Node покомандно. - Обов’язкове попереднє налаштування: - - Android-застосунок уже підключений і спарений із Gateway. + - Android-застосунок уже підключено й спаровано з 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) -## Живі тести: smoke-тести моделей (ключі профілю) +## Live: smoke-тест моделі (ключі профілю) -Живі тести поділено на два шари, щоб можна було ізолювати збої: +Live-тести поділено на два рівні, щоб можна було ізолювати збої: -- «Безпосередня модель» показує, чи провайдер/модель взагалі може відповісти з наданим ключем. -- «Smoke-тест Gateway» показує, чи працює для цієї моделі повний конвеєр gateway+agent (сесії, історія, інструменти, політика пісочниці тощо). +- «Пряма модель» показує, чи може провайдер/модель взагалі відповісти з наданим ключем. +- «Smoke-тест Gateway» показує, чи працює для цієї моделі весь конвеєр gateway+agent (сеанси, історія, інструменти, політика sandbox тощо). -### Шар 1: безпосереднє завершення моделі (без gateway) +### Рівень 1: Пряме завершення моделі (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: @@ -82,60 +82,60 @@ Plivo успішна перевірка готовності потребує п - Виконати невелике завершення для кожної моделі (і цільові регресійні перевірки за потреби) - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб реально запустити цей набір; інакше його буде пропущено, щоб `pnpm test:live` лишався зосередженим на smoke-тесті gateway -- Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для сучасного allowlist +- Встановіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб фактично запустити цей набір тестів; інакше його буде пропущено, щоб `pnpm test:live` залишався зосередженим на smoke-тесті gateway +- Як вибрати моделі: + - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Для modern/all перевірок за замовчуванням використовується підібране обмеження з високим сигналом; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого обмеження. - - Вичерпні перевірки використовують `OPENCLAW_LIVE_TEST_TIMEOUT_MS` як тайм-аут усього тесту безпосередньої моделі. За замовчуванням: 60 хвилин. - - Перевірки безпосередніх моделей за замовчуванням виконуються з паралелізмом 20; для перевизначення встановіть `OPENCLAW_LIVE_MODEL_CONCURRENCY`. -- Як вибирати провайдерів: + - Для modern/all-перевірок за замовчуванням використовується підібране обмеження з високим сигналом; встановіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого ліміту. + - Для вичерпних перевірок використовується `OPENCLAW_LIVE_TEST_TIMEOUT_MS` як тайм-аут для всього тесту прямої моделі. За замовчуванням: 60 хвилин. + - Перевірки прямої моделі за замовчуванням виконуються з паралелізмом 20; для перевизначення встановіть `OPENCLAW_LIVE_MODEL_CONCURRENCY`. +- Як вибрати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - За замовчуванням: сховище профілів і резервні варіанти з env - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** + - Встановіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - - Відокремлює «API провайдера зламане / ключ недійсний» від «конвеєр агента gateway зламаний» - - Містить невеликі ізольовані регресії (приклад: повторення міркувань OpenAI Responses/Codex Responses + сценарії виклику інструментів) + - Відокремлює «API провайдера зламаний / ключ недійсний» від «конвеєр gateway agent зламаний» + - Містить невеликі ізольовані регресії (приклад: відтворення міркувань OpenAI Responses/Codex Responses + процеси tool-call) -### Шар 2: smoke-тест Gateway + dev agent (тобто того, що реально робить "@openclaw") +### Рівень 2: Smoke-тест Gateway + dev agent (що фактично робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Підняти in-process gateway - - Створити/оновити сесію `agent:dev:*` (з перевизначенням моделі для кожного запуску) - - Перебрати моделі з ключами та перевірити: + - Запустити вбудований gateway + - Створити/виправити сеанс `agent:dev:*` (перевизначення моделі для кожного запуску) + - Перебрати моделі з ключами й перевірити: - «змістовну» відповідь (без інструментів) - - що реальний виклик інструмента працює (перевірка `read`) - - необов’язкові додаткові перевірки інструментів (перевірка `exec+read`) - - що регресійні сценарії OpenAI (лише виклик інструмента → наступний крок) і далі працюють -- Подробиці перевірок (щоб ви могли швидко пояснювати збої): - - Перевірка `read`: тест записує nonce-файл у робочому просторі та просить агента виконати `read` і повернути nonce. - - Перевірка `exec+read`: тест просить агента через `exec` записати nonce у тимчасовий файл, а потім прочитати його через `read`. - - Перевірка зображення: тест додає згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. + - що працює реальний виклик інструмента (перевірка read) + - необов’язкові додаткові перевірки інструментів (перевірка exec+read) + - що шляхи регресії OpenAI (лише tool-call → follow-up) і далі працюють +- Деталі перевірок (щоб ви могли швидко пояснити збої): + - перевірка `read`: тест записує nonce-файл у workspace і просить agent виконати `read` для нього та повернути nonce. + - перевірка `exec+read`: тест просить agent через `exec` записати nonce у тимчасовий файл, а потім через `read` прочитати його назад. + - перевірка зображення: тест прикріплює згенерований PNG (cat + випадковий код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) -- Як вибирати моделі: - - За замовчуванням: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для сучасного allowlist - - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір - - Для modern/all gateway-перевірок за замовчуванням використовується підібране обмеження з високим сигналом; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого обмеження. -- Як вибирати провайдерів (щоб уникнути сценарію «весь OpenRouter»): +- Як вибрати моделі: + - За замовчуванням: modern allowlist (Opus/Sonnet 4.6+, GPT-5.2 + Codex, Gemini 3, DeepSeek V4, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для modern allowlist + - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому) для звуження + - Для modern/all gateway-перевірок за замовчуванням використовується підібране обмеження з високим сигналом; встановіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого ліміту. +- Як вибрати провайдерів (уникнути «все з OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Перевірки інструментів і зображень у цьому живому тесті завжди увімкнені: +- Перевірки інструментів і зображень у цьому live-тесті завжди ввімкнені: - перевірка `read` + перевірка `exec+read` (навантаження на інструменти) - - перевірка зображення виконується, коли модель оголошує підтримку вхідних зображень - - Потік (на високому рівні): - - Тест генерує маленький PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) + - перевірка зображення виконується, коли модель оголошує підтримку введення зображень + - Процес (на високому рівні): + - Тест генерує крихітний PNG з «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - Gateway розбирає вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Вбудований агент пересилає мультимодальне повідомлення користувача моделі - - Перевірка: відповідь містить `cat` + код (OCR-толерантність: незначні помилки допускаються) + - Вбудований agent пересилає мультимодальне повідомлення користувача моделі + - Перевірка: відповідь містить `cat` + код (допускається OCR-толерантність: незначні помилки дозволені) -Щоб побачити, що саме можна тестувати на вашій машині (і точні id `provider/model`), виконайте: +Щоб побачити, що можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: ```bash openclaw models list @@ -144,27 +144,27 @@ openclaw models list --json -## Живі тести: smoke-тест бекенда CLI (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke-тест бекенду CLI (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent за допомогою локального бекенда CLI, не змінюючи вашої стандартної конфігурації. -- Значення за замовчуванням для smoke-тесту, специфічні для бекенда, зберігаються у визначенні `cli-backend.ts` відповідного розширення. +- Мета: перевірити конвеєр Gateway + agent за допомогою локального бекенду CLI, не змінюючи вашу типову конфігурацію. +- Типові значення smoke-тесту для конкретного бекенду містяться у визначенні `cli-backend.ts` розширення-власника. - Увімкнення: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Значення за замовчуванням: - Провайдер/модель за замовчуванням: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image береться з метаданих плагіна бекенда CLI-власника. + - Поведінка command/args/image походить із метаданих Plugin CLI-бекенду-власника. - Перевизначення (необов’язково): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2"` - `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`, щоб надіслати реальне вкладення-зображення (шляхи інжектуються в запит). У рецептах Docker це за замовчуванням вимкнено, якщо не запрошено явно. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість інжекції в запит. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати тим, як передаються аргументи зображень, коли задано `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити сценарій resume. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1`, щоб явно ввімкнути перевірку безперервності тієї самої сесії Claude Sonnet -> Opus, коли вибрана модель підтримує ціль перемикання. У рецептах Docker це за замовчуванням вимкнено для загальної надійності. - - `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1`, щоб явно ввімкнути перевірку loopback MCP/tool. У рецептах Docker це за замовчуванням вимкнено, якщо не запрошено явно. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальне вкладення-зображення (шляхи впроваджуються в prompt). У рецептах Docker це за замовчуванням вимкнено, якщо явно не запитано. + - `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`, щоб надіслати другий хід і перевірити процес відновлення. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1`, щоб увімкнути перевірку безперервності в межах одного сеансу Claude Sonnet -> Opus, коли вибрана модель підтримує ціль перемикання. У рецептах Docker це за замовчуванням вимкнено для загальної надійності. + - `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1`, щоб увімкнути перевірку MCP/tool loopback. У рецептах Docker це за замовчуванням вимкнено, якщо явно не запитано. Приклад: @@ -174,17 +174,17 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:live src/gateway/gateway-cli-backend.live.test.ts ``` -Дешева smoke-перевірка конфігурації Gemini MCP: +Недорогий smoke-тест конфігурації Gemini MCP: ```bash OPENCLAW_LIVE_TEST=1 \ pnpm test:live src/agents/cli-runner/bundle-mcp.gemini.live.test.ts ``` -Це не просить Gemini згенерувати відповідь. Тест записує ті самі системні -налаштування, які OpenClaw передає Gemini, а потім виконує `gemini --debug mcp list`, щоб довести, що -збережений сервер `transport: "streamable-http"` нормалізується до HTTP MCP-форми Gemini -і може підключатися до локального streamable-HTTP MCP-сервера. +Це не просить Gemini згенерувати відповідь. Воно записує ті самі системні +налаштування, які OpenClaw надає Gemini, а потім запускає `gemini --debug mcp list`, щоб довести, що +збережений сервер `transport: "streamable-http"` нормалізується до HTTP MCP-форми Gemini і +може підключатися до локального streamable-HTTP MCP-сервера. Рецепт Docker: @@ -203,29 +203,29 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker-runner розташований у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає живий smoke-тест CLI-backend усередині Docker-образу репозиторію від непривілейованого користувача `node`. -- Він визначає метадані smoke-тесту CLI із відповідного розширення, а потім встановлює відповідний Linux-пакет CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований каталог із правом запису за префіксом `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` вимагає portable Claude Code subscription OAuth через `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType` або через `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку тест безпосередньо перевіряє `claude -p` у Docker, а потім виконує два ходи Gateway CLI-backend без збереження змінних середовища з ключами Anthropic API. У цій subscription-гілці перевірки Claude MCP/tool і image за замовчуванням вимкнено, тому що Claude зараз маршрутизує використання сторонніх застосунків через білінг додаткового використання, а не через звичайні обмеження тарифного плану підписки. -- Живий smoke-тест CLI-backend тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід із класифікацією зображення, а потім виклик інструмента MCP `cron`, перевірений через gateway CLI. -- Smoke-тест Claude за замовчуванням також оновлює сесію із Sonnet до Opus і перевіряє, що відновлена сесія досі пам’ятає попередню нотатку. +- Docker-раннер розташований у `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke-тест CLI-бекенду всередині Docker-образу репозиторію від імені непривілейованого користувача `node`. +- Він визначає метадані smoke-тесту CLI з розширення-власника, а потім встановлює відповідний Linux-пакет CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` потребує переносної OAuth-підписки Claude Code через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він доводить роботу прямого `claude -p` у Docker, а потім виконує два ходи Gateway CLI-бекенду без збереження env-змінних API-ключа Anthropic. У цьому режимі підписки за замовчуванням вимкнено перевірки Claude MCP/tool і зображень, оскільки Claude наразі маршрутизує використання сторонніх застосунків через тарифікацію додаткового використання замість звичайних лімітів плану підписки. +- Live smoke-тест CLI-бекенду тепер перевіряє той самий наскрізний процес для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через gateway CLI. +- Типовий smoke-тест Claude також виправляє сеанс із Sonnet на Opus і перевіряє, що відновлений сеанс усе ще пам’ятає попередню нотатку. -## Живі тести: smoke-тест прив’язки ACP (`/acp spawn ... --bind here`) +## Live: smoke-тест прив’язки ACP (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний процес прив’язки розмов ACP із живим ACP-агентом: +- Мета: перевірити реальний процес conversation-bind ACP із live ACP-agent: - надіслати `/acp spawn --bind here` - прив’язати синтетичну розмову каналу повідомлень на місці - - надіслати звичайне подальше повідомлення в цій самій розмові - - переконатися, що подальше повідомлення потрапляє в транскрипт прив’язаної ACP-сесії + - надіслати звичайне follow-up у тій самій розмові + - перевірити, що follow-up потрапляє до transcript прив’язаного сеансу ACP - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Значення за замовчуванням: - - ACP-агенти в Docker: `claude,codex,gemini` - - ACP-агент для прямого `pnpm test:live ...`: `claude` + - ACP-agents у Docker: `claude,codex,gemini` + - ACP-agent для прямого `pnpm test:live ...`: `claude` - Синтетичний канал: контекст розмови у стилі Slack DM - - ACP-бекенд: `acpx` + - Бекенд ACP: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -240,9 +240,9 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1` - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.2` - Примітки: - - Цей маршрут використовує поверхню gateway `chat.send` з адміністративними синтетичними полями originating-route, щоб тести могли додавати контекст каналу повідомлень без імітації зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр агентів плагіна `acpx` для вибраного ACP-агента тестового стенда. - - Створення MCP `cron` для прив’язаної сесії за замовчуванням працює в режимі best-effort, оскільки зовнішні ACP-стенди можуть скасовувати виклики MCP після проходження перевірки прив’язки/зображення; установіть `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1`, щоб зробити цю перевірку `cron` після прив’язки суворою. + - Цей lane використовує поверхню gateway `chat.send` з admin-only синтетичними полями originating-route, щоб тести могли додавати контекст каналу повідомлень без імітації зовнішньої доставки. + - Якщо `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent з Plugin `acpx` для вибраного harness-agent ACP. + - Створення bound-session cron MCP за замовчуванням є best-effort, оскільки зовнішні harness ACP можуть скасовувати виклики MCP після проходження bind/image-перевірки; встановіть `OPENCLAW_LIVE_ACP_BIND_REQUIRE_CRON=1`, щоб зробити цю післяприв’язочну перевірку cron суворою. Приклад: @@ -258,7 +258,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:docker:live-acp-bind ``` -Рецепти Docker для одного агента: +Рецепти Docker для одного agent: ```bash pnpm test:docker:live-acp-bind:claude @@ -270,39 +270,39 @@ pnpm test:docker:live-acp-bind:opencode Примітки щодо Docker: -- Docker-runner розташований у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він послідовно запускає smoke-тест прив’язки ACP для сукупних живих CLI-агентів: `claude`, `codex`, потім `gemini`. +- Docker-раннер розташований у `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він послідовно запускає ACP bind smoke-тест для сукупності live CLI-agents: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=droid`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=opencode`, щоб звузити матрицю. -- Він виконує `source ~/.profile`, підготовлює відповідний автентифікаційний матеріал CLI у контейнері, а потім за потреби встановлює потрібний живий CLI (`@anthropic-ai/claude-code`, `@openai/codex`, Factory Droid через `https://app.factory.ai/cli`, `@google/gemini-cli` або `opencode-ai`). Сам ACP-бекенд — це вбудований пакет середовища виконання `acpx/runtime` із плагіна `acpx`. -- Варіант Docker для Droid готує `~/.factory` для налаштувань, передає `FACTORY_API_KEY` і вимагає цей API-ключ, оскільки локальна автентифікація Factory через OAuth/keyring не є переносною в контейнер. Він використовує вбудований запис реєстру ACPX `droid exec --output-format acp`. -- Варіант Docker для OpenCode — це суворий одоагентний маршрут регресії. Після `source ~/.profile` він записує тимчасову модель за замовчуванням `OPENCODE_CONFIG_CONTENT` із `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL` (за замовчуванням `opencode/kimi-k2.6`), а `pnpm test:docker:live-acp-bind:opencode` вимагає транскрипт прив’язаного помічника замість прийняття загального пропуску після прив’язки. -- Прямі виклики CLI `acpx` — це лише ручний/обхідний шлях для порівняння поведінки поза Gateway. Docker smoke-тест прив’язки ACP перевіряє вбудований бекенд середовища виконання `acpx` OpenClaw. +- Він виконує `source ~/.profile`, підготовлює відповідні auth-матеріали CLI у контейнері, а потім встановлює запитаний live CLI (`@anthropic-ai/claude-code`, `@openai/codex`, Factory Droid через `https://app.factory.ai/cli`, `@google/gemini-cli` або `opencode-ai`), якщо його бракує. Сам бекенд ACP — це пакет вбудованого runtime `acpx/runtime`, що постачається разом із Plugin `acpx`. +- Варіант Docker для Droid готує `~/.factory` для налаштувань, пересилає `FACTORY_API_KEY` і вимагає цей API-ключ, оскільки локальна Factory OAuth/keyring-auth не є переносною в контейнер. Він використовує вбудований запис реєстру ACPX `droid exec --output-format acp`. +- Варіант Docker для OpenCode — це суворий regression-lane для одного agent. Після виконання `source ~/.profile` він записує тимчасову типову модель `OPENCODE_CONFIG_CONTENT` із `OPENCLAW_LIVE_ACP_BIND_OPENCODE_MODEL` (типово `opencode/kimi-k2.6`), а `pnpm test:docker:live-acp-bind:opencode` вимагає transcript прив’язаного assistant замість прийняття загального post-bind skip. +- Прямі виклики CLI `acpx` — це лише ручний/обхідний шлях для порівняння поведінки поза Gateway. Docker ACP bind smoke-тест перевіряє вбудований у OpenClaw бекенд runtime `acpx`. -## Живі тести: smoke-тест стенда app-server Codex +## Live: smoke-тест harness app-server Codex -- Мета: перевірити плагіновий стенд Codex через звичайний метод gateway - `agent`: - - завантажити вбудований плагін `codex` +- Мета: перевірити harness Codex, яким володіє plugin, через звичайний + метод gateway `agent`: + - завантажити вбудований Plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - - надіслати перший хід gateway agent до `openai/gpt-5.2` із примусовим використанням стенда Codex - - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що тред - app-server можна продовжити + - надіслати перший хід gateway agent до `openai/gpt-5.2` із примусово вибраним harness Codex + - надіслати другий хід у той самий сеанс OpenClaw і перевірити, що thread app-server + може відновитися - виконати `/codex status` і `/codex models` через той самий шлях - команд gateway - - за потреби виконати дві перевірки оболонки з ескалацією, переглянуті Guardian: одну безпечну - команду, яку має бути схвалено, і одне фіктивне завантаження секрету, - яке має бути відхилено, щоб агент перепитав + команди gateway + - за потреби виконати дві escalated shell-перевірки, переглянуті Guardian: одну нешкідливу + команду, яку слід схвалити, і одну фальшиву передачу секрету, + яку слід відхилити, щоб agent перепитав - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` -- Модель за замовчуванням: `openai/gpt-5.2` +- Типова модель: `openai/gpt-5.2` - Необов’язкова перевірка зображення: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` - Необов’язкова перевірка MCP/tool: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` - Необов’язкова перевірка Guardian: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- Smoke-тест установлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний стенд Codex - не міг пройти перевірку через тихий перехід до PI. -- Автентифікація: автентифікація app-server Codex із локального входу за підпискою Codex. Docker - smoke-тести також можуть надавати `OPENAI_API_KEY` для перевірок, не пов’язаних із Codex, якщо це доречно, - а також необов’язково копіювати `~/.codex/auth.json` і `~/.codex/config.toml`. +- Smoke-тест встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний harness Codex + не міг пройти, непомітно переключившись на Pi. +- Auth: auth app-server Codex із локального логіну підписки Codex. Docker- + smoke-тести також можуть надавати `OPENAI_API_KEY` для перевірок, не пов’язаних із Codex, де це доречно, + а також необов’язкові скопійовані `~/.codex/auth.json` і `~/.codex/config.toml`. Локальний рецепт: @@ -325,73 +325,73 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker-runner розташований у `scripts/test-live-codex-harness-docker.sh`. -- Він виконує `source` для змонтованого `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - автентифікації CLI Codex, якщо вони є, встановлює `@openai/codex` у змонтований npm-префікс - із правом запису, готує дерево вихідного коду, а потім запускає лише живий тест стенда Codex. -- У Docker перевірки image, MCP/tool і Guardian увімкнено за замовчуванням. Установіть - `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або +- Docker-раннер розташований у `scripts/test-live-codex-harness-docker.sh`. +- Він виконує `source` змонтованого `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + auth CLI Codex, якщо вони є, встановлює `@openai/codex` у записуваний змонтований npm- + префікс, готує дерево вихідного коду, а потім запускає лише live-тест harness Codex. +- Docker за замовчуванням вмикає перевірки зображення, MCP/tool і Guardian. Встановіть + `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0`, `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` або - `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий налагоджувальний + `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли вам потрібен вужчий налагоджувальний запуск. -- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і конфігурація живого - тесту, щоб застарілі псевдоніми або резервний перехід до PI не могли приховати - регресію стенда Codex. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і в конфігурації live- + тесту, щоб застарілі псевдоніми або fallback до PI не могли приховати регресію + harness Codex. -### Рекомендовані рецепти живих тестів +### Рекомендовані live-рецепти -Вузькі, явні allowlist є найшвидшими та найменш схильними до нестабільності: +Вузькі, явні allowlist — найшвидші й найменш схильні до збоїв: - Одна модель, напряму (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts` -- Одна модель, smoke-тест gateway: +- Одна модель, gateway smoke-тест: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Виклик інструментів у кількох провайдерів: +- Виклик інструментів через кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Фокус на Google (API-ключ Gemini + Antigravity): - Gemini (API-ключ): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Smoke-тест адаптивного мислення Google: - - Якщо локальні ключі живуть у профілі оболонки: `source ~/.profile` - - Динамічне значення Gemini 3 за замовчуванням: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000` - - Динамічний бюджет Gemini 2.5: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000` +- Smoke-тест adaptive thinking Google: + - Якщо локальні ключі містяться в профілі shell: `source ~/.profile` + - Gemini 3 dynamic default: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000` + - Gemini 2.5 dynamic budget: `pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000` Примітки: - `google/...` використовує Gemini API (API-ключ). -- `google-antigravity/...` використовує міст Antigravity OAuth (ендпойнт агента у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний CLI Gemini на вашій машині (окрема автентифікація + особливості інструментів). +- `google-antigravity/...` використовує міст Antigravity OAuth (кінцева точка agent у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема auth + особливості tooling). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає розміщений Google Gemini API через HTTP (API-ключ / автентифікація профілю); це те, що більшість користувачів має на увазі під «Gemini». - - CLI: OpenClaw викликає локальний бінарний файл `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/підтримка інструментів/розсинхрон версій). + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (API-ключ / auth профілю); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw виконує локальний двійковий файл `gemini`; він має власну auth і може поводитися інакше (streaming/tool support/version skew). -## Живі тести: матриця моделей (що ми охоплюємо) +## Live: матриця моделей (що ми охоплюємо) -Немає фіксованого «списку моделей CI» (живі тести вмикаються за бажанням), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. +Фіксованого «списку моделей CI» немає (live вмикається за бажанням), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. -### Сучасний набір smoke-тестів (виклик інструментів + зображення) +### Сучасний smoke-набір (виклик інструментів + зображення) -Це запуск «поширених моделей», який ми очікуємо бачити працездатним: +Це запуск «поширених моделей», який, як ми очікуємо, має залишатися працездатним: - OpenAI (не Codex): `openai/gpt-5.2` - OpenAI Codex OAuth: `openai-codex/gpt-5.2` - 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) +- Google (Gemini API): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старих моделей Gemini 2.x) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` і `google-antigravity/gemini-3-flash` - DeepSeek: `deepseek/deepseek-v4-flash` і `deepseek/deepseek-v4-pro` - Z.AI (GLM): `zai/glm-5.1` - MiniMax: `minimax/MiniMax-M2.7` -Запуск smoke-тесту gateway з інструментами + зображенням: +Запустіть gateway smoke-тест з інструментами + зображенням: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,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,deepseek/deepseek-v4-flash,zai/glm-5.1,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` ### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) -Виберіть щонайменше по одній моделі на сімейство провайдерів: +Виберіть принаймні одну модель із кожної родини провайдерів: - OpenAI: `openai/gpt-5.2` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -400,81 +400,82 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-5.1` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (бажано мати): +Необов’язкове додаткове покриття (було б добре мати): -- xAI: `xai/grok-4` (або найновішу доступну) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою інструментів, яку у вас ввімкнено) +- xAI: `xai/grok-4` (або найновіша доступна) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яка у вас увімкнена) - Cerebras: `cerebras/`… (якщо у вас є доступ) - LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) ### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) -Додайте принаймні одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI з підтримкою vision тощо), щоб перевірити сценарій із зображенням. +Додайте принаймні одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI vision-capable variants тощо), щоб перевірити image probe. ### Агрегатори / альтернативні gateway -Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: +Якщо у вас є ввімкнені ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти відповідні кандидати з підтримкою інструментів і зображень) -- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) +- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Інші провайдери, яких можна включити до живої матриці (якщо у вас є облікові дані/конфігурація): +Більше провайдерів, які можна включити до live-матриці (якщо у вас є облікові дані/конфігурація): - Вбудовані: `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` (користувацькі ендпойнти): `minimax` (хмара/API), а також будь-який проксі, сумісний з OpenAI/Anthropic (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (custom endpoints): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) -Не задавайте в документації жорстко «всі моделі». Авторитетним списком є те, що повертає `discoverModels(...)` на вашій машині, плюс доступні ключі. +Не хардкодьте "all models" у документації. Авторитетний список — це все, що `discoverModels(...)` повертає на вашій машині, плюс усі доступні ключі. ## Облікові дані (ніколи не комітьте) -Живі тести виявляють облікові дані так само, як і CLI. Практичні наслідки: +Live-тести виявляють облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, живі тести мають знаходити ті самі ключі. -- Якщо живий тест повідомляє «no creds», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. +- Якщо CLI працює, live-тести мають знаходити ті самі ключі. +- Якщо live-тест повідомляє «немає облікових даних», налагоджуйте це так само, як ви налагоджували б `openclaw models list` / вибір моделі. -- Профілі автентифікації для окремих агентів: `~/.openclaw/agents//agent/auth-profiles.json` (саме це у живих тестах мається на увазі під «profile keys») +- Профілі auth для кожного agent: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «ключі профілю» в live-тестах) - Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Застарілий каталог стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але це не основне сховище profile keys) -- Локальні живі запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для окремих агентів, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасового домашнього каталогу тесту; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` і `agentDir` прибираються, щоб перевірки не торкалися вашого реального робочого простору хоста. +- Застарілий каталог стану: `~/.openclaw/credentials/` (копіюється в підготовлений live-home за наявності, але це не основне сховище ключів профілю) +- Локальні live-запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного agent, застарілий `credentials/` і підтримувані зовнішні каталоги auth CLI до тимчасового test-home; підготовлені live-home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб перевірки не торкалися вашого реального host-workspace. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-runner-и нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на ключі env (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-раннери нижче (вони можуть монтувати `~/.profile` у контейнер). -## Живі тести Deepgram (транскрипція аудіо) +## Deepgram live (транскрибування аудіо) - Тест: `extensions/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` -## Живі тести BytePlus coding plan +## BytePlus coding plan live - Тест: `extensions/byteplus/live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Живі тести медіа для workflow ComfyUI +## 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 для зображень, відео та `music_generate` - Пропускає кожну можливість, якщо не налаштовано `plugins.entries.comfy.config.` - - Корисно після змін у надсиланні workflow comfy, опитуванні, завантаженнях або реєстрації плагіна + - Корисно після змін у надсиланні workflow comfy, опитуванні, завантаженнях або реєстрації Plugin -## Живі тести генерації зображень +## Image generation live - Тест: `test/image-generation.runtime.live.test.ts` - Команда: `pnpm test:live test/image-generation.runtime.live.test.ts` -- Стенд: `pnpm test:live:media image` -- Область: - - Перелічує кожен зареєстрований плагін провайдера генерації зображень - - Завантажує відсутні env-змінні провайдерів із вашої login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує живі/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки - - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Проганяє кожного налаштованого провайдера через спільне runtime генерації зображень: +- Harness: `pnpm test:live:media image` +- Обсяг: + - Перелічує кожен зареєстрований Plugin-провайдер генерації зображень + - Завантажує відсутні env-змінні провайдера з вашої оболонки входу (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API-ключі перед збереженими профілями auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки + - Пропускає провайдерів без придатної auth/профілю/моделі + - Запускає кожен налаштований провайдер через спільний runtime генерації зображень: - `:generate` - - `:edit`, коли провайдер заявляє підтримку редагування -- Поточні вбудовані провайдери, що покриваються: + - `:edit`, коли провайдер оголошує підтримку редагування +- Поточні вбудовані провайдери, які покриваються: + - `deepinfra` - `fal` - `google` - `minimax` @@ -484,13 +485,14 @@ pnpm test:docker:live-codex-harness - `xai` - Необов’язкове звуження: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,openrouter,xai"` + - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="deepinfra"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"` -- Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише з env +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів та ігнорувати перевизначення лише через env -Для шляху shipped CLI додайте smoke-перевірку `infer` після того, як пройде живий -тест провайдера/runtime: +Для шляху shipped CLI додайте smoke-тест `infer` після успішного проходження live- +тесту провайдера/runtime: ```bash OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_INFER_CLI_TEST=1 pnpm test:live -- test/image-generation.infer-cli.live.test.ts @@ -502,77 +504,77 @@ openclaw infer image generate \ --json ``` -Це покриває парсинг аргументів CLI, визначення config/default-agent, активацію -вбудованого плагіна, відновлення залежностей вбудованого runtime на вимогу, спільний -runtime генерації зображень і живий запит до провайдера. +Це покриває розбір аргументів CLI, визначення config/default-agent, активацію +вбудованих Plugin, repair залежностей runtime вбудованих компонентів на вимогу, спільний +runtime генерації зображень і live-запит до провайдера. -## Живі тести генерації музики +## Music generation live - Тест: `extensions/music-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` -- Стенд: `pnpm test:live:media music` -- Область: - - Перевіряє спільний вбудований шлях провайдерів генерації музики +- Harness: `pnpm test:live:media music` +- Обсяг: + - Перевіряє спільний шлях вбудованого провайдера генерації музики - Наразі охоплює Google і MiniMax - - Завантажує env-змінні провайдерів із вашої login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує живі/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки - - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Запускає обидва заявлені режими runtime, коли вони доступні: - - `generate` з введенням лише prompt - - `edit`, коли провайдер заявляє `capabilities.edit.enabled` - - Поточне покриття спільного маршруту: + - Завантажує env-змінні провайдера з вашої оболонки входу (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API-ключі перед збереженими профілями auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки + - Пропускає провайдерів без придатної auth/профілю/моделі + - Запускає обидва оголошені режими runtime, коли вони доступні: + - `generate` із введенням лише prompt + - `edit`, коли провайдер оголошує `capabilities.edit.enabled` + - Поточне покриття спільного lane: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий живий файл Comfy, а не ця спільна перевірка + - `comfy`: окремий live-файл Comfy, а не ця спільна перевірка - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.6"` -- Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише з env +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів та ігнорувати перевизначення лише через env -## Живі тести генерації відео +## Video generation live - Тест: `extensions/video-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` -- Стенд: `pnpm test:live:media video` -- Область: - - Перевіряє спільний вбудований шлях провайдерів генерації відео - - За замовчуванням використовує безпечний для релізу маршрут smoke-тесту: провайдери без FAL, один запит text-to-video на провайдера, односекундний prompt про лобстера і ліміт операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) - - За замовчуванням пропускає FAL, оскільки затримка черги на боці провайдера може домінувати над часом релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб явно запустити його - - Завантажує env-змінні провайдерів із вашої login shell (`~/.profile`) перед перевіркою - - За замовчуванням використовує живі/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки - - Пропускає провайдерів без придатної автентифікації/профілю/моделі +- Harness: `pnpm test:live:media video` +- Обсяг: + - Перевіряє спільний шлях вбудованого провайдера генерації відео + - За замовчуванням використовує безпечний для релізу шлях smoke-тесту: провайдери без FAL, один запит text-to-video на провайдера, односекундний prompt про лобстера та обмеження операції для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) + - За замовчуванням пропускає FAL, оскільки затримка черги на боці провайдера може домінувати над часом релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб явно його запустити + - Завантажує env-змінні провайдера з вашої оболонки входу (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API-ключі перед збереженими профілями auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки + - Пропускає провайдерів без придатної auth/профілю/моделі - За замовчуванням запускає лише `generate` - - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати заявлені режими перетворення, коли вони доступні: - - `imageToVideo`, коли провайдер заявляє `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальне введення зображення на основі буфера в межах спільної перевірки - - `videoToVideo`, коли провайдер заявляє `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальне введення відео на основі буфера в межах спільної перевірки - - Поточні заявлені, але пропущені провайдери `imageToVideo` у спільній перевірці: - - `vydra`, тому що вбудований `veo3` працює лише з текстом, а вбудований `kling` вимагає віддалений URL зображення + - Встановіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими перетворення, коли вони доступні: + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід зображення з backing buffer у спільній перевірці + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід відео з backing buffer у спільній перевірці + - Поточні провайдери `imageToVideo`, оголошені, але пропущені в спільній перевірці: + - `vydra`, оскільки вбудований `veo3` підтримує лише text, а вбудований `kling` вимагає віддалену URL-адресу зображення - Покриття Vydra для конкретного провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс маршрут `kling`, який за замовчуванням використовує фікстуру віддаленого URL зображення - - Поточне живе покриття `videoToVideo`: + - цей файл запускає `veo3` text-to-video плюс lane `kling`, який за замовчуванням використовує fixture із віддаленою URL-адресою зображення + - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні заявлені, але пропущені провайдери `videoToVideo` у спільній перевірці: - - `alibaba`, `qwen`, `xai`, тому що ці шляхи зараз вимагають віддалені еталонні URL `http(s)` / MP4 - - `google`, тому що поточний спільний маршрут Gemini/Veo використовує локальне введення на основі буфера, і цей шлях не приймається у спільній перевірці - - `openai`, тому що поточний спільний маршрут не гарантує доступ до video inpaint/remix для конкретної org + - Поточні провайдери `videoToVideo`, оголошені, але пропущені в спільній перевірці: + - `alibaba`, `qwen`, `xai`, оскільки ці шляхи наразі вимагають віддалені довідкові URL `http(s)` / MP4 + - `google`, оскільки поточний спільний lane Gemini/Veo використовує локальний вхід із backing buffer, і цей шлях не приймається у спільній перевірці + - `openai`, оскільки поточний спільний lane не гарантує доступ до org-specific video inpaint/remix - Необов’язкове звуження: - - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` + - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="deepinfra,google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити до перевірки за замовчуванням кожного провайдера, включно з FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції для кожного провайдера в агресивному smoke-запуску -- Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише з env + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типової перевірки, включно з FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити обмеження операції кожного провайдера для агресивного smoke-запуску +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів та ігнорувати перевизначення лише через env -## Стенд живих медіатестів +## Harness для media live - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні живі набори тестів для зображень, музики та відео через єдиний нативний для репозиторію entrypoint - - Автоматично завантажує відсутні env-змінні провайдерів із `~/.profile` - - За замовчуванням автоматично звужує кожен набір тестів до провайдерів, які зараз мають придатну автентифікацію - - Повторно використовує `scripts/test-live.mjs`, тож Heartbeat і поведінка quiet mode залишаються узгодженими + - Запускає спільні live-набори для зображень, музики та відео через одну нативну для репозиторію точку входу + - Автоматично завантажує відсутні env-змінні провайдера з `~/.profile` + - Автоматично звужує кожен набір до провайдерів, які зараз мають придатну auth, за замовчуванням + - Повторно використовує `scripts/test-live.mjs`, тому поведінка Heartbeat і тихого режиму залишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -581,4 +583,4 @@ runtime генерації зображень і живий запит до пр ## Пов’язане -- [Testing](/uk/help/testing) — модульні, інтеграційні, QA- та Docker-набори тестів +- [Тестування](/uk/help/testing) — unit, integration, QA і Docker-набори тестів diff --git a/docs/uk/platforms/mac/peekaboo.md b/docs/uk/platforms/mac/peekaboo.md index 54897c4f9..b1b700c9b 100644 --- a/docs/uk/platforms/mac/peekaboo.md +++ b/docs/uk/platforms/mac/peekaboo.md @@ -3,71 +3,75 @@ read_when: - Розміщення PeekabooBridge у OpenClaw.app - Інтеграція Peekaboo через Swift Package Manager - Зміна протоколу/шляхів PeekabooBridge -summary: Інтеграція PeekabooBridge для автоматизації UI у macOS + - Вибір між PeekabooBridge, Codex Computer Use і cua-driver MCP +summary: Інтеграція PeekabooBridge для автоматизації інтерфейсу macOS title: Міст Peekaboo x-i18n: - generated_at: "2026-04-24T04:17:02Z" + generated_at: "2026-04-28T00:34:02Z" model: gpt-5.4 provider: openai - source_hash: 3646f66551645733292fb183e0ff2c56697e7b24248ff7c32a0dc925431f6ba7 + source_hash: 92effdd6cfe4002fff2b8cd1092999f837e93694acf110eaebd30648b0a6946e source_path: platforms/mac/peekaboo.md workflow: 15 --- -OpenClaw може розміщувати **PeekabooBridge** як локальний брокер автоматизації UI з урахуванням дозволів. Це дає змогу CLI `peekaboo` керувати автоматизацією UI, повторно використовуючи дозволи TCC застосунку macOS. +OpenClaw може розміщувати **PeekabooBridge** як локальний брокер автоматизації інтерфейсу з урахуванням дозволів. Це дає змогу CLI `peekaboo` керувати автоматизацією інтерфейсу, повторно використовуючи дозволи TCC macOS застосунку. -## Що це таке (і чим не є) +## Що це таке (і чим це не є) -- **Хост**: OpenClaw.app може виступати хостом PeekabooBridge. -- **Клієнт**: використовуйте CLI `peekaboo` (окремої поверхні `openclaw ui ...` немає). -- **UI**: візуальні накладки залишаються в Peekaboo.app; OpenClaw є тонким хостом-брокером. +- **Хост**: OpenClaw.app може діяти як хост PeekabooBridge. +- **Клієнт**: використовуйте CLI `peekaboo` (без окремої поверхні `openclaw ui ...`). +- **Інтерфейс**: візуальні накладки залишаються в Peekaboo.app; OpenClaw є тонким брокерським хостом. -## Увімкнення bridge +## Зв’язок із Computer Use + +OpenClaw має три шляхи керування робочим столом, і вони навмисно залишаються окремими: + +- **Хост PeekabooBridge**: OpenClaw.app може розміщувати локальний сокет PeekabooBridge. Клієнтом лишається CLI `peekaboo`, який використовує дозволи macOS OpenClaw.app для примітивів автоматизації Peekaboo, як-от знімки екрана, кліки, меню, діалоги, дії Dock і керування вікнами. +- **Codex Computer Use**: вбудований Plugin `codex` готує сервер застосунку Codex, перевіряє, що MCP-сервер `computer-use` Codex доступний, а потім дає Codex змогу керувати викликами вбудованих інструментів керування робочим столом під час ходів у режимі Codex. OpenClaw не проксіює ці дії через PeekabooBridge. +- **Прямий MCP `cua-driver`**: OpenClaw може зареєструвати висхідний сервер TryCua `cua-driver mcp` як звичайний MCP-сервер. Це надає агентам власні схеми драйвера CUA та його робочий процес pid/window/element-index без маршрутизації через маркетплейс Codex або сокет PeekabooBridge. + +Використовуйте Peekaboo, коли вам потрібна широка поверхня автоматизації macOS і хост-мост OpenClaw.app з урахуванням дозволів. Використовуйте Codex Computer Use, коли агент у режимі Codex має покладатися на вбудований Plugin computer-use від Codex. Використовуйте прямий `cua-driver mcp`, коли хочете, щоб драйвер CUA був доступний будь-якому середовищу виконання під керуванням OpenClaw як звичайний MCP-сервер. + +## Увімкнення моста У застосунку macOS: -- Settings → **Enable Peekaboo Bridge** +- Налаштування → **Увімкнути Peekaboo Bridge** -Коли bridge увімкнено, OpenClaw запускає локальний сервер UNIX socket. Якщо його вимкнено, хост -зупиняється, а `peekaboo` повертається до інших доступних хостів. +Коли цю опцію ввімкнено, OpenClaw запускає локальний сервер UNIX-сокета. Якщо її вимкнено, хост зупиняється, а `peekaboo` повертається до інших доступних хостів. ## Порядок виявлення клієнта Клієнти Peekaboo зазвичай пробують хости в такому порядку: -1. Peekaboo.app (повний UX) +1. Peekaboo.app (повноцінний UX) 2. Claude.app (якщо встановлено) 3. OpenClaw.app (тонкий брокер) -Використовуйте `peekaboo bridge status --verbose`, щоб побачити, який хост активний і який -шлях socket використовується. Ви можете перевизначити його так: +Скористайтеся `peekaboo bridge status --verbose`, щоб побачити, який хост активний і який шлях сокета використовується. Ви можете перевизначити це так: ```bash export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock ``` -## Безпека та дозволи +## Безпека й дозволи -- Bridge перевіряє **підписи коду клієнта**; застосовується allowlist TeamID - (TeamID хоста Peekaboo + TeamID застосунку OpenClaw). +- Міст перевіряє **підписи коду викликача**; застосовується список дозволених TeamID (TeamID хоста Peekaboo + TeamID застосунку OpenClaw). - Час очікування запитів спливає приблизно через 10 секунд. -- Якщо бракує потрібних дозволів, bridge повертає чітке повідомлення про помилку, - а не запускає System Settings. +- Якщо бракує потрібних дозволів, міст повертає чітке повідомлення про помилку замість запуску System Settings. -## Поведінка snapshot (автоматизація) +## Поведінка знімків (автоматизація) -Snapshot зберігаються в пам’яті й автоматично зникають через короткий час. +Знімки зберігаються в пам’яті та автоматично видаляються через короткий проміжок часу. Якщо вам потрібне довше зберігання, повторно захопіть їх із клієнта. -## Усунення несправностей +## Усунення проблем -- Якщо `peekaboo` повідомляє “bridge client is not authorized”, переконайтеся, що клієнт - належно підписано, або запускайте хост із `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` - лише в режимі **debug**. -- Якщо жодного хоста не знайдено, відкрийте один із хост-застосунків (Peekaboo.app або OpenClaw.app) - і підтвердьте, що дозволи надано. +- Якщо `peekaboo` повідомляє “bridge client is not authorized”, переконайтеся, що клієнт підписано належним чином, або запускайте хост із `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` лише в режимі **debug**. +- Якщо не знайдено жодного хоста, відкрийте один із хост-застосунків (Peekaboo.app або OpenClaw.app) і підтвердьте, що дозволи надано. ## Пов’язане -- [Застосунок для macOS](/uk/platforms/macos) +- [Застосунок macOS](/uk/platforms/macos) - [Дозволи macOS](/uk/platforms/mac/permissions) diff --git a/docs/uk/plugins/codex-computer-use.md b/docs/uk/plugins/codex-computer-use.md index 78b5c3730..6eb19b381 100644 --- a/docs/uk/plugins/codex-computer-use.md +++ b/docs/uk/plugins/codex-computer-use.md @@ -1,33 +1,78 @@ --- read_when: - Ви хочете, щоб агенти OpenClaw у режимі Codex використовували Codex Computer Use - - Ви налаштовуєте `computerUse` для вбудованого плагіна Codex - - Ви усуваєте неполадки зі станом або встановленням `/codex computer-use` + - Ви обираєте між Codex Computer Use, PeekabooBridge і прямим cua-driver MCP + - Ви обираєте між Codex Computer Use і прямим налаштуванням cua-driver MCP + - Ви налаштовуєте `computerUse` для вбудованого Plugin Codex + - Ви усуваєте проблеми зі статусом або встановленням `/codex computer-use` summary: Налаштуйте Codex Computer Use для агентів OpenClaw у режимі Codex title: Codex Computer Use x-i18n: - generated_at: "2026-04-27T23:44:58Z" + generated_at: "2026-04-28T00:34:01Z" model: gpt-5.4 provider: openai - source_hash: cc48252f6bc55a1aa9e10f5053d6daaa58787cabf9bcd45ce545a5c23e80e539 + source_hash: 93fe881b384f746137c8ded83d8736ec7d71ad4203aaa64d6b53ee6ef067022a source_path: plugins/codex-computer-use.md workflow: 15 --- -Computer Use — це власний для Codex MCP-плагін для локального керування робочим столом. OpenClaw -не постачає застосунок для робочого столу, не виконує дії на робочому столі самостійно і не обходить -дозволи Codex. Вбудований плагін `codex` лише готує app-server Codex: -він вмикає підтримку плагінів Codex, знаходить або встановлює налаштований плагін Codex +Computer Use — це нативний для Codex MCP Plugin для локального керування робочим столом. OpenClaw +не постачає застосунок для робочого столу, не виконує дії на робочому столі самостійно й не обходить +дозволи Codex. Вбудований Plugin `codex` лише готує app-server Codex: +він вмикає підтримку Plugin Codex, знаходить або встановлює налаштований Plugin Codex Computer Use, перевіряє, що MCP-сервер `computer-use` доступний, а -потім дозволяє Codex керувати власними викликами інструментів MCP під час ходів у режимі Codex. +потім дозволяє Codex керувати нативними викликами інструментів MCP під час ходів у режимі Codex. -Використовуйте цю сторінку, коли OpenClaw уже використовує нативний harness Codex. Щодо -самого налаштування середовища виконання див. [harness Codex](/uk/plugins/codex-harness). +Використовуйте цю сторінку, коли OpenClaw уже використовує нативний harness Codex. Для +налаштування самого середовища виконання див. [harness Codex](/uk/plugins/codex-harness). + +## OpenClaw.app і Peekaboo + +Інтеграція Peekaboo в OpenClaw.app є окремою від Codex Computer Use. Застосунок +macOS може розміщувати сокет PeekabooBridge, щоб CLI `peekaboo` міг повторно +використовувати локальні дозволи Accessibility і Screen Recording застосунку для +власних інструментів автоматизації Peekaboo. Цей міст не встановлює й не проксіює Codex Computer Use, а +Codex Computer Use не викликає інструменти через сокет PeekabooBridge. + +Використовуйте [міст Peekaboo](/uk/platforms/mac/peekaboo), коли хочете, щоб OpenClaw.app був +хостом із урахуванням дозволів для автоматизації через CLI Peekaboo. Використовуйте цю сторінку, коли агент OpenClaw +у режимі Codex повинен мати доступний нативний MCP Plugin `computer-use` Codex +до початку ходу. + +## Прямий cua-driver MCP + +Codex Computer Use — не єдиний спосіб надати керування робочим столом. Якщо ви хочете, щоб +середовища виконання під керуванням OpenClaw викликали драйвер TryCua безпосередньо, використовуйте +висхідний сервер `cua-driver mcp` через реєстр MCP OpenClaw замість +специфічного для Codex потоку marketplace. + +Після встановлення `cua-driver` або попросіть його надати команду для OpenClaw: + +```bash +cua-driver mcp-config --client openclaw +``` + +або зареєструйте stdio-сервер самостійно: + +```bash +openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}' +``` + +Цей шлях зберігає поверхню інструментів висхідного MCP без змін, включно зі схемами +драйвера та структурованими відповідями MCP. Використовуйте його, коли хочете, щоб драйвер CUA +був доступний як звичайний MCP-сервер OpenClaw. Використовуйте налаштування Codex Computer Use на +цій сторінці, коли app-server Codex повинен керувати встановленням Plugin, перезавантаженнями MCP +і нативними викликами інструментів у межах ходів у режимі Codex. + +Драйвер CUA є специфічним для macOS і все одно потребує локальних дозволів macOS, +які запитує його застосунок, наприклад Accessibility і Screen Recording. OpenClaw +не встановлює `cua-driver`, не надає ці дозволи й не обходить модель безпеки +висхідного драйвера. ## Швидке налаштування -Установіть `plugins.entries.codex.config.computerUse`, якщо для ходів у режимі Codex -Computer Use має бути доступний до початку потоку: +Встановіть `plugins.entries.codex.config.computerUse`, якщо ходи в режимі Codex повинні мати +доступний Computer Use до початку треду: ```json5 { @@ -55,25 +100,25 @@ Computer Use має бути доступний до початку потоку } ``` -За такої конфігурації OpenClaw перевіряє app-server Codex перед кожним ходом у режимі Codex. +Із цією конфігурацією OpenClaw перевіряє app-server Codex перед кожним ходом у режимі Codex. Якщо Computer Use відсутній, але app-server Codex уже виявив -маркетплейс, доступний для встановлення, OpenClaw просить app-server Codex встановити або знову ввімкнути -плагін і перезавантажити MCP-сервери. У macOS, коли не зареєстровано -відповідного маркетплейсу і стандартний пакет застосунку Codex існує, OpenClaw також намагається -зареєструвати вбудований маркетплейс Codex із +marketplace, доступний для встановлення, OpenClaw просить app-server Codex встановити або знову ввімкнути +Plugin і перезавантажити MCP-сервери. На macOS, коли не зареєстровано відповідного marketplace +і існує стандартний bundle застосунку Codex, OpenClaw також намагається +зареєструвати вбудований marketplace Codex із `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled`, перш ніж -завершити роботу з помилкою. Якщо після налаштування MCP-сервер усе ще недоступний, -хід завершується помилкою ще до початку потоку. +завершити з помилкою. Якщо після налаштування MCP-сервер усе ще не стає доступним, +хід завершується помилкою до початку треду. -Наявні сеанси зберігають своє середовище виконання та прив’язку до потоку Codex. Після зміни -`agentRuntime` або конфігурації Computer Use використайте `/new` або `/reset` у відповідному -чаті перед перевіркою. +Наявні сесії зберігають своє середовище виконання та прив’язку до треду Codex. Після зміни +`agentRuntime` або конфігурації Computer Use використайте `/new` або `/reset` у +відповідному чаті перед тестуванням. ## Команди Використовуйте команди `/codex computer-use` з будь-якої поверхні чату, де доступна -поверхня команд плагіна `codex`. Це команди чату/середовища виконання OpenClaw, -а не підкоманди CLI `openclaw codex ...`: +поверхня команд Plugin `codex`. Це команди чату/середовища виконання OpenClaw, а не +підкоманди CLI `openclaw codex ...`: ```text /codex computer-use status @@ -83,44 +128,44 @@ Computer Use має бути доступний до початку потоку /codex computer-use install --marketplace ``` -`status` — лише для читання. Він не додає джерела маркетплейсу, не встановлює плагіни й -не вмикає підтримку плагінів Codex. +`status` — лише для читання. Він не додає джерела marketplace, не встановлює Plugin +і не вмикає підтримку Plugin Codex. -`install` вмикає підтримку плагінів в app-server Codex, за потреби додає налаштоване -джерело маркетплейсу, встановлює або знову вмикає налаштований плагін через Codex -app-server, перезавантажує MCP-сервери й перевіряє, що MCP-сервер надає інструменти. +`install` вмикає підтримку Plugin в app-server Codex, за потреби додає налаштоване +джерело marketplace, встановлює або знову вмикає налаштований Plugin через app-server Codex, +перезавантажує MCP-сервери й перевіряє, що MCP-сервер надає інструменти. -## Варіанти маркетплейсу +## Варіанти marketplace OpenClaw використовує той самий API app-server, який надає сам Codex. Поля -маркетплейсу визначають, де Codex має шукати `computer-use`. +marketplace визначають, де Codex повинен шукати `computer-use`. -| Поле | Використовуйте, коли | Підтримка встановлення | -| -------------------- | ------------------------------------------------------------- | ---------------------------------------------------- | -| Без поля marketplace | Ви хочете, щоб app-server Codex використовував уже відомі йому маркетплейси. | Так, якщо app-server повертає локальний маркетплейс. | -| `marketplaceSource` | У вас є джерело маркетплейсу Codex, яке app-server може додати. | Так, для явного `/codex computer-use install`. | -| `marketplacePath` | Ви вже знаєте шлях до локального файла маркетплейсу на хості. | Так, для явного встановлення та autoInstall на початку ходу. | -| `marketplaceName` | Ви хочете вибрати вже зареєстрований маркетплейс за назвою. | Так, лише якщо вибраний маркетплейс має локальний шлях. | +| Field | Use when | Install support | +| -------------------- | --------------------------------------------------------------- | -------------------------------------------------------- | +| Без поля marketplace | Ви хочете, щоб app-server Codex використовував marketplace, які він уже знає. | Так, коли app-server повертає локальний marketplace. | +| `marketplaceSource` | У вас є джерело marketplace Codex, яке app-server може додати. | Так, для явного `/codex computer-use install`. | +| `marketplacePath` | Ви вже знаєте шлях до локального файла marketplace на хості. | Так, для явного встановлення й autoInstall на старті ходу. | +| `marketplaceName` | Ви хочете вибрати вже зареєстрований marketplace за назвою. | Так, лише коли вибраний marketplace має локальний шлях. | -Новим домашнім каталогам Codex може знадобитися трохи часу, щоб ініціалізувати офіційні -маркетплейси. Під час встановлення OpenClaw опитує `plugin/list` протягом -`marketplaceDiscoveryTimeoutMs` мілісекунд. Значення за замовчуванням — 60 секунд. +Новим home-каталогам Codex може знадобитися трохи часу, щоб заповнити офіційні +marketplace. Під час встановлення OpenClaw опитує `plugin/list` протягом +`marketplaceDiscoveryTimeoutMs` мілісекунд. Типове значення — 60 секунд. -Якщо Computer Use міститься в кількох відомих маркетплейсах, OpenClaw надає перевагу +Якщо кілька відомих marketplace містять Computer Use, OpenClaw надає перевагу `openai-bundled`, потім `openai-curated`, потім `local`. Невідомі неоднозначні збіги -завершуються безпечною відмовою і пропонують вам установити `marketplaceName` або `marketplacePath`. +завершуються в закритому стані й пропонують установити `marketplaceName` або `marketplacePath`. -## Вбудований маркетплейс macOS +## Вбудований marketplace macOS -У нещодавніх збірках Codex для робочого столу Computer Use постачається тут: +У свіжих збірках Codex для робочого столу Computer Use постачається тут: ```text /Applications/Codex.app/Contents/Resources/plugins/openai-bundled/plugins/computer-use ``` -Коли `computerUse.autoInstall` має значення true і жоден маркетплейс, що містить -`computer-use`, не зареєстрований, OpenClaw намагається автоматично додати стандартний -корінь вбудованого маркетплейсу: +Коли `computerUse.autoInstall` має значення true і не зареєстровано жодного marketplace, що містить +`computer-use`, OpenClaw намагається автоматично додати стандартний кореневий +вбудований marketplace: ```text /Applications/Codex.app/Contents/Resources/plugins/openai-bundled @@ -133,17 +178,17 @@ codex plugin marketplace add /Applications/Codex.app/Contents/Resources/plugins/ ``` Якщо ви використовуєте нестандартний шлях до застосунку Codex, установіть `computerUse.marketplacePath` на -шлях до локального файла маркетплейсу або один раз виконайте `/codex computer-use install --source +шлях до локального файла marketplace або один раз виконайте `/codex computer-use install --source `. ## Обмеження віддаленого каталогу -app-server Codex може перелічувати й читати записи каталогу, доступні лише віддалено, але наразі -не підтримує віддалений `plugin/install`. Це означає, що `marketplaceName` може -вибрати маркетплейс, доступний лише віддалено, для перевірок стану, але для встановлення й повторного ввімкнення -усе одно потрібен локальний маркетплейс через `marketplaceSource` або `marketplacePath`. +app-server Codex може перелічувати та читати записи каталогу, доступні лише віддалено, але +наразі не підтримує віддалений `plugin/install`. Це означає, що `marketplaceName` може +вибрати marketplace, доступний лише віддалено, для перевірок статусу, але встановлення й повторне ввімкнення +усе ще потребують локального marketplace через `marketplaceSource` або `marketplacePath`. -Якщо стан показує, що плагін доступний у віддаленому маркетплейсі Codex, але віддалене +Якщо статус повідомляє, що Plugin доступний у віддаленому marketplace Codex, але віддалене встановлення не підтримується, виконайте встановлення з локальним джерелом або шляхом: ```text @@ -153,88 +198,88 @@ app-server Codex може перелічувати й читати записи ## Довідник конфігурації -| Поле | За замовчуванням | Значення | -| ------------------------------- | ---------------- | ---------------------------------------------------------------------------- | -| `enabled` | виводиться | Вимагати Computer Use. За замовчуванням дорівнює true, коли встановлено інше поле Computer Use. | -| `autoInstall` | false | Встановити або знову ввімкнути з уже виявлених маркетплейсів на початку ходу. | -| `marketplaceDiscoveryTimeoutMs` | 60000 | Скільки часу встановлення чекає на виявлення маркетплейсу app-server Codex. | -| `marketplaceSource` | не встановлено | Рядок джерела, переданий у `marketplace/add` app-server Codex. | -| `marketplacePath` | не встановлено | Шлях до локального файла маркетплейсу Codex, що містить плагін. | -| `marketplaceName` | не встановлено | Назва зареєстрованого маркетплейсу Codex для вибору. | -| `pluginName` | `computer-use` | Назва плагіна маркетплейсу Codex. | -| `mcpServerName` | `computer-use` | Назва MCP-сервера, який надає встановлений плагін. | +| Field | Default | Meaning | +| ------------------------------- | -------------- | ------------------------------------------------------------------------------ | +| `enabled` | inferred | Вимагати Computer Use. Типово дорівнює true, коли встановлено інше поле Computer Use. | +| `autoInstall` | false | Встановити або знову ввімкнути з уже виявлених marketplace на старті ходу. | +| `marketplaceDiscoveryTimeoutMs` | 60000 | Скільки часу встановлення чекає на виявлення marketplace app-server Codex. | +| `marketplaceSource` | unset | Рядок джерела, переданий у `marketplace/add` app-server Codex. | +| `marketplacePath` | unset | Шлях до локального файла marketplace Codex, що містить Plugin. | +| `marketplaceName` | unset | Назва зареєстрованого marketplace Codex для вибору. | +| `pluginName` | `computer-use` | Назва Plugin marketplace Codex. | +| `mcpServerName` | `computer-use` | Назва MCP-сервера, яку надає встановлений Plugin. | -AutoInstall на початку ходу навмисно відхиляє налаштовані значення -`marketplaceSource`. Додавання нового джерела — це явна операція налаштування, тож -один раз використайте `/codex computer-use install --source `, а потім -дозвольте `autoInstall` обробляти майбутні повторні ввімкнення з виявлених локальних маркетплейсів. -AutoInstall на початку ходу може використовувати налаштований `marketplacePath`, оскільки це +AutoInstall на старті ходу навмисно відхиляє налаштовані значення +`marketplaceSource`. Додавання нового джерела — це явна операція налаштування, тож один раз використайте +`/codex computer-use install --source `, а потім дозвольте +`autoInstall` виконувати майбутні повторні ввімкнення з виявлених локальних marketplace. +AutoInstall на старті ходу може використовувати налаштований `marketplacePath`, оскільки це вже локальний шлях на хості. ## Що перевіряє OpenClaw OpenClaw внутрішньо повідомляє стабільну причину стану налаштування й форматує -користувацький статус для чату: +статус, видимий користувачу, для чату: -| Причина | Значення | Наступний крок | -| ---------------------------- | ---------------------------------------------------- | ----------------------------------------------- | -| `disabled` | `computerUse.enabled` розгорнулося в false. | Установіть `enabled` або інше поле Computer Use. | -| `marketplace_missing` | Відповідний маркетплейс був недоступний. | Налаштуйте джерело, шлях або назву маркетплейсу. | -| `plugin_not_installed` | Маркетплейс існує, але плагін не встановлено. | Виконайте install або ввімкніть `autoInstall`. | -| `plugin_disabled` | Плагін установлено, але вимкнено в конфігурації Codex. | Виконайте install, щоб знову його ввімкнути. | -| `remote_install_unsupported` | Вибраний маркетплейс доступний лише віддалено. | Використайте `marketplaceSource` або `marketplacePath`. | -| `mcp_missing` | Плагін увімкнено, але MCP-сервер недоступний. | Перевірте Codex Computer Use і дозволи ОС. | -| `ready` | Плагін та інструменти MCP доступні. | Почніть хід у режимі Codex. | -| `check_failed` | Під час перевірки стану не вдалося виконати запит до app-server Codex. | Перевірте підключення до app-server і журнали. | -| `auto_install_blocked` | Налаштування на початку ходу потребувало б додавання нового джерела. | Спочатку виконайте явне встановлення. | +| Reason | Meaning | Next step | +| ---------------------------- | ------------------------------------------------------ | --------------------------------------------- | +| `disabled` | `computerUse.enabled` визначено як false. | Установіть `enabled` або інше поле Computer Use. | +| `marketplace_missing` | Не було доступно відповідного marketplace. | Налаштуйте source, path або назву marketplace. | +| `plugin_not_installed` | Marketplace існує, але Plugin не встановлено. | Виконайте install або ввімкніть `autoInstall`. | +| `plugin_disabled` | Plugin встановлено, але вимкнено в конфігурації Codex. | Виконайте install, щоб знову ввімкнути його. | +| `remote_install_unsupported` | Вибраний marketplace доступний лише віддалено. | Використайте `marketplaceSource` або `marketplacePath`. | +| `mcp_missing` | Plugin увімкнено, але MCP-сервер недоступний. | Перевірте Codex Computer Use і дозволи ОС. | +| `ready` | Plugin та інструменти MCP доступні. | Почніть хід у режимі Codex. | +| `check_failed` | Запит app-server Codex завершився помилкою під час перевірки статусу. | Перевірте з’єднання з app-server і журнали. | +| `auto_install_blocked` | Налаштування на старті ходу потребувало б додавання нового джерела. | Спочатку виконайте явне install. | -Вивід у чаті містить стан плагіна, стан MCP-сервера, маркетплейс, інструменти -за наявності, а також конкретне повідомлення для кроку налаштування, що завершився помилкою. +Вивід у чаті містить стан Plugin, стан MCP-сервера, marketplace, інструменти +за наявності та конкретне повідомлення для кроку налаштування, який завершився помилкою. ## Дозволи macOS -Computer Use призначений лише для macOS. MCP-сервер під керуванням Codex може потребувати локальних +Computer Use є специфічним для macOS. MCP-сервер, яким керує Codex, може потребувати локальних дозволів ОС, перш ніж зможе перевіряти або керувати застосунками. Якщо OpenClaw повідомляє, що Computer Use -установлено, але MCP-сервер недоступний, спочатку перевірте налаштування Computer -Use на боці Codex: +встановлено, але MCP-сервер недоступний, спочатку перевірте налаштування +Computer Use на боці Codex: -- app-server Codex працює на тому самому хості, де має відбуватися керування робочим столом. -- Плагін Computer Use увімкнено в конфігурації Codex. -- MCP-сервер `computer-use` з’являється в стані MCP app-server Codex. -- macOS надала необхідні дозволи для застосунку керування робочим столом. -- Поточний сеанс хоста має доступ до робочого столу, яким керують. +- app-server Codex запущено на тому самому хості, де має відбуватися + керування робочим столом. +- Plugin Computer Use увімкнено в конфігурації Codex. +- MCP-сервер `computer-use` відображається у статусі MCP app-server Codex. +- macOS надала потрібні дозволи для застосунку керування робочим столом. +- Поточна сесія хоста має доступ до робочого столу, яким виконується керування. -OpenClaw навмисно безпечно завершує роботу з помилкою, коли `computerUse.enabled` має значення true. Хід +OpenClaw навмисно завершує роботу в закритому стані, коли `computerUse.enabled` має значення true. Хід у режимі Codex не повинен непомітно продовжуватися без нативних інструментів робочого столу, які вимагала конфігурація. -## Усунення неполадок +## Усунення проблем -**Стан показує, що не встановлено.** Виконайте `/codex computer-use install`. Якщо -маркетплейс не виявлено, передайте `--source` або `--marketplace-path`. +**Статус повідомляє, що не встановлено.** Виконайте `/codex computer-use install`. Якщо +marketplace не виявлено, передайте `--source` або `--marketplace-path`. -**Стан показує, що встановлено, але вимкнено.** Знову виконайте `/codex computer-use install`. -Встановлення через app-server Codex знову записує конфігурацію плагіна як увімкнену. +**Статус повідомляє, що встановлено, але вимкнено.** Знову виконайте `/codex computer-use install`. +Встановлення через app-server Codex знову записує конфігурацію Plugin у стан enabled. -**Стан показує, що віддалене встановлення не підтримується.** Використайте локальне джерело маркетплейсу або -шлях. Записи каталогу, доступні лише віддалено, можна перевіряти, але не можна встановлювати через +**Статус повідомляє, що віддалене встановлення не підтримується.** Використайте локальне джерело marketplace або +шлях. Записи каталогу, доступні лише віддалено, можна переглядати, але не можна встановлювати через поточний API app-server. -**Стан показує, що MCP-сервер недоступний.** Повторно виконайте встановлення один раз, щоб -MCP-сервери перезавантажилися. Якщо він і далі недоступний, виправте застосунок Codex Computer Use, -стан MCP app-server Codex або дозволи macOS. +**Статус повідомляє, що MCP-сервер недоступний.** Один раз повторно виконайте встановлення, щоб +MCP-сервери перезавантажилися. Якщо він усе ще недоступний, виправте застосунок Codex Computer Use, +статус MCP app-server Codex або дозволи macOS. -**Стан або перевірка перевищують час очікування на `computer-use.list_apps`.** Плагін і MCP- -сервер наявні, але локальний міст Computer Use не відповів. Закрийте або -перезапустіть Codex Computer Use, за потреби повторно запустіть Codex Desktop, а потім спробуйте знову в -новому сеансі OpenClaw. +**Статус або перевірка зависає за тайм-аутом на `computer-use.list_apps`.** Plugin і MCP- +сервер присутні, але локальний міст Computer Use не відповів. Завершіть роботу або перезапустіть Codex Computer Use, +за потреби перезапустіть Codex Desktop, а потім повторіть спробу в новій сесії OpenClaw. **Інструмент Computer Use повідомляє `Native hook relay unavailable`.** Нативний для Codex -перехоплювач інструментів звернувся до OpenClaw із застарілою або відсутньою реєстрацією relay. Почніть -новий сеанс OpenClaw за допомогою `/new` або `/reset`. Якщо це продовжує траплятися, перезапустіть -Gateway, щоб скинути старі потоки app-server і реєстрації перехоплювачів, а потім спробуйте ще раз. +hook інструмента дістався OpenClaw із застарілою або відсутньою реєстрацією relay. Почніть +нову сесію OpenClaw за допомогою `/new` або `/reset`. Якщо це продовжує траплятися, перезапустіть +gateway, щоб скинути старі треди app-server і реєстрації hook, а потім повторіть спробу. -**AutoInstall на початку ходу відхиляє джерело.** Це навмисно. Спочатку додайте -джерело явною командою `/codex computer-use install --source `, -а потім у майбутньому autoInstall на початку ходу зможе використовувати виявлений локальний -маркетплейс. +**Автовстановлення на старті ходу відхиляє source.** Це навмисно. Спочатку додайте +source явною командою `/codex computer-use install --source `, +а потім у майбутньому автовстановлення на старті ходу зможе використовувати виявлений локальний +marketplace. diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index 5a932012a..3b58e18ee 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -1,58 +1,58 @@ --- read_when: - - Ви хочете використовувати вбудований app-server harness Codex + - Ви хочете використовувати комплектний app-server harness Codex - Вам потрібні приклади конфігурації harness Codex - - Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість переходу на Pi -summary: Запускайте ходи вбудованого агента OpenClaw через вбудований app-server harness Codex + - Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість переходу до Pi +summary: Запускайте вбудовані ходи агента OpenClaw через комплектний app-server harness Codex title: harness Codex x-i18n: - generated_at: "2026-04-28T00:03:45Z" + generated_at: "2026-04-28T00:34:04Z" model: gpt-5.4 provider: openai - source_hash: c048ff928fb0b601b6a75631f9e33bbf23d08d1c21ad762b22ac3fb182d862ff + source_hash: 4275f06cfaba2cc1f3f03204993c5c8678939979f734aca08b8053bbc14d7d8f source_path: plugins/codex-harness.md workflow: 15 --- -Вбудований Plugin `codex` дає OpenClaw змогу запускати ходи вбудованого агента через app-server Codex замість вбудованого harness PI. +Комплектний Plugin `codex` дає OpenClaw змогу запускати вбудовані ходи агента через Codex app-server замість вбудованого harness Pi. -Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням моделей, нативним відновленням потоку, нативною Compaction та виконанням через app-server. -OpenClaw і далі керує чат-каналами, файлами сесій, вибором моделей, інструментами, -погодженнями, доставкою медіа та видимим дзеркалом транскрипту. +Використовуйте це, коли ви хочете, щоб Codex керував низькорівневою сесією агента: виявленням моделей, нативним відновленням потоку, нативною Compaction і виконанням через app-server. +OpenClaw, як і раніше, керує каналами чату, файлами сесій, вибором моделей, інструментами, погодженнями, доставкою медіа та видимим дзеркалом транскрипту. -Якщо ви лише починаєте орієнтуватися, почніть із -[Середовища виконання агентів](/uk/concepts/agent-runtimes). Коротко: +Якщо ви намагаєтеся зорієнтуватися, почніть із +[Середовища виконання агентів](/uk/concepts/agent-runtimes). Коротка версія така: `openai/gpt-5.5` — це посилання на модель, `codex` — це середовище виконання, а Telegram, -Discord, Slack або інший канал лишається поверхнею комунікації. +Discord, Slack або інший канал залишається поверхнею комунікації. ## Що змінює цей Plugin -Вбудований Plugin `codex` додає кілька окремих можливостей: +Комплектний Plugin `codex` додає кілька окремих можливостей: -| Можливість | Як її використовувати | Що вона робить | -| -------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- | -| Нативне вбудоване середовище виконання | `agentRuntime.id: "codex"` | Запускає ходи вбудованого агента OpenClaw через app-server Codex. | -| Нативні команди керування чатом | `/codex bind`, `/codex resume`, `/codex steer`, ... | Прив’язує та керує потоками app-server Codex із розмови в месенджері. | -| Провайдер/каталог app-server Codex | внутрішні частини `codex`, доступні через harness | Дозволяє середовищу виконання виявляти та перевіряти моделі app-server. | -| Шлях розуміння медіа Codex | шляхи сумісності моделей зображень `codex/*` | Запускає обмежені ходи app-server Codex для підтримуваних моделей розуміння зображень. | -| Нативна ретрансляція хуків | Хуки Plugin навколо нативних подій Codex | Дозволяє OpenClaw спостерігати/блокувати підтримувані нативні події інструментів/завершення Codex. | +| Можливість | Як це використовувати | Що це робить | +| ------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------- | +| Нативне вбудоване середовище виконання | `agentRuntime.id: "codex"` | Запускає вбудовані ходи агента OpenClaw через Codex app-server. | +| Нативні команди керування чатом | `/codex bind`, `/codex resume`, `/codex steer`, ... | Прив’язує та керує потоками Codex app-server із розмови в месенджері. | +| Провайдер/каталог Codex app-server | внутрішні компоненти `codex`, доступні через harness | Дає середовищу виконання змогу виявляти та перевіряти моделі app-server. | +| Шлях розуміння медіа в Codex | шляхи сумісності моделей зображень `codex/*` | Запускає обмежені ходи Codex app-server для підтримуваних моделей розуміння зображень. | +| Нативна ретрансляція hook | hooks Plugin навколо нативних подій Codex | Дає OpenClaw змогу спостерігати/блокувати підтримувані нативні події інструментів/завершення Codex. | Увімкнення Plugin робить ці можливості доступними. Воно **не**: - не починає використовувати Codex для кожної моделі OpenAI - не перетворює посилання на моделі `openai-codex/*` на нативне середовище виконання -- не робить ACP/acpx типовим шляхом для Codex -- не перемикає на ходу наявні сесії, у яких уже зафіксовано середовище виконання PI -- не замінює доставку каналів OpenClaw, файли сесій, сховище auth-profile або +- не робить ACP/acpx типовим шляхом Codex +- не перемикає на льоту наявні сесії, у яких уже зафіксоване середовище виконання Pi +- не замінює доставку каналів OpenClaw, файли сесій, сховище auth profile або маршрутизацію повідомлень -Цей самий Plugin також володіє нативною поверхнею команд керування чатом `/codex`. Якщо -Plugin увімкнено і користувач просить прив’язати, відновити, спрямувати, зупинити або перевірити -потоки Codex із чату, агенти мають надавати перевагу `/codex ...` замість ACP. ACP лишається -явним резервним варіантом, коли користувач просить ACP/acpx або тестує адаптер ACP Codex. +Той самий Plugin також володіє нативною поверхнею команд керування чатом `/codex`. Якщо +Plugin увімкнений і користувач просить прив’язати, відновити, спрямувати, зупинити або перевірити +потоки Codex із чату, агенти мають віддавати перевагу `/codex ...`, а не ACP. ACP залишається +явним резервним варіантом, коли користувач просить ACP/acpx або тестує адаптер ACP +Codex. -Нативні ходи Codex зберігають хуки Plugin OpenClaw як публічний шар сумісності. -Це внутрішньопроцесні хуки OpenClaw, а не командні хуки Codex `hooks.json`: +Нативні ходи Codex зберігають hooks Plugin OpenClaw як публічний рівень сумісності. +Це внутрішньопроцесні hooks OpenClaw, а не командні hooks Codex `hooks.json`: - `before_prompt_build` - `before_compaction`, `after_compaction` @@ -62,129 +62,134 @@ Plugin увімкнено і користувач просить прив’яз - `before_agent_finalize` через ретрансляцію Codex `Stop` - `agent_end` -Plugins також можуть реєструвати нейтральне до середовища виконання middleware результатів інструментів, щоб переписувати динамічні результати інструментів OpenClaw після того, як OpenClaw виконає інструмент, і до того, як результат буде повернено до Codex. Це окремо від публічного хука Plugin +Plugins також можуть реєструвати нейтральне до середовища виконання middleware результатів інструментів, щоб переписувати динамічні результати інструментів OpenClaw після того, як OpenClaw виконає інструмент, і до того, як результат буде повернуто в Codex. Це окремо від публічного hook Plugin `tool_result_persist`, який перетворює записи результатів інструментів у транскрипті, якими володіє OpenClaw. -Про семантику самих хуків Plugin дивіться [Хуки Plugin](/uk/plugins/hooks) -та [Поведінка guard у Plugin](/uk/tools/plugin). +Про саму семантику hooks Plugin див. [Hooks Plugin](/uk/plugins/hooks) +і [Поведінка guard Plugin](/uk/tools/plugin). -Harness вимкнений типово. У нових конфігураціях слід зберігати канонічні -посилання на моделі OpenAI як `openai/gpt-*` і явно примусово вказувати +За замовчуванням harness вимкнено. У нових конфігураціях слід зберігати посилання на моделі OpenAI +канонічними як `openai/gpt-*` і явно примусово задавати `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли -потрібне нативне виконання через app-server. Устарілі посилання на моделі `codex/*` усе ще автоматично вибирають -harness для сумісності, але усталені префікси провайдерів, підкріплені середовищем виконання, не показуються як звичайні варіанти моделей/провайдерів. +потрібне нативне виконання через app-server. Застарілі посилання на моделі `codex/*`, як і раніше, автоматично вибирають +harness для сумісності, але застарілі префікси провайдера, підтримані середовищем виконання, +не показуються як звичайні варіанти моделі/провайдера. -Якщо Plugin `codex` увімкнено, але основна модель усе ще +Якщо Plugin `codex` увімкнений, але основна модель усе ще `openai-codex/*`, `openclaw doctor` показує попередження замість зміни маршруту. Це -навмисно: `openai-codex/*` лишається шляхом OAuth/підписки PI Codex, а -нативне виконання через app-server лишається явним вибором середовища виконання. +зроблено навмисно: `openai-codex/*` залишається шляхом OAuth/підписки PI Codex, а +нативне виконання через app-server залишається явним вибором середовища виконання. -## Карта маршрутів +## Мапа маршрутів -Скористайтеся цією таблицею перед зміною конфігурації: +Використовуйте цю таблицю перед зміною конфігурації: -| Бажана поведінка | Посилання на модель | Конфігурація середовища виконання | Вимога до Plugin | Очікувана мітка стану | -| ------------------------------------------ | -------------------------- | -------------------------------------- | -------------------------- | ----------------------------- | -| API OpenAI через звичайний раннер OpenClaw | `openai/gpt-*` | пропущено або `runtime: "pi"` | Провайдер OpenAI | `Runtime: OpenClaw Pi Default` | -| OAuth/підписка Codex через PI | `openai-codex/gpt-*` | пропущено або `runtime: "pi"` | Провайдер OpenAI Codex OAuth | `Runtime: OpenClaw Pi Default` | -| Нативні вбудовані ходи app-server Codex | `openai/gpt-*` | `agentRuntime.id: "codex"` | Plugin `codex` | `Runtime: OpenAI Codex` | -| Змішані провайдери з консервативним авто-режимом | посилання провайдера | `agentRuntime.id: "auto"` | Необов’язкові Plugin runtime | Залежить від вибраного runtime | -| Явна сесія адаптера ACP Codex | залежить від prompt/моделі ACP | `sessions_spawn` з `runtime: "acp"` | справний бекенд `acpx` | Статус задачі/сесії ACP | +| Бажана поведінка | Посилання на модель | Конфігурація середовища виконання | Вимога до Plugin | Очікувана мітка стану | +| ------------------------------------------ | -------------------------- | -------------------------------------- | ------------------------- | ------------------------------ | +| API OpenAI через звичайний runner OpenClaw | `openai/gpt-*` | пропущено або `runtime: "pi"` | Провайдер OpenAI | `Runtime: OpenClaw Pi Default` | +| OAuth/підписка Codex через PI | `openai-codex/gpt-*` | пропущено або `runtime: "pi"` | Провайдер OAuth OpenAI Codex | `Runtime: OpenClaw Pi Default` | +| Нативні вбудовані ходи Codex app-server | `openai/gpt-*` | `agentRuntime.id: "codex"` | Plugin `codex` | `Runtime: OpenAI Codex` | +| Змішані провайдери з консервативним авто-режимом | посилання, специфічні для провайдера | `agentRuntime.id: "auto"` | Необов’язкові середовища виконання Plugin | Залежить від вибраного середовища виконання | +| Явна сесія адаптера Codex ACP | залежить від prompt/моделі ACP | `sessions_spawn` з `runtime: "acp"` | справний бекенд `acpx` | Стан задачі/сесії ACP | -Ключове розділення — це провайдер проти середовища виконання: +Важливий поділ тут — провайдер проти середовища виконання: -- `openai-codex/*` відповідає на питання «який маршрут провайдера/автентифікації має використовувати PI?» -- `agentRuntime.id: "codex"` відповідає на питання «який цикл має виконувати цей +- `openai-codex/*` відповідає на запитання «який маршрут провайдера/автентифікації має використовувати PI?» +- `agentRuntime.id: "codex"` відповідає на запитання «який цикл має виконувати цей вбудований хід?» -- `/codex ...` відповідає на питання «до якої нативної розмови Codex слід прив’язати - цей чат або якою слід керувати?» -- ACP відповідає на питання «який зовнішній процес harness має запускати acpx?» +- `/codex ...` відповідає на запитання «до якої нативної розмови Codex цей чат має прив’язатися + або якою керувати?» +- ACP відповідає на запитання «який зовнішній процес harness має запускати acpx?» ## Виберіть правильний префікс моделі -Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли хочете -OAuth Codex через PI; використовуйте `openai/*`, коли хочете прямий доступ до API OpenAI або -коли примусово використовуєте нативний harness app-server Codex: +Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли вам потрібен +OAuth Codex через PI; використовуйте `openai/*`, коли вам потрібен прямий доступ до API OpenAI або +коли ви примусово використовуєте нативний harness Codex app-server: -| Посилання на модель | Шлях середовища виконання | Використовуйте, коли | -| -------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------- | -| `openai/gpt-5.4` | Провайдер OpenAI через обв’язку OpenClaw/PI | Вам потрібен поточний прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.5` | OpenAI Codex OAuth через OpenClaw/PI | Вам потрібна автентифікація підпискою ChatGPT/Codex із типовим раннером PI. | -| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | harness app-server Codex | Вам потрібне нативне виконання app-server Codex для ходу вбудованого агента. | +| Посилання на модель | Шлях середовища виконання | Використовуйте, коли | +| -------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------- | +| `openai/gpt-5.4` | Провайдер OpenAI через зв’язку OpenClaw/PI | Вам потрібен поточний прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.5` | OAuth OpenAI Codex через OpenClaw/PI | Вам потрібна автентифікація за підпискою ChatGPT/Codex із типовим runner Pi. | +| `openai/gpt-5.5` + `agentRuntime.id: "codex"` | harness Codex app-server | Вам потрібне нативне виконання через Codex app-server для вбудованого ходу агента. | -GPT-5.5 наразі в OpenClaw доступний лише через підписку/OAuth. Використовуйте -`openai-codex/gpt-5.5` для PI OAuth або `openai/gpt-5.5` з harness app-server Codex. Прямий доступ через API key для `openai/gpt-5.5` підтримується, -щойно OpenAI ввімкне GPT-5.5 у публічному API. +Наразі GPT-5.5 в OpenClaw доступна лише через підписку/OAuth. Використовуйте +`openai-codex/gpt-5.5` для OAuth через PI або `openai/gpt-5.5` з harness Codex +app-server. Прямий доступ за API-ключем для `openai/gpt-5.5` підтримуватиметься, +щойно OpenAI увімкне GPT-5.5 у публічному API. -Устарілі посилання `codex/gpt-*` і далі приймаються як сумісні псевдоніми. Doctor -міграція сумісності переписує усталені основні посилання на runtime до канонічних посилань на моделі та окремо зберігає політику середовища виконання, тоді як усталені посилання лише для резервного варіанта лишаються без змін, бо runtime налаштовується для всього контейнера агента. -Нові конфігурації PI Codex OAuth мають використовувати `openai-codex/gpt-*`; нові -конфігурації harness app-server мають використовувати `openai/gpt-*` разом із +Застарілі посилання `codex/gpt-*`, як і раніше, приймаються як псевдоніми для сумісності. Doctor +під час міграції сумісності переписує застарілі основні посилання середовища виконання на канонічні посилання на модель +і записує політику середовища виконання окремо, тоді як застарілі посилання, що використовуються лише як резервні, +залишаються без змін, оскільки середовище виконання налаштовується для всього контейнера агента. +У нових конфігураціях PI Codex OAuth слід використовувати `openai-codex/gpt-*`; у нових нативних +конфігураціях harness app-server слід використовувати `openai/gpt-*` разом із `agentRuntime.id: "codex"`. -`agents.defaults.imageModel` дотримується такого ж розділення за префіксами. Використовуйте -`openai-codex/gpt-*`, коли розуміння зображень має виконуватися через шлях провайдера OpenAI +`agents.defaults.imageModel` дотримується того самого поділу префіксів. Використовуйте +`openai-codex/gpt-*`, коли розуміння зображень має працювати через шлях провайдера OpenAI Codex OAuth. Використовуйте `codex/gpt-*`, коли розуміння зображень має виконуватися -через обмежений хід app-server Codex. Модель app-server Codex має -оголошувати підтримку вхідних зображень; текстові моделі Codex завершуються помилкою ще до початку медіа-ходу. +через обмежений хід Codex app-server. Модель Codex app-server має +заявляти підтримку вхідних зображень; текстові моделі Codex завершуються з помилкою ще до +початку медіа-ходу. -Використовуйте `/status`, щоб підтвердити фактичний harness для поточної сесії. Якщо вибір виявився неочікуваним, увімкніть налагоджувальне журналювання для підсистеми `agents/harness` +Використовуйте `/status`, щоб підтвердити фактичний harness для поточної сесії. Якщо вибір виявився неочікуваним, увімкніть журналювання налагодження для підсистеми `agents/harness` і перевірте структурований запис gateway `agent harness selected`. Він -містить id вибраного harness, причину вибору, політику runtime/резервного варіанта і, +містить ідентифікатор вибраного harness, причину вибору, політику середовища виконання/резервного варіанта та, у режимі `auto`, результат підтримки для кожного кандидата Plugin. ### Що означають попередження doctor `openclaw doctor` показує попередження, коли всі ці умови істинні: -- вбудований Plugin `codex` увімкнено або дозволено +- комплектний Plugin `codex` увімкнений або дозволений - основна модель агента — `openai-codex/*` -- фактичне runtime цього агента — не `codex` +- фактичне середовище виконання цього агента — не `codex` -Це попередження існує, тому що користувачі часто очікують, що «Plugin Codex увімкнено» означає -«нативне runtime app-server Codex». OpenClaw не робить такого кроку. Попередження означає: +Таке попередження існує, тому що користувачі часто очікують, що «Plugin Codex увімкнений» означає +«нативне середовище виконання Codex app-server». OpenClaw не робить такого автоматичного висновку. Попередження означає: -- **Жодних змін не потрібно**, якщо ви мали на увазі OAuth ChatGPT/Codex через PI. +- **Нічого змінювати не потрібно**, якщо ви мали на увазі OAuth ChatGPT/Codex через PI. - Змініть модель на `openai/` і встановіть `agentRuntime.id: "codex"`, якщо ви мали на увазі нативне виконання через app-server. -- Наявні сесії все одно потребують `/new` або `/reset` після зміни runtime, - тому що прив’язки runtime сесії є сталими. +- Наявні сесії, як і раніше, потребують `/new` або `/reset` після зміни середовища виконання, + тому що фіксація середовища виконання сесії є сталою. -Вибір harness — це не механізм керування живою сесією. Коли виконується вбудований хід, -OpenClaw записує id вибраного harness у цій сесії й продовжує використовувати його для -наступних ходів із тим самим id сесії. Змінюйте конфігурацію `agentRuntime` або -`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший harness; +Вибір harness не є механізмом керування живою сесією. Коли виконується вбудований хід, +OpenClaw записує ідентифікатор вибраного harness у цю сесію і продовжує використовувати його для +наступних ходів у межах того самого ідентифікатора сесії. Змініть конфігурацію `agentRuntime` або +`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб у майбутніх сесіях використовувався інший harness; використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням наявної -розмови між PI та Codex. Це запобігає повторному програванню одного транскрипту через +розмови між PI і Codex. Це дає змогу уникнути повторного програвання одного транскрипту через дві несумісні нативні системи сесій. -Устарілі сесії, створені до появи прив’язок harness, вважаються прив’язаними до PI, щойно +Застарілі сесії, створені до появи фіксації harness, розглядаються як прив’язані до PI, щойно вони мають історію транскрипту. Використовуйте `/new` або `/reset`, щоб перевести цю розмову на Codex після зміни конфігурації. -`/status` показує фактичне runtime моделі. Типовий harness PI відображається як -`Runtime: OpenClaw Pi Default`, а harness app-server Codex — як +`/status` показує фактичне середовище виконання моделі. Типовий harness Pi відображається як +`Runtime: OpenClaw Pi Default`, а harness Codex app-server — як `Runtime: OpenAI Codex`. ## Вимоги -- OpenClaw із доступним вбудованим Plugin `codex`. -- Codex app-server `0.125.0` або новіший. Вбудований Plugin типово керує сумісним - двійковим файлом app-server Codex, тому локальні команди `codex` у `PATH` не - впливають на звичайний запуск harness. -- Автентифікація Codex, доступна для процесу app-server або для bridge автентифікації Codex в OpenClaw. +- OpenClaw із доступним комплектним Plugin `codex`. +- Codex app-server `0.125.0` або новіший. Комплектний Plugin за замовчуванням керує сумісним + бінарним файлом Codex app-server, тому локальні команди `codex` у `PATH` + не впливають на звичайний запуск harness. +- Доступна автентифікація Codex для процесу app-server або для мосту автентифікації Codex у OpenClaw. -Plugin блокує старіші або неверсіоновані handshake app-server. Це утримує -OpenClaw у межах поверхні протоколу, з якою його тестували. +Plugin блокує старіші або безверсійні handshake app-server. Це утримує +OpenClaw на поверхні протоколу, з якою його тестували. -Для live- і Docker smoke-тестів автентифікація зазвичай походить від облікового запису Codex CLI -або auth-profile `openai-codex` в OpenClaw. Локальні запуски app-server через stdio також -можуть використовувати `CODEX_API_KEY` / `OPENAI_API_KEY`, коли облікового запису немає. +Для live- і Docker smoke-тестів автентифікація зазвичай надходить з облікового запису Codex CLI +або з auth profile `openai-codex` в OpenClaw. Локальні запуски app-server через stdio +також можуть використовувати як резервний варіант `CODEX_API_KEY` / `OPENAI_API_KEY`, якщо облікового запису немає. ## Мінімальна конфігурація -Використовуйте `openai/gpt-5.5`, увімкніть вбудований Plugin і примусово вкажіть harness `codex`: +Використовуйте `openai/gpt-5.5`, увімкніть комплектний Plugin і примусово задайте harness `codex`: ```json5 { @@ -206,7 +211,7 @@ OpenClaw у межах поверхні протоколу, з якою його } ``` -Якщо ваша конфігурація використовує `plugins.allow`, додайте туди також `codex`: +Якщо у вашій конфігурації використовується `plugins.allow`, додайте туди також `codex`: ```json5 { @@ -221,27 +226,27 @@ OpenClaw у межах поверхні протоколу, з якою його } ``` -Устарілі конфігурації, які задають `agents.defaults.model` або модель агента як -`codex/`, усе ще автоматично вмикають вбудований Plugin `codex`. Нові конфігурації мають -надавати перевагу `openai/` разом із явним записом `agentRuntime`, наведеним вище. +Застарілі конфігурації, які задають `agents.defaults.model` або модель агента як +`codex/`, як і раніше, автоматично вмикають комплектний Plugin `codex`. У нових конфігураціях слід +використовувати `openai/` разом із явним записом `agentRuntime`, наведеним вище. ## Додайте Codex поруч з іншими моделями -Не задавайте `agentRuntime.id: "codex"` глобально, якщо той самий агент має вільно перемикатися -між моделями провайдера Codex і не-Codex. Примусове runtime застосовується до кожного -вбудованого ходу для цього агента або сесії. Якщо ви виберете модель Anthropic, поки -це runtime примусово задане, OpenClaw усе одно спробує використати harness Codex і завершиться помилкою -без неявного маршрутування цього ходу через PI. +Не встановлюйте `agentRuntime.id: "codex"` глобально, якщо той самий агент має вільно перемикатися +між Codex і моделями інших провайдерів. Примусово задане середовище виконання застосовується до кожного +вбудованого ходу для цього агента або сесії. Якщо ви виберете модель Anthropic, коли +це середовище виконання примусово задане, OpenClaw усе одно спробує використати harness Codex і завершиться помилкою +без тихого маршрутизації цього ходу через PI. -Використовуйте натомість одну з цих схем: +Використовуйте одну з таких форм: -- Виділіть Codex в окремого агента з `agentRuntime.id: "codex"`. -- Залиште типовому агенту `agentRuntime.id: "auto"` і резервний перехід на PI для звичайного змішаного +- Розмістіть Codex на окремому агенті з `agentRuntime.id: "codex"`. +- Залиште типовий агент на `agentRuntime.id: "auto"` з резервним варіантом PI для звичайного змішаного використання провайдерів. -- Використовуйте застарілі посилання `codex/*` лише для сумісності. Нові конфігурації мають надавати перевагу - `openai/*` разом із явною політикою runtime Codex. +- Використовуйте застарілі посилання `codex/*` лише для сумісності. У нових конфігураціях слід + надавати перевагу `openai/*` разом із явною політикою середовища виконання Codex. -Наприклад, така конфігурація залишає типовий агент на звичайному автоматичному виборі та +Наприклад, це залишає типовий агент на звичайному автоматичному виборі та додає окремого агента Codex: ```json5 @@ -279,37 +284,37 @@ OpenClaw у межах поверхні протоколу, з якою його } ``` -За такої схеми: +За такої структури: -- Типовий агент `main` використовує звичайний шлях провайдера та резервну сумісність із PI. -- Агент `codex` використовує harness app-server Codex. -- Якщо Codex відсутній або не підтримується для агента `codex`, хід - завершується помилкою замість тихого переходу на PI. +- Типовий агент `main` використовує звичайний шлях провайдера та резервний варіант сумісності PI. +- Агент `codex` використовує harness Codex app-server. +- Якщо для агента `codex` Codex відсутній або не підтримується, хід завершується помилкою + замість тихого використання PI. ## Маршрутизація команд агента Агенти мають маршрутизувати запити користувача за наміром, а не лише за словом "Codex": -| Користувач просить... | Агент має використовувати... | -| ----------------------------------------------------- | ----------------------------------------------- | -| "Прив’яжи цей чат до Codex" | `/codex bind` | -| "Віднови тут потік Codex ``" | `/codex resume ` | -| "Покажи потоки Codex" | `/codex threads` | -| "Використовуй Codex як runtime для цього агента" | зміну конфігурації `agentRuntime.id` | -| "Використовуй мою підписку ChatGPT/Codex зі звичайним OpenClaw" | посилання на моделі `openai-codex/*` | -| "Запусти Codex через ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | -| "Запусти Claude Code/Gemini/OpenCode/Cursor у потоці" | ACP/acpx, не `/codex` і не нативні субагенти | +| Користувач просить... | Агент має використовувати... | +| ----------------------------------------------------- | ------------------------------------------------ | +| "Прив’яжи цей чат до Codex" | `/codex bind` | +| "Віднови тут потік Codex ``" | `/codex resume ` | +| "Покажи потоки Codex" | `/codex threads` | +| "Використовуй Codex як середовище виконання для цього агента" | зміна конфігурації `agentRuntime.id` | +| "Використовуй мою підписку ChatGPT/Codex зі звичайним OpenClaw" | посилання на моделі `openai-codex/*` | +| "Запусти Codex через ACP/acpx" | ACP `sessions_spawn({ runtime: "acp", ... })` | +| "Запусти Claude Code/Gemini/OpenCode/Cursor у потоці" | ACP/acpx, не `/codex` і не нативні субагенти | -OpenClaw показує агентам вказівки щодо запуску через ACP лише тоді, коли ACP увімкнено, -його можна диспетчеризувати, і він підтримується завантаженим backend runtime. Якщо ACP недоступний, -системний prompt і Skills Plugin не мають навчати агента маршрутизації +OpenClaw показує агентам інструкції щодо запуску через ACP лише тоді, коли ACP увімкнено, +доступний для диспетчеризації та підтримується завантаженим бекендом середовища виконання. Якщо ACP недоступний, +системний prompt і Skills Plugin не повинні навчати агента маршрутизації через ACP. ## Розгортання лише з Codex -Примусово використовуйте harness Codex, коли потрібно довести, що кожен хід вбудованого агента -використовує Codex. Явні runtime Plugin типово працюють без резервного переходу на PI, тому -`fallback: "none"` необов’язковий, але часто корисний як документація: +Примусово використовуйте harness Codex, коли вам потрібно довести, що кожен вбудований хід агента +використовує Codex. Явні середовища виконання Plugin типово не мають резервного варіанта PI, тож +`fallback: "none"` є необов’язковим, але часто корисним як документація: ```json5 { @@ -325,20 +330,20 @@ OpenClaw показує агентам вказівки щодо запуску } ``` -Перевизначення через змінну середовища: +Перевизначення через середовище: ```bash OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -Якщо Codex примусово увімкнено, OpenClaw завершується помилкою на ранньому етапі, якщо Plugin Codex вимкнено, app-server -застарілий або app-server не може запуститися. Встановлюйте -`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише якщо ви свідомо хочете, щоб PI обробляв +Коли Codex примусово задано, OpenClaw завершується помилкою на ранньому етапі, якщо Plugin Codex вимкнений, якщо +app-server занадто старий або якщо app-server не може запуститися. Встановлюйте +`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише тоді, коли ви свідомо хочете, щоб PI обробляв відсутній вибір harness. ## Codex для окремого агента -Ви можете зробити одного агента лише з Codex, тоді як типовий агент зберігатиме нормальний +Ви можете зробити один агент лише для Codex, тоді як типовий агент зберігатиме звичайний автовибір: ```json5 @@ -371,14 +376,14 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` Використовуйте звичайні команди сесії, щоб перемикати агентів і моделі. `/new` створює нову -сесію OpenClaw, а harness Codex створює або відновлює свій sidecar-потік app-server -за потреби. `/reset` очищує прив’язку сесії OpenClaw для цього потоку -і дає змогу наступному ходу знову визначити harness із поточної конфігурації. +сесію OpenClaw, а harness Codex за потреби створює або відновлює свій sidecar app-server +потік. `/reset` очищає прив’язку сесії OpenClaw для цього потоку +і дозволяє наступному ходу знову визначити harness з поточної конфігурації. ## Виявлення моделей -Типово Plugin Codex запитує app-server про доступні моделі. Якщо -виявлення завершується помилкою або перевищує час очікування, він використовує вбудований резервний каталог для: +За замовчуванням Plugin Codex запитує app-server про доступні моделі. Якщо +виявлення завершується помилкою або тайм-аутом, він використовує комплектний резервний каталог для: - GPT-5.5 - GPT-5.4 mini @@ -404,8 +409,8 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -Вимкніть виявлення, якщо хочете, щоб запуск не намагався опитувати Codex і дотримувався -резервного каталогу: +Вимкніть виявлення, якщо хочете, щоб під час запуску не відбувалося зондування Codex і використовувався +резервний каталог: ```json5 { @@ -424,27 +429,27 @@ OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run } ``` -## Підключення до app-server і політика +## Підключення app-server і політика -Типово Plugin локально запускає керований OpenClaw двійковий файл Codex такою командою: +За замовчуванням Plugin локально запускає керований OpenClaw бінарний файл Codex із: ```bash codex app-server --listen stdio:// ``` -Керований двійковий файл оголошено як вбудовану залежність runtime Plugin і підготовлено -разом з іншими залежностями Plugin `codex`. Це прив’язує версію app-server -до вбудованого Plugin, а не до будь-якого окремого Codex CLI, -який випадково встановлено локально. Встановлюйте `appServer.command` лише тоді, коли -свідомо хочете запускати інший виконуваний файл. +Керований бінарний файл оголошено як комплектну залежність середовища виконання Plugin і підготовлено +разом з рештою залежностей Plugin `codex`. Це прив’язує версію app-server +до комплектного Plugin, а не до окремого Codex CLI, +який випадково встановлений локально. Встановлюйте `appServer.command` лише тоді, коли +свідомо хочете запустити інший виконуваний файл. -Типово OpenClaw запускає локальні сесії harness Codex у режимі YOLO: +За замовчуванням OpenClaw запускає локальні сесії harness Codex у режимі YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` і -`sandbox: "danger-full-access"`. Це довірена локальна операторська модель, що використовується -для автономних Heartbeat: Codex може використовувати shell та мережеві інструменти без +`sandbox: "danger-full-access"`. Це довірена локальна операційна модель, яка використовується +для автономних Heartbeat: Codex може використовувати shell і мережеві інструменти без зупинки на нативних prompt підтвердження, на які нікому відповісти. -Щоб увімкнути підтвердження з нативною перевіркою guardian у Codex, встановіть `appServer.mode: +Щоб увімкнути погодження Codex, перевірювані guardian, задайте `appServer.mode: "guardian"`: ```json5 @@ -465,18 +470,18 @@ codex app-server --listen stdio:// } ``` -Режим Guardian використовує нативний шлях автоматичної перевірки підтверджень Codex. Коли Codex просить -вийти з sandbox, записати за межами робочого простору або додати дозволи на кшталт доступу до мережі, -Codex надсилає такий запит на підтвердження нативному рецензенту замість -людського prompt. Рецензент застосовує модель оцінки ризику Codex і схвалює або відхиляє -конкретний запит. Використовуйте Guardian, коли вам потрібні суворіші обмеження, ніж у режимі YOLO, -але при цьому потрібно, щоб агенти без нагляду могли просуватися далі. +Режим guardian використовує нативний шлях автоматичної перевірки погоджень Codex. Коли Codex просить +вийти з sandbox, писати поза робочим простором або додати дозволи, як-от доступ до мережі, +Codex маршрутизує цей запит на погодження до нативного рецензента, а не до +людського prompt. Рецензент застосовує модель ризику Codex і схвалює або відхиляє +конкретний запит. Використовуйте Guardian, коли вам потрібні сильніші запобіжники, ніж у режимі YOLO, +але при цьому потрібен прогрес агентів без нагляду. -Попереднє налаштування `guardian` розгортається в `approvalPolicy: "on-request"`, +Шаблон `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "auto_review"` і `sandbox: "workspace-write"`. -Окремі поля політики все одно мають пріоритет над `mode`, тож розширені розгортання можуть поєднувати -цей preset із явними налаштуваннями. Старе значення рецензента `guardian_subagent` -і далі приймається як псевдонім для сумісності, але нові конфігурації мають використовувати +Окремі поля політики все ще перевизначають `mode`, тож у розширених розгортаннях можна поєднувати +цей шаблон з явними налаштуваннями. Старіше значення рецензента `guardian_subagent` +і далі приймається як псевдонім сумісності, але в нових конфігураціях слід використовувати `auto_review`. Для вже запущеного app-server використовуйте транспорт WebSocket: @@ -501,25 +506,24 @@ Codex надсилає такий запит на підтвердження н } ``` -Запуски app-server через stdio типово успадковують середовище процесу OpenClaw, -але OpenClaw керує bridge облікового запису app-server Codex. Автентифікація вибирається в такому +Запуски app-server через stdio за замовчуванням успадковують середовище процесу OpenClaw, +але OpenClaw володіє мостом облікового запису Codex app-server. Автентифікація вибирається в такому порядку: -1. Явний auth-profile Codex OpenClaw для агента. +1. Явний auth profile Codex OpenClaw для агента. 2. Наявний обліковий запис app-server, наприклад локальний вхід ChatGPT у Codex CLI. -3. Лише для локальних запусків app-server через stdio: `CODEX_API_KEY`, потім - `OPENAI_API_KEY`, якщо облікового запису app-server немає, а автентифікація OpenAI - усе ще потрібна. +3. Лише для локальних запусків app-server через stdio — `CODEX_API_KEY`, потім + `OPENAI_API_KEY`, якщо обліковий запис app-server відсутній і автентифікація OpenAI + все ще потрібна. -Коли OpenClaw бачить auth-profile Codex у стилі підписки ChatGPT, він видаляє +Коли OpenClaw бачить auth profile Codex у стилі підписки ChatGPT, він видаляє `CODEX_API_KEY` і `OPENAI_API_KEY` із породженого дочірнього процесу Codex. Це -дозволяє API key на рівні Gateway лишатися доступними для embeddings або прямих моделей OpenAI, -не спричиняючи випадкового білінгу нативних ходів app-server Codex через API. -Явні профілі Codex з API key і локальний резервний варіант env-key для stdio використовують вхід app-server, а не успадковане середовище дочірнього процесу. Підключення до app-server через WebSocket -не отримують резервний варіант API key із середовища Gateway; використовуйте явний auth-profile або +дозволяє зберегти API-ключі рівня Gateway для embeddings або прямих моделей OpenAI, +не допускаючи при цьому, щоб нативні ходи Codex app-server випадково оплачувалися через API. +Явні профілі Codex з API-ключем і локальний резервний варіант із ключем середовища для stdio використовують вхід app-server замість успадкованого середовища дочірнього процесу. Підключення до app-server через WebSocket не отримують резервного варіанта з API-ключем середовища Gateway; використовуйте явний auth profile або власний обліковий запис віддаленого app-server. -Якщо розгортанню потрібна додаткова ізоляція змінних середовища, додайте ці змінні до +Якщо розгортанню потрібна додаткова ізоляція середовища, додайте ці змінні до `appServer.clearEnv`: ```json5 @@ -539,27 +543,27 @@ Codex надсилає такий запит на підтвердження н } ``` -`appServer.clearEnv` впливає лише на породжений дочірній процес app-server Codex через stdio. +`appServer.clearEnv` впливає лише на породжений дочірній процес Codex app-server через stdio. Підтримувані поля `appServer`: | Поле | Типове значення | Значення | | ------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | -| `command` | керований двійковий файл Codex | Виконуваний файл для транспорту stdio. Залиште порожнім, щоб використовувати керований двійковий файл; задавайте лише для явного перевизначення. | +| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | +| `command` | керований бінарний файл Codex | Виконуваний файл для транспорту stdio. Залиште порожнім, щоб використовувати керований бінарний файл; задавайте лише для явного перевизначення. | | `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | -| `url` | не встановлено | URL app-server WebSocket. | -| `authToken` | не встановлено | Bearer token для транспорту WebSocket. | +| `url` | не задано | URL app-server WebSocket. | +| `authToken` | не задано | Bearer token для транспорту WebSocket. | | `headers` | `{}` | Додаткові заголовки WebSocket. | -| `clearEnv` | `[]` | Додаткові назви змінних середовища, які видаляються з породженого процесу stdio app-server після того, як OpenClaw сформує успадковане середовище. | -| `requestTimeoutMs` | `60000` | Час очікування для викликів control-plane app-server. | -| `mode` | `"yolo"` | Preset для виконання в режимі YOLO або з перевіркою guardian. | -| `approvalPolicy` | `"never"` | Нативна політика підтверджень Codex, що надсилається під час запуску/відновлення потоку/ходу. | -| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що надсилається під час запуску/відновлення потоку. | -| `approvalsReviewer` | `"user"` | Використовуйте `"auto_review"`, щоб дозволити Codex перевіряти нативні prompt підтвердження. `guardian_subagent` лишається застарілим псевдонімом. | -| `serviceTier` | не встановлено | Необов’язковий service tier app-server Codex: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. | +| `clearEnv` | `[]` | Додаткові назви змінних середовища, які видаляються з породженого процесу app-server через stdio після того, як OpenClaw сформує успадковане середовище. | +| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control plane app-server. | +| `mode` | `"yolo"` | Шаблон для виконання в режимі YOLO або з перевіркою guardian. | +| `approvalPolicy` | `"never"` | Нативна політика погоджень Codex, що передається під час старту/відновлення потоку/ходу. | +| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що передається під час старту/відновлення потоку. | +| `approvalsReviewer` | `"user"` | Використовуйте `"auto_review"`, щоб дозволити Codex перевіряти нативні prompt погодження. `guardian_subagent` залишається застарілим псевдонімом. | +| `serviceTier` | не задано | Необов’язковий рівень сервісу Codex app-server: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. | -Перевизначення через змінні середовища і далі доступні для локального тестування: +Перевизначення через середовище залишаються доступними для локального тестування: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -567,25 +571,30 @@ Codex надсилає такий запит на підтвердження н - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`OPENCLAW_CODEX_APP_SERVER_BIN` обходить керований двійковий файл, коли +`OPENCLAW_CODEX_APP_SERVER_BIN` обходить керований бінарний файл, коли `appServer.command` не задано. -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` видалено. Натомість використовуйте -`plugins.entries.codex.config.appServer.mode: "guardian"` або -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Конфігурація -є кращим варіантом для відтворюваних розгортань, оскільки зберігає поведінку Plugin в тому самому -перевіреному файлі, що й решта налаштувань harness Codex. +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було вилучено. Використовуйте +`plugins.entries.codex.config.appServer.mode: "guardian"` натомість або +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Для +відтворюваних розгортань перевага надається конфігурації, оскільки вона зберігає поведінку Plugin +в тому самому перевіреному файлі, що й решта налаштування harness Codex. ## Використання комп’ютера Використання комп’ютера описано в окремому посібнику з налаштування: -[Codex Computer Use](/uk/plugins/codex-computer-use). +[Використання комп’ютера Codex](/uk/plugins/codex-computer-use). -Коротко: OpenClaw не постачає застосунок для керування робочим столом і не виконує -дії на робочому столі самостійно. Він готує app-server Codex, перевіряє, що +Коротка версія: OpenClaw не постачає застосунок керування робочим столом і не виконує +дії на робочому столі самостійно. Він готує Codex app-server, перевіряє, що MCP-сервер `computer-use` доступний, а потім дозволяє Codex обробляти нативні виклики інструментів MCP під час ходів у режимі Codex. +Для прямого доступу до драйвера TryCua поза потоком маркетплейсу Codex зареєструйте +`cua-driver mcp` за допомогою `openclaw mcp set cua-driver '{"command":"cua-driver","args":["mcp"]}'`. +Див. [Використання комп’ютера Codex](/uk/plugins/codex-computer-use) щодо різниці +між Computer Use, яким керує Codex, і прямою реєстрацією MCP. + Мінімальна конфігурація: ```json5 @@ -621,18 +630,17 @@ MCP-сервер `computer-use` доступний, а потім дозволя - `/codex computer-use install --source ` - `/codex computer-use install --marketplace-path ` -Computer Use призначений для macOS і може потребувати локальних дозволів ОС, перш ніж -MCP-сервер Codex зможе керувати застосунками. Якщо `computerUse.enabled` має значення true, а MCP- -сервер недоступний, ходи в режимі Codex завершуються помилкою ще до запуску потоку, замість -тихої роботи без нативних інструментів Computer Use. Див. -[Codex Computer Use](/uk/plugins/codex-computer-use) для відомостей про варіанти marketplace, -обмеження віддаленого каталогу, причини станів і усунення несправностей. +Використання комп’ютера специфічне для macOS і може вимагати локальних дозволів ОС, перш ніж +MCP-сервер Codex зможе керувати застосунками. Якщо `computerUse.enabled` має значення true і MCP-сервер недоступний, ходи в режимі Codex завершуються помилкою до запуску потоку, а не +тихо виконуються без нативних інструментів Computer Use. Див. +[Використання комп’ютера Codex](/uk/plugins/codex-computer-use) щодо варіантів маркетплейсу, +обмежень віддаленого каталогу, причин стану та усунення несправностей. Коли `computerUse.autoInstall` має значення true, OpenClaw може зареєструвати стандартний -вбудований marketplace Codex Desktop із +комплектний маркетплейс Codex Desktop із `/Applications/Codex.app/Contents/Resources/plugins/openai-bundled`, якщо Codex -ще не виявив локальний marketplace. Використовуйте `/new` або `/reset` після -зміни конфігурації runtime або Computer Use, щоб наявні сесії не зберігали стару +ще не виявив локальний маркетплейс. Використовуйте `/new` або `/reset` після +зміни конфігурації середовища виконання або Computer Use, щоб наявні сесії не зберігали стару прив’язку потоку PI або Codex. ## Поширені рецепти @@ -673,7 +681,7 @@ MCP-сервер Codex зможе керувати застосунками. Я } ``` -Підтвердження Codex із перевіркою guardian: +Погодження Codex із перевіркою guardian: ```json5 { @@ -695,7 +703,7 @@ MCP-сервер Codex зможе керувати застосунками. Я } ``` -Віддалений app-server із явними заголовками: +Віддалений app-server з явними заголовками: ```json5 { @@ -718,186 +726,185 @@ MCP-сервер Codex зможе керувати застосунками. Я } ``` -Перемикання моделей і далі контролюється OpenClaw. Коли сесію OpenClaw приєднано +Перемикання моделей залишається під контролем OpenClaw. Коли сесію OpenClaw приєднано до наявного потоку Codex, наступний хід знову надсилає до -app-server поточну вибрану модель OpenAI, провайдера, політику підтверджень, sandbox і service tier. -Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає -прив’язку до потоку, але просить Codex продовжити з новою вибраною моделлю. +app-server поточно вибрану модель OpenAI, провайдера, політику погоджень, sandbox і рівень сервісу. +Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає прив’язку +потоку, але просить Codex продовжити з нововибраною моделлю. ## Команда Codex -Вбудований Plugin реєструє `/codex` як авторизовану slash-команду. Вона є -універсальною і працює в будь-якому каналі, що підтримує текстові команди OpenClaw. +Комплектний Plugin реєструє `/codex` як авторизовану slash-команду. Вона є +загальною і працює на будь-якому каналі, що підтримує текстові команди OpenClaw. Поширені форми: -- `/codex status` показує живе підключення до app-server, моделі, обліковий запис, обмеження швидкості, MCP-сервери та Skills. -- `/codex models` перелічує живі моделі app-server Codex. -- `/codex threads [filter]` перелічує нещодавні потоки Codex. +- `/codex status` показує живе підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP-сервери та skills. +- `/codex models` показує список живих моделей Codex app-server. +- `/codex threads [filter]` показує список останніх потоків Codex. - `/codex resume ` приєднує поточну сесію OpenClaw до наявного потоку Codex. -- `/codex compact` просить app-server Codex виконати Compaction приєднаного потоку. +- `/codex compact` просить Codex app-server виконати Compaction для приєднаного потоку. - `/codex review` запускає нативну перевірку Codex для приєднаного потоку. - `/codex computer-use status` перевіряє налаштований Plugin Computer Use і MCP-сервер. - `/codex computer-use install` встановлює налаштований Plugin Computer Use і перезавантажує MCP-сервери. -- `/codex account` показує стан облікового запису та обмежень швидкості. -- `/codex mcp` перелічує стан MCP-сервера app-server Codex. -- `/codex skills` перелічує Skills app-server Codex. +- `/codex account` показує стан облікового запису та лімітів швидкості. +- `/codex mcp` показує список станів MCP-серверів Codex app-server. +- `/codex skills` показує список skills Codex app-server. -`/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для -звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає -поточну вибрану модель OpenClaw до app-server і зберігає ввімкнену +`/codex resume` записує той самий файл sidecar-прив’язки, який harness використовує для +звичайних ходів. Під час наступного повідомлення OpenClaw відновлює цей потік Codex, передає +поточну вибрану модель OpenClaw в app-server і зберігає ввімкнену розширену історію. -Поверхня команд потребує Codex app-server `0.125.0` або новішої версії. Окремі -методи керування позначаються як `unsupported by this Codex app-server`, якщо -майбутній або спеціальний app-server не надає цей метод JSON-RPC. +Поверхня команд вимагає Codex app-server `0.125.0` або новіший. Про окремі +методи керування повідомляється як `unsupported by this Codex app-server`, якщо +майбутній або користувацький app-server не надає цей метод JSON-RPC. -## Межі хуків +## Межі hooks -Harness Codex має три шари хуків: +Harness Codex має три шари hooks: | Шар | Власник | Призначення | | ------------------------------------- | ------------------------ | ------------------------------------------------------------------ | -| Хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness PI та Codex. | -| Middleware розширення app-server Codex | Вбудовані Plugins OpenClaw | Поведінка адаптера на рівні ходу навколо динамічних інструментів OpenClaw. | -| Нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і політика нативних інструментів із конфігурації Codex. | +| hooks Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness Pi і Codex. | +| Middleware розширень Codex app-server | Комплектні plugins OpenClaw | Поведінка адаптера навколо динамічних інструментів OpenClaw для кожного ходу. | +| Нативні hooks Codex | Codex | Низькорівневий життєвий цикл Codex і політика нативних інструментів із конфігурації Codex. | -OpenClaw не використовує файли проєктного або глобального Codex `hooks.json` для маршрутизації -поведінки Plugin OpenClaw. Для підтримуваного bridge нативних інструментів і дозволів +OpenClaw не використовує файли `hooks.json` Codex на рівні проєкту або глобально для маршрутизації +поведінки Plugin OpenClaw. Для підтримуваного мосту нативних інструментів і дозволів OpenClaw впроваджує конфігурацію Codex для кожного потоку для `PreToolUse`, `PostToolUse`, -`PermissionRequest` і `Stop`. Інші хуки Codex, такі як `SessionStart` і -`UserPromptSubmit`, залишаються елементами керування на рівні Codex; вони не відкриваються як -хуки Plugin OpenClaw у контракті v1. +`PermissionRequest` і `Stop`. Інші hooks Codex, такі як `SessionStart` і +`UserPromptSubmit`, залишаються механізмами керування рівня Codex; вони не відкриваються як +hooks Plugin OpenClaw у контракті v1. Для динамічних інструментів OpenClaw OpenClaw виконує інструмент після того, як Codex запитує -виклик, тому OpenClaw запускає належну йому поведінку Plugin і middleware в +виклик, тому OpenClaw запускає поведінку Plugin і middleware, якою він володіє, у адаптері harness. Для нативних інструментів Codex Codex володіє канонічним записом інструмента. -OpenClaw може дзеркалити вибрані події, але не може переписати нативний потік Codex, -якщо Codex не відкриває цю операцію через app-server або зворотні виклики -нативних хуків. +OpenClaw може віддзеркалювати вибрані події, але не може переписувати нативний потік Codex, +якщо тільки Codex не надає цю операцію через app-server або нативні +callback hooks. -Проєкції Compaction і життєвого циклу LLM надходять із -сповіщень app-server Codex і стану адаптера OpenClaw, а не з команд нативних хуків Codex. +Проєкції Compaction і життєвого циклу LLM надходять з +сповіщень Codex app-server і стану адаптера OpenClaw, а не з нативних команд hooks Codex. Події OpenClaw `before_compaction`, `after_compaction`, `llm_input` і -`llm_output` — це спостереження на рівні адаптера, а не побайтові захоплення +`llm_output` — це спостереження рівня адаптера, а не побайтові захоплення внутрішнього запиту Codex або payload Compaction. -Нативні сповіщення app-server Codex `hook/started` і `hook/completed` +Нативні сповіщення Codex app-server `hook/started` і `hook/completed` проєктуються як події агента `codex_app_server.hook` для траєкторії та налагодження. -Вони не викликають хуки Plugin OpenClaw. +Вони не викликають hooks Plugin OpenClaw. ## Контракт підтримки V1 -Режим Codex — це не PI з іншим викликом моделі під ним. Codex керує більшою частиною +Режим Codex — це не PI з іншим викликом моделі під ним. Codex контролює більшу частину нативного циклу моделі, а OpenClaw адаптує свої поверхні Plugin і сесій навколо цієї межі. -Підтримується в runtime Codex v1: +Підтримується в середовищі виконання Codex v1: -| Поверхня | Підтримка | Чому | -| --------------------------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Цикл моделі OpenAI через Codex | Підтримується | App-server Codex керує ходом OpenAI, нативним відновленням потоку та нативним продовженням інструментів. | -| Маршрутизація та доставка каналів OpenClaw | Підтримується | Telegram, Discord, Slack, WhatsApp, iMessage та інші канали залишаються поза runtime моделі. | -| Динамічні інструменти OpenClaw | Підтримується | Codex просить OpenClaw виконувати ці інструменти, тому OpenClaw залишається в шляху виконання. | -| Plugins prompt і контексту | Підтримується | OpenClaw будує накладки prompt і проєктує контекст у хід Codex перед запуском або відновленням потоку. | -| Життєвий цикл рушія контексту | Підтримується | Збирання, ingest або обслуговування після ходу, а також координація Compaction рушія контексту виконуються для ходів Codex. | -| Хуки динамічних інструментів | Підтримується | `before_tool_call`, `after_tool_call` і middleware результатів інструментів виконуються навколо динамічних інструментів, якими володіє OpenClaw. | -| Хуки життєвого циклу | Підтримуються як спостереження адаптера | `llm_input`, `llm_output`, `agent_end`, `before_compaction` і `after_compaction` спрацьовують із чесними payload для режиму Codex. | -| Шлюз перегляду фінальної відповіді | Підтримується через ретрансляцію нативних хуків | `Stop` Codex ретранслюється до `before_agent_finalize`; `revise` просить Codex зробити ще один прохід моделі перед завершенням. | -| Блокування або спостереження за нативними shell, patch і MCP | Підтримується через ретрансляцію нативних хуків | `PreToolUse` і `PostToolUse` Codex ретранслюються для зафіксованих поверхонь нативних інструментів, включно з payload MCP у Codex app-server `0.125.0` або новішому. Блокування підтримується; переписування аргументів — ні. | -| Нативна політика дозволів | Підтримується через ретрансляцію нативних хуків | `PermissionRequest` Codex можна маршрутизувати через політику OpenClaw там, де runtime це підтримує. Якщо OpenClaw не повертає рішення, Codex продовжує через свій звичайний шлях підтвердження guardian або користувача. | -| Захоплення траєкторії app-server | Підтримується | OpenClaw записує запит, який він надіслав до app-server, і сповіщення app-server, які отримує. | +| Поверхня | Підтримка | Чому | +| --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Цикл моделі OpenAI через Codex | Підтримується | Codex app-server керує ходом OpenAI, нативним відновленням потоку та нативним продовженням інструментів. | +| Маршрутизація та доставка каналів OpenClaw | Підтримується | Telegram, Discord, Slack, WhatsApp, iMessage та інші канали залишаються поза середовищем виконання моделі. | +| Динамічні інструменти OpenClaw | Підтримується | Codex просить OpenClaw виконати ці інструменти, тож OpenClaw залишається на шляху виконання. | +| Plugins prompt і контексту | Підтримується | OpenClaw будує накладки prompt і проєктує контекст у хід Codex перед запуском або відновленням потоку. | +| Життєвий цикл рушія контексту | Підтримується | Збирання, поглинання або післяходове обслуговування та координація Compaction рушія контексту виконуються для ходів Codex. | +| hooks динамічних інструментів | Підтримується | `before_tool_call`, `after_tool_call` і middleware результатів інструментів працюють навколо динамічних інструментів OpenClaw. | +| hooks життєвого циклу | Підтримується як спостереження адаптера | `llm_input`, `llm_output`, `agent_end`, `before_compaction` і `after_compaction` запускаються з коректними payload для режиму Codex. | +| Шлюз перегляду фінальної відповіді | Підтримується через ретрансляцію нативних hooks | Codex `Stop` ретранслюється в `before_agent_finalize`; `revise` просить Codex виконати ще один прохід моделі перед фіналізацією. | +| Нативне shell, patch і блокування або спостереження MCP | Підтримується через ретрансляцію нативних hooks | `PreToolUse` і `PostToolUse` Codex ретранслюються для зафіксованих поверхонь нативних інструментів, включно з payload MCP у Codex app-server `0.125.0` або новішому. Блокування підтримується; переписування аргументів — ні. | +| Нативна політика дозволів | Підтримується через ретрансляцію нативних hooks | `PermissionRequest` Codex може маршрутизуватися через політику OpenClaw там, де середовище виконання це підтримує. Якщо OpenClaw не повертає рішення, Codex продовжує своїм звичайним шляхом погодження guardian або користувача. | +| Захоплення траєкторії app-server | Підтримується | OpenClaw записує запит, який він надіслав до app-server, і сповіщення, які отримує від app-server. | -Не підтримується в runtime Codex v1: +Не підтримується в середовищі виконання Codex v1: -| Поверхня | Межа V1 | Подальший шлях | -| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | -| Мутація аргументів нативних інструментів | Нативні pre-tool hooks Codex можуть блокувати, але OpenClaw не переписує аргументи нативних інструментів Codex. | Потребує підтримки Codex hooks/schema для заміни вхідних даних інструмента. | -| Редагована історія нативного транскрипту Codex | Codex володіє канонічною історією нативного потоку. OpenClaw володіє дзеркалом і може проєктувати майбутній контекст, але не повинен змінювати непідтримувані внутрішні механізми. | Додати явні API app-server Codex, якщо потрібне втручання в нативний потік. | -| `tool_result_persist` для записів нативних інструментів Codex | Цей hook перетворює записи транскрипту, якими володіє OpenClaw, а не записи нативних інструментів Codex. | Може дзеркалити перетворені записи, але канонічне переписування потребує підтримки Codex. | -| Багаті метадані нативної Compaction | OpenClaw спостерігає початок і завершення Compaction, але не отримує стабільного списку збереженого/відкинутого, дельти токенів або payload підсумку. | Потрібні багатші події Compaction у Codex. | -| Втручання в Compaction | Поточні hooks Compaction в OpenClaw працюють у режимі Codex на рівні сповіщень. | Додати hooks Codex до/після Compaction, якщо Plugins мають блокувати або переписувати нативну Compaction. | -| Побайтове захоплення запиту до API моделі | OpenClaw може захоплювати запити та сповіщення app-server, але ядро Codex формує фінальний запит до OpenAI API внутрішньо. | Потрібна подія трасування запиту моделі Codex або debug API. | +| Поверхня | Межа V1 | Майбутній шлях | +| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| Мутація аргументів нативних інструментів | Нативні pre-tool hooks Codex можуть блокувати, але OpenClaw не переписує аргументи нативних інструментів Codex. | Потребує підтримки hooks/схеми Codex для заміни вхідних даних інструмента. | +| Редагована історія транскрипту нативного Codex | Codex володіє канонічною історією нативного потоку. OpenClaw володіє дзеркалом і може проєктувати майбутній контекст, але не повинен змінювати непідтримувані внутрішні компоненти. | Додати явні API Codex app-server, якщо потрібне втручання в нативний потік. | +| `tool_result_persist` для записів нативних інструментів Codex | Цей hook перетворює записи транскрипту, якими володіє OpenClaw, а не записи нативних інструментів Codex. | Може віддзеркалювати перетворені записи, але канонічне переписування потребує підтримки Codex. | +| Розширені метадані нативної Compaction | OpenClaw спостерігає початок і завершення Compaction, але не отримує стабільного списку збережених/відкинутих елементів, дельти токенів або payload підсумку. | Потребує багатших подій Compaction у Codex. | +| Втручання в Compaction | Поточні hooks Compaction OpenClaw у режимі Codex працюють на рівні сповіщень. | Додати pre/post hooks Compaction у Codex, якщо Plugins потребують блокування або переписування нативної Compaction. | +| Побайтове захоплення запиту до API моделі | OpenClaw може захоплювати запити й сповіщення app-server, але ядро Codex формує фінальний запит до OpenAI API внутрішньо. | Потребує події трасування запиту моделі Codex або API налагодження. | ## Інструменти, медіа та Compaction Harness Codex змінює лише низькорівневий виконавець вбудованого агента. -OpenClaw і далі будує список інструментів і отримує результати динамічних інструментів від -harness. Текст, зображення, відео, музика, TTS, підтвердження та вивід інструментів повідомлень -і далі проходять через звичайний шлях доставки OpenClaw. +OpenClaw, як і раніше, будує список інструментів і отримує результати динамічних інструментів від +harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів обміну повідомленнями +продовжують проходити через звичайний шлях доставки OpenClaw. -Ретрансляція нативних hooks навмисно є загальною, але контракт підтримки v1 -обмежено шляхами нативних інструментів і дозволів Codex, які тестує OpenClaw. У -runtime Codex це включає payload `PreToolUse`, -`PostToolUse` і `PermissionRequest` для shell, patch та MCP. Не припускайте, що кожна майбутня -подія hook Codex є поверхнею Plugin OpenClaw, доки контракт runtime -не назве її явно. +Ретрансляція нативних hooks навмисно є узагальненою, але контракт підтримки v1 +обмежений нативними шляхами інструментів і дозволів Codex, які тестує OpenClaw. У +середовищі виконання Codex це включає payload `PreToolUse`, +`PostToolUse` і `PermissionRequest` для shell, patch і MCP. Не припускайте, що кожна майбутня +подія hooks Codex є поверхнею Plugin OpenClaw, доки це не буде прямо названо +контрактом середовища виконання. Для `PermissionRequest` OpenClaw повертає явні рішення allow або deny -лише коли це визначає політика. Результат без рішення — це не allow. Codex трактує його як -відсутність рішення hook і переходить до власного шляху підтвердження guardian або користувача. +лише тоді, коли це визначає політика. Результат без рішення — це не allow. Codex трактує його як відсутність +рішення hook і переходить до власного шляху погодження guardian або користувача. -Запити на підтвердження інструментів MCP Codex маршрутизуються через -потік підтвердження Plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як +Запити на погодження інструментів MCP Codex маршрутизуються через потік погодження Plugin +OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як `"mcp_tool_call"`. Prompt `request_user_input` Codex надсилаються назад до -початкового чату, а наступне повідомлення в черзі відповідає на цей запит нативного -сервера замість того, щоб спрямовуватися як додатковий контекст. Інші запити MCP на отримання даних -і далі завершуються помилкою безпечним способом. +вихідного чату, а наступне поставлене в чергу follow-up повідомлення відповідає на цей нативний +запит сервера, замість того щоб спрямовуватися як додатковий контекст. Інші запити elicitation MCP, як і раніше, завершуються помилкою безпеки. Коли вибрана модель використовує harness Codex, нативна Compaction потоку -делегується app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу, +делегується Codex app-server. OpenClaw зберігає дзеркало транскрипту для історії каналу, пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало -містить prompt користувача, фінальний текст асистента та полегшені записи міркування або плану Codex, коли app-server їх надсилає. Наразі OpenClaw лише записує сигнали початку та завершення нативної Compaction. Він іще не показує -людинозрозумілий підсумок Compaction або аудитований список того, які записи Codex +включає prompt користувача, фінальний текст асистента та полегшені записи міркувань або плану Codex, коли їх генерує app-server. Наразі OpenClaw лише записує сигнали початку й завершення нативної Compaction. Він поки що не показує +людинозрозумілий підсумок Compaction або придатний для аудиту список записів, які Codex зберіг після Compaction. Оскільки Codex володіє канонічним нативним потоком, `tool_result_persist` наразі не -переписує записи результатів нативних інструментів Codex. Він застосовується лише коли -OpenClaw записує результат інструмента в транскрипт сесії, яким володіє OpenClaw. +переписує записи результатів нативних інструментів Codex. Він застосовується лише тоді, коли +OpenClaw записує результат інструмента у транскрипт сесії, яким володіє OpenClaw. -Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і розуміння медіа -і далі використовують відповідні налаштування провайдера/моделі, як-от +Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і +розуміння медіа, як і раніше, використовують відповідні налаштування провайдера/моделі, як-от `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і `messages.tts`. ## Усунення несправностей -**Codex не з’являється як звичайний провайдер `/model`:** це очікувано для +**Codex не з’являється як звичайний провайдер `/model`:** це очікувана поведінка для нових конфігурацій. Виберіть модель `openai/gpt-*` з -`agentRuntime.id: "codex"` (або застаріле посилання `codex/*`), увімкніть -`plugins.entries.codex.enabled` і перевірте, чи `plugins.allow` не виключає +`agentRuntime.id: "codex"` (або застарілим посиланням `codex/*`), увімкніть +`plugins.entries.codex.enabled` і перевірте, чи не виключає `plugins.allow` `codex`. **OpenClaw використовує PI замість Codex:** `agentRuntime.id: "auto"` усе ще може використовувати PI як -backend сумісності, коли жоден harness Codex не бере виконання на себе. Встановіть -`agentRuntime.id: "codex"`, щоб примусово вибрати Codex під час тестування. Примусове -runtime Codex тепер завершується помилкою замість переходу на PI, якщо ви -явно не встановили `agentRuntime.fallback: "pi"`. Щойно app-server Codex -вибрано, його збої проявляються безпосередньо без додаткової конфігурації резервного варіанта. +бекенд сумісності, коли жоден harness Codex не бере на себе виконання. Встановіть +`agentRuntime.id: "codex"`, щоб примусово вибрати Codex під час тестування. Тепер +примусове середовище виконання Codex завершується помилкою замість переходу до PI, якщо ви +явно не встановите `agentRuntime.fallback: "pi"`. Щойно буде +вибрано Codex app-server, його помилки відображаються безпосередньо без додаткової конфігурації резервного варіанта. **app-server відхиляється:** оновіть Codex так, щоб handshake app-server повідомляв версію `0.125.0` або новішу. Попередні випуски тієї самої версії або версії із суфіксом збірки, як-от `0.125.0-alpha.2` або `0.125.0+custom`, відхиляються, оскільки -стабільна нижня межа протоколу `0.125.0` — це те, що тестує OpenClaw. +стабільний поріг протоколу `0.125.0` — це те, що тестує OpenClaw. -**Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` +**Виявлення моделі повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` або вимкніть виявлення. **Транспорт WebSocket одразу завершується помилкою:** перевірте `appServer.url`, `authToken` -і що віддалений app-server використовує ту саму версію протоколу app-server Codex. +і те, що віддалений app-server використовує ту саму версію протоколу Codex app-server. -**Модель не Codex використовує PI:** це очікувано, якщо ви не примусово встановили +**Модель не Codex використовує PI:** це очікувана поведінка, якщо ви не примусово встановили `agentRuntime.id: "codex"` для цього агента або не вибрали застаріле -посилання `codex/*`. Звичайні `openai/gpt-*` та інші посилання провайдерів залишаються на своєму -звичайному шляху провайдера в режимі `auto`. Якщо ви примусово встановите `agentRuntime.id: "codex"`, кожен вбудований -хід для цього агента має використовувати підтримувану Codex модель OpenAI. +посилання `codex/*`. Звичайні `openai/gpt-*` та інші посилання провайдерів залишаються на своєму звичайному +шляху провайдера в режимі `auto`. Якщо ви примусово задасте `agentRuntime.id: "codex"`, кожен вбудований +хід для цього агента має бути моделлю OpenAI, яку підтримує Codex. **Computer Use встановлено, але інструменти не працюють:** перевірте -`/codex computer-use status` із нової сесії. Якщо інструмент повідомляє -`Native hook relay unavailable`, використайте `/new` або `/reset`; якщо це не допомагає, перезапустіть +`/codex computer-use status` у новій сесії. Якщо інструмент повідомляє +`Native hook relay unavailable`, використайте `/new` або `/reset`; якщо проблема не зникає, перезапустіть gateway, щоб очистити застарілі реєстрації нативних hooks. Якщо `computer-use.list_apps` -перевищує час очікування, перезапустіть Codex Computer Use або Codex Desktop і повторіть спробу. +зависає за тайм-аутом, перезапустіть Codex Computer Use або Codex Desktop і повторіть спробу. ## Пов’язане @@ -906,6 +913,6 @@ gateway, щоб очистити застарілі реєстрації нат - [Провайдери моделей](/uk/concepts/model-providers) - [Провайдер OpenAI](/uk/providers/openai) - [Стан](/uk/cli/status) -- [Хуки Plugin](/uk/plugins/hooks) -- [Довідник із конфігурації](/uk/gateway/configuration-reference) +- [Hooks Plugin](/uk/plugins/hooks) +- [Довідник з конфігурації](/uk/gateway/configuration-reference) - [Тестування](/uk/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/uk/plugins/compatibility.md b/docs/uk/plugins/compatibility.md index 4232208fa..b84bd9c2d 100644 --- a/docs/uk/plugins/compatibility.md +++ b/docs/uk/plugins/compatibility.md @@ -1,61 +1,61 @@ --- read_when: - - Ви підтримуєте plugin OpenClaw - - Ви бачите попередження про сумісність plugin - - Ви плануєте міграцію SDK plugin або маніфесту + - Ви підтримуєте Plugin OpenClaw + - Ви бачите попередження про сумісність Plugin + - Ви плануєте міграцію SDK Plugin або маніфесту summary: Контракти сумісності Plugin, метадані застарівання та очікування щодо міграції title: Сумісність Plugin x-i18n: - generated_at: "2026-04-27T14:18:59Z" + generated_at: "2026-04-28T00:34:00Z" model: gpt-5.4 provider: openai - source_hash: bfe6896830a9493660b064a17ee2e082ae5bf5b43222a5652f0b37116332e997 + source_hash: f097e51beb57790dc8b491793edb398adf3ab0457cc2404f5fe4b1c89159d112 source_path: plugins/compatibility.md workflow: 15 --- -OpenClaw зберігає старіші контракти Plugin підключеними через іменовані -адаптери сумісності перед їх видаленням. Це захищає наявні вбудовані й зовнішні -plugins, поки розвиваються контракти SDK, маніфесту, налаштування, конфігурації -та середовища виконання агента. +OpenClaw зберігає старі контракти сумісності Plugin, підключені через іменовані +адаптери сумісності, перш ніж видаляти їх. Це захищає наявні вбудовані та зовнішні +Plugins, поки розвиваються контракти SDK, маніфесту, налаштування, конфігурації та +середовища виконання агента. ## Реєстр сумісності Контракти сумісності Plugin відстежуються в основному реєстрі за адресою `src/plugins/compat/registry.ts`. -Кожен запис містить: +Кожен запис має: - стабільний код сумісності -- статус: `active`, `deprecated`, `removal-pending` або `removed` -- власника: SDK, config, setup, channel, provider, виконання plugin, середовище виконання агента +- status: `active`, `deprecated`, `removal-pending` або `removed` +- owner: SDK, config, setup, channel, provider, виконання plugin, середовище виконання агента або core -- дати запровадження та застарівання, якщо застосовно -- вказівки щодо заміни -- документацію, діагностику й тести, які покривають стару та нову поведінку +- дати впровадження та застарівання, коли це застосовно +- рекомендації щодо заміни +- docs, diagnostics і тести, які охоплюють стару й нову поведінку -Реєстр є джерелом для планування супровідниками та майбутніх перевірок -інспектора plugin. Якщо змінюється поведінка, видима для plugin, додайте або +Реєстр є джерелом для планування супроводжувачів і майбутніх перевірок +інспектора plugin. Якщо змінюється поведінка, видима для Plugin, додайте або оновіть запис сумісності в тій самій зміні, що додає адаптер. -Сумісність відновлення doctor і міграції відстежується окремо в +Сумісність repair і міграції для doctor відстежується окремо в `src/commands/doctor/shared/deprecation-compat.ts`. Ці записи охоплюють старі -форми конфігурації, макети журналу встановлення й шими відновлення, які можуть -потребувати збереження після видалення шляху сумісності середовища виконання. +форми конфігурації, макети журналу встановлення та repair shim-и, які, можливо, +потрібно буде залишити доступними після видалення шляху сумісності середовища виконання. -Під час перевірок перед випуском слід перевіряти обидва реєстри. Не видаляйте -міграцію doctor лише тому, що відповідний запис сумісності середовища -виконання або конфігурації втратив чинність; спочатку перевірте, що не -залишилося підтримуваного шляху оновлення, який усе ще потребує цього -відновлення. Також повторно перевіряйте кожну анотацію заміни під час -планування випуску, оскільки володіння plugin і охоплення конфігурації можуть -змінюватися, коли providers і channels виносяться з core. +Під час перевірок перед релізом слід перевіряти обидва реєстри. Не видаляйте +міграцію doctor лише тому, що відповідний запис сумісності середовища виконання +або конфігурації втратив чинність; спочатку переконайтеся, що немає +підтримуваного шляху оновлення, який усе ще потребує repair. Також повторно +перевіряйте кожну анотацію заміни під час планування релізу, оскільки +відповідальність за plugin і обсяг конфігурації можуть змінюватися, коли +providers і channels виносяться з core. ## Пакет інспектора plugin -Інспектор plugin має розміщуватися поза основним репозиторієм OpenClaw як -окремий пакет/репозиторій, що спирається на версіоновані контракти сумісності -й маніфесту. +Інспектор plugin має жити поза основним репозиторієм OpenClaw як окремий +пакет/репозиторій, що спирається на версіоновані контракти сумісності та +маніфесту. CLI першого дня має бути таким: @@ -65,36 +65,35 @@ openclaw-plugin-inspector ./my-plugin Він має виводити: -- перевірку маніфесту/схеми -- версію контракту сумісності, яка перевіряється +- валідацію маніфесту/схеми +- версію сумісності контракту, яка перевіряється - перевірки метаданих встановлення/джерела - перевірки імпорту холодного шляху - попередження про застарівання та сумісність -Використовуйте `--json` для стабільного машинозчитуваного виводу в анотаціях -CI. Core OpenClaw має надавати контракти й фікстури, які інспектор може -використовувати, але не повинен публікувати бінарний файл інспектора з -основного пакета `openclaw`. +Використовуйте `--json` для стабільного машиночитного виводу в анотаціях CI. Core +OpenClaw має надавати контракти й фікстури, які може споживати інспектор, але не +повинен публікувати двійковий файл інспектора з основного пакета `openclaw`. ## Політика застарівання OpenClaw не повинен видаляти задокументований контракт Plugin у тому самому -випуску, в якому запроваджується його заміна. +релізі, у якому впроваджується його заміна. Послідовність міграції така: 1. Додайте новий контракт. 2. Залиште стару поведінку підключеною через іменований адаптер сумісності. -3. Виводьте діагностику або попередження, коли автори plugin уже можуть діяти. -4. Задокументуйте заміну та часову шкалу. +3. Виводьте diagnostics або warnings, коли автори Plugins можуть діяти. +4. Задокументуйте заміну та часові рамки. 5. Протестуйте і старий, і новий шляхи. 6. Дочекайтеся завершення оголошеного вікна міграції. 7. Видаляйте лише за явного схвалення для релізу з несумісними змінами. -Записи зі статусом deprecated мають містити дату початку попередження, заміну, -посилання на документацію та остаточну дату видалення не пізніше ніж через три -місяці після початку попередження. Не додавайте застарілий шлях сумісності з -відкритим строком видалення, якщо супровідники явно не вирішили, що це +Записи зі статусом deprecated мають містити дату початку попереджень, заміну, +посилання на docs і остаточну дату видалення не пізніше ніж через три місяці +після початку попереджень. Не додавайте застарілий шлях сумісності з +невизначеним вікном видалення, якщо супроводжувачі явно не вирішили, що це постійна сумісність, і не позначили його як `active`. ## Поточні області сумісності @@ -102,49 +101,52 @@ OpenClaw не повинен видаляти задокументований Поточні записи сумісності включають: - застарілі широкі імпорти SDK, такі як `openclaw/plugin-sdk/compat` -- застарілі форми plugin лише для hook і `before_agent_start` +- застарілі форми plugin лише з hook-ами та `before_agent_start` - застарілі точки входу plugin `activate(api)`, поки plugins мігрують на `register(api)` - застарілі псевдоніми SDK, такі як `openclaw/extension-api`, - `openclaw/plugin-sdk/channel-runtime`, `openclaw/plugin-sdk/command-auth` - status builders, `openclaw/plugin-sdk/test-utils` і псевдоніми типів `ClawdbotConfig` / + `openclaw/plugin-sdk/channel-runtime`, побудовники status для `openclaw/plugin-sdk/command-auth`, + `openclaw/plugin-sdk/test-utils` і псевдоніми типів `ClawdbotConfig` / `OpenClawSchemaType` -- поведінку allowlist і ввімкнення вбудованих plugins -- застарілі метадані маніфесту env var для provider/channel -- застарілі hooks plugin provider і псевдоніми типів, поки providers - переходять на явні hooks для catalog, auth, thinking, replay і transport +- allowlist вбудованих plugins і поведінка ввімкнення +- застарілі метадані маніфесту env-var для provider/channel +- застарілі hook-и provider plugin і псевдоніми типів, поки providers переходять на + явні hook-и catalog, auth, thinking, replay і transport - застарілі псевдоніми середовища виконання, такі як `api.runtime.taskFlow`, - `api.runtime.subagent.getSession`, `api.runtime.stt` і застарілі + `api.runtime.subagent.getSession`, `api.runtime.stt`, а також застарілі `api.runtime.config.loadConfig()` / `api.runtime.config.writeConfigFile(...)` -- застарілу розділену реєстрацію memory-plugin, поки plugins пам’яті переходять на +- застаріла розділена реєстрація memory-plugin, поки memory plugins переходять на `registerMemoryCapability` -- застарілі допоміжні засоби SDK channel для нативних схем повідомлень, обмеження - згадок, форматування вхідних envelope та вкладення можливостей погодження -- підказки активації, які замінюються володінням внесками маніфесту -- резервний шлях середовища виконання `setup-api`, поки дескриптори setup - переходять на холодні метадані `setup.requiresRuntime: false` -- hooks provider `discovery`, поки hooks каталогу provider переходять на +- застарілі допоміжні засоби channel SDK для нативних схем повідомлень, обмеження згадок, + форматування вхідного envelope та вкладеності можливостей схвалення +- застарілі псевдоніми ключа маршруту channel і допоміжних засобів comparable-target, поки plugins + переходять на `openclaw/plugin-sdk/channel-route` +- підказки активації, які замінюються відповідальністю внеску маніфесту +- резервний шлях середовища виконання `setup-api`, поки дескриптори setup переходять на холодні + метадані `setup.requiresRuntime: false` +- hook-и provider `discovery`, поки hook-и каталогу provider переходять на `catalog.run(...)` -- метадані channel `showConfigured` / `showInSetup`, поки пакети channel - переходять на `openclaw.channel.exposure` +- метадані channel `showConfigured` / `showInSetup`, поки пакети channel переходять до + `openclaw.channel.exposure` - застарілі ключі конфігурації runtime-policy, поки doctor мігрує операторів на `agentRuntime` -- резервне використання згенерованих метаданих конфігурації вбудованих channel, поки - з’являються метадані `channelConfigs` у стилі registry-first -- прапорці середовища для вимкнення збереженого реєстру plugin і міграції встановлення, поки - потоки відновлення мігрують операторів на `openclaw plugins registry --refresh` і +- резервний шлях згенерованих метаданих конфігурації вбудованого channel, поки впроваджуються + метадані `channelConfigs`, орієнтовані на реєстр +- прапорці env для persisted plugin registry disable та install-migration, поки + потоки repair мігрують операторів на `openclaw plugins registry --refresh` і `openclaw doctor --fix` -- застарілі шляхи конфігурації `plugins.installs`, створені авторами, і псевдоніми шляхів - завантаження вбудованих plugin, поки метадані встановлення переходять до - керованого станом журналу plugin +- застарілі шляхи конфігурації web search, web fetch і x_search, що належать plugin, поки + doctor мігрує їх до `plugins.entries..config` +- застаріла авторська конфігурація `plugins.installs` і псевдоніми шляхів завантаження вбудованих plugin, поки + метадані встановлення переносяться до керованого станом журналу plugin -Новий код plugin має використовувати заміну, зазначену в реєстрі та в -конкретному посібнику з міграції. Наявні plugins можуть і надалі -використовувати шлях сумісності, доки документація, діагностика та примітки до -випуску не оголосять вікно видалення. +Новий код plugin має надавати перевагу заміні, зазначеній у реєстрі та в +конкретному посібнику з міграції. Наявні plugins можуть і далі використовувати +шлях сумісності, доки docs, diagnostics і примітки до релізу не оголосять +вікно видалення. -## Примітки до випуску +## Примітки до релізу -Примітки до випуску мають містити майбутні застарівання Plugin із цільовими -датами та посиланнями на документацію з міграції. Таке попередження має -з’явитися до того, як шлях сумісності перейде в `removal-pending` або `removed`. +Примітки до релізу мають містити майбутні застарівання plugin із цільовими +датами та посиланнями на docs міграції. Це попередження має з’явитися до того, +як шлях сумісності перейде в `removal-pending` або `removed`. diff --git a/docs/uk/plugins/hooks.md b/docs/uk/plugins/hooks.md index 993b2af2a..b30a2e213 100644 --- a/docs/uk/plugins/hooks.md +++ b/docs/uk/plugins/hooks.md @@ -2,29 +2,29 @@ read_when: - Ви створюєте plugin, якому потрібні `before_tool_call`, `before_agent_reply`, хуки повідомлень або хуки життєвого циклу - Вам потрібно блокувати, переписувати або вимагати схвалення для викликів інструментів із plugin - - 'Ви вирішуєте, що вибрати: внутрішні хуки чи хуки Plugin' + - Ви обираєте між внутрішніми хуками та хуками plugin summary: 'Хуки Plugin: перехоплюють події життєвого циклу агента, інструмента, повідомлення, сесії та Gateway' -title: хуки Plugin +title: Хуки Plugin x-i18n: - generated_at: "2026-04-28T00:10:39Z" + generated_at: "2026-04-28T00:34:03Z" model: gpt-5.4 provider: openai - source_hash: 2bdc52ada8f8949f24b7930ee1daac254477ef678396ea61102775173f68e0d5 + source_hash: 689f4c15058f03cff1feb2a8aa1450c75cc3f8648d8ac7cc03ea952b3a1975bd source_path: plugins/hooks.md workflow: 15 --- -Хуки Plugin — це точки розширення в процесі виконання для plugin OpenClaw. Використовуйте їх, +Хуки Plugin — це внутрішньопроцесні точки розширення для plugin у OpenClaw. Використовуйте їх, коли plugin має перевіряти або змінювати запуски агента, виклики інструментів, потік повідомлень, життєвий цикл сесії, маршрутизацію субагентів, встановлення або запуск Gateway. -Натомість використовуйте [внутрішні хуки](/uk/automation/hooks), коли вам потрібен невеликий -скрипт `HOOK.md`, встановлений оператором, для подій команд і Gateway, таких як +Натомість використовуйте [внутрішні хуки](/uk/automation/hooks), якщо вам потрібен невеликий +встановлюваний оператором скрипт `HOOK.md` для подій команд і Gateway, таких як `/new`, `/reset`, `/stop`, `agent:bootstrap` або `gateway:startup`. ## Швидкий старт -Зареєструйте типізовані хуки plugin за допомогою `api.on(...)` з точки входу вашого plugin: +Зареєструйте типізовані хуки plugin за допомогою `api.on(...)` у точці входу вашого plugin: ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -56,35 +56,34 @@ export default definePluginEntry({ }); ``` -Обробники хуків виконуються послідовно в порядку спадання `priority`. Хуки з -однаковим пріоритетом зберігають порядок реєстрації. +Обробники хуків виконуються послідовно у порядку спадання `priority`. Хуки з однаковим пріоритетом +зберігають порядок реєстрації. -Кожен хук отримує `event.context.pluginConfig` — обчислену конфігурацію для -plugin, який зареєстрував цей обробник. Використовуйте її для рішень у хуках, -яким потрібні поточні параметри plugin; OpenClaw додає її для кожного -обробника без змінювання спільного об’єкта події, який бачать інші plugins. +Кожен хук отримує `event.context.pluginConfig` — обчислену конфігурацію для plugin, який зареєстрував цей обробник. Використовуйте її для рішень хуків, яким потрібні +поточні параметри plugin; OpenClaw додає її окремо для кожного обробника, не змінюючи +спільний об’єкт події, який бачать інші plugin. ## Каталог хуків Хуки згруповані за поверхнею, яку вони розширюють. Назви **жирним** приймають -результат рішення (блокування, скасування, перевизначення або вимога схвалення); -усі інші призначені лише для спостереження. +результат рішення (блокування, скасування, перевизначення або вимога схвалення); усі інші +призначені лише для спостереження. **Хід агента** - `before_model_resolve` — перевизначити провайдера або модель до завантаження повідомлень сесії -- `agent_turn_prepare` — спожити поставлені в чергу ін’єкції ходу plugin і додати контекст того самого ходу до хуків промпта -- `before_prompt_build` — додати динамічний контекст або текст системного промпта до виклику моделі -- `before_agent_start` — комбінована фаза лише для сумісності; натомість віддавайте перевагу двом хукам вище -- **`before_agent_reply`** — перервати хід моделі синтетичною відповіддю або безшумно +- `agent_turn_prepare` — спожити поставлені в чергу ін’єкції ходу plugin і додати контекст цього ж ходу перед хуками prompt +- `before_prompt_build` — додати динамічний контекст або текст системного prompt перед викликом моделі +- `before_agent_start` — сумісна об’єднана фаза; натомість віддавайте перевагу двом хукам вище +- **`before_agent_reply`** — замкнути хід моделі достроково синтетичною відповіддю або тишею - **`before_agent_finalize`** — перевірити природну фінальну відповідь і запросити ще один прохід моделі -- `agent_end` — спостерігати фінальні повідомлення, стан успіху та тривалість запуску -- `heartbeat_prompt_contribution` — додати контекст лише для Heartbeat для фонових моніторів і plugin життєвого циклу +- `agent_end` — спостерігати фінальні повідомлення, стан успішності та тривалість запуску +- `heartbeat_prompt_contribution` — додати контекст лише для heartbeat для фонових моніторів і plugin життєвого циклу **Спостереження за розмовою** -- `model_call_started` / `model_call_ended` — спостерігати очищені метадані виклику провайдера/моделі, час, результат і обмежені хеші request-id без вмісту промпта або відповіді -- `llm_input` — спостерігати вхід провайдера (системний промпт, промпт, історія) +- `model_call_started` / `model_call_ended` — спостерігати санітовані метадані виклику провайдера/моделі, час, результат і обмежені хеші request-id без вмісту prompt або відповіді +- `llm_input` — спостерігати вхід провайдера (системний prompt, prompt, історію) - `llm_output` — спостерігати вихід провайдера **Інструменти** @@ -92,15 +91,15 @@ plugin, який зареєстрував цей обробник. Викори - **`before_tool_call`** — переписати параметри інструмента, заблокувати виконання або вимагати схвалення - `after_tool_call` — спостерігати результати інструмента, помилки та тривалість - **`tool_result_persist`** — переписати повідомлення помічника, створене з результату інструмента -- **`before_message_write`** — перевірити або заблокувати запис повідомлення в процесі (рідко) +- **`before_message_write`** — перевірити або заблокувати запис повідомлення, що виконується (рідко) -**Повідомлення та доставка** +**Повідомлення і доставка** - **`inbound_claim`** — перехопити вхідне повідомлення до маршрутизації агента (синтетичні відповіді) -- `message_received` — спостерігати вхідний вміст, відправника, гілку та метадані +- `message_received` — спостерігати вхідний вміст, відправника, потік і метадані - **`message_sending`** — переписати вихідний вміст або скасувати доставку -- `message_sent` — спостерігати успіх або збій вихідної доставки -- **`before_dispatch`** — перевірити або переписати вихідне dispatch до передавання каналу +- `message_sent` — спостерігати успіх або невдачу вихідної доставки +- **`before_dispatch`** — перевірити або переписати вихідне dispatch перед передачею каналу - **`reply_dispatch`** — брати участь у фінальному конвеєрі dispatch відповіді **Сесії та Compaction** @@ -111,7 +110,7 @@ plugin, який зареєстрував цей обробник. Викори **Субагенти** -- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — координувати маршрутизацію субагентів і доставку після завершення +- `subagent_spawning` / `subagent_delivery_target` / `subagent_spawned` / `subagent_ended` — координувати маршрутизацію субагентів і доставку завершення **Життєвий цикл** @@ -127,7 +126,7 @@ plugin, який зареєстрував цей обробник. Викори - необов’язковий `event.runId` - необов’язковий `event.toolCallId` - поля контексту, такі як `ctx.agentId`, `ctx.sessionKey`, `ctx.sessionId`, - `ctx.runId`, `ctx.jobId` (встановлюється для запусків, керованих cron), і діагностичний `ctx.trace` + `ctx.runId`, `ctx.jobId` (встановлюється для запусків, ініційованих cron), і діагностичний `ctx.trace` Він може повертати: @@ -153,59 +152,84 @@ type BeforeToolCallResult = { Правила: - `block: true` є термінальним і пропускає обробники з нижчим пріоритетом. -- `block: false` розглядається як відсутність рішення. +- `block: false` вважається відсутністю рішення. - `params` переписує параметри інструмента для виконання. -- `requireApproval` призупиняє запуск агента й запитує користувача через схвалення plugin. Команда `/approve` може схвалювати як exec, так і схвалення plugin. -- `block: true` із нижчим пріоритетом усе одно може заблокувати після того, як хук із вищим пріоритетом запросив схвалення. +- `requireApproval` призупиняє запуск агента і запитує користувача через схвалення plugin. + Команда `/approve` може схвалювати і exec-, і plugin-схвалення. +- `block: true` з нижчим пріоритетом усе ще може заблокувати після того, як хук із вищим пріоритетом + запросив схвалення. - `onResolution` отримує підсумкове рішення щодо схвалення — `allow-once`, `allow-always`, `deny`, `timeout` або `cancelled`. -Вбудовані plugins, яким потрібна політика рівня хоста, можуть реєструвати довірені політики інструментів через `api.registerTrustedToolPolicy(...)`. Вони виконуються до звичайних хуків `before_tool_call` і до рішень зовнішніх plugin. Використовуйте їх лише для довірених хостом бар’єрів, таких як політика робочого простору, контроль бюджету або безпека зарезервованих робочих процесів. Зовнішні plugins мають використовувати звичайні хуки `before_tool_call`. +Вбудовані plugin, яким потрібна політика на рівні хоста, можуть реєструвати довірені політики інструментів +за допомогою `api.registerTrustedToolPolicy(...)`. Вони виконуються до звичайних +хуків `before_tool_call` і до рішень зовнішніх plugin. Використовуйте їх лише +для довірених на рівні хоста обмежень, таких як політика робочого простору, контроль бюджету або +безпека зарезервованих робочих процесів. Зовнішні plugin мають використовувати звичайні хуки `before_tool_call`. -### Збереження результатів інструмента +### Збереження результатів інструментів -Результати інструмента можуть містити структуровані `details` для рендерингу в UI, діагностики, -маршрутизації медіа або метаданих, що належать plugin. Розглядайте `details` як -метадані часу виконання, а не як вміст промпта: +Результати інструментів можуть містити структуровані `details` для рендерингу в UI, діагностики, +маршрутизації медіа або метаданих, якими володіє plugin. Розглядайте `details` як метадані виконання, +а не як вміст prompt: -- OpenClaw видаляє `toolResult.details` перед повторним відтворенням провайдером і входом Compaction, щоб метадані не ставали контекстом моделі. -- Постійно збережені записи сесії містять лише обмежені `details`. Завеликі details замінюються компактним підсумком і `persistedDetailsTruncated: true`. -- `tool_result_persist` і `before_message_write` виконуються до фінального обмеження на постійне збереження. Хуки все одно мають тримати повернуті `details` малими й уникати розміщення тексту, релевантного для промпта, лише в `details`; видимий для моделі вихід інструмента слід поміщати в `content`. +- OpenClaw видаляє `toolResult.details` перед повторним програванням провайдеру та перед входом Compaction, + щоб метадані не ставали контекстом моделі. +- Збережені записи сесії містять лише обмежені `details`. Надмірно великі details + замінюються компактним підсумком і `persistedDetailsTruncated: true`. +- `tool_result_persist` і `before_message_write` виконуються до фінального + обмеження збереження. Усе ж хуки мають повертати невеликі `details` і уникати + розміщення тексту, важливого для prompt, лише в `details`; вивід інструмента, видимий моделі, + слід поміщати в `content`. -## Хуки промпта та моделі +## Хуки prompt і моделі -Для нових plugins використовуйте хуки, специфічні для фази: +Для нових plugin використовуйте хуки, специфічні для фази: -- `before_model_resolve`: отримує лише поточний промпт і метадані вкладень. Поверніть `providerOverride` або `modelOverride`. -- `agent_turn_prepare`: отримує поточний промпт, підготовлені повідомлення сесії та будь-які ін’єкції рівно-один-раз, зняті з черги для цієї сесії. Поверніть `prependContext` або `appendContext`. -- `before_prompt_build`: отримує поточний промпт і повідомлення сесії. Поверніть `prependContext`, `appendContext`, `systemPrompt`, `prependSystemContext` або `appendSystemContext`. -- `heartbeat_prompt_contribution`: виконується лише для ходів Heartbeat і повертає `prependContext` або `appendContext`. Призначений для фонових моніторів, яким потрібно підсумовувати поточний стан без зміни ходів, ініційованих користувачем. +- `before_model_resolve`: отримує лише поточний prompt і метадані вкладень. + Поверніть `providerOverride` або `modelOverride`. +- `agent_turn_prepare`: отримує поточний prompt, підготовлені повідомлення сесії + і будь-які ін’єкції, поставлені в чергу рівно один раз і вилучені для цієї сесії. Поверніть + `prependContext` або `appendContext`. +- `before_prompt_build`: отримує поточний prompt і повідомлення сесії. + Поверніть `prependContext`, `appendContext`, `systemPrompt`, + `prependSystemContext` або `appendSystemContext`. +- `heartbeat_prompt_contribution`: виконується лише для heartbeat-ходів і повертає + `prependContext` або `appendContext`. Він призначений для фонових моніторів, + яким потрібно підсумувати поточний стан без зміни ходів, ініційованих користувачем. -`before_agent_start` зберігається для сумісності. Віддавайте перевагу явним хукам вище, -щоб ваш plugin не залежав від застарілої комбінованої фази. +`before_agent_start` залишається для сумісності. Віддавайте перевагу явним хукам вище, +щоб ваш plugin не залежав від застарілої об’єднаної фази. `before_agent_start` і `agent_end` містять `event.runId`, коли OpenClaw може -визначити активний запуск. Те саме значення також доступне в `ctx.runId`. -Запуски, керовані Cron, також надають `ctx.jobId` (ідентифікатор вихідної Cron-задачі), щоб -хуки plugin могли прив’язувати метрики, побічні ефекти або стан до конкретної -запланованої задачі. +ідентифікувати активний запуск. Це саме значення також доступне в `ctx.runId`. +Запуски, ініційовані Cron, також надають `ctx.jobId` (ідентифікатор вихідного cron-завдання), щоб +хуки plugin могли прив’язувати метрики, побічні ефекти або стан до конкретного запланованого +завдання. -Використовуйте `model_call_started` і `model_call_ended` для телеметрії -викликів провайдера, яка не повинна отримувати сирі промпти, історію, відповіді, заголовки, тіла запитів або request ID провайдера. Ці хуки містять стабільні метадані, такі як -`runId`, `callId`, `provider`, `model`, необов’язкові `api`/`transport`, фінальні -`durationMs`/`outcome` та `upstreamRequestIdHash`, коли OpenClaw може вивести +`agent_end` — це хук спостереження, який виконується у режимі fire-and-forget після ходу. Runner +хуків застосовує тайм-аут у 30 секунд, щоб завислий plugin або embedding- +endpoint не могли залишити promise хука назавжди в очікуванні. Тайм-аут логуються, і +OpenClaw продовжує роботу; це не скасовує мережеву роботу plugin, +якщо plugin також не використовує власний сигнал abort. + +Використовуйте `model_call_started` і `model_call_ended` для телеметрії викликів провайдера, +яка не повинна отримувати сирі prompt, історію, відповіді, заголовки, тіла +запитів або request ID провайдера. Ці хуки містять стабільні метадані, такі як +`runId`, `callId`, `provider`, `model`, необов’язкові `api`/`transport`, +фінальні `durationMs`/`outcome` і `upstreamRequestIdHash`, коли OpenClaw може отримати обмежений хеш request-id провайдера. `before_agent_finalize` виконується лише тоді, коли harness збирається прийняти природну -фінальну відповідь помічника. Це не шлях скасування `/stop`, і він не -виконується, коли користувач перериває хід. Поверніть `{ action: "revise", reason }`, щоб -попросити harness виконати ще один прохід моделі до фіналізації, `{ action: -"finalize", reason? }`, щоб примусово завершити фіналізацію, або не повертайте результат, щоб продовжити. -Власні хуки `Stop` у Codex передаються в цей хук як рішення OpenClaw +фінальну відповідь асистента. Це не шлях скасування `/stop`, і він не виконується, +коли користувач перериває хід. Поверніть `{ action: "revise", reason }`, щоб +попросити harness зробити ще один прохід моделі перед фіналізацією, `{ action: +"finalize", reason? }`, щоб примусово фіналізувати, або не повертайте результат, +щоб продовжити. Вбудовані в Codex хуки `Stop` передаються в цей хук як рішення OpenClaw `before_agent_finalize`. -Невбудовані plugins, яким потрібні `llm_input`, `llm_output`, -`before_agent_finalize` або `agent_end`, мають встановити: +Невбудовані plugin, яким потрібні `llm_input`, `llm_output`, +`before_agent_finalize` або `agent_end`, мають задати: ```json { @@ -221,32 +245,28 @@ type BeforeToolCallResult = { } ``` -Хуки, що змінюють промпт, і стійкі ін’єкції наступного ходу можна вимкнути для кожного plugin +Хуки, що змінюють prompt, і стійкі ін’єкції наступного ходу можна вимкнути для кожного plugin через `plugins.entries..hooks.allowPromptInjection=false`. ### Розширення сесії та ін’єкції наступного ходу -Workflow plugins можуть зберігати невеликий JSON-сумісний стан сесії за допомогою +Plugin для workflow можуть зберігати невеликий JSON-сумісний стан сесії за допомогою `api.registerSessionExtension(...)` і оновлювати його через метод Gateway -`sessions.pluginPatch`. Рядки сесії проєктують зареєстрований стан розширення через -`pluginExtensions`, що дозволяє Control UI та іншим клієнтам відображати -стан, який належить plugin, без вивчення внутрішньої реалізації plugin. +`sessions.pluginPatch`. Рядки сесій проєктують стан зареєстрованого розширення через +`pluginExtensions`, даючи змогу Control UI та іншим клієнтам відображати +стан, що належить plugin, без знання внутрішньої логіки plugin. -Використовуйте `api.enqueueNextTurnInjection(...)`, коли plugin потрібен стійкий контекст, який -має потрапити до наступного ходу моделі рівно один раз. OpenClaw знімає поставлені в чергу ін’єкції до -хуків промпта, відкидає прострочені ін’єкції та усуває дублікати за `idempotencyKey` -для кожного plugin. Це правильна точка інтеграції для відновлення після схвалення, -підсумків політик, змін від фонового монітора та продовжень команд, які -мають бути видимі моделі на наступному ході, але не повинні ставати постійним -текстом системного промпта. +Використовуйте `api.enqueueNextTurnInjection(...)`, коли plugin має передати стійкий контекст +до наступного ходу моделі рівно один раз. OpenClaw вилучає поставлені в чергу ін’єкції перед +хуками prompt, відкидає прострочені ін’єкції та усуває дублікати за `idempotencyKey` +для кожного plugin. Це правильна точка розширення для відновлення після схвалень, підсумків політик, +дельт фонових моніторів і продовжень команд, які мають бути видимі +моделі на наступному ході, але не повинні ставати постійним текстом системного prompt. -Семантика очищення є частиною контракту. Зворотні виклики очищення розширень сесії та -очищення життєвого циклу часу виконання отримують `reset`, `delete`, `disable` або -`restart`. Хост видаляє постійний стан розширення сесії плагіна-власника та -очікувані ін’єкції наступного ходу для `reset`/`delete`/`disable`; `restart` зберігає -стійкий стан сесії, а зворотні виклики очищення дають plugins змогу звільняти -задачі планувальника, контекст виконання та інші позасмугові ресурси для старого -покоління часу виконання. +Семантика очищення є частиною контракту. Зворотні виклики очищення розширень сесії та очищення життєвого циклу runtime отримують `reset`, `delete`, `disable` або +`restart`. Хост видаляє стан постійного розширення сесії та очікувані ін’єкції наступного ходу, +що належать plugin, для `reset`/`delete`/`disable`; `restart` зберігає стійкий стан сесії, тоді як зворотні виклики очищення дають plugin змогу звільнити завдання планувальника, +контекст запуску та інші зовнішні ресурси старого покоління runtime. ## Хуки повідомлень @@ -255,72 +275,70 @@ Workflow plugins можуть зберігати невеликий JSON-сум - `message_received`: спостерігати вхідний вміст, відправника, `threadId`, `messageId`, `senderId`, необов’язкову кореляцію запуску/сесії та метадані. - `message_sending`: переписати `content` або повернути `{ cancel: true }`. -- `message_sent`: спостерігати фінальний успіх або збій. +- `message_sent`: спостерігати фінальний успіх або невдачу. -Для відповідей TTS лише з аудіо `content` може містити приховану транскрипцію -озвученого тексту, навіть якщо payload каналу не має видимого тексту/підпису. Переписування цього -`content` оновлює лише видиму для хука транскрипцію; воно не відображається як +Для TTS-відповідей лише з аудіо `content` може містити прихований озвучений транскрипт, +навіть якщо payload каналу не має видимого тексту/підпису. Переписування цього +`content` оновлює лише транскрипт, видимий хуку; він не відображається як підпис медіа. Контексти хуків повідомлень надають стабільні поля кореляції, коли вони доступні: `ctx.sessionKey`, `ctx.runId`, `ctx.messageId`, `ctx.senderId`, `ctx.trace`, `ctx.traceId`, `ctx.spanId`, `ctx.parentSpanId` і `ctx.callDepth`. Віддавайте перевагу -цим полям першого класу, перш ніж звертатися до застарілих метаданих. +цим полям першого класу, перш ніж читати застарілі метадані. -Віддавайте перевагу типізованим полям `threadId` і `replyToId`, перш ніж використовувати -метадані, специфічні для каналу. +Віддавайте перевагу типізованим полям `threadId` і `replyToId` перед використанням +метаданих, специфічних для каналу. Правила рішень: - `message_sending` з `cancel: true` є термінальним. -- `message_sending` з `cancel: false` розглядається як відсутність рішення. -- Переписаний `content` передається далі хукам із нижчим пріоритетом, якщо пізніший хук +- `message_sending` з `cancel: false` вважається відсутністю рішення. +- Переписаний `content` передається хукам із нижчим пріоритетом, якщо пізніший хук не скасує доставку. ## Хуки встановлення -`before_install` виконується після вбудованого сканування для встановлень skill і plugin. -Поверніть додаткові результати або `{ block: true, blockReason }`, щоб зупинити +`before_install` виконується після вбудованого сканування встановлень skill і plugin. +Поверніть додаткові результати перевірки або `{ block: true, blockReason }`, щоб зупинити встановлення. -`block: true` є термінальним. `block: false` розглядається як відсутність рішення. +`block: true` є термінальним. `block: false` вважається відсутністю рішення. ## Життєвий цикл Gateway Використовуйте `gateway_start` для сервісів plugin, яким потрібен стан, що належить Gateway. Контекст -надає `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для -перевірки та оновлення cron. Використовуйте `gateway_stop`, щоб очищати довготривалі -ресурси. +надає `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для перевірки й оновлення +cron. Використовуйте `gateway_stop` для очищення довготривалих ресурсів. -Не покладайтеся на внутрішній хук `gateway:startup` для сервісів часу виконання, -що належать plugin. +Не покладайтеся на внутрішній хук `gateway:startup` для runtime-сервісів, що належать plugin. ## Майбутні застарівання -Кілька поверхонь, суміжних із хуками, застаріли, але все ще підтримуються. Виконайте -міграцію до наступного мажорного релізу: +Кілька поверхонь, суміжних із хуками, є застарілими, але все ще підтримуються. Перейдіть +на нові варіанти до наступного мажорного релізу: -- **Незашифровані конверти каналу** в обробниках `inbound_claim` і `message_received`. +- **Конверти каналів у відкритому тексті** в обробниках `inbound_claim` і `message_received`. Читайте `BodyForAgent` і структуровані блоки контексту користувача - замість парсингу плоского тексту конверта. Див. - [Незашифровані конверти каналу → BodyForAgent](/uk/plugins/sdk-migration#active-deprecations). -- **`before_agent_start`** зберігається для сумісності. Нові plugins мають використовувати - `before_model_resolve` і `before_prompt_build` замість комбінованої + замість розбору плоского тексту конверта. Див. + [Конверти каналів у відкритому тексті → BodyForAgent](/uk/plugins/sdk-migration#active-deprecations). +- **`before_agent_start`** залишається для сумісності. Нові plugin повинні використовувати + `before_model_resolve` і `before_prompt_build` замість об’єднаної фази. - **`onResolution` у `before_tool_call`** тепер використовує типізоване об’єднання `PluginApprovalResolution` (`allow-once` / `allow-always` / `deny` / `timeout` / `cancelled`) замість довільного `string`. Повний список — реєстрація можливостей пам’яті, профіль thinking провайдера, -зовнішні провайдери автентифікації, типи виявлення провайдерів, аксесори часу виконання задач +зовнішні провайдери автентифікації, типи виявлення провайдера, runtime-аксесори завдань і перейменування `command-auth` → `command-status` — див. у [Міграція Plugin SDK → Активні застарівання](/uk/plugins/sdk-migration#active-deprecations). ## Пов’язане -- [Міграція Plugin SDK](/uk/plugins/sdk-migration) — активні застарівання та графік видалення -- [Створення plugins](/uk/plugins/building-plugins) +- [Міграція Plugin SDK](/uk/plugins/sdk-migration) — активні застарівання та часові рамки видалення +- [Створення plugin](/uk/plugins/building-plugins) - [Огляд Plugin SDK](/uk/plugins/sdk-overview) - [Точки входу Plugin](/uk/plugins/sdk-entrypoints) - [Внутрішні хуки](/uk/automation/hooks) -- [Внутрішня архітектура Plugin](/uk/plugins/architecture-internals) +- [Внутрішня архітектура plugin](/uk/plugins/architecture-internals) diff --git a/docs/uk/plugins/memory-lancedb.md b/docs/uk/plugins/memory-lancedb.md index e141f7d7b..fc5cb7227 100644 --- a/docs/uk/plugins/memory-lancedb.md +++ b/docs/uk/plugins/memory-lancedb.md @@ -1,34 +1,26 @@ --- read_when: - - Ви налаштовуєте вбудований плагін memory-lancedb - - Вам потрібна довготривала пам’ять на базі LanceDB з автоматичним пригадуванням або автоматичним збереженням + - Ви налаштовуєте вбудований Plugin memory-lancedb + - Вам потрібна довготривала пам’ять на базі LanceDB з автоматичним пригадуванням або автоматичним захопленням - Ви використовуєте локальні ембединги, сумісні з OpenAI, наприклад Ollama sidebarTitle: Memory LanceDB -summary: Налаштуйте вбудований плагін пам’яті LanceDB, включно з локальними ембедингами, сумісними з Ollama +summary: Налаштування вбудованого Plugin пам’яті LanceDB, зокрема локальних ембедингів, сумісних з Ollama title: Пам’ять LanceDB x-i18n: - generated_at: "2026-04-28T00:03:39Z" + generated_at: "2026-04-28T00:34:22Z" model: gpt-5.4 provider: openai - source_hash: e3d0e1a286dfae36967a04863c047f40b629656efa62364c65e67283d3c7a945 + source_hash: b6e7b8b1b391d6f72e363c8153d282bca510dc528da02ed36fcc80470229310c source_path: plugins/memory-lancedb.md workflow: 15 --- -`memory-lancedb` — це вбудований плагін пам’яті, який зберігає довготривалу пам’ять у -LanceDB і використовує ембединги для пригадування. Він може автоматично -пригадувати релевантні спогади перед ходом моделі та фіксувати важливі факти -після відповіді. +`memory-lancedb` — це вбудований Plugin пам’яті, який зберігає довготривалу пам’ять у LanceDB і використовує ембединги для пригадування. Він може автоматично пригадувати релевантні спогади перед ходом моделі та фіксувати важливі факти після відповіді. -Використовуйте його, якщо вам потрібна локальна векторна база даних для пам’яті, -потрібна точка доступу до ембедингів, сумісна з OpenAI, або якщо ви хочете -зберігати базу даних пам’яті поза типовим вбудованим сховищем пам’яті. +Використовуйте його, якщо вам потрібна локальна векторна база даних для пам’яті, потрібна кінцева точка ембедингів, сумісна з OpenAI, або ви хочете зберігати базу даних пам’яті поза типовим вбудованим сховищем пам’яті. -`memory-lancedb` — це активний плагін пам’яті. Увімкніть його, вибравши слот -пам’яті через `plugins.slots.memory = "memory-lancedb"`. Супутні плагіни, такі як -`memory-wiki`, можуть працювати поруч із ним, але лише один плагін володіє -слотом Active Memory. +`memory-lancedb` — це Plugin Active Memory. Увімкніть його, вибравши слот пам’яті через `plugins.slots.memory = "memory-lancedb"`. Супутні Plugins, такі як `memory-wiki`, можуть працювати поруч із ним, але лише один Plugin володіє активним слотом пам’яті. ## Швидкий старт @@ -56,13 +48,13 @@ LanceDB і використовує ембединги для пригадува } ``` -Перезапустіть Gateway після зміни конфігурації плагіна: +Після зміни конфігурації Plugin перезапустіть Gateway: ```bash openclaw gateway restart ``` -Потім перевірте, що плагін завантажено: +Потім переконайтеся, що Plugin завантажено: ```bash openclaw plugins list @@ -71,9 +63,7 @@ openclaw plugins list ## Ембединги Ollama `memory-lancedb` викликає ембединги через API ембедингів, сумісний з OpenAI. -Для ембедингів Ollama використовуйте тут endpoint сумісності Ollama `/v1`. Це -стосується лише ембедингів; провайдер чату/моделей Ollama використовує нативний -URL API Ollama, описаний у [Ollama](/uk/providers/ollama). +Для ембедингів Ollama використовуйте тут кінцеву точку сумісності Ollama `/v1`. Це стосується лише ембедингів; провайдер чату/моделі Ollama використовує власний URL API Ollama, описаний у [Ollama](/uk/providers/ollama). ```json5 { @@ -101,37 +91,58 @@ URL API Ollama, описаний у [Ollama](/uk/providers/ollama). } ``` -Установіть `dimensions` для нестандартних моделей ембедингів. OpenClaw знає -розмірність для `text-embedding-3-small` і `text-embedding-3-large`; для -користувацьких моделей потрібно вказати це значення в конфігурації, щоб LanceDB -міг створити векторний стовпець. +Встановіть `dimensions` для нестандартних моделей ембедингів. OpenClaw знає +розмірності для `text-embedding-3-small` і `text-embedding-3-large`; для +користувацьких моделей це значення потрібно вказати в конфігурації, щоб LanceDB міг створити векторний стовпець. -Для невеликих локальних моделей ембедингів зменште `recallMaxChars`, якщо -бачите помилки довжини контексту від локального сервера. +Для невеликих локальних моделей ембедингів зменште `recallMaxChars`, якщо бачите помилки довжини контексту від локального сервера. -## Обмеження пригадування та збереження +## Провайдери, сумісні з OpenAI -`memory-lancedb` має два окремі текстові обмеження: +Деякі провайдери ембедингів, сумісні з OpenAI, відхиляють параметр `encoding_format`, +тоді як інші ігнорують його й завжди повертають вектори `number[]`. +Тому `memory-lancedb` пропускає `encoding_format` у запитах на ембединги та +приймає або відповіді з масивом чисел з плаваючою комою, або відповіді з float32 у кодуванні base64. -| Налаштування | Типово | Діапазон | Застосовується до | -| ---------------- | ------- | --------- | --------------------------------------------- | -| `recallMaxChars` | `1000` | 100-10000 | тексту, надісланого до API ембедингів для пригадування | -| `captureMaxChars` | `500` | 100-10000 | довжини повідомлення асистента, придатної для збереження | +Встановіть `embedding.dimensions` для провайдерів, чиї розмірності моделей не +вбудовані. Наприклад, ZhiPu `embedding-3` використовує `2048` розмірностей: -`recallMaxChars` керує автоматичним пригадуванням, інструментом `memory_recall`, -шляхом запиту `memory_forget` і `openclaw ltm search`. Автоматичне пригадування -надає перевагу останньому повідомленню користувача в ході та повертається до -повного prompt лише тоді, коли повідомлення користувача недоступне. Це дозволяє -не включати метадані каналу й великі блоки prompt у запит на ембединг. +```json5 +{ + plugins: { + entries: { + "memory-lancedb": { + enabled: true, + config: { + embedding: { + apiKey: "${ZHIPU_API_KEY}", + baseUrl: "https://open.bigmodel.cn/api/paas/v4", + model: "embedding-3", + dimensions: 2048, + }, + }, + }, + }, + }, +} +``` -`captureMaxChars` визначає, чи є відповідь достатньо короткою, щоб її можна було -розглядати для автоматичного збереження. Це не обмежує ембединги запитів для -пригадування. +## Обмеження пригадування та фіксації + +`memory-lancedb` має два окремі обмеження тексту: + +| Налаштування | Типово | Діапазон | Застосовується до | +| ---------------- | ------- | --------- | -------------------------------------------- | +| `recallMaxChars` | `1000` | 100-10000 | тексту, що надсилається до API ембедингів для пригадування | +| `captureMaxChars` | `500` | 100-10000 | довжини повідомлення асистента, придатної для фіксації | + +`recallMaxChars` керує автоматичним пригадуванням, інструментом `memory_recall`, шляхом запиту `memory_forget` і `openclaw ltm search`. Автоматичне пригадування надає перевагу останньому повідомленню користувача в ході та повертається до повного prompt лише тоді, коли повідомлення користувача недоступне. Це не дає метаданим каналу й великим блокам prompt потрапляти до запиту на ембединги. + +`captureMaxChars` визначає, чи є відповідь достатньо короткою, щоб її можна було розглядати для автоматичної фіксації. Воно не обмежує ембединги запитів для пригадування. ## Команди -Коли `memory-lancedb` є активним плагіном пам’яті, він реєструє простір імен CLI -`ltm`: +Коли `memory-lancedb` є активним Plugin пам’яті, він реєструє простір імен CLI `ltm`: ```bash openclaw ltm list @@ -139,16 +150,15 @@ openclaw ltm search "project preferences" openclaw ltm stats ``` -Агенти також отримують інструменти пам’яті LanceDB від активного плагіна пам’яті: +Агенти також отримують інструменти пам’яті LanceDB від активного Plugin пам’яті: - `memory_recall` для пригадування на базі LanceDB - `memory_store` для збереження важливих фактів, уподобань, рішень і сутностей -- `memory_forget` для видалення відповідних спогадів +- `memory_forget` для видалення спогадів, що відповідають запиту ## Сховище -Типово дані LanceDB розміщуються в `~/.openclaw/memory/lancedb`. Щоб змінити -шлях, використайте `dbPath`: +Типово дані LanceDB зберігаються в `~/.openclaw/memory/lancedb`. Перевизначте шлях за допомогою `dbPath`: ```json5 { @@ -169,8 +179,7 @@ openclaw ltm stats } ``` -`storageOptions` приймає рядкові пари ключ/значення для бекендів сховища LanceDB -і підтримує розгортання `${ENV_VAR}`: +`storageOptions` приймає рядкові пари ключ/значення для бекендів сховища LanceDB і підтримує розгортання `${ENV_VAR}`: ```json5 { @@ -198,18 +207,12 @@ openclaw ltm stats ## Залежності середовища виконання -`memory-lancedb` залежить від нативного пакета `@lancedb/lancedb`. Паковані -встановлення OpenClaw спочатку намагаються використати вбудовану залежність -середовища виконання та можуть відновити залежність середовища виконання плагіна -в стані OpenClaw, якщо вбудований імпорт недоступний. +`memory-lancedb` залежить від нативного пакета `@lancedb/lancedb`. Упаковані +встановлення OpenClaw спочатку намагаються використати вбудовану залежність середовища виконання й можуть відновити залежність середовища виконання Plugin у стані OpenClaw, якщо вбудований імпорт недоступний. -Якщо в старішому встановленні під час завантаження плагіна в журналі з’являється -помилка про відсутній `dist/package.json` або відсутній `@lancedb/lancedb`, -оновіть OpenClaw і перезапустіть Gateway. +Якщо у старішому встановленні під час завантаження Plugin з’являється журнал про відсутній `dist/package.json` або помилку відсутності `@lancedb/lancedb`, оновіть OpenClaw і перезапустіть Gateway. -Якщо плагін журналює, що LanceDB недоступний на `darwin-x64`, використовуйте на -цій машині типовий бекенд пам’яті, перенесіть Gateway на підтримувану платформу -або вимкніть `memory-lancedb`. +Якщо Plugin повідомляє, що LanceDB недоступний на `darwin-x64`, використовуйте типовий бекенд пам’яті на цій машині, перенесіть Gateway на підтримувану платформу або вимкніть `memory-lancedb`. ## Усунення проблем @@ -221,7 +224,7 @@ openclaw ltm stats memory-lancedb: recall failed: Error: 400 the input length exceeds the context length ``` -Установіть менше значення `recallMaxChars`, а потім перезапустіть Gateway: +Встановіть менше значення `recallMaxChars`, а потім перезапустіть Gateway: ```json5 { @@ -237,7 +240,7 @@ memory-lancedb: recall failed: Error: 400 the input length exceeds the context l } ``` -Для Ollama також перевірте, що сервер ембедингів доступний з хоста Gateway: +Для Ollama також перевірте, що сервер ембедингів доступний із хоста Gateway: ```bash curl http://127.0.0.1:11434/v1/embeddings \ @@ -247,25 +250,21 @@ curl http://127.0.0.1:11434/v1/embeddings \ ### Непідтримувана модель ембедингів -Без `dimensions` відомі лише вбудовані розмірності ембедингів OpenAI. Для -локальних або користувацьких моделей ембедингів установіть `embedding.dimensions` -у розмір вектора, який повідомляє ця модель. +Без `dimensions` відомі лише вбудовані розмірності ембедингів OpenAI. +Для локальних або користувацьких моделей ембедингів установіть `embedding.dimensions` відповідно до розміру вектора, який повертає ця модель. -### Плагін завантажується, але спогади не з’являються +### Plugin завантажується, але спогади не з’являються -Перевірте, що `plugins.slots.memory` вказує на `memory-lancedb`, а потім -виконайте: +Перевірте, що `plugins.slots.memory` вказує на `memory-lancedb`, а потім виконайте: ```bash openclaw ltm stats openclaw ltm search "recent preference" ``` -Якщо `autoCapture` вимкнено, плагін пригадуватиме наявні спогади, але не -зберігатиме автоматично нові. Використовуйте інструмент `memory_store` або -увімкніть `autoCapture`, якщо хочете автоматичне збереження. +Якщо `autoCapture` вимкнено, Plugin пригадуватиме наявні спогади, але не зберігатиме нові автоматично. Використовуйте інструмент `memory_store` або увімкніть `autoCapture`, якщо хочете автоматичну фіксацію. -## Пов’язані матеріали +## Пов’язане - [Огляд пам’яті](/uk/concepts/memory) - [Active Memory](/uk/concepts/active-memory) diff --git a/docs/uk/plugins/sdk-channel-plugins.md b/docs/uk/plugins/sdk-channel-plugins.md index 9ce24df8d..acdf47060 100644 --- a/docs/uk/plugins/sdk-channel-plugins.md +++ b/docs/uk/plugins/sdk-channel-plugins.md @@ -1,121 +1,129 @@ --- read_when: - - Ви створюєте новий plugin каналу повідомлень + - Ви створюєте новий Plugin каналу повідомлень - Ви хочете підключити OpenClaw до платформи обміну повідомленнями - Вам потрібно зрозуміти поверхню адаптера ChannelPlugin sidebarTitle: Channel Plugins -summary: Покроковий посібник зі створення plugin каналу повідомлень для OpenClaw -title: Створення plugin каналів +summary: Покроковий посібник зі створення Plugin каналу повідомлень для OpenClaw +title: Створення Plugin каналів x-i18n: - generated_at: "2026-04-25T02:39:58Z" + generated_at: "2026-04-28T00:34:26Z" model: gpt-5.4 provider: openai - source_hash: 0a466decff828bdce1d9d3e85127867b88f43c6eca25aa97306f8bd0df39f3a9 + source_hash: 9f005ea0e7928dfb055758e928f10a333979c8e67a0b85353d663940abb6a7b4 source_path: plugins/sdk-channel-plugins.md workflow: 15 --- -Цей посібник описує створення plugin каналу, який підключає OpenClaw до -платформи обміну повідомленнями. Наприкінці у вас буде робочий канал із -безпекою DM, сполученням, прив’язкою відповідей до гілок і вихідними повідомленнями. +Цей посібник проведе вас через створення Plugin каналу, який підключає OpenClaw до +платформи обміну повідомленнями. Наприкінці у вас буде робочий канал із безпекою DM, +паруванням, потоками відповідей і вихідними повідомленнями. - Якщо ви раніше не створювали жодного plugin для OpenClaw, спочатку прочитайте - [Getting Started](/uk/plugins/building-plugins), щоб ознайомитися з базовою - структурою пакета та налаштуванням маніфесту. + Якщо ви раніше не створювали жодного Plugin для OpenClaw, спочатку прочитайте + [Початок роботи](/uk/plugins/building-plugins) про базову структуру пакета + та налаштування маніфесту. -## Як працюють plugin каналів +## Як працюють Plugin каналів -Plugin каналів не потребують власних інструментів send/edit/react. OpenClaw -зберігає один спільний інструмент `message` у core. Ваш plugin відповідає за: +Plugin каналів не потребують власних інструментів send/edit/react. OpenClaw зберігає один +спільний інструмент `message` у core. Ваш Plugin відповідає за: -- **Config** — визначення облікового запису та майстер налаштування -- **Security** — політика DM і списки дозволених -- **Pairing** — потік підтвердження DM -- **Session grammar** — як специфічні для провайдера ідентифікатори розмов зіставляються з базовими чатами, ідентифікаторами гілок і резервними батьківськими значеннями -- **Outbound** — надсилання тексту, медіа та опитувань на платформу -- **Threading** — як відповіді прив’язуються до гілок -- **Heartbeat typing** — необов’язкові сигнали typing/busy для цілей доставки Heartbeat +- **Конфігурацію** — визначення облікового запису та майстер налаштування +- **Безпеку** — політику DM та списки дозволених +- **Парування** — потік підтвердження DM +- **Граматику сесії** — як специфічні для провайдера ідентифікатори розмов зіставляються з базовими чатами, ідентифікаторами потоків і резервними батьківськими значеннями +- **Вихідні повідомлення** — надсилання тексту, медіа та опитувань на платформу +- **Потоки** — як групуються відповіді +- **Набір Heartbeat typing** — необов’язкові сигнали набору/зайнятості для цілей доставки heartbeat -Core відповідає за спільний інструмент повідомлень, підключення prompt, зовнішню -форму ключа сесії, загальний облік `:thread:` і диспетчеризацію. +Core відповідає за спільний інструмент message, підключення prompt, зовнішню форму ключа сесії, +загальний облік `:thread:` та диспетчеризацію. -Якщо ваш канал підтримує індикатори набору поза вхідними відповідями, -експонуйте `heartbeat.sendTyping(...)` у plugin каналу. Core викликає його з -визначеною ціллю доставки heartbeat до початку запуску моделі heartbeat і -використовує спільний життєвий цикл typing keepalive/cleanup. Додайте -`heartbeat.clearTyping(...)`, якщо платформі потрібен явний сигнал зупинки. +Якщо ваш канал підтримує індикатори набору поза межами вхідних відповідей, надайте +`heartbeat.sendTyping(...)` у Plugin каналу. Core викликає його з +визначеною ціллю доставки heartbeat перед початком запуску моделі heartbeat і +використовує спільний життєвий цикл keepalive/cleanup для набору. Додайте `heartbeat.clearTyping(...)`, +коли платформі потрібен явний сигнал зупинки. -Якщо ваш канал додає параметри інструмента message, які містять джерела медіа, -експонуйте ці імена параметрів через `describeMessageTool(...).mediaSourceParams`. -Core використовує цей явний список для нормалізації шляхів sandbox і політики -доступу до вихідних медіа, тому plugins не потребують спеціальних випадків у -спільному core для специфічних для провайдера параметрів avatar, attachment або -cover-image. -Рекомендовано повертати мапу з ключами дій, наприклад +Якщо ваш канал додає параметри інструмента message, що містять джерела медіа, надайте ці +назви параметрів через `describeMessageTool(...).mediaSourceParams`. Core використовує +цей явний список для нормалізації шляхів sandbox і політики доступу до вихідних медіа, +щоб Plugin не потребували особливих випадків у спільному core для специфічних для провайдера +параметрів avatar, attachment або cover-image. +Краще повертати мапу з ключами дій, наприклад `{ "set-profile": ["avatarUrl", "avatarPath"] }`, щоб не пов’язані дії не -успадковували медіа-аргументи іншої дії. Плоский масив також працює для -параметрів, які навмисно є спільними для кожної експонованої дії. +успадковували медіааргументи іншої дії. Плоский масив також працює для параметрів, які +навмисно спільні для кожної доступної дії. -Якщо ваша платформа зберігає додаткову область в ідентифікаторах розмов, -залишайте цей розбір у plugin за допомогою `messaging.resolveSessionConversation(...)`. -Це канонічний hook для зіставлення `rawId` з базовим ідентифікатором розмови, -необов’язковим ідентифікатором гілки, явним `baseConversationId` і будь-якими -`parentConversationCandidates`. -Коли ви повертаєте `parentConversationCandidates`, зберігайте їхній порядок від -найвужчого батьківського значення до найширшої/базової розмови. +Якщо ваша платформа зберігає додаткову область видимості в ідентифікаторах розмов, тримайте цей +розбір у Plugin за допомогою `messaging.resolveSessionConversation(...)`. Це +канонічний хук для зіставлення `rawId` з базовим ідентифікатором розмови, необов’язковим +ідентифікатором потоку, явним `baseConversationId` і будь-якими `parentConversationCandidates`. +Коли ви повертаєте `parentConversationCandidates`, зберігайте їх упорядкованими від +найвужчого батьківського до найширшої/базової розмови. -Вбудовані plugins, яким потрібен той самий розбір до запуску реєстру каналів, -також можуть експонувати файл верхнього рівня `session-key-api.ts` з відповідним -експортом `resolveSessionConversation(...)`. Core використовує цю безпечну для -bootstrap поверхню лише тоді, коли реєстр runtime plugin ще недоступний. +Використовуйте `openclaw/plugin-sdk/channel-route`, коли коду Plugin потрібно нормалізувати +поля, схожі на route, порівняти дочірній потік з його батьківським route або побудувати +стабільний ключ дедуплікації з `{ channel, to, accountId, threadId }`. Цей helper +нормалізує числові ідентифікатори потоків так само, як це робить core, тому Plugin мають +надавати йому перевагу замість спеціальних порівнянь `String(threadId)`. +Plugin зі специфічною для провайдера граматикою цілі можуть передати свій парсер у +`resolveChannelRouteTargetWithParser(...)` і все одно отримати ту саму форму route target +і семантику резервного потоку, яку використовує core. -`messaging.resolveParentConversationCandidates(...)` лишається доступним як -застарілий резервний варіант сумісності, коли plugin потребує лише резервних -батьківських значень поверх загального/raw id. Якщо існують обидва hooks, core -спочатку використовує +Вбудовані Plugin, яким потрібен той самий розбір до запуску реєстру каналів, +також можуть надавати файл верхнього рівня `session-key-api.ts` з відповідним +експортом `resolveSessionConversation(...)`. Core використовує цю безпечну для bootstrap поверхню +лише тоді, коли реєстр Plugin середовища виконання ще недоступний. + +`messaging.resolveParentConversationCandidates(...)` залишається доступним як +застарілий сумісний резервний варіант, коли Plugin потребує лише батьківських резервних значень +поверх загального/raw id. Якщо існують обидва хуки, core спочатку використовує `resolveSessionConversation(...).parentConversationCandidates` і переходить до -`resolveParentConversationCandidates(...)` лише тоді, коли канонічний hook -їх не вказує. +`resolveParentConversationCandidates(...)` лише тоді, коли канонічний хук їх +не повертає. -## Підтвердження та можливості каналів +## Підтвердження та можливості каналу -Більшості plugin каналів не потрібен код, специфічний для підтверджень. +Більшості Plugin каналів не потрібен код, специфічний для підтверджень. - Core відповідає за `/approve` у тому самому чаті, спільні payload кнопок підтвердження та загальну резервну доставку. -- Надавайте перевагу одному об’єкту `approvalCapability` у plugin каналу, якщо каналу потрібна поведінка, специфічна для підтверджень. -- `ChannelPlugin.approvals` видалено. Розміщуйте факти про доставку/native/render/auth підтверджень у `approvalCapability`. -- `plugin.auth` призначений лише для login/logout; core більше не читає hooks auth підтверджень із цього об’єкта. -- `approvalCapability.authorizeActorAction` і `approvalCapability.getActionAvailabilityState` — це канонічна межа approval-auth. +- Надавайте перевагу одному об’єкту `approvalCapability` у Plugin каналу, коли каналу потрібна поведінка, специфічна для підтверджень. +- `ChannelPlugin.approvals` вилучено. Розміщуйте факти про доставку/native/render/auth підтверджень у `approvalCapability`. +- `plugin.auth` — лише для login/logout; core більше не читає хуки auth підтверджень із цього об’єкта. +- `approvalCapability.authorizeActorAction` і `approvalCapability.getActionAvailabilityState` — це канонічний шов auth для підтверджень. - Використовуйте `approvalCapability.getActionAvailabilityState` для доступності auth підтверджень у тому самому чаті. -- Якщо ваш канал експонує native exec підтвердження, використовуйте `approvalCapability.getExecInitiatingSurfaceState` для стану initiating-surface/native-client, коли він відрізняється від auth підтверджень у тому самому чаті. Core використовує цей специфічний для exec hook, щоб розрізняти `enabled` і `disabled`, визначати, чи підтримує initiating channel native exec підтвердження, і включати канал до вказівок із резервного переходу native-client. `createApproverRestrictedNativeApprovalCapability(...)` заповнює це для поширеного випадку. -- Використовуйте `outbound.shouldSuppressLocalPayloadPrompt` або `outbound.beforeDeliverPayload` для специфічної для каналу поведінки життєвого циклу payload, як-от приховування дубльованих локальних prompts підтвердження або надсилання індикаторів typing перед доставкою. -- Використовуйте `approvalCapability.delivery` лише для native-маршрутизації підтверджень або вимкнення резервної доставки. -- Використовуйте `approvalCapability.nativeRuntime` для фактів native підтверджень, якими керує канал. Залишайте його lazy на гарячих точках входу каналу за допомогою `createLazyChannelApprovalNativeRuntimeAdapter(...)`, який може імпортувати ваш runtime-модуль на вимогу, водночас дозволяючи core збирати життєвий цикл підтверджень. +- Якщо ваш канал надає native exec-підтвердження, використовуйте `approvalCapability.getExecInitiatingSurfaceState` для стану initiating-surface/native-client, коли він відрізняється від auth підтверджень у тому самому чаті. Core використовує цей специфічний для exec хук, щоб розрізняти `enabled` і `disabled`, визначати, чи підтримує ініціювальний канал native exec-підтвердження, і включати канал у резервні вказівки для native-client. `createApproverRestrictedNativeApprovalCapability(...)` заповнює це для типового випадку. +- Використовуйте `outbound.shouldSuppressLocalPayloadPrompt` або `outbound.beforeDeliverPayload` для поведінки життєвого циклу payload, специфічної для каналу, наприклад приховування дубльованих локальних prompt підтвердження або надсилання індикаторів набору перед доставкою. +- Використовуйте `approvalCapability.delivery` лише для native-маршрутизації підтверджень або пригнічення резервного варіанту. +- Використовуйте `approvalCapability.nativeRuntime` для фактів native-підтверджень, що належать каналу. Тримайте його лінивим у гарячих точках входу каналу за допомогою `createLazyChannelApprovalNativeRuntimeAdapter(...)`, який може імпортувати ваш модуль runtime за запитом, водночас дозволяючи core збирати життєвий цикл підтверджень. - Використовуйте `approvalCapability.render` лише тоді, коли каналу справді потрібні власні payload підтвердження замість спільного renderer. -- Використовуйте `approvalCapability.describeExecApprovalSetup`, коли канал хоче, щоб відповідь на вимкнений шлях пояснювала точні параметри config, потрібні для ввімкнення native exec підтверджень. Hook отримує `{ channel, channelLabel, accountId }`; канали з іменованими обліковими записами мають відображати шляхи з областю облікового запису, як-от `channels..accounts..execApprovals.*`, а не defaults верхнього рівня. -- Якщо канал може вивести стабільні схожі на власника DM-ідентичності з наявного config, використовуйте `createResolvedApproverActionAuthAdapter` з `openclaw/plugin-sdk/approval-runtime`, щоб обмежити `/approve` у тому самому чаті без додавання логіки core, специфічної для підтверджень. -- Якщо каналу потрібна native-доставка підтверджень, зосередьте код каналу на нормалізації цілей і фактах transport/presentation. Використовуйте `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` і `createApproverRestrictedNativeApprovalCapability` з `openclaw/plugin-sdk/approval-runtime`. Розміщуйте специфічні для каналу факти за `approvalCapability.nativeRuntime`, бажано через `createChannelApprovalNativeRuntimeAdapter(...)` або `createLazyChannelApprovalNativeRuntimeAdapter(...)`, щоб core міг зібрати handler і взяти на себе фільтрацію запитів, маршрутизацію, дедуплікацію, строки дії, підписку Gateway і сповіщення routed-elsewhere. `nativeRuntime` поділено на кілька менших меж: +- Використовуйте `approvalCapability.describeExecApprovalSetup`, коли канал хоче, щоб відповідь на вимкнений шлях пояснювала точні параметри конфігурації, потрібні для ввімкнення native exec-підтверджень. Хук отримує `{ channel, channelLabel, accountId }`; канали з іменованими обліковими записами мають рендерити шляхи з областю дії облікового запису, наприклад `channels..accounts..execApprovals.*`, а не top-level значення за замовчуванням. +- Якщо канал може виводити стабільні DM-ідентичності, подібні до власників, з наявної конфігурації, використовуйте `createResolvedApproverActionAuthAdapter` з `openclaw/plugin-sdk/approval-runtime`, щоб обмежити `/approve` у тому самому чаті без додавання логіки, специфічної для підтверджень, у core. +- Якщо каналу потрібна native-доставка підтверджень, тримайте код каналу зосередженим на нормалізації цілі та фактах transport/presentation. Використовуйте `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` і `createApproverRestrictedNativeApprovalCapability` з `openclaw/plugin-sdk/approval-runtime`. Розміщуйте специфічні для каналу факти за `approvalCapability.nativeRuntime`, бажано через `createChannelApprovalNativeRuntimeAdapter(...)` або `createLazyChannelApprovalNativeRuntimeAdapter(...)`, щоб core міг зібрати обробник і керувати фільтрацією запитів, маршрутизацією, дедуплікацією, строком дії, підпискою Gateway та сповіщеннями про перенаправлення в інше місце. `nativeRuntime` поділено на кілька менших швів: +- `createChannelNativeOriginTargetResolver` типово використовує спільний matcher channel-route для цілей `{ to, accountId, threadId }`. Передавайте `targetsMatch` лише тоді, коли канал має специфічні для провайдера правила еквівалентності, наприклад зіставлення префікса timestamp у Slack. +- Передавайте `normalizeTargetForMatch` у `createChannelNativeOriginTargetResolver`, коли каналу потрібно канонізувати ідентифікатори провайдера перед запуском типового matcher route або власного callback `targetsMatch`, зберігаючи початкову ціль для доставки. Використовуйте `normalizeTarget` лише тоді, коли сама визначена ціль доставки має бути канонізована. - `availability` — чи налаштовано обліковий запис і чи слід обробляти запит -- `presentation` — зіставлення спільної view model підтвердження з native payload у станах pending/resolved/expired або з фінальними діями +- `presentation` — зіставлення спільної view model підтвердження з pending/resolved/expired native payload або фінальними діями - `transport` — підготовка цілей плюс надсилання/оновлення/видалення native-повідомлень підтвердження -- `interactions` — необов’язкові hooks bind/unbind/clear-action для native-кнопок або реакцій -- `observe` — необов’язкові hooks діагностики доставки -- Якщо каналу потрібні об’єкти, якими володіє runtime, як-от client, token, Bolt app або Webhook receiver, реєструйте їх через `openclaw/plugin-sdk/channel-runtime-context`. Загальний реєстр runtime-context дозволяє core ініціалізувати handlers, керовані capability, зі стану запуску каналу без додавання обгорток glue, специфічних для підтверджень. -- Звертайтеся до низькорівневих `createChannelApprovalHandler` або `createChannelNativeApprovalRuntime` лише тоді, коли межа, керована capability, ще недостатньо виразна. -- Канали native підтверджень мають маршрутизувати і `accountId`, і `approvalKind` через ці helper-и. `accountId` зберігає політику підтверджень для кількох облікових записів у правильній області bot-облікового запису, а `approvalKind` зберігає поведінку exec проти plugin підтверджень доступною для каналу без жорстко закодованих гілок у core. -- Core тепер також відповідає за сповіщення про перенаправлення підтверджень. Plugin каналів не повинні надсилати власні додаткові повідомлення на кшталт «підтвердження перейшло в DM / інший канал» з `createChannelNativeApprovalRuntime`; натомість експонуйте точну маршрутизацію origin + approver-DM через спільні helper-и capability підтверджень і дозвольте core агрегувати фактичні доставки перед публікацією будь-якого сповіщення назад в initiating chat. -- Зберігайте вид доставленого id підтвердження наскрізно. Native clients не повинні - вгадувати або переписувати маршрутизацію exec проти plugin підтверджень на основі локального стану каналу. -- Різні види підтверджень можуть навмисно експонувати різні native-поверхні. +- `interactions` — необов’язкові хуки bind/unbind/clear-action для native-кнопок або реакцій +- `observe` — необов’язкові хуки діагностики доставки +- Якщо каналу потрібні об’єкти, що належать runtime, як-от client, token, застосунок Bolt або отримувач Webhook, зареєструйте їх через `openclaw/plugin-sdk/channel-runtime-context`. Загальний реєстр runtime-context дає core змогу ініціалізувати обробники, керовані можливостями, зі стану запуску каналу без додавання обгорткового glue, специфічного для підтверджень. +- Використовуйте нижчорівневі `createChannelApprovalHandler` або `createChannelNativeApprovalRuntime` лише тоді, коли шов, керований можливостями, ще недостатньо виразний. +- Канали native-підтверджень мають маршрутизувати і `accountId`, і `approvalKind` через ці helper. `accountId` зберігає політику підтверджень для кількох облікових записів у межах правильного облікового запису бота, а `approvalKind` зберігає доступність поведінки exec проти Plugin-підтверджень для каналу без жорстко закодованих розгалужень у core. +- Core тепер також відповідає за сповіщення про перенаправлення підтверджень. Plugin каналів не повинні надсилати власні подальші повідомлення на кшталт «підтвердження перейшло в DM / в інший канал» з `createChannelNativeApprovalRuntime`; натомість надавайте точну маршрутизацію origin + approver-DM через спільні helper можливостей підтвердження та дозвольте core агрегувати фактичні доставки перед публікацією будь-якого сповіщення назад в ініціювальний чат. +- Зберігайте тип delivered approval id від початку до кінця. Native-клієнти не повинні + вгадувати або переписувати маршрутизацію exec чи Plugin-підтверджень на основі локального для каналу стану. +- Різні види підтверджень можуть навмисно надавати різні native-поверхні. Поточні вбудовані приклади: - - Slack зберігає доступною native-маршрутизацію підтверджень як для exec-, так і для plugin-id. - - Matrix зберігає ту саму native DM/channel-маршрутизацію та UX реакцій для exec- - і plugin-підтверджень, водночас дозволяючи auth відрізнятися за видом підтвердження. -- `createApproverRestrictedNativeApprovalAdapter` усе ще існує як обгортка сумісності, але новий код має надавати перевагу builder-у capability та експонувати `approvalCapability` у plugin. + - Slack зберігає доступність native-маршрутизації підтверджень як для exec, так і для Plugin id. + - Matrix зберігає ту саму native DM/channel-маршрутизацію та UX реакцій для exec + і Plugin-підтверджень, водночас дозволяючи auth відрізнятися за видом підтвердження. +- `createApproverRestrictedNativeApprovalAdapter` усе ще існує як обгортка сумісності, але новий код має надавати перевагу builder можливостей і надавати `approvalCapability` у Plugin. -Для гарячих точок входу каналу надавайте перевагу вужчим runtime subpath, коли вам потрібна лише +Для гарячих точок входу каналу надавайте перевагу вужчим підшляхам runtime, коли вам потрібна лише одна частина цієї сім’ї: - `openclaw/plugin-sdk/approval-auth-runtime` @@ -128,123 +136,118 @@ bootstrap поверхню лише тоді, коли реєстр runtime plug - `openclaw/plugin-sdk/approval-reply-runtime` - `openclaw/plugin-sdk/channel-runtime-context` -Аналогічно надавайте перевагу `openclaw/plugin-sdk/setup-runtime`, +Так само надавайте перевагу `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/reply-runtime`, `openclaw/plugin-sdk/reply-dispatch-runtime`, `openclaw/plugin-sdk/reply-reference` і -`openclaw/plugin-sdk/reply-chunking`, коли вам не потрібна ширша umbrella- -поверхня. +`openclaw/plugin-sdk/reply-chunking`, коли вам не потрібна ширша +загальна поверхня. -Зокрема для setup: +Окремо для setup: -- `openclaw/plugin-sdk/setup-runtime` охоплює безпечні для runtime helper-и setup: +- `openclaw/plugin-sdk/setup-runtime` охоплює безпечні для runtime helper setup: безпечні для імпорту адаптери patch setup (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, - `createSetupInputPresenceValidator`), виведення приміток lookup, - `promptResolvedAllowFrom`, `splitSetupEntries` і builders делегованого + `createSetupInputPresenceValidator`), виведення lookup-note, + `promptResolvedAllowFrom`, `splitSetupEntries` і builder delegated setup-proxy -- `openclaw/plugin-sdk/setup-adapter-runtime` — це вузька env-aware межа adapter - для `createEnvPatchedAccountSetupAdapter` -- `openclaw/plugin-sdk/channel-setup` охоплює builders setup для необов’язкового встановлення плюс кілька setup-safe примітивів: +- `openclaw/plugin-sdk/setup-adapter-runtime` — це вузький env-aware adapter + seam для `createEnvPatchedAccountSetupAdapter` +- `openclaw/plugin-sdk/channel-setup` охоплює builder optional-install setup + плюс кілька примітивів, безпечних для setup: `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -Якщо ваш канал підтримує setup або auth на основі env і загальні потоки startup/config -мають знати ці імена env до завантаження runtime, оголосіть їх у -маніфесті plugin через `channelEnvVars`. Залишайте `envVars` runtime каналу або локальні -константи лише для копірайту, орієнтованого на операторів. +Якщо ваш канал підтримує setup або auth, керовані env, і загальні потоки startup/config +мають знати ці імена env до завантаження runtime, оголосіть їх у маніфесті Plugin через +`channelEnvVars`. Зберігайте `envVars` runtime каналу або локальні константи лише для копії, видимої оператору. Якщо ваш канал може з’являтися в `status`, `channels list`, `channels status` або -скануваннях SecretRef до запуску runtime plugin, додайте `openclaw.setupEntry` у -`package.json`. Ця точка входу має бути безпечною для імпорту в read-only шляхах команд -і має повертати метадані каналу, безпечний для setup adapter config, adapter status -і метадані channel secret target, потрібні для цих зведень. Не запускайте clients, -listeners або runtime transport із точки входу setup. +скануваннях SecretRef до запуску runtime Plugin, додайте `openclaw.setupEntry` у +`package.json`. Ця точка входу має бути безпечною для імпорту в командних шляхах лише для читання +і повинна повертати метадані каналу, безпечний для setup адаптер конфігурації, адаптер status і метадані цілі секретів каналу, потрібні для цих зведень. Не +запускайте clients, listeners або transport runtime з точки входу setup. -Тримайте вузьким і головний шлях імпорту точки входу каналу. Виявлення може -обчислювати точку входу та модуль plugin каналу для реєстрації capability без -активації каналу. Файли на кшталт `channel-plugin-api.ts` мають експортувати об’єкт plugin каналу -без імпорту майстрів setup, clients transport, listeners socket, запускальників subprocess -або модулів запуску сервісів. Розміщуйте ці runtime-частини в модулях, що -завантажуються з `registerFull(...)`, setter-ів runtime або lazy adapter-ів capability. +Також тримайте вузьким шлях імпорту основної точки входу каналу. Під час виявлення можуть оцінюватися +точка входу та модуль Plugin каналу для реєстрації можливостей без активації каналу. +Такі файли, як `channel-plugin-api.ts`, мають експортувати об’єкт Plugin каналу без імпорту +майстрів setup, transport clients, socket listeners, launcher підпроцесів або модулів запуску сервісів. Розміщуйте ці частини runtime в модулях, які завантажуються з `registerFull(...)`, setter runtime або лінивих адаптерів можливостей. `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` і `splitSetupEntries` -- використовуйте ширшу межу `openclaw/plugin-sdk/setup` лише тоді, коли вам також потрібні - важчі спільні helper-и setup/config, як-от +- використовуйте ширший seam `openclaw/plugin-sdk/setup` лише тоді, коли вам також потрібні + важчі спільні helper setup/config, такі як `moveSingleAccountChannelSectionToDefaultAccount(...)` -Якщо ваш канал лише хоче показувати «спочатку встановіть цей plugin» у поверхнях +Якщо ваш канал лише хоче показувати «спочатку встановіть цей Plugin» у поверхнях setup, надавайте перевагу `createOptionalChannelSetupSurface(...)`. Згенеровані -adapter/wizard безпечно відмовляють у записі config і завершенні, а також -повторно використовують те саме повідомлення про обов’язкове встановлення в -валідації, завершенні та тексті з посиланням на документацію. +adapter/wizard закриваються за замовчуванням для записів конфігурації та фіналізації й повторно використовують +те саме повідомлення про потребу встановлення для validation, finalize і копії з посиланням на документацію. -Для інших гарячих шляхів каналу надавайте перевагу вузьким helper-ам замість -ширших застарілих поверхонь: +Для інших гарячих шляхів каналу надавайте перевагу вузьким helper замість ширших застарілих +поверхонь: - `openclaw/plugin-sdk/account-core`, `openclaw/plugin-sdk/account-id`, `openclaw/plugin-sdk/account-resolution` і - `openclaw/plugin-sdk/account-helpers` для config з кількома обліковими записами та - резервного переходу до облікового запису за замовчуванням + `openclaw/plugin-sdk/account-helpers` для конфігурації з кількома обліковими записами та + резервного варіанту default-account - `openclaw/plugin-sdk/inbound-envelope` і - `openclaw/plugin-sdk/inbound-reply-dispatch` для маршруту/конверта inbound і + `openclaw/plugin-sdk/inbound-reply-dispatch` для route/envelope вхідних повідомлень та зв’язування record-and-dispatch - `openclaw/plugin-sdk/messaging-targets` для розбору/зіставлення цілей - `openclaw/plugin-sdk/outbound-media` і - `openclaw/plugin-sdk/outbound-runtime` для завантаження медіа плюс outbound - identity/send delegate-ів і планування payload + `openclaw/plugin-sdk/outbound-runtime` для завантаження медіа плюс делегатів + ідентифікації/надсилання вихідних повідомлень і планування payload - `buildThreadAwareOutboundSessionRoute(...)` з - `openclaw/plugin-sdk/channel-core`, коли маршрут outbound має зберігати явний + `openclaw/plugin-sdk/channel-core`, коли вихідний route має зберігати явний `replyToId`/`threadId` або відновлювати поточну сесію `:thread:`, - якщо базовий ключ сесії все ще збігається. Plugins провайдерів можуть - перевизначати пріоритет, поведінку суфіксів і нормалізацію id гілки, коли - їхня платформа має native-семантику доставки в гілки. + якщо базовий ключ сесії все ще збігається. Plugin провайдерів можуть перевизначати + пріоритет, поведінку суфіксів і нормалізацію ідентифікаторів потоків, якщо їхня платформа + має нативну семантику доставки в потоки. - `openclaw/plugin-sdk/thread-bindings-runtime` для життєвого циклу thread-binding - і реєстрації adapter-ів -- `openclaw/plugin-sdk/agent-media-payload` лише тоді, коли все ще потрібне - застаріле компонування полів payload агента/медіа -- `openclaw/plugin-sdk/telegram-command-config` для нормалізації користувацьких - команд Telegram, валідації дублікатів/конфліктів і стабільного щодо fallback - контракту config команд + і реєстрації адаптерів +- `openclaw/plugin-sdk/agent-media-payload` лише тоді, коли все ще потрібна + застаріла схема полів payload агента/медіа +- `openclaw/plugin-sdk/telegram-command-config` для нормалізації + користувацьких команд Telegram, validation дублікатів/конфліктів і стабільного при резервних варіантах контракту конфігурації команд -Канали лише з auth зазвичай можуть зупинитися на шляху за замовчуванням: core обробляє підтвердження, а plugin лише експонує можливості outbound/auth. Канали native підтверджень, як-от Matrix, Slack, Telegram і власні chat-транспорти, мають використовувати спільні native helper-и замість створення власного життєвого циклу підтверджень. +Канали лише з auth зазвичай можуть зупинитися на типовому шляху: core обробляє підтвердження, а Plugin лише надає можливості outbound/auth. Канали з native-підтвердженнями, як-от Matrix, Slack, Telegram і власні chat transport, мають використовувати спільні native-helper замість створення власного життєвого циклу підтверджень. ## Політика вхідних згадок -Зберігайте обробку вхідних згадок розділеною на два рівні: +Тримайте обробку вхідних згадок розділеною на два шари: -- збирання доказів, яким володіє plugin +- збирання доказів, що належить Plugin - спільне оцінювання політики -Використовуйте `openclaw/plugin-sdk/channel-mention-gating` для рішень політики згадок. +Використовуйте `openclaw/plugin-sdk/channel-mention-gating` для рішень щодо політики згадок. Використовуйте `openclaw/plugin-sdk/channel-inbound` лише тоді, коли вам потрібен ширший -barrel helper-ів inbound. +barrel helper для вхідних повідомлень. -Добре підходить для локальної логіки plugin: +Добре підходить для локальної логіки Plugin: - виявлення reply-to-bot - виявлення quoted-bot -- перевірки участі в гілці +- перевірки участі в потоці - виключення службових/системних повідомлень -- native-кеші платформи, потрібні для підтвердження участі бота +- нативні для платформи кеші, потрібні для підтвердження участі бота -Добре підходить для спільного helper-а: +Добре підходить для спільного helper: - `requireMention` - явний результат згадки -- allowlist неявних згадок +- список дозволених неявних згадок - обхід команд -- фінальне рішення про пропуск +- остаточне рішення про пропуск Рекомендований потік: -1. Обчисліть локальні факти згадки. +1. Обчисліть локальні факти згадок. 2. Передайте ці факти в `resolveInboundMentionDecision({ facts, policy })`. -3. Використовуйте `decision.effectiveWasMentioned`, `decision.shouldBypassMention` і `decision.shouldSkip` у вашому вхідному шлюзі. +3. Використовуйте `decision.effectiveWasMentioned`, `decision.shouldBypassMention` і `decision.shouldSkip` у вашому вхідному gate. ```typescript import { @@ -283,8 +286,8 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -`api.runtime.channel.mentions` експонує ті самі спільні helper-и згадок для -вбудованих plugin каналів, які вже залежать від ін’єкції runtime: +`api.runtime.channel.mentions` надає ті самі спільні helper для згадок для +вбудованих Plugin каналів, які вже залежать від ін’єкції runtime: - `buildMentionRegexes` - `matchesMentionPatterns` @@ -295,9 +298,9 @@ if (decision.shouldSkip) return; Якщо вам потрібні лише `implicitMentionKindWhen` і `resolveInboundMentionDecision`, імпортуйте з `openclaw/plugin-sdk/channel-mention-gating`, щоб уникнути завантаження не пов’язаних -helper-ів runtime inbound. +helper runtime для вхідних повідомлень. -Старі helper-и `resolveMentionGating*` залишаються в +Старіші helper `resolveMentionGating*` залишаються в `openclaw/plugin-sdk/channel-inbound` лише як експорти сумісності. Новий код має використовувати `resolveInboundMentionDecision({ facts, policy })`. @@ -306,9 +309,9 @@ helper-ів runtime inbound. - Створіть стандартні файли plugin. Поле `channel` у `package.json` — - це те, що робить його plugin каналу. Для повної поверхні метаданих пакета - див. [Налаштування і Config plugin](/uk/plugins/sdk-setup#openclaw-channel): + Створіть стандартні файли Plugin. Поле `channel` у `package.json` + робить це Plugin каналу. Для повної поверхні метаданих пакета + див. [Налаштування та конфігурація Plugin](/uk/plugins/sdk-setup#openclaw-channel): ```json package.json @@ -366,15 +369,15 @@ helper-ів runtime inbound. `configSchema` валідує `plugins.entries.acme-chat.config`. Використовуйте його для - налаштувань, якими володіє plugin, що не є config облікового запису каналу. `channelConfigs` - валідує `channels.acme-chat` і є джерелом cold-path, яке використовують schema - config, setup і поверхні UI до завантаження runtime plugin. + налаштувань, що належать Plugin і не є конфігурацією облікового запису каналу. `channelConfigs` + валідує `channels.acme-chat` і є джерелом холодного шляху, яке використовують схема конфігурації, + setup і поверхні UI до завантаження runtime Plugin. - - Інтерфейс `ChannelPlugin` має багато необов’язкових поверхонь adapter-ів. Почніть із - мінімуму — `id` і `setup` — і додавайте adapter-и за потреби. + + Інтерфейс `ChannelPlugin` має багато необов’язкових поверхонь адаптерів. Почніть із + мінімуму — `id` і `setup` — і додавайте адаптери за потреби. Створіть `src/channel.ts`: @@ -469,26 +472,26 @@ helper-ів runtime inbound. }); ``` - - Замість ручної реалізації низькорівневих інтерфейсів adapter-ів ви передаєте + + Замість ручної реалізації низькорівневих інтерфейсів адаптерів ви передаєте декларативні параметри, а builder компонує їх: - | Option | Що він підключає | + | Параметр | Що він підключає | | --- | --- | - | `security.dm` | Розв’язувач безпеки DM з областю каналу на основі полів config | - | `pairing.text` | Потік текстового сполучення DM з обміном кодами | - | `threading` | Розв’язувач режиму reply-to (фіксований, з областю облікового запису або власний) | - | `outbound.attachedResults` | Функції надсилання, які повертають метадані результату (id повідомлень) | + | `security.dm` | Scoped-резолвер безпеки DM з полів конфігурації | + | `pairing.text` | Потік парування DM на основі тексту з обміном кодами | + | `threading` | Резолвер режиму reply-to (фіксований, прив’язаний до облікового запису або власний) | + | `outbound.attachedResults` | Функції надсилання, які повертають метадані результату (ідентифікатори повідомлень) | - Ви також можете передавати сирі об’єкти adapter-ів замість декларативних параметрів, + Ви також можете передавати сирі об’єкти адаптерів замість декларативних параметрів, якщо вам потрібен повний контроль. - Сирі adapter-и outbound можуть визначати функцію `chunker(text, limit, ctx)`. - Необов’язковий `ctx.formatting` містить рішення форматування під час доставки, - як-от `maxLinesPerMessage`; застосовуйте його до надсилання, щоб прив’язка - відповідей до гілок і межі chunk визначалися один раз спільною outbound-доставкою. + Сирі адаптери outbound можуть визначати функцію `chunker(text, limit, ctx)`. + Необов’язковий `ctx.formatting` містить рішення щодо форматування під час доставки, + такі як `maxLinesPerMessage`; застосовуйте їх перед надсиланням, щоб потоки відповідей + і межі chunk були визначені один раз спільною доставкою outbound. Контексти надсилання також містять `replyToIdSource` (`implicit` або `explicit`), - коли native-ціль відповіді було визначено, щоб helper-и payload могли зберігати + коли було визначено нативну ціль відповіді, щоб helper payload могли зберігати явні теги відповіді без використання неявного одноразового слота reply. @@ -530,23 +533,22 @@ helper-ів runtime inbound. }); ``` - Розміщуйте CLI descriptors, якими володіє канал, у `registerCliMetadata(...)`, щоб OpenClaw + Розміщуйте дескриптори CLI, що належать каналу, у `registerCliMetadata(...)`, щоб OpenClaw міг показувати їх у кореневій довідці без активації повного runtime каналу, - тоді як звичайні повні завантаження все одно підхоплюватимуть ті самі descriptors для реєстрації - реальних команд. Залишайте `registerFull(...)` для роботи, що виконується лише в runtime. - Якщо `registerFull(...)` реєструє gateway RPC methods, використовуйте - префікс, специфічний для plugin. - Простори імен адміністрування core (`config.*`, + водночас звичайні повні завантаження все одно підхоплюватимуть ті самі дескриптори для реєстрації + реальних команд. Залишайте `registerFull(...)` для роботи лише в runtime. + Якщо `registerFull(...)` реєструє методи Gateway RPC, використовуйте + префікс, специфічний для Plugin. Простори імен адміністрування core (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди зіставляються з `operator.admin`. `defineChannelPluginEntry` автоматично обробляє це розділення режимів реєстрації. Див. - [Entry Points](/uk/plugins/sdk-entrypoints#definechannelpluginentry) для всіх + [Точки входу](/uk/plugins/sdk-entrypoints#definechannelpluginentry) для всіх параметрів. - Створіть `setup-entry.ts` для полегшеного завантаження під час onboarding: + Створіть `setup-entry.ts` для полегшеного завантаження під час онбордингу: ```typescript setup-entry.ts import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core"; @@ -556,32 +558,32 @@ helper-ів runtime inbound. ``` OpenClaw завантажує це замість повної точки входу, коли канал вимкнено - або не налаштовано. Це дає змогу уникнути підключення важкого runtime-коду під час потоків setup. - Докладніше див. у [Setup and Config](/uk/plugins/sdk-setup#setup-entry). + або не налаштовано. Це дозволяє уникнути підтягування важкого коду runtime під час потоків setup. + Докладніше див. у [Setup і конфігурація](/uk/plugins/sdk-setup#setup-entry). - Вбудовані workspace-канали, які розділяють безпечні для setup експорти в sidecar- - модулях, можуть використовувати `defineBundledChannelSetupEntry(...)` з + Вбудовані канали робочого простору, які виносять безпечні для setup експорти в sidecar-модулі, + можуть використовувати `defineBundledChannelSetupEntry(...)` з `openclaw/plugin-sdk/channel-entry-contract`, коли їм також потрібен - явний setter runtime під час setup. + явний setter runtime на час setup. - - Ваш plugin має отримувати повідомлення з платформи та пересилати їх до + + Ваш Plugin має отримувати повідомлення з платформи й пересилати їх до OpenClaw. Типовий шаблон — це Webhook, який перевіряє запит і - диспетчеризує його через inbound handler вашого каналу: + диспетчеризує його через обробник вхідних повідомлень вашого каналу: ```typescript registerFull(api) { api.registerHttpRoute({ path: "/acme-chat/webhook", - auth: "plugin", // auth, яким керує plugin (підписи перевіряйте самі) + auth: "plugin", // plugin-managed auth (verify signatures yourself) handler: async (req, res) => { const event = parseWebhookPayload(req); - // Ваш inbound handler диспетчеризує повідомлення до OpenClaw. - // Точне підключення залежить від SDK вашої платформи — - // реальний приклад див. у вбудованому пакеті plugin Microsoft Teams або Google Chat. + // Your inbound handler dispatches the message to OpenClaw. + // The exact wiring depends on your platform SDK — + // see a real example in the bundled Microsoft Teams or Google Chat plugin package. await handleAcmeChatInbound(api, event); res.statusCode = 200; @@ -593,9 +595,9 @@ helper-ів runtime inbound. ``` - Обробка вхідних повідомлень є специфічною для каналу. Кожен plugin каналу - володіє власним inbound pipeline. Подивіться на вбудовані plugins каналів - (наприклад, пакет plugin Microsoft Teams або Google Chat), щоб побачити реальні шаблони. + Обробка вхідних повідомлень є специфічною для каналу. Кожен Plugin каналу + відповідає за власний конвеєр вхідних повідомлень. Подивіться на вбудовані Plugin каналів + (наприклад, пакет Plugin Microsoft Teams або Google Chat), щоб побачити реальні шаблони. @@ -640,7 +642,7 @@ helper-ів runtime inbound. pnpm test -- /acme-chat/ ``` - Спільні helper-и для тестування див. у [Testing](/uk/plugins/sdk-testing). + Спільні helper для тестування див. у [Тестування](/uk/plugins/sdk-testing). @@ -650,51 +652,51 @@ helper-ів runtime inbound. ``` /acme-chat/ ├── package.json # метадані openclaw.channel -├── openclaw.plugin.json # Маніфест зі schema config +├── openclaw.plugin.json # Маніфест зі схемою конфігурації ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry ├── api.ts # Публічні експорти (необов’язково) -├── runtime-api.ts # Внутрішні runtime-експорти (необов’язково) +├── runtime-api.ts # Внутрішні експорти runtime (необов’язково) └── src/ ├── channel.ts # ChannelPlugin через createChatChannelPlugin ├── channel.test.ts # Тести - ├── client.ts # API client платформи + ├── client.ts # API-клієнт платформи └── runtime.ts # Сховище runtime (за потреби) ``` ## Розширені теми - - Фіксовані, з областю облікового запису або власні режими reply + + Фіксовані, прив’язані до облікового запису або власні режими reply describeMessageTool і виявлення дій - + inferTargetChatType, looksLikeId, resolveTarget - + TTS, STT, медіа, subagent через api.runtime -Деякі вбудовані helper seams усе ще існують для підтримки вбудованих plugins і -сумісності. Це не рекомендований шаблон для нових plugin каналів; -надавайте перевагу загальним subpath channel/setup/reply/runtime зі спільної -поверхні SDK, якщо лише ви не підтримуєте цю родину вбудованих plugins безпосередньо. +Деякі вбудовані helper seam усе ще існують для підтримки вбудованих Plugin і +сумісності. Вони не є рекомендованим шаблоном для нових Plugin каналів; +надавайте перевагу загальним підшляхам channel/setup/reply/runtime зі спільної +поверхні SDK, якщо тільки ви не підтримуєте цю сім’ю вбудованих Plugin безпосередньо. ## Наступні кроки -- [Plugins провайдерів](/uk/plugins/sdk-provider-plugins) — якщо ваш plugin також надає моделі -- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів subpath +- [Plugin провайдерів](/uk/plugins/sdk-provider-plugins) — якщо ваш Plugin також надає моделі +- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник з імпортів за підшляхами - [Тестування SDK](/uk/plugins/sdk-testing) — утиліти тестування та контрактні тести -- [Маніфест plugin](/uk/plugins/manifest) — повна schema маніфесту +- [Маніфест Plugin](/uk/plugins/manifest) — повна схема маніфесту ## Пов’язане -- [Налаштування SDK plugin](/uk/plugins/sdk-setup) -- [Створення plugins](/uk/plugins/building-plugins) -- [Plugins harness агента](/uk/plugins/sdk-agent-harness) +- [Setup Plugin SDK](/uk/plugins/sdk-setup) +- [Створення Plugin](/uk/plugins/building-plugins) +- [Plugin обв’язки агента](/uk/plugins/sdk-agent-harness) diff --git a/docs/uk/plugins/sdk-migration.md b/docs/uk/plugins/sdk-migration.md index 0cdaf7ae9..c55985490 100644 --- a/docs/uk/plugins/sdk-migration.md +++ b/docs/uk/plugins/sdk-migration.md @@ -3,83 +3,118 @@ read_when: - Ви бачите попередження OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED - Ви бачите попередження OPENCLAW_EXTENSION_API_DEPRECATED - Ви використовували `api.registerEmbeddedExtensionFactory` до OpenClaw 2026.4.25 - - Ви оновлюєте плагін до сучасної архітектури плагінів - - Ви підтримуєте зовнішній плагін OpenClaw + - Ви оновлюєте Plugin до сучасної архітектури plugin + - Ви підтримуєте зовнішній Plugin OpenClaw sidebarTitle: Migrate to SDK -summary: Перейдіть зі застарілого шару зворотної сумісності на сучасний SDK плагінів -title: Міграція SDK плагінів +summary: Мігруйте із застарілого шару зворотної сумісності на сучасний SDK Plugin +title: Міграція SDK Plugin x-i18n: - generated_at: "2026-04-27T20:08:58Z" + generated_at: "2026-04-28T00:34:31Z" model: gpt-5.4 provider: openai - source_hash: 19e2e5af310234544a3e1ae7a440554f9134f407c6bc896e58b134ed4376b2b3 + source_hash: d3c04ccf641cbcaf34c015d079e5403be738a87fc4bddd974b14455c9cafe0ee source_path: plugins/sdk-migration.md workflow: 15 --- -OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури плагінів зі сфокусованими, задокументованими імпортами. Якщо ваш плагін було створено до появи нової архітектури, цей посібник допоможе вам виконати міграцію. +OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури plugin +із цільовими, задокументованими імпортами. Якщо ваш Plugin було створено до +нової архітектури, цей посібник допоможе вам виконати міграцію. ## Що змінюється -Стара система плагінів надавала дві дуже широкі поверхні, які дозволяли плагінам імпортувати все необхідне з однієї точки входу: +Стара система plugin надавала дві широкі поверхні, які дозволяли plugins імпортувати +все потрібне з однієї точки входу: -- **`openclaw/plugin-sdk/compat`** — єдиний імпорт, який повторно експортував десятки допоміжних функцій. Його було запроваджено, щоб старіші hook-орієнтовані плагіни продовжували працювати, поки будувалася нова архітектура плагінів. -- **`openclaw/plugin-sdk/infra-runtime`** — широкий barrel допоміжних функцій runtime, який поєднував системні події, стан Heartbeat, черги доставки, допоміжні функції fetch/proxy, файлові допоміжні функції, типи approvals і не пов’язані між собою утиліти. -- **`openclaw/plugin-sdk/config-runtime`** — широкий barrel сумісності конфігурації, який під час вікна міграції все ще містить застарілі прямі допоміжні функції load/write. -- **`openclaw/extension-api`** — міст, який надавав плагінам прямий доступ до helper-функцій на боці хоста, таких як вбудований runner агента. -- **`api.registerEmbeddedExtensionFactory(...)`** — вилучений hook для вбудованих розширень лише для Pi, який міг спостерігати за подіями embedded runner, такими як `tool_result`. +- **`openclaw/plugin-sdk/compat`** — один імпорт, який повторно експортував десятки + допоміжних засобів. Його було запроваджено, щоб старіші plugins на основі hook-ів + продовжували працювати, поки будувалася нова архітектура plugin. +- **`openclaw/plugin-sdk/infra-runtime`** — широкий barrel допоміжних засобів середовища виконання, + який змішував системні події, стан Heartbeat, черги доставки, допоміжні засоби fetch/proxy, + файлові допоміжні засоби, типи схвалення та не пов’язані між собою утиліти. +- **`openclaw/plugin-sdk/config-runtime`** — широкий barrel сумісності конфігурації, + який усе ще містить застарілі прямі допоміжні засоби load/write протягом + вікна міграції. +- **`openclaw/extension-api`** — міст, який надавав plugins прямий доступ до + допоміжних засобів на боці хоста, таких як вбудований виконавець агента. +- **`api.registerEmbeddedExtensionFactory(...)`** — вилучений hook вбудованого + extension лише для Pi, який міг спостерігати за подіями вбудованого виконавця, такими як + `tool_result`. -Широкі поверхні імпорту тепер **застарілі**. Вони все ще працюють під час runtime, але нові плагіни не повинні їх використовувати, а наявним плагінам слід виконати міграцію до того, як наступний мажорний реліз їх вилучить. API реєстрації factory вбудованих розширень лише для Pi було вилучено; натомість використовуйте middleware для результатів інструментів. +Широкі поверхні імпорту тепер **deprecated**. Вони все ще працюють у середовищі виконання, +але нові plugins не повинні їх використовувати, а наявні plugins повинні виконати міграцію до +того, як наступний мажорний реліз їх видалить. API реєстрації фабрики вбудованого extension +лише для Pi було вилучено; замість нього використовуйте middleware результатів інструментів. -OpenClaw не вилучає і не переосмислює задокументовану поведінку плагінів у тій самій зміні, яка вводить заміну. Зміни контракту, що ламають сумісність, спочатку мають проходити через адаптер сумісності, діагностику, документацію та вікно застарівання. Це стосується імпортів SDK, полів маніфесту, API setup, hooks і поведінки реєстрації runtime. +OpenClaw не видаляє й не переосмислює задокументовану поведінку plugin у тій самій +зміні, яка вводить заміну. Зміни контрактів із порушенням сумісності спочатку +мають пройти через адаптер сумісності, diagnostics, docs і вікно застарівання. +Це стосується імпортів SDK, полів маніфесту, API setup, hook-ів і поведінки +реєстрації середовища виконання. Шар зворотної сумісності буде вилучено в одному з майбутніх мажорних релізів. - Плагіни, які все ще імпортують із цих поверхонь, перестануть працювати, коли це станеться. - Реєстрації factory вбудованих розширень лише для Pi вже більше не завантажуються. + Plugins, які все ще імпортують із цих поверхонь, перестануть працювати, коли це станеться. + Реєстрації фабрики вбудованого extension лише для Pi вже більше не завантажуються. ## Чому це змінилося -Старий підхід створював проблеми: +Старий підхід спричиняв проблеми: -- **Повільний запуск** — імпорт однієї helper-функції завантажував десятки не пов’язаних модулів +- **Повільний запуск** — імпорт одного допоміжного засобу завантажував десятки не пов’язаних модулів - **Циклічні залежності** — широкі повторні експорти спрощували створення циклів імпорту -- **Неясна поверхня API** — не було способу зрозуміти, які exports були стабільними, а які внутрішніми +- **Нечітка поверхня API** — не було способу зрозуміти, які експорти є стабільними, а які внутрішніми -Сучасний SDK плагінів виправляє це: кожен шлях імпорту (`openclaw/plugin-sdk/\`) є невеликим, самодостатнім модулем із чітким призначенням і задокументованим контрактом. +Сучасний SDK Plugin це виправляє: кожен шлях імпорту (`openclaw/plugin-sdk/\`) +є невеликим, самодостатнім модулем із чітким призначенням і задокументованим контрактом. -Застарілі зручні seams провайдера для вбудованих каналів також прибрано. -Допоміжні seams із брендуванням каналу були приватними скороченнями mono-repo, а не стабільними контрактами плагінів. Натомість використовуйте вузькі загальні subpath SDK. Усередині workspace вбудованого плагіна зберігайте helper-функції, що належать провайдеру, у власному `api.ts` або `runtime-api.ts` цього плагіна. +Застарілі допоміжні з’єднання зручності provider для вбудованих channels також зникли. +Допоміжні з’єднання з брендуванням channel були приватними скороченнями mono-repo, а не стабільними +контрактами plugin. Натомість використовуйте вузькі загальні підшляхи SDK. Усередині +робочого простору вбудованого plugin тримайте допоміжні засоби, що належать provider, у власному +`api.ts` або `runtime-api.ts` цього plugin. -Приклади поточних вбудованих провайдерів: +Поточні приклади вбудованих provider: -- Anthropic зберігає helper-функції потоку, специфічні для Claude, у власному seam `api.ts` / `contract-api.ts` -- OpenAI зберігає builder-и провайдера, helper-функції моделі за замовчуванням і builder-и realtime-провайдера у власному `api.ts` -- OpenRouter зберігає builder провайдера та helper-функції онбордингу/конфігурації у власному `api.ts` +- Anthropic зберігає допоміжні засоби потоку, специфічні для Claude, у власному з’єднанні `api.ts` / + `contract-api.ts` +- OpenAI зберігає побудовники provider, допоміжні засоби моделей за замовчуванням і побудовники + provider реального часу у власному `api.ts` +- OpenRouter зберігає побудовник provider і допоміжні засоби онбордингу/конфігурації у власному + `api.ts` ## Політика сумісності -Для зовнішніх плагінів робота із сумісністю виконується в такому порядку: +Для зовнішніх plugins робота із сумісністю виконується в такому порядку: 1. додати новий контракт -2. зберегти стару поведінку, підключивши її через адаптер сумісності -3. вивести діагностику або попередження з указанням старого шляху та заміни -4. покрити тестами обидва шляхи +2. залишити стару поведінку підключеною через адаптер сумісності +3. вивести diagnostic або warning, який називає старий шлях і заміну +4. покрити обидва шляхи тестами 5. задокументувати застарівання та шлях міграції -6. вилучати лише після оголошеного вікна міграції, зазвичай у мажорному релізі +6. видаляти лише після оголошеного вікна міграції, зазвичай у мажорному релізі -Якщо поле маніфесту все ще приймається, автори плагінів можуть і надалі його використовувати, доки документація та діагностика не скажуть інакше. Новий код має надавати перевагу задокументованій заміні, але наявні плагіни не повинні ламатися під час звичайних мінорних релізів. +Якщо поле маніфесту все ще приймається, автори plugins можуть і далі використовувати його, +доки docs і diagnostics не скажуть інакше. Новий код має надавати перевагу +задокументованій заміні, але наявні plugins не повинні ламатися під час звичайних +мінорних релізів. ## Як виконати міграцію - - Вбудовані плагіни мають припинити прямі виклики + + Вбудовані plugins мають припинити прямі виклики `api.runtime.config.loadConfig()` і - `api.runtime.config.writeConfigFile(...)`. Натомість віддавайте перевагу конфігурації, яку вже передано в активний шлях виклику. Довгоживучі обробники, яким потрібен поточний snapshot процесу, можуть використовувати `api.runtime.config.current()`. Довгоживучі інструменти агента мають використовувати `ctx.getRuntimeConfig()` із контексту інструмента всередині `execute`, щоб інструмент, створений до запису конфігурації, усе одно бачив оновлену конфігурацію runtime. + `api.runtime.config.writeConfigFile(...)`. Надавайте перевагу конфігурації, яку вже + було передано в активний шлях виклику. Довгоживучі обробники, яким потрібен + поточний знімок процесу, можуть використовувати `api.runtime.config.current()`. Довгоживучі + інструменти агента мають використовувати `ctx.getRuntimeConfig()` із контексту інструмента в + `execute`, щоб інструмент, створений до запису конфігурації, усе одно бачив + оновлену конфігурацію середовища виконання. - Запис конфігурації має відбуватися через транзакційні helper-функції з вибором політики після запису: + Запис конфігурації має виконуватися через транзакційні допоміжні засоби з + вибором політики після запису: ```typescript await api.runtime.config.mutateConfigFile({ @@ -92,45 +127,51 @@ OpenClaw не вилучає і не переосмислює задокумен Використовуйте `afterWrite: { mode: "restart", reason: "..." }`, коли викликач знає, що зміна потребує чистого перезапуску Gateway, і - `afterWrite: { mode: "none", reason: "..." }` лише тоді, коли викликач сам відповідає - за наступні дії та свідомо хоче вимкнути планувальник перезавантаження. - Результати мутацій містять типізований підсумок `followUp` для тестів і логування; - Gateway як і раніше відповідає за застосування або планування перезапуску. - `loadConfig` і `writeConfigFile` залишаються як застарілі helper-функції сумісності - для зовнішніх плагінів протягом вікна міграції та один раз показують попередження з - кодом сумісності `runtime-config-load-write`. Вбудовані плагіни та код runtime репозиторію - захищені scanner-обмеженнями у + `afterWrite: { mode: "none", reason: "..." }` лише тоді, коли викликач сам керує + наступним кроком і свідомо хоче приглушити планувальник перезавантаження. + Результати мутації містять типізований підсумок `followUp` для тестів і журналювання; + Gateway і далі відповідає за застосування або планування перезапуску. + `loadConfig` і `writeConfigFile` залишаються як застарілі допоміжні засоби + сумісності для зовнішніх plugins протягом вікна міграції та один раз попереджають + із кодом сумісності `runtime-config-load-write`. Вбудовані plugins і код + середовища виконання репозиторію захищені обмеженнями сканера в `pnpm check:deprecated-internal-config-api` і - `pnpm check:no-runtime-action-load-config`: нове використання виробничими плагінами - відразу завершується помилкою, прямі записи конфігурації завершуються помилкою, методи сервера gateway мають використовувати snapshot runtime запиту, helper-функції send/action/client каналу runtime мають отримувати конфігурацію зі своєї межі, а довгоживучі модулі runtime мають нульову допустиму кількість ambient-викликів `loadConfig()`. + `pnpm check:no-runtime-action-load-config`: нове використання plugin у production + одразу завершується помилкою, прямі записи конфігурації завершуються помилкою, + методи сервера gateway мають використовувати знімок середовища виконання запиту, + допоміжні засоби send/action/client середовища виконання channel + мають отримувати конфігурацію зі своєї межі, а довгоживучі модулі середовища виконання + мають нуль допустимих фонових викликів `loadConfig()`. - Новий код плагінів також має уникати імпорту широкого barrel сумісності - `openclaw/plugin-sdk/config-runtime`. Використовуйте вузький subpath SDK, який відповідає завданню: + Новий код plugin також повинен уникати імпорту широкого + barrel сумісності `openclaw/plugin-sdk/config-runtime`. Використовуйте + вузький підшлях SDK, що відповідає задачі: | Потреба | Імпорт | | --- | --- | | Типи конфігурації, такі як `OpenClawConfig` | `openclaw/plugin-sdk/config-types` | - | Перевірки вже завантаженої конфігурації та пошук конфігурації запису плагіна | `openclaw/plugin-sdk/plugin-config-runtime` | - | Читання поточного snapshot runtime | `openclaw/plugin-sdk/runtime-config-snapshot` | + | Перевірки вже завантаженої конфігурації та пошук конфігурації запису plugin | `openclaw/plugin-sdk/plugin-config-runtime` | + | Читання поточного знімка середовища виконання | `openclaw/plugin-sdk/runtime-config-snapshot` | | Записи конфігурації | `openclaw/plugin-sdk/config-mutation` | - | Helper-функції сховища сесій | `openclaw/plugin-sdk/session-store-runtime` | + | Допоміжні засоби сховища сесій | `openclaw/plugin-sdk/session-store-runtime` | | Конфігурація таблиць Markdown | `openclaw/plugin-sdk/markdown-table-runtime` | - | Helper-функції runtime для політики груп | `openclaw/plugin-sdk/runtime-group-policy` | + | Допоміжні засоби середовища виконання політики груп | `openclaw/plugin-sdk/runtime-group-policy` | | Розв’язання secret input | `openclaw/plugin-sdk/secret-input-runtime` | | Перевизначення моделі/сесії | `openclaw/plugin-sdk/model-session-runtime` | - Вбудовані плагіни та їхні тести захищені scanner-перевірками від широкого - barrel, тому імпорти й mocks залишаються локальними для потрібної їм поведінки. Широкий - barrel усе ще існує для зовнішньої сумісності, але новий код не повинен від нього залежати. + Вбудовані plugins та їхні тести захищені сканером від цього широкого + barrel, щоб імпорти й mock-и залишалися локальними для потрібної їм поведінки. Широкий + barrel і далі існує для зовнішньої сумісності, але новий код не повинен від нього залежати. - - Вбудовані плагіни мають замінити обробники результатів інструментів лише для Pi через - `api.registerEmbeddedExtensionFactory(...)` на runtime-нейтральне middleware. + + Вбудовані plugins мають замінити обробники результатів інструментів + `api.registerEmbeddedExtensionFactory(...)` лише для Pi + на middleware, нейтральне до середовища виконання. ```typescript - // Pi and Codex runtime dynamic tools + // Динамічні інструменти середовища виконання Pi і Codex api.registerAgentToolResultMiddleware(async (event) => { return compactToolResult(event); }, { @@ -138,7 +179,7 @@ OpenClaw не вилучає і не переосмислює задокумен }); ``` - Одночасно оновіть маніфест плагіна: + Одночасно оновіть маніфест plugin: ```json { @@ -148,61 +189,61 @@ OpenClaw не вилучає і не переосмислює задокумен } ``` - Зовнішні плагіни не можуть реєструвати middleware результатів інструментів, оскільки воно може - переписувати високодовірений вивід інструмента до того, як його побачить модель. + Зовнішні plugins не можуть реєструвати middleware результатів інструментів, оскільки воно + може переписувати високодовірений вивід інструментів до того, як модель його побачить. - - Плагіни каналів із підтримкою approval тепер надають нативну поведінку approval через - `approvalCapability.nativeRuntime` разом зі спільним реєстром runtime-context. + + Plugins channel із можливістю схвалення тепер надають native-поведінку схвалення через + `approvalCapability.nativeRuntime` плюс спільний реєстр контексту середовища виконання. - Основні зміни: + Ключові зміни: - Замініть `approvalCapability.handler.loadRuntime(...)` на `approvalCapability.nativeRuntime` - - Перенесіть auth/delivery, специфічні для approval, зі старої прив’язки `plugin.auth` / - `plugin.approvals` до `approvalCapability` + - Перенесіть auth/delivery, специфічні для схвалення, зі застарілої зв’язки `plugin.auth` / + `plugin.approvals` на `approvalCapability` - `ChannelPlugin.approvals` вилучено з публічного контракту channel-plugin; перенесіть поля delivery/native/render до `approvalCapability` - - `plugin.auth` залишається лише для потоків входу/виходу в channel; approval - hooks там більше не зчитуються ядром - - Реєструйте об’єкти runtime, що належать каналу, такі як клієнти, токени або Bolt + - `plugin.auth` залишається лише для потоків входу/виходу channel; auth + hook-и схвалення там більше не зчитуються core + - Реєструйте об’єкти середовища виконання, що належать channel, такі як clients, tokens або Bolt apps, через `openclaw/plugin-sdk/channel-runtime-context` - - Не надсилайте сповіщення reroute, що належать плагіну, із native approval handlers; - тепер ядро саме відповідає за routed-elsewhere notices на основі фактичних результатів доставки - - Під час передавання `channelRuntime` у `createChannelManager(...)` надавайте + - Не надсилайте сповіщення reroute, що належать plugin, з native-обробників схвалення; + core тепер сам володіє сповіщеннями routed-elsewhere з фактичних результатів доставки + - Передаючи `channelRuntime` до `createChannelManager(...)`, надавайте реальну поверхню `createPluginRuntime().channel`. Часткові stubs відхиляються. - Поточну структуру capability approval див. у `/plugins/sdk-channel-plugins`. + Поточну структуру можливостей схвалення дивіться в `/plugins/sdk-channel-plugins`. - - Якщо ваш плагін використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані Windows - wrapper-и `.cmd`/`.bat` тепер завершуються із закритою відмовою, якщо ви явно не передасте + + Якщо ваш Plugin використовує `openclaw/plugin-sdk/windows-spawn`, + нерозв’язані wrappers Windows `.cmd`/`.bat` тепер завершуються відмовою за замовчуванням, якщо ви явно не передасте `allowShellFallback: true`. ```typescript - // Before + // До const program = applyWindowsSpawnProgramPolicy({ candidate }); - // After + // Після const program = applyWindowsSpawnProgramPolicy({ candidate, - // Only set this for trusted compatibility callers that intentionally - // accept shell-mediated fallback. + // Установлюйте це лише для довірених сумісних викликачів, які свідомо + // допускають резервний перехід через shell. allowShellFallback: true, }); ``` - Якщо ваш викликач навмисно не покладається на shell fallback, не встановлюйте + Якщо ваш викликач свідомо не покладається на резервний перехід через shell, не встановлюйте `allowShellFallback`, а натомість обробляйте викинуту помилку. - Виконайте пошук у своєму плагіні імпортів із будь-якої застарілої поверхні: + Знайдіть у своєму plugin імпорти з будь-якої застарілої поверхні: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -213,36 +254,36 @@ OpenClaw не вилучає і не переосмислює задокумен - - Кожен export зі старої поверхні відповідає певному сучасному шляху імпорту: + + Кожен експорт зі старої поверхні відповідає конкретному сучасному шляху імпорту: ```typescript - // Before (deprecated backwards-compatibility layer) + // До (застарілий шар зворотної сумісності) import { createChannelReplyPipeline, createPluginRuntimeStore, resolveControlCommandGate, } from "openclaw/plugin-sdk/compat"; - // After (modern focused imports) + // Після (сучасні цільові імпорти) import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - Для helper-функцій на боці хоста використовуйте інжектований runtime плагіна замість + Для допоміжних засобів на боці хоста використовуйте впроваджене середовище виконання plugin замість прямого імпорту: ```typescript - // Before (deprecated extension-api bridge) + // До (застарілий міст extension-api) import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); - // After (injected runtime) + // Після (впроваджене середовище виконання) const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - Той самий шаблон застосовується й до інших legacy helper-функцій bridge: + Та сама схема застосовується й до інших застарілих допоміжних засобів моста: | Старий імпорт | Сучасний еквівалент | | --- | --- | @@ -252,41 +293,65 @@ OpenClaw не вилучає і не переосмислює задокумен | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | helper-функції сховища сесій | `api.runtime.agent.session.*` | + | допоміжні засоби сховища сесій | `api.runtime.agent.session.*` | `openclaw/plugin-sdk/infra-runtime` усе ще існує для зовнішньої - сумісності, але новий код має імпортувати сфокусовану поверхню helper-функцій, + сумісності, але новий код повинен імпортувати цільову поверхню допоміжних засобів, яка йому фактично потрібна: | Потреба | Імпорт | | --- | --- | - | Helper-функції черги системних подій | `openclaw/plugin-sdk/system-event-runtime` | - | Helper-функції подій і видимості Heartbeat | `openclaw/plugin-sdk/heartbeat-runtime` | - | Зливання черги відкладеної доставки | `openclaw/plugin-sdk/delivery-queue-runtime` | - | Телеметрія активності каналу | `openclaw/plugin-sdk/channel-activity-runtime` | + | Допоміжні засоби черги системних подій | `openclaw/plugin-sdk/system-event-runtime` | + | Допоміжні засоби подій і видимості Heartbeat | `openclaw/plugin-sdk/heartbeat-runtime` | + | Злив черги очікуваної доставки | `openclaw/plugin-sdk/delivery-queue-runtime` | + | Телеметрія активності channel | `openclaw/plugin-sdk/channel-activity-runtime` | | In-memory кеші дедуплікації | `openclaw/plugin-sdk/dedupe-runtime` | - | Безпечні helper-функції шляхів до локальних файлів/медіа | `openclaw/plugin-sdk/file-access-runtime` | + | Безпечні допоміжні засоби шляхів до локальних файлів/медіа | `openclaw/plugin-sdk/file-access-runtime` | | Fetch з урахуванням dispatcher | `openclaw/plugin-sdk/runtime-fetch` | - | Helper-функції proxy і guarded fetch | `openclaw/plugin-sdk/fetch-runtime` | + | Допоміжні засоби proxy і захищеного fetch | `openclaw/plugin-sdk/fetch-runtime` | | Типи політики SSRF dispatcher | `openclaw/plugin-sdk/ssrf-dispatcher` | - | Типи запиту/розв’язання approval | `openclaw/plugin-sdk/approval-runtime` | - | Payload відповіді approval і helper-функції команд | `openclaw/plugin-sdk/approval-reply-runtime` | - | Helper-функції форматування помилок | `openclaw/plugin-sdk/error-runtime` | - | Очікування готовності транспорту | `openclaw/plugin-sdk/transport-ready-runtime` | - | Helper-функції безпечних токенів | `openclaw/plugin-sdk/secure-random-runtime` | - | Обмежена конкурентність асинхронних завдань | `openclaw/plugin-sdk/concurrency-runtime` | + | Типи запиту/розв’язання схвалення | `openclaw/plugin-sdk/approval-runtime` | + | Допоміжні засоби payload відповіді на схвалення та команд | `openclaw/plugin-sdk/approval-reply-runtime` | + | Допоміжні засоби форматування помилок | `openclaw/plugin-sdk/error-runtime` | + | Очікування готовності transport | `openclaw/plugin-sdk/transport-ready-runtime` | + | Допоміжні засоби безпечних токенів | `openclaw/plugin-sdk/secure-random-runtime` | + | Обмежена конкурентність асинхронних задач | `openclaw/plugin-sdk/concurrency-runtime` | | Числове приведення | `openclaw/plugin-sdk/number-runtime` | - | Асинхронне блокування локального процесу | `openclaw/plugin-sdk/async-lock-runtime` | + | Асинхронне блокування в межах процесу | `openclaw/plugin-sdk/async-lock-runtime` | | Блокування файлів | `openclaw/plugin-sdk/file-lock` | - Вбудовані плагіни захищені scanner-перевірками від `infra-runtime`, тож код репозиторію + Вбудовані plugins захищені сканером від `infra-runtime`, тому код репозиторію не може повернутися до широкого barrel. + + Новий код маршрутів channel повинен використовувати `openclaw/plugin-sdk/channel-route`. + Старіші назви route-key і comparable-target залишаються як псевдоніми + сумісності протягом вікна міграції, але нові plugins повинні використовувати назви маршрутів, + які безпосередньо описують поведінку: + + | Старий допоміжний засіб | Сучасний допоміжний засіб | + | --- | --- | + | `channelRouteIdentityKey(...)` | `channelRouteDedupeKey(...)` | + | `channelRouteKey(...)` | `channelRouteCompactKey(...)` | + | `ComparableChannelTarget` | `ChannelRouteParsedTarget` | + | `resolveComparableTargetForChannel(...)` | `resolveRouteTargetForChannel(...)` | + | `resolveComparableTargetForLoadedChannel(...)` | `resolveRouteTargetForLoadedChannel(...)` | + | `comparableChannelTargetsMatch(...)` | `channelRouteTargetsMatchExact(...)` | + | `comparableChannelTargetsShareRoute(...)` | `channelRouteTargetsShareConversation(...)` | + + Сучасні допоміжні засоби маршрутів послідовно нормалізують + `{ channel, to, accountId, threadId }` для native-схвалень, приглушення відповідей, дедуплікації вхідних даних, + доставки Cron і маршрутизації сесій. Якщо ваш Plugin володіє власною граматикою + цілей, використовуйте `resolveChannelRouteTargetWithParser(...)`, щоб адаптувати цей + parser до того самого контракту цілі маршруту. + + + ```bash pnpm build @@ -298,194 +363,193 @@ OpenClaw не вилучає і не переосмислює задокумен ## Довідник шляхів імпорту - | Import path | Призначення | Ключові exports | + | Шлях імпорту | Призначення | Ключові експорти | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Канонічний helper для входу плагіна | `definePluginEntry` | - | `plugin-sdk/core` | Застарілий umbrella-реекспорт для визначень/builders входу каналу | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/plugin-entry` | Канонічний допоміжний засіб точки входу plugin | `definePluginEntry` | + | `plugin-sdk/core` | Застарілий umbrella-повторний експорт для визначень/побудовників точки входу channel | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | Експорт кореневої схеми конфігурації | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Helper для входу одного провайдера | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Сфокусовані визначення та builders входу каналу | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Спільні helper-функції майстра налаштування | Підказки allowlist, builders статусу налаштування | - | `plugin-sdk/setup-runtime` | Helper-функції runtime під час налаштування | Безпечні для імпорту setup patch adapters, helper-функції lookup-note, `promptResolvedAllowFrom`, `splitSetupEntries`, delegated setup proxies | - | `plugin-sdk/setup-adapter-runtime` | Helper-функції setup adapter | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | Helper-функції інструментів налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helper-функції для кількох облікових записів | Helper-функції списку/конфігурації/шлюзу дій облікових записів | - | `plugin-sdk/account-id` | Helper-функції account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id | - | `plugin-sdk/account-resolution` | Helper-функції пошуку облікового запису | Helper-функції пошуку облікового запису + fallback до значення за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі helper-функції для облікових записів | Helper-функції списку облікових записів/дій облікових записів | - | `plugin-sdk/channel-setup` | Adapters майстра налаштування | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/provider-entry` | Допоміжний засіб точки входу одного provider | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Цільові визначення та побудовники точки входу channel | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | Спільні допоміжні засоби майстра setup | Запити allowlist, побудовники статусу setup | + | `plugin-sdk/setup-runtime` | Допоміжні засоби середовища виконання під час setup | Безпечні для імпорту адаптери patch setup, допоміжні засоби приміток lookup, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі setup | + | `plugin-sdk/setup-adapter-runtime` | Допоміжні засоби адаптера setup | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | Допоміжні засоби інструментів setup | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | Допоміжні засоби для кількох облікових записів | Допоміжні засоби списку/конфігурації/шлюзу дій облікових записів | + | `plugin-sdk/account-id` | Допоміжні засоби account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id | + | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікових записів | Допоміжні засоби пошуку облікових записів + резервного використання за замовчуванням | + | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби облікових записів | Допоміжні засоби списку облікових записів/дій над обліковими записами | + | `plugin-sdk/channel-setup` | Адаптери майстра setup | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | | `plugin-sdk/channel-pairing` | Примітиви pairing для DM | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | Підключення префікса відповіді + typing | `createChannelReplyPipeline` | - | `plugin-sdk/channel-config-helpers` | Factory config adapter | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Builders схем конфігурації | Спільні примітиви схеми конфігурації каналу та лише загальний builder | - | `plugin-sdk/channel-config-schema-legacy` | Застарілі схеми конфігурації вбудованих плагінів | Лише для сумісності вбудованих плагінів; нові плагіни мають визначати локальні схеми плагіна | - | `plugin-sdk/telegram-command-config` | Helper-функції конфігурації команд Telegram | Нормалізація імен команд, обрізання опису, перевірка дублікатів/конфліктів | - | `plugin-sdk/channel-policy` | Розв’язання політики груп/DM | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | Helper-функції статусу облікового запису та життєвого циклу draft stream | `createAccountStatusSink`, helper-функції завершення preview чернетки | - | `plugin-sdk/inbound-envelope` | Helper-функції вхідного envelope | Спільні helper-функції маршрутизації + builder envelope | - | `plugin-sdk/inbound-reply-dispatch` | Helper-функції вхідної відповіді | Спільні helper-функції запису та dispatch | - | `plugin-sdk/messaging-targets` | Парсинг цілей повідомлень | Helper-функції парсингу/зіставлення цілей | - | `plugin-sdk/outbound-media` | Helper-функції вихідних медіа | Спільне завантаження вихідних медіа | - | `plugin-sdk/outbound-send-deps` | Helper-функції залежностей outbound send | Полегшений пошук `resolveOutboundSendDep` без імпорту всього outbound runtime | - | `plugin-sdk/outbound-runtime` | Helper-функції outbound runtime | Helper-функції outbound delivery, delegate identity/send, session, formatting і планування payload | - | `plugin-sdk/thread-bindings-runtime` | Helper-функції thread-binding | Helper-функції життєвого циклу та adapters thread-binding | - | `plugin-sdk/agent-media-payload` | Застарілі helper-функції media payload | Builder media payload агента для застарілих layout полів | - | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти channel runtime | - | `plugin-sdk/channel-send-result` | Типи результату send | Типи результату відповіді | - | `plugin-sdk/runtime-store` | Постійне сховище плагіна | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | Широкі helper-функції runtime | Helper-функції runtime/logging/backup/встановлення плагінів | - | `plugin-sdk/runtime-env` | Вузькі helper-функції runtime env | Helper-функції logger/runtime env, timeout, retry і backoff | - | `plugin-sdk/plugin-runtime` | Спільні helper-функції runtime плагіна | Helper-функції команд/hooks/http/interactive плагіна | - | `plugin-sdk/hook-runtime` | Helper-функції pipeline hooks | Спільні helper-функції pipeline webhook/internal hook | - | `plugin-sdk/lazy-runtime` | Helper-функції lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Helper-функції процесу | Спільні helper-функції exec | - | `plugin-sdk/cli-runtime` | Helper-функції CLI runtime | Форматування команд, очікування, helper-функції версій | - | `plugin-sdk/gateway-runtime` | Helper-функції Gateway | Helper-функції клієнта Gateway і patch статусу каналу | + | `plugin-sdk/channel-reply-pipeline` | Зв’язування префікса відповіді + typing | `createChannelReplyPipeline` | + | `plugin-sdk/channel-config-helpers` | Фабрики адаптерів конфігурації | `createHybridChannelConfigAdapter` | + | `plugin-sdk/channel-config-schema` | Побудовники схем конфігурації | Спільні примітиви схеми конфігурації channel і лише загальний побудовник | + | `plugin-sdk/channel-config-schema-legacy` | Застарілі схеми конфігурації вбудованих channel | Лише сумісність для вбудованих; нові plugins мають визначати локальні схеми plugin | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби конфігурації команд Telegram | Нормалізація назв команд, обрізання описів, перевірка дублікатів/конфліктів | + | `plugin-sdk/channel-policy` | Визначення політики груп/DM | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-lifecycle` | Допоміжні засоби статусу облікового запису та життєвого циклу потоку чернеток | `createAccountStatusSink`, допоміжні засоби фіналізації попереднього перегляду чернетки | + | `plugin-sdk/inbound-envelope` | Допоміжні засоби inbound envelope | Спільні допоміжні засоби маршруту + побудовника envelope | + | `plugin-sdk/inbound-reply-dispatch` | Допоміжні засоби inbound reply | Спільні допоміжні засоби запису й dispatch | + | `plugin-sdk/messaging-targets` | Розбір цілей повідомлень | Допоміжні засоби розбору/зіставлення цілей | + | `plugin-sdk/outbound-media` | Допоміжні засоби outbound media | Спільне завантаження outbound media | + | `plugin-sdk/outbound-send-deps` | Допоміжні засоби залежностей outbound send | Полегшений пошук `resolveOutboundSendDep` без імпорту повного outbound runtime | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби outbound runtime | Допоміжні засоби outbound доставки, identity/send delegate, сесій, форматування та планування payload | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби прив’язок потоків | Допоміжні засоби життєвого циклу та адаптера прив’язок потоків | + | `plugin-sdk/agent-media-payload` | Застарілі допоміжні засоби media payload | Побудовник media payload агента для застарілих макетів полів | + | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти середовища виконання channel | + | `plugin-sdk/channel-send-result` | Типи результатів send | Типи результатів reply | + | `plugin-sdk/runtime-store` | Постійне сховище plugin | `createPluginRuntimeStore` | + | `plugin-sdk/runtime` | Широкі допоміжні засоби середовища виконання | Допоміжні засоби runtime/logging/backup/встановлення plugin | + | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env | Logger/runtime env, timeout, retry та допоміжні засоби backoff | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби середовища виконання plugin | Допоміжні засоби команд/hooks/http/interactive plugin | + | `plugin-sdk/hook-runtime` | Допоміжні засоби pipeline hook | Спільні допоміжні засоби pipeline Webhook/внутрішніх hook | + | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Допоміжні засоби процесу | Спільні допоміжні засоби exec | + | `plugin-sdk/cli-runtime` | Допоміжні засоби середовища виконання CLI | Форматування команд, очікування, допоміжні засоби версії | + | `plugin-sdk/gateway-runtime` | Допоміжні засоби Gateway | Допоміжні засоби клієнта Gateway та patch статусу channel | | `plugin-sdk/config-runtime` | Застарілий shim сумісності конфігурації | Надавайте перевагу `config-types`, `plugin-config-runtime`, `runtime-config-snapshot` і `config-mutation` | - | `plugin-sdk/telegram-command-config` | Helper-функції команд Telegram | Стабільні helper-функції перевірки команд Telegram із fallback, коли поверхня контракту вбудованого Telegram недоступна | - | `plugin-sdk/approval-runtime` | Helper-функції prompts approval | Payload approval exec/plugin, helper-функції capability/profile approval, helper-функції маршрутизації/runtime native approval і форматування шляху структурованого відображення approval | - | `plugin-sdk/approval-auth-runtime` | Helper-функції auth approval | Розв’язання approver, auth дій у тому ж чаті | - | `plugin-sdk/approval-client-runtime` | Helper-функції клієнта approval | Helper-функції profile/filter native exec approval | - | `plugin-sdk/approval-delivery-runtime` | Helper-функції delivery approval | Adapters capability/delivery native approval | - | `plugin-sdk/approval-gateway-runtime` | Helper-функції Gateway approval | Спільна helper-функція gateway-resolution approval | - | `plugin-sdk/approval-handler-adapter-runtime` | Helper-функції adapters approval | Полегшені helper-функції завантаження adapter native approval для hot entrypoint каналів | - | `plugin-sdk/approval-handler-runtime` | Helper-функції handlers approval | Ширші helper-функції runtime handlers approval; надавайте перевагу вужчим seams adapter/gateway, коли їх достатньо | - | `plugin-sdk/approval-native-runtime` | Helper-функції цілей approval | Helper-функції native approval target/account binding | - | `plugin-sdk/approval-reply-runtime` | Helper-функції відповіді approval | Helper-функції payload відповіді approval exec/plugin | - | `plugin-sdk/channel-runtime-context` | Helper-функції runtime-context каналу | Загальні helper-функції register/get/watch для runtime-context каналу | - | `plugin-sdk/security-runtime` | Helper-функції безпеки | Спільні helper-функції trust, DM gating, external-content і збирання секретів | - | `plugin-sdk/ssrf-policy` | Helper-функції політики SSRF | Helper-функції allowlist хостів і політики приватної мережі | - | `plugin-sdk/ssrf-runtime` | Helper-функції SSRF runtime | Helper-функції pinned-dispatcher, guarded fetch, SSRF policy | - | `plugin-sdk/system-event-runtime` | Helper-функції системних подій | `enqueueSystemEvent`, `peekSystemEventEntries` | - | `plugin-sdk/heartbeat-runtime` | Helper-функції Heartbeat | Helper-функції подій і видимості Heartbeat | - | `plugin-sdk/delivery-queue-runtime` | Helper-функції черги доставки | `drainPendingDeliveries` | - | `plugin-sdk/channel-activity-runtime` | Helper-функції активності каналу | `recordChannelActivity` | - | `plugin-sdk/dedupe-runtime` | Helper-функції дедуплікації | In-memory кеші дедуплікації | - | `plugin-sdk/file-access-runtime` | Helper-функції доступу до файлів | Безпечні helper-функції шляхів до локальних файлів/медіа | - | `plugin-sdk/transport-ready-runtime` | Helper-функції готовності транспорту | `waitForTransportReady` | - | `plugin-sdk/collection-runtime` | Helper-функції обмеженого кешу | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Helper-функції керування діагностикою | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | Helper-функції форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, helper-функції графа помилок | - | `plugin-sdk/fetch-runtime` | Обгорнуті helper-функції fetch/proxy | `resolveFetch`, helper-функції proxy | - | `plugin-sdk/host-runtime` | Helper-функції нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | Helper-функції retry | `RetryConfig`, `retryAsync`, runners політики | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби команд Telegram | Допоміжні засоби перевірки команд Telegram зі стабільним резервним варіантом, коли поверхня контракту вбудованого Telegram недоступна | + | `plugin-sdk/approval-runtime` | Допоміжні засоби запитів схвалення | Payload схвалення exec/plugin, допоміжні засоби capability/profile схвалення, native-маршрутизація/середовище виконання схвалення та форматування шляху структурованого відображення схвалення | + | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби auth схвалення | Визначення approver, auth дій у тому самому чаті | + | `plugin-sdk/approval-client-runtime` | Допоміжні засоби клієнта схвалення | Допоміжні засоби profile/filter native exec approval | + | `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби доставки схвалення | Адаптери capability/delivery native approval | + | `plugin-sdk/approval-gateway-runtime` | Допоміжні засоби Gateway схвалення | Спільний допоміжний засіб визначення Gateway схвалення | + | `plugin-sdk/approval-handler-adapter-runtime` | Допоміжні засоби адаптера схвалення | Полегшені допоміжні засоби завантаження адаптера native approval для гарячих точок входу channel | + | `plugin-sdk/approval-handler-runtime` | Допоміжні засоби обробника схвалення | Ширші допоміжні засоби середовища виконання обробника схвалення; надавайте перевагу вужчим з’єднанням adapter/gateway, якщо їх достатньо | + | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей схвалення | Допоміжні засоби прив’язки цілі/облікового запису native approval | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби reply схвалення | Допоміжні засоби payload відповіді на схвалення exec/plugin | + | `plugin-sdk/channel-runtime-context` | Допоміжні засоби runtime-context channel | Загальні допоміжні засоби register/get/watch runtime-context channel | + | `plugin-sdk/security-runtime` | Допоміжні засоби безпеки | Спільні допоміжні засоби trust, обмеження DM, зовнішнього вмісту та збирання секретів | + | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF | Допоміжні засоби allowlist хостів і політики приватної мережі | + | `plugin-sdk/ssrf-runtime` | Допоміжні засоби SSRF runtime | Допоміжні засоби pinned-dispatcher, guarded fetch, політики SSRF | + | `plugin-sdk/system-event-runtime` | Допоміжні засоби системних подій | `enqueueSystemEvent`, `peekSystemEventEntries` | + | `plugin-sdk/heartbeat-runtime` | Допоміжні засоби Heartbeat | Допоміжні засоби подій і видимості Heartbeat | + | `plugin-sdk/delivery-queue-runtime` | Допоміжні засоби черги доставки | `drainPendingDeliveries` | + | `plugin-sdk/channel-activity-runtime` | Допоміжні засоби активності channel | `recordChannelActivity` | + | `plugin-sdk/dedupe-runtime` | Допоміжні засоби дедуплікації | In-memory кеші дедуплікації | + | `plugin-sdk/file-access-runtime` | Допоміжні засоби доступу до файлів | Безпечні допоміжні засоби шляхів до локальних файлів/медіа | + | `plugin-sdk/transport-ready-runtime` | Допоміжні засоби готовності transport | `waitForTransportReady` | + | `plugin-sdk/collection-runtime` | Допоміжні засоби обмеженого кешу | `pruneMapToMaxSize` | + | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби керування diagnostics | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | Допоміжні засоби форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні засоби графа помилок | + | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch/proxy | `resolveFetch`, допоміжні засоби proxy | + | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/retry-runtime` | Допоміжні засоби retry | `RetryConfig`, `retryAsync`, виконавці політики | | `plugin-sdk/allow-from` | Форматування allowlist | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Відображення входів allowlist | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Helper-функції gating команд і поверхні команд | `resolveControlCommandGate`, helper-функції авторизації відправника, helper-функції реєстру команд, включно з форматуванням меню динамічних аргументів | - | `plugin-sdk/command-status` | Renderers статусу/довідки команд | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | Парсинг secret input | Helper-функції secret input | - | `plugin-sdk/webhook-ingress` | Helper-функції запиту Webhook | Утиліти цілі Webhook | - | `plugin-sdk/webhook-request-guards` | Helper-функції guards тіла запиту Webhook | Helper-функції читання/обмеження тіла запиту | - | `plugin-sdk/reply-runtime` | Спільний reply runtime | Inbound dispatch, Heartbeat, planner відповіді, chunking | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі helper-функції dispatch відповіді | Helper-функції finalize, dispatch провайдера та міток розмов | - | `plugin-sdk/reply-history` | Helper-функції історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | - | `plugin-sdk/reply-reference` | Планування посилань відповіді | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Helper-функції chunk відповіді | Helper-функції chunking тексту/markdown | - | `plugin-sdk/session-store-runtime` | Helper-функції сховища сесій | Helper-функції шляху сховища + updated-at | - | `plugin-sdk/state-paths` | Helper-функції шляхів стану | Helper-функції каталогів стану та OAuth | - | `plugin-sdk/routing` | Helper-функції маршрутизації/ключів сесії | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, helper-функції нормалізації ключів сесії | - | `plugin-sdk/status-helpers` | Helper-функції статусу каналу | Builders підсумку статусу каналу/облікового запису, значення за замовчуванням для runtime-state, helper-функції метаданих проблем | - | `plugin-sdk/target-resolver-runtime` | Helper-функції розв’язання цілей | Спільні helper-функції target resolver | - | `plugin-sdk/string-normalization-runtime` | Helper-функції нормалізації рядків | Helper-функції нормалізації slug/рядків | - | `plugin-sdk/request-url` | Helper-функції URL запиту | Витягування рядкових URL із request-подібних входів | - | `plugin-sdk/run-command` | Helper-функції команд із таймером | Runner команд із таймером і нормалізованими stdout/stderr | - | `plugin-sdk/param-readers` | Readers параметрів | Загальні readers параметрів tool/CLI | - | `plugin-sdk/tool-payload` | Витягування payload інструмента | Витягування нормалізованих payload із об’єктів результатів інструментів | + | `plugin-sdk/allowlist-resolution` | Відображення вхідних даних allowlist | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Допоміжні засоби командного gating і поверхні команд | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, допоміжні засоби реєстру команд, включно з форматуванням меню динамічних аргументів | + | `plugin-sdk/command-status` | Засоби відтворення статусу/довідки команд | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | + | `plugin-sdk/secret-input` | Розбір secret input | Допоміжні засоби secret input | + | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів Webhook | Утиліти цілей Webhook | + | `plugin-sdk/webhook-request-guards` | Допоміжні засоби guard для тіла запиту Webhook | Допоміжні засоби читання/обмеження тіла запиту | + | `plugin-sdk/reply-runtime` | Спільне середовище виконання reply | Inbound dispatch, Heartbeat, планувальник reply, розбиття на частини | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch reply | Допоміжні засоби фіналізації, dispatch provider і міток розмов | + | `plugin-sdk/reply-history` | Допоміжні засоби історії reply | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-reference` | Планування посилань reply | `createReplyReferencePlanner` | + | `plugin-sdk/reply-chunking` | Допоміжні засоби chunk для reply | Допоміжні засоби chunk для text/markdown | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища сесій | Допоміжні засоби шляху сховища + updated-at | + | `plugin-sdk/state-paths` | Допоміжні засоби шляхів стану | Допоміжні засоби каталогів стану й OAuth | + | `plugin-sdk/routing` | Допоміжні засоби routing/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні засоби нормалізації session-key | + | `plugin-sdk/status-helpers` | Допоміжні засоби статусу channel | Побудовники підсумків статусу channel/account, значення runtime-state за замовчуванням, допоміжні засоби метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Допоміжні засоби визначення цілей | Спільні допоміжні засоби визначення цілей | + | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації рядків | Допоміжні засоби нормалізації slug/рядків | + | `plugin-sdk/request-url` | Допоміжні засоби URL запиту | Витягування рядкових URL із request-подібних вхідних даних | + | `plugin-sdk/run-command` | Допоміжні засоби команд із вимірюванням часу | Виконавець команд із вимірюванням часу з нормалізованими stdout/stderr | + | `plugin-sdk/param-readers` | Засоби читання параметрів | Загальні засоби читання параметрів tool/CLI | + | `plugin-sdk/tool-payload` | Витягування payload інструмента | Витягування нормалізованих payload з об’єктів результатів інструментів | | `plugin-sdk/tool-send` | Витягування send інструмента | Витягування канонічних полів цілі send з аргументів інструмента | - | `plugin-sdk/temp-path` | Helper-функції тимчасових шляхів | Спільні helper-функції шляхів для тимчасових завантажень | - | `plugin-sdk/logging-core` | Helper-функції логування | Helper-функції logger підсистеми та редагування | - | `plugin-sdk/markdown-table-runtime` | Helper-функції таблиць Markdown | Helper-функції режиму таблиць Markdown | - | `plugin-sdk/reply-payload` | Типи reply повідомлень | Типи payload відповіді | - | `plugin-sdk/provider-setup` | Добірні helper-функції налаштування локальних/self-hosted провайдерів | Helper-функції виявлення/конфігурації self-hosted провайдерів | - | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані helper-функції налаштування self-hosted провайдерів, сумісних з OpenAI | Ті самі helper-функції виявлення/конфігурації self-hosted провайдерів | - | `plugin-sdk/provider-auth-runtime` | Helper-функції auth провайдера для runtime | Helper-функції розв’язання API-ключа під час runtime | - | `plugin-sdk/provider-auth-api-key` | Helper-функції налаштування API-ключа провайдера | Helper-функції онбордингу/запису профілю API-ключа | - | `plugin-sdk/provider-auth-result` | Helper-функції auth-result провайдера | Стандартний builder auth-result OAuth | - | `plugin-sdk/provider-auth-login` | Helper-функції інтерактивного входу провайдера | Спільні helper-функції інтерактивного входу | - | `plugin-sdk/provider-selection-runtime` | Helper-функції вибору провайдера | Вибір налаштованого або автоматичного провайдера та об’єднання сирої конфігурації провайдера | - | `plugin-sdk/provider-env-vars` | Helper-функції env vars провайдера | Helper-функції пошуку env vars auth провайдера | - | `plugin-sdk/provider-model-shared` | Спільні helper-функції моделей/replay провайдера | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні builders політики replay, helper-функції endpoint провайдера та helper-функції нормалізації model-id | - | `plugin-sdk/provider-catalog-shared` | Спільні helper-функції каталогу провайдера | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | Патчі онбордингу провайдера | Helper-функції конфігурації онбордингу | - | `plugin-sdk/provider-http` | HTTP helper-функції провайдера | Загальні helper-функції HTTP/можливостей endpoint провайдера, включно з helper-функціями multipart form для транскрибування аудіо | - | `plugin-sdk/provider-web-fetch` | Helper-функції web-fetch провайдера | Helper-функції реєстрації/кешу провайдера web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Helper-функції конфігурації web-search провайдера | Вузькі helper-функції конфігурації/облікових даних web-search для провайдерів, яким не потрібна прив’язка ввімкнення плагіна | - | `plugin-sdk/provider-web-search-contract` | Helper-функції контракту web-search провайдера | Вузькі helper-функції контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setters/getters облікових даних | - | `plugin-sdk/provider-web-search` | Helper-функції web-search провайдера | Helper-функції реєстрації/кешу/runtime провайдера web-search | - | `plugin-sdk/provider-tools` | Helper-функції сумісності tool/schema провайдера | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + diagnostics і helper-функції сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | Helper-функції usage провайдера | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші helper-функції usage провайдера | - | `plugin-sdk/provider-stream` | Helper-функції wrappers потоків провайдера | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи wrappers потоків і спільні helper-функції wrappers для Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Helper-функції транспорту провайдера | Нативні helper-функції транспорту провайдера, такі як guarded fetch, перетворення транспортних повідомлень і writable event streams транспорту | - | `plugin-sdk/keyed-async-queue` | Упорядкована асинхронна черга | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Спільні helper-функції медіа | Helper-функції fetch/transform/store медіа та builders payload медіа | - | `plugin-sdk/media-generation-runtime` | Спільні helper-функції генерації медіа | Спільні helper-функції failover, вибору кандидатів і повідомлень про відсутню модель для генерації зображень/відео/музики | - | `plugin-sdk/media-understanding` | Helper-функції розуміння медіа | Типи провайдерів розуміння медіа та provider-facing exports helper-функцій зображень/аудіо | - | `plugin-sdk/text-runtime` | Спільні text helper-функції | Видалення видимого для асистента тексту, helper-функції render/chunking/table для markdown, helper-функції редагування, helper-функції тегів директив, утиліти безпечного тексту та пов’язані helper-функції тексту/логування | - | `plugin-sdk/text-chunking` | Helper-функції chunking тексту | Helper-функція chunking вихідного тексту | - | `plugin-sdk/speech` | Helper-функції мовлення | Типи провайдерів мовлення та provider-facing helper-функції directives, registry і validation | - | `plugin-sdk/speech-core` | Спільне ядро мовлення | Типи провайдерів мовлення, registry, directives, нормалізація | - | `plugin-sdk/realtime-transcription` | Helper-функції realtime-транскрибування | Типи провайдерів, helper-функції registry і спільна helper-функція сесії WebSocket | - | `plugin-sdk/realtime-voice` | Helper-функції realtime voice | Типи провайдерів, helper-функції registry/resolution і helper-функції bridge session | - | `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Типи генерації зображень, helper-функції failover, auth і registry | - | `plugin-sdk/music-generation` | Helper-функції генерації музики | Типи провайдера/запиту/результату генерації музики | - | `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, helper-функції failover, пошук провайдера та парсинг model-ref | - | `plugin-sdk/video-generation` | Helper-функції генерації відео | Типи провайдера/запиту/результату генерації відео | - | `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, helper-функції failover, пошук провайдера та парсинг model-ref | - | `plugin-sdk/interactive-runtime` | Helper-функції інтерактивної відповіді | Нормалізація/зменшення payload інтерактивної відповіді | - | `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви channel config-schema | - | `plugin-sdk/channel-config-writes` | Helper-функції запису конфігурації каналу | Helper-функції авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільний prelude каналу | Exports спільного prelude channel plugin | - | `plugin-sdk/channel-status` | Helper-функції статусу каналу | Спільні helper-функції snapshot/summary статусу каналу | - | `plugin-sdk/allowlist-config-edit` | Helper-функції конфігурації allowlist | Helper-функції редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Helper-функції доступу до груп | Спільні helper-функції рішень group-access | - | `plugin-sdk/direct-dm` | Helper-функції direct-DM | Спільні helper-функції auth/guard direct-DM | - | `plugin-sdk/extension-shared` | Спільні helper-функції розширень | Примітиви passive-channel/status і ambient proxy helper | - | `plugin-sdk/webhook-targets` | Helper-функції цілей Webhook | Реєстр цілей Webhook і helper-функції встановлення маршрутів | - | `plugin-sdk/webhook-path` | Helper-функції шляху Webhook | Helper-функції нормалізації шляху Webhook | - | `plugin-sdk/web-media` | Спільні helper-функції web media | Helper-функції завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Реекспорт Zod | Повторно експортований `zod` для споживачів SDK плагінів | - | `plugin-sdk/memory-core` | Вбудовані helper-функції memory-core | Поверхня helper-функцій менеджера memory, конфігурації, файлів і CLI | - | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime рушія memory | Фасад runtime індексу/пошуку memory | - | `plugin-sdk/memory-core-host-engine-foundation` | Базовий рушій хоста memory | Exports базового рушія хоста memory | - | `plugin-sdk/memory-core-host-engine-embeddings` | Embedding-рушій хоста memory | Контракти embedding memory, доступ до registry, локальний провайдер і загальні helper-функції batch/remote; конкретні remote-провайдери знаходяться у плагінах, яким вони належать | - | `plugin-sdk/memory-core-host-engine-qmd` | QMD-рушій хоста memory | Exports QMD-рушія хоста memory | - | `plugin-sdk/memory-core-host-engine-storage` | Рушій сховища хоста memory | Exports рушія сховища хоста memory | - | `plugin-sdk/memory-core-host-multimodal` | Багатомодальні helper-функції хоста memory | Багатомодальні helper-функції хоста memory | - | `plugin-sdk/memory-core-host-query` | Query helper-функції хоста memory | Query helper-функції хоста memory | - | `plugin-sdk/memory-core-host-secret` | Secret helper-функції хоста memory | Secret helper-функції хоста memory | - | `plugin-sdk/memory-core-host-events` | Helper-функції журналу подій хоста memory | Helper-функції журналу подій хоста memory | - | `plugin-sdk/memory-core-host-status` | Helper-функції статусу хоста memory | Helper-функції статусу хоста memory | - | `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime хоста memory | CLI runtime helper-функції хоста memory | - | `plugin-sdk/memory-core-host-runtime-core` | Базовий runtime хоста memory | Базові runtime helper-функції хоста memory | - | `plugin-sdk/memory-core-host-runtime-files` | Helper-функції файлів/runtime хоста memory | Helper-функції файлів/runtime хоста memory | - | `plugin-sdk/memory-host-core` | Псевдонім базового runtime хоста memory | Нейтральний до вендора псевдонім для базових runtime helper-функцій хоста memory | - | `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста memory | Нейтральний до вендора псевдонім для helper-функцій журналу подій хоста memory | - | `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста memory | Нейтральний до вендора псевдонім для helper-функцій файлів/runtime хоста memory | - | `plugin-sdk/memory-host-markdown` | Helper-функції керованого markdown | Спільні helper-функції керованого markdown для плагінів, суміжних із memory | - | `plugin-sdk/memory-host-search` | Фасад пошуку Active Memory | Lazy runtime-фасад менеджера пошуку active-memory | - | `plugin-sdk/memory-host-status` | Псевдонім статусу хоста memory | Нейтральний до вендора псевдонім для helper-функцій статусу хоста memory | - | `plugin-sdk/memory-lancedb` | Вбудовані helper-функції memory-lancedb | Поверхня helper-функцій memory-lancedb | - | `plugin-sdk/testing` | Тестові утиліти | Test helpers і mocks | + | `plugin-sdk/temp-path` | Допоміжні засоби тимчасових шляхів | Спільні допоміжні засоби шляхів тимчасового завантаження | + | `plugin-sdk/logging-core` | Допоміжні засоби logging | Допоміжні засоби logger підсистеми та редагування чутливих даних | + | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби таблиць Markdown | Допоміжні засоби режиму таблиць Markdown | + | `plugin-sdk/reply-payload` | Типи reply повідомлень | Типи payload reply | + | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби setup локального/self-hosted provider | Допоміжні засоби виявлення/конфігурації self-hosted provider | + | `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні засоби setup self-hosted provider, сумісного з OpenAI | Ті самі допоміжні засоби виявлення/конфігурації self-hosted provider | + | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби auth provider у середовищі виконання | Допоміжні засоби визначення API-key у середовищі виконання | + | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби setup API-key provider | Допоміжні засоби онбордингу/запису профілю API-key | + | `plugin-sdk/provider-auth-result` | Допоміжні засоби auth-result provider | Стандартний побудовник OAuth auth-result | + | `plugin-sdk/provider-auth-login` | Допоміжні засоби інтерактивного входу provider | Спільні допоміжні засоби інтерактивного входу | + | `plugin-sdk/provider-selection-runtime` | Допоміжні засоби вибору provider | Вибір provider з конфігурації або автоматично та злиття сирих конфігурацій provider | + | `plugin-sdk/provider-env-vars` | Допоміжні засоби env-var provider | Допоміжні засоби пошуку auth env-var provider | + | `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби моделей/replay provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники replay-policy, допоміжні засоби endpoint provider та допоміжні засоби нормалізації model-id | + | `plugin-sdk/provider-catalog-shared` | Спільні допоміжні засоби каталогу provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | Патчі онбордингу provider | Допоміжні засоби конфігурації онбордингу | + | `plugin-sdk/provider-http` | Допоміжні засоби HTTP provider | Загальні допоміжні засоби HTTP/capability endpoint provider, включно з допоміжними засобами multipart form для транскрибування аудіо | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch provider | Допоміжні засоби реєстрації/кешу provider для web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Допоміжні засоби конфігурації web-search provider | Вузькі допоміжні засоби конфігурації/облікових даних web-search для provider, яким не потрібна зв’язка ввімкнення plugin | + | `plugin-sdk/provider-web-search-contract` | Допоміжні засоби контракту web-search provider | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setters/getters облікових даних | + | `plugin-sdk/provider-web-search` | Допоміжні засоби web-search provider | Допоміжні засоби реєстрації/кешу/середовища виконання provider для web-search | + | `plugin-sdk/provider-tools` | Допоміжні засоби сумісності tool/schema provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + diagnostics і допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | Допоміжні засоби usage provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні засоби usage provider | + | `plugin-sdk/provider-stream` | Допоміжні засоби обгорток stream provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток stream і спільні допоміжні засоби обгорток Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Допоміжні засоби transport provider | Допоміжні засоби native transport provider, такі як guarded fetch, перетворення повідомлень transport і потоки подій transport із можливістю запису | + | `plugin-sdk/keyed-async-queue` | Впорядкована асинхронна черга | `KeyedAsyncQueue` | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби media | Допоміжні засоби fetch/transform/store для media плюс побудовники payload media | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби генерації media | Спільні допоміжні засоби failover, вибору кандидатів і повідомлень про відсутню модель для генерації зображень/відео/музики | + | `plugin-sdk/media-understanding` | Допоміжні засоби media-understanding | Типи provider для media understanding плюс експортовані допоміжні засоби для зображень/аудіо, орієнтовані на provider | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту | Видалення видимого для асистента тексту, допоміжні засоби render/chunking/table для markdown, допоміжні засоби редагування чутливих даних, допоміжні засоби тегів directive, утиліти safe-text та пов’язані допоміжні засоби тексту/logging | + | `plugin-sdk/text-chunking` | Допоміжні засоби chunking тексту | Допоміжний засіб chunking для outbound text | + | `plugin-sdk/speech` | Допоміжні засоби speech | Типи provider для speech плюс допоміжні засоби directive, registry і validation, орієнтовані на provider | + | `plugin-sdk/speech-core` | Спільне ядро speech | Типи provider для speech, registry, directives, нормалізація | + | `plugin-sdk/realtime-transcription` | Допоміжні засоби транскрибування в реальному часі | Типи provider, допоміжні засоби registry і спільний допоміжний засіб сесії WebSocket | + | `plugin-sdk/realtime-voice` | Допоміжні засоби голосу в реальному часі | Типи provider, допоміжні засоби registry/визначення та допоміжні засоби bridge session | + | `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/interactive-runtime` | Допоміжні засоби інтерактивних reply | Нормалізація/скорочення payload інтерактивних reply | + | `plugin-sdk/channel-config-primitives` | Примітиви конфігурації channel | Вузькі примітиви `channel config-schema` | + | `plugin-sdk/channel-config-writes` | Допоміжні засоби запису конфігурації channel | Допоміжні засоби авторизації запису конфігурації channel | + | `plugin-sdk/channel-plugin-common` | Спільний prelude channel | Експорти спільного prelude channel plugin | + | `plugin-sdk/channel-status` | Допоміжні засоби статусу channel | Спільні допоміжні засоби знімка/підсумку статусу channel | + | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби конфігурації allowlist | Допоміжні засоби редагування/читання конфігурації allowlist | + | `plugin-sdk/group-access` | Допоміжні засоби доступу до груп | Спільні допоміжні засоби рішень щодо group-access | + | `plugin-sdk/direct-dm` | Допоміжні засоби direct-DM | Спільні допоміжні засоби auth/guard для direct-DM | + | `plugin-sdk/extension-shared` | Спільні допоміжні засоби extension | Примітиви пасивного channel/status і ambient proxy helper | + | `plugin-sdk/webhook-targets` | Допоміжні засоби цілей Webhook | Реєстр цілей Webhook і допоміжні засоби встановлення route | + | `plugin-sdk/webhook-path` | Допоміжні засоби шляху Webhook | Допоміжні засоби нормалізації шляху Webhook | + | `plugin-sdk/web-media` | Спільні допоміжні засоби web media | Допоміжні засоби завантаження віддалених/локальних media | + | `plugin-sdk/zod` | Повторний експорт Zod | Повторно експортований `zod` для споживачів SDK Plugin | + | `plugin-sdk/memory-core` | Допоміжні засоби вбудованого memory-core | Поверхня допоміжних засобів memory manager/config/file/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Фасад середовища виконання рушія memory | Фасад середовища виконання index/search для memory | + | `plugin-sdk/memory-core-host-engine-foundation` | Foundation engine хоста memory | Експорти foundation engine хоста memory | + | `plugin-sdk/memory-core-host-engine-embeddings` | Embedding engine хоста memory | Контракти embeddings memory, доступ до registry, локальний provider і загальні допоміжні засоби batch/remote; конкретні remote providers знаходяться у plugins-власниках | + | `plugin-sdk/memory-core-host-engine-qmd` | QMD engine хоста memory | Експорти QMD engine хоста memory | + | `plugin-sdk/memory-core-host-engine-storage` | Storage engine хоста memory | Експорти storage engine хоста memory | + | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста memory | Мультимодальні допоміжні засоби хоста memory | + | `plugin-sdk/memory-core-host-query` | Допоміжні засоби query хоста memory | Допоміжні засоби query хоста memory | + | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret хоста memory | Допоміжні засоби secret хоста memory | + | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста memory | Допоміжні засоби журналу подій хоста memory | + | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста memory | Допоміжні засоби статусу хоста memory | + | `plugin-sdk/memory-core-host-runtime-cli` | Середовище виконання CLI хоста memory | Допоміжні засоби середовища виконання CLI хоста memory | + | `plugin-sdk/memory-core-host-runtime-core` | Основне середовище виконання хоста memory | Допоміжні засоби основного середовища виконання хоста memory | + | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/середовища виконання хоста memory | Допоміжні засоби файлів/середовища виконання хоста memory | + | `plugin-sdk/memory-host-core` | Псевдонім основного середовища виконання хоста memory | Нейтральний до постачальника псевдонім для допоміжних засобів основного середовища виконання хоста memory | + | `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста memory | Нейтральний до постачальника псевдонім для допоміжних засобів журналу подій хоста memory | + | `plugin-sdk/memory-host-files` | Псевдонім файлів/середовища виконання хоста memory | Нейтральний до постачальника псевдонім для допоміжних засобів файлів/середовища виконання хоста memory | + | `plugin-sdk/memory-host-markdown` | Допоміжні засоби керованого markdown | Спільні допоміжні засоби керованого markdown для plugins, суміжних із memory | + | `plugin-sdk/memory-host-search` | Фасад пошуку Active Memory | Lazy-фасад середовища виконання менеджера пошуку active-memory | + | `plugin-sdk/memory-host-status` | Псевдонім статусу хоста memory | Нейтральний до постачальника псевдонім для допоміжних засобів статусу хоста memory | + | `plugin-sdk/memory-lancedb` | Допоміжні засоби вбудованого memory-lancedb | Поверхня допоміжних засобів memory-lancedb | + | `plugin-sdk/testing` | Утиліти тестування | Допоміжні засоби тестування та mock-и | Ця таблиця навмисно є поширеною підмножиною для міграції, а не повною -поверхнею SDK. Повний список із понад 200 entrypoint-ів міститься в +поверхнею SDK. Повний список із понад 200 точок входу розміщено в `scripts/lib/plugin-sdk-entrypoints.json`. -Цей список усе ще містить деякі seams helper-функцій вбудованих плагінів, такі як +Цей список усе ще включає деякі допоміжні з’єднання для вбудованих plugins, такі як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони й надалі експортуються для -підтримки та сумісності вбудованих плагінів, але навмисно -не включені до поширеної таблиці міграції й не є рекомендованою ціллю для -нового коду плагінів. +супроводу вбудованих plugins і сумісності, але навмисно пропущені з поширеної +таблиці міграції та не є рекомендованою ціллю для нового коду plugin. -Те саме правило застосовується й до інших сімейств helper-функцій вбудованих плагінів, таких як: +Те саме правило стосується інших сімейств вбудованих допоміжних засобів, таких як: -- helper-функції підтримки браузера: `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` +- допоміжні засоби підтримки браузера: `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` - Matrix: `plugin-sdk/matrix*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- поверхні вбудованих helper-функцій/плагінів, такі як `plugin-sdk/googlechat`, +- поверхні вбудованих допоміжних засобів/plugin, такі як `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, @@ -495,130 +559,130 @@ OpenClaw не вилучає і не переосмислює задокумен `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, і `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` наразі надає вузьку поверхню helper-функцій токена: +`plugin-sdk/github-copilot-token` наразі надає вузьку поверхню допоміжних засобів токенів: `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken`. -Використовуйте найвужчий імпорт, який відповідає завданню. Якщо ви не можете знайти export, +Використовуйте найвужчий імпорт, що відповідає задачі. Якщо ви не можете знайти експорт, перевірте вихідний код у `src/plugin-sdk/` або запитайте в Discord. ## Активні застарівання -Вужчі застарівання, які застосовуються в усьому SDK плагінів, контракті провайдера, -поверхні runtime і маніфесті. Кожне з них іще працює сьогодні, але буде вилучене -в одному з майбутніх мажорних релізів. Запис під кожним елементом зіставляє старий API з його -канонічною заміною. +Вужчі застарівання, які застосовуються в SDK Plugin, контракті provider, +поверхні середовища виконання та маніфесті. Кожне з них усе ще працює сьогодні, +але буде вилучене в одному з майбутніх мажорних релізів. Запис під кожним +елементом відображає старий API на його канонічну заміну. - + **Старе (`openclaw/plugin-sdk/command-auth`)**: `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage`. **Нове (`openclaw/plugin-sdk/command-status`)**: ті самі сигнатури, ті самі - exports — лише імпортовані з вужчого subpath. `command-auth` - повторно експортує їх як compat stubs. + експорти — лише імпортовані з вужчого підшляху. `command-auth` + повторно експортує їх як сумісні stubs. ```typescript - // Before + // До import { buildHelpMessage } from "openclaw/plugin-sdk/command-auth"; - // After + // Після import { buildHelpMessage } from "openclaw/plugin-sdk/command-status"; ``` - + **Старе**: `resolveInboundMentionRequirement({ facts, policy })` і `shouldDropInboundForMention(...)` з `openclaw/plugin-sdk/channel-inbound` або `openclaw/plugin-sdk/channel-mention-gating`. **Нове**: `resolveInboundMentionDecision({ facts, policy })` — повертає - єдиний об’єкт рішення замість двох окремих викликів. + один об’єкт рішення замість двох розділених викликів. - Downstream channel-плагіни (Slack, Discord, Matrix, Microsoft Teams) уже + Нижчерозташовані plugins channel (Slack, Discord, Matrix, Microsoft Teams) уже перейшли. - + `openclaw/plugin-sdk/channel-runtime` — це shim сумісності для старіших - channel-плагінів. Не імпортуйте його в новому коді; використовуйте - `openclaw/plugin-sdk/channel-runtime-context` для реєстрації об’єктів runtime. + plugins channel. Не імпортуйте його в новому коді; використовуйте + `openclaw/plugin-sdk/channel-runtime-context` для реєстрації об’єктів + середовища виконання. - Helper-функції `channelActions*` у `openclaw/plugin-sdk/channel-actions` є - застарілими разом із сирими exports каналу «actions». Натомість розкривайте - можливості через семантичну поверхню `presentation` — channel-плагіни - оголошують, що саме вони відображають (cards, buttons, selects), а не які сирі - назви дій вони приймають. + Допоміжні засоби `channelActions*` у `openclaw/plugin-sdk/channel-actions` є + deprecated разом із сирими експортами channel "actions". Натомість надавайте можливості + через семантичну поверхню `presentation` — plugins channel + оголошують, що саме вони відтворюють (картки, кнопки, списки вибору), а не + які сирі назви дій вони приймають. - - **Старе**: factory `tool()` з `openclaw/plugin-sdk/provider-web-search`. + + **Старе**: фабрика `tool()` із `openclaw/plugin-sdk/provider-web-search`. - **Нове**: реалізуйте `createTool(...)` безпосередньо в плагіні провайдера. - OpenClaw більше не потребує helper-функції SDK для реєстрації wrapper-а інструмента. + **Нове**: реалізуйте `createTool(...)` безпосередньо в plugin provider. + OpenClaw більше не потребує допоміжного засобу SDK для реєстрації обгортки інструмента. - + **Старе**: `formatInboundEnvelope(...)` (і - `ChannelMessageForAgent.channelEnvelope`) для створення плоского текстового prompt - envelope із вхідних повідомлень каналу. + `ChannelMessageForAgent.channelEnvelope`) для побудови плаского plaintext prompt + envelope з вхідних повідомлень channel. - **Нове**: `BodyForAgent` разом зі структурованими блоками контексту користувача. - Channel-плагіни прикріплюють метадані маршрутизації (thread, topic, reply-to, reactions) як - типізовані поля замість конкатенації їх у рядок prompt. Helper-функція - `formatAgentEnvelope(...)` іще підтримується для синтезованих envelope, - видимих асистенту, але вхідні текстові envelope у відкритому вигляді - поступово виводяться з ужитку. + **Нове**: `BodyForAgent` плюс структуровані блоки контексту користувача. Plugins + channel додають метадані маршрутизації (потік, тема, reply-to, реакції) як + типізовані поля замість конкатенації їх у рядок prompt. Допоміжний засіб + `formatAgentEnvelope(...)` і далі підтримується для синтезованих envelope, + видимих асистенту, але вхідні plaintext envelope поступово виводяться з ужитку. - Порушені ділянки: `inbound_claim`, `message_received` і будь-який власний - channel-плагін, який виконував постобробку тексту `channelEnvelope`. + Зачеплені області: `inbound_claim`, `message_received` і будь-який власний + Plugin channel, який виконував постобробку тексту `channelEnvelope`. - - Чотири псевдоніми типів виявлення тепер є тонкими wrappers над типами епохи - каталогу: + + Чотири псевдоніми типів discovery тепер є тонкими обгортками над типами + епохи catalog: - | Старий псевдонім | Новий тип | - | ------------------------- | ------------------------- | - | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` | - | `ProviderDiscoveryContext`| `ProviderCatalogContext` | - | `ProviderDiscoveryResult` | `ProviderCatalogResult` | - | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | + | Старий псевдонім | Новий тип | + | ------------------------- | ------------------------ | + | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` | + | `ProviderDiscoveryContext`| `ProviderCatalogContext` | + | `ProviderDiscoveryResult` | `ProviderCatalogResult` | + | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | - Плюс застарілий статичний набір `ProviderCapabilities` — плагіни провайдера - мають прикріплювати факти capability через контракт runtime провайдера, + Плюс застарілий статичний контейнер `ProviderCapabilities` — plugins provider + мають прив’язувати факти можливостей через контракт середовища виконання provider, а не через статичний об’єкт. - - **Старе** (три окремі hooks у `ProviderThinkingPolicy`): + + **Старе** (три окремі hook-и в `ProviderThinkingPolicy`): `isBinaryThinking(ctx)`, `supportsXHighThinking(ctx)` і `resolveDefaultThinkingLevel(ctx)`. - **Нове**: єдиний `resolveThinkingProfile(ctx)`, який повертає - `ProviderThinkingProfile` із канонічним `id`, необов’язковою `label` і - ранжованим списком рівнів. OpenClaw автоматично знижує застарілі збережені - значення за рангом профілю. + **Нове**: один `resolveThinkingProfile(ctx)`, який повертає + `ProviderThinkingProfile` із канонічним `id`, необов’язковим `label` і + ранжованим списком рівнів. OpenClaw автоматично знижує застарілі збережені значення + за рангом профілю. - Реалізуйте один hook замість трьох. Застарілі hooks продовжують працювати під час - вікна застарівання, але не комбінуються з результатом профілю. + Реалізуйте один hook замість трьох. Застарілі hook-и продовжують працювати протягом + вікна застарівання, але не композуються з результатом профілю. - + **Старе**: реалізація `resolveExternalOAuthProfiles(...)` без - оголошення провайдера в маніфесті плагіна. + оголошення provider у маніфесті plugin. - **Нове**: оголосіть `contracts.externalAuthProviders` у маніфесті плагіна + **Нове**: оголосіть `contracts.externalAuthProviders` у маніфесті plugin **і** реалізуйте `resolveExternalAuthProfiles(...)`. Старий шлях - «auth fallback» показує попередження під час runtime і буде вилучений. + "auth fallback" виводить warning у середовищі виконання і буде вилучений. ```json { @@ -630,79 +694,79 @@ OpenClaw не вилучає і не переосмислює задокумен - + **Старе** поле маніфесту: `providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`. - **Нове**: віддзеркальте той самий пошук env vars у `setup.providers[].envVars` - у маніфесті. Це консолідує метадані env для setup/status в одному - місці й дає змогу уникнути запуску runtime плагіна лише для відповіді на - пошук env vars. + **Нове**: продублюйте той самий пошук env-var у `setup.providers[].envVars` + маніфесту. Це об’єднує метадані env setup/status в одному + місці й дозволяє уникнути запуску середовища виконання plugin лише для відповіді на + запити env-var. - `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності + `providerAuthEnvVars` і далі підтримується через адаптер сумісності до завершення вікна застарівання. - + **Старе**: три окремі виклики — `api.registerMemoryPromptSection(...)`, `api.registerMemoryFlushPlan(...)`, `api.registerMemoryRuntime(...)`. - **Нове**: один виклик в API memory-state — + **Нове**: один виклик на API memory-state — `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`. - Ті самі слоти, один виклик реєстрації. Додаткові helper-функції memory + Ті самі слоти, один виклик реєстрації. Додаткові допоміжні засоби memory (`registerMemoryPromptSupplement`, `registerMemoryCorpusSupplement`, - `registerMemoryEmbeddingProvider`) це не зачіпає. + `registerMemoryEmbeddingProvider`) не зачеплені. Два застарілі псевдоніми типів усе ще експортуються з `src/plugins/runtime/types.ts`: - | Старе | Нове | - | ----------------------------- | ------------------------------- | - | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | - | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | + | Старе | Нове | + | ---------------------------- | -------------------------------- | + | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | + | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | - Метод runtime `readSession` є застарілим на користь + Метод середовища виконання `readSession` є deprecated на користь `getSessionMessages`. Та сама сигнатура; старий метод викликає новий. - **Старе**: `runtime.tasks.flow` (однина) повертав live accessor TaskFlow. + **Старе**: `runtime.tasks.flow` (однина) повертав живий accessor TaskFlow. - **Нове**: `runtime.tasks.flows` (множина) повертає доступ до TaskFlow на основі DTO, - який є безпечним для імпорту й не вимагає завантаження повного runtime завдань. + **Нове**: `runtime.tasks.flows` (множина) повертає DTO-орієнтований доступ до TaskFlow, + безпечний для імпорту й такий, що не вимагає завантаження повного runtime задач. ```typescript - // Before + // До const flow = api.runtime.tasks.flow(ctx); - // After + // Після const flows = api.runtime.tasks.flows(ctx); ``` - - Розглянуто вище в розділі «Як виконати міграцію → Перенесіть розширення результатів інструментів Pi на - middleware». Додано тут для повноти: вилучений шлях лише для Pi - `api.registerEmbeddedExtensionFactory(...)` замінено на - `api.registerAgentToolResultMiddleware(...)` з явним - списком runtime у `contracts.agentToolResultMiddleware`. + + Розглянуто вище в розділі "Як виконати міграцію → Виконайте міграцію Pi extension результатів інструментів на + middleware". Тут включено для повноти: вилучений шлях + `api.registerEmbeddedExtensionFactory(...)` лише для Pi замінено на + `api.registerAgentToolResultMiddleware(...)` з явним списком runtime у + `contracts.agentToolResultMiddleware`. - `OpenClawSchemaType`, повторно експортований з `openclaw/plugin-sdk`, тепер є + `OpenClawSchemaType`, повторно експортований із `openclaw/plugin-sdk`, тепер є однорядковим псевдонімом для `OpenClawConfig`. Надавайте перевагу канонічній назві. ```typescript - // Before + // До import type { OpenClawSchemaType } from "openclaw/plugin-sdk"; - // After + // Після import type { OpenClawConfig } from "openclaw/plugin-sdk/config-schema"; ``` @@ -710,24 +774,24 @@ OpenClaw не вилучає і не переосмислює задокумен -Застарівання на рівні розширень (усередині вбудованих channel/provider плагінів у -`extensions/`) відстежуються у їхніх власних barrels `api.ts` і `runtime-api.ts`. -Вони не впливають на контракти сторонніх плагінів і тут не перелічені. -Якщо ви напряму використовуєте локальний barrel вбудованого плагіна, прочитайте +Застарівання на рівні extension (усередині вбудованих channel/provider plugins у +`extensions/`) відстежуються у власних barrel-файлах `api.ts` і `runtime-api.ts`. +Вони не впливають на контракти сторонніх plugins і тут не перелічені. +Якщо ви безпосередньо споживаєте локальний barrel вбудованого plugin, прочитайте коментарі про застарівання в цьому barrel перед оновленням. -## Хронологія вилучення +## Хронологія видалення | Коли | Що відбувається | | ---------------------- | ----------------------------------------------------------------------- | -| **Зараз** | Застарілі поверхні показують попередження під час runtime | -| **Наступний мажорний реліз** | Застарілі поверхні буде вилучено; плагіни, які все ще їх використовують, перестануть працювати | +| **Зараз** | Застарілі поверхні виводять warnings під час виконання | +| **Наступний мажорний реліз** | Застарілі поверхні буде вилучено; plugins, які все ще їх використовують, завершаться помилкою | -Усі core-плагіни вже мігровано. Зовнішнім плагінам слід виконати міграцію +Усі основні plugins уже мігровано. Зовнішні plugins мають виконати міграцію до наступного мажорного релізу. -## Тимчасове вимкнення попереджень +## Тимчасове приглушення попереджень Установіть ці змінні середовища, поки працюєте над міграцією: @@ -740,9 +804,9 @@ OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ## Пов’язане -- [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший плагін -- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів subpath -- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення плагінів каналів -- [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — створення плагінів провайдерів -- [Внутрішня будова плагінів](/uk/plugins/architecture) — глибокий огляд архітектури -- [Маніфест плагіна](/uk/plugins/manifest) — довідник схеми маніфесту +- [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший Plugin +- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів підшляхів +- [Plugins channel](/uk/plugins/sdk-channel-plugins) — створення plugins channel +- [Plugins provider](/uk/plugins/sdk-provider-plugins) — створення plugins provider +- [Внутрішня будова Plugin](/uk/plugins/architecture) — глибоке занурення в архітектуру +- [Маніфест Plugin](/uk/plugins/manifest) — довідник схеми маніфесту diff --git a/docs/uk/plugins/sdk-subpaths.md b/docs/uk/plugins/sdk-subpaths.md index 0692b8826..4b5c26a58 100644 --- a/docs/uk/plugins/sdk-subpaths.md +++ b/docs/uk/plugins/sdk-subpaths.md @@ -1,317 +1,319 @@ --- read_when: - Вибір правильного підшляху plugin-sdk для імпорту Plugin - - Аудит підшляхів bundled-plugin і поверхонь допоміжних функцій + - Аудит підшляхів bundled-plugin і допоміжних поверхонь summary: 'Каталог підшляхів Plugin SDK: які імпорти де розміщені, згруповано за областями' title: Підшляхи Plugin SDK x-i18n: - generated_at: "2026-04-28T00:03:44Z" + generated_at: "2026-04-28T00:34:53Z" model: gpt-5.4 provider: openai - source_hash: 5a51833cc4d8136f4e432822f3fc27e38373784519cfcb7ce209dbe01fa0a325 + source_hash: e6ad6676f134169657efbd160ec57018090b02325ea95262f493ccb1d2648d5b source_path: plugins/sdk-subpaths.md workflow: 15 --- - Plugin SDK представлений як набір вузьких підшляхів у `openclaw/plugin-sdk/`. - На цій сторінці наведено каталог поширених підшляхів, згрупованих за призначенням. Згенерований - повний список із понад 200 підшляхів міститься у `scripts/lib/plugin-sdk-entrypoints.json`; - зарезервовані допоміжні підшляхи bundled-plugin також наведені там, але є деталями - реалізації, якщо лише певна сторінка документації явно не рекомендує їх. + Plugin SDK представлено як набір вузьких підшляхів у `openclaw/plugin-sdk/`. + На цій сторінці каталогізовано найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`; зарезервовані допоміжні підшляхи bundled-plugin також там відображаються, але є деталями реалізації, якщо тільки сторінка документації явно не рекомендує їх. Посібник з розробки Plugin див. у [Огляд Plugin SDK](/uk/plugins/sdk-overview). ## Точка входу Plugin - | Підшлях | Основні експорти | - | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `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/testing` | Публічні тестові фікстури Plugin, допоміжні функції реєстрації/каталогу провайдерів, хуки контрактів майстра та допоміжні функції підтримки контрактів bundled-plugin | - | `plugin-sdk/plugin-test-api` | Мінімальний конструктор мока `OpenClawPluginApi` для прямих модульних тестів реєстрації Plugin | - | `plugin-sdk/channel-test-helpers` | Допоміжні функції для тестування життєвого циклу облікового запису каналу, директорії, конфігурації надсилання, мока середовища виконання та хуків | - | `plugin-sdk/plugin-test-contracts` | Допоміжні функції контрактів для реєстрації Plugin, маніфесту пакета, публічного артефакту, API середовища виконання, побічного ефекту імпорту та прямого імпорту | - | `plugin-sdk/provider-test-contracts` | Допоміжні функції контрактів для середовища виконання провайдера, автентифікації, виявлення, онбордингу, каталогу, web-search/fetch і майстра | - | `plugin-sdk/migration` | Допоміжні функції елементів провайдера міграції, як-от `createMigrationItem`, константи причин, маркери статусу елементів, допоміжні функції редагування та `summarizeMigrationItems` | - | `plugin-sdk/migration-runtime` | Допоміжні функції міграції для середовища виконання, як-от `copyMigrationFileItem` і `writeMigrationReport` | + | Підшлях | Ключові експорти | + | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | + | `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/testing` | Загальнодоступні тестові фікстури Plugin, допоміжні засоби реєстрації/каталогу провайдерів, хуки контрактів майстра та допоміжні засоби підтримки контрактів bundled-plugin | + | `plugin-sdk/plugin-test-api` | Мінімальний побудовник моків `OpenClawPluginApi` для модульних тестів прямої реєстрації Plugin | + | `plugin-sdk/channel-test-helpers` | Допоміжні засоби тестування життєвого циклу облікових записів каналу, каталогів, send-config, моків runtime і хуків | + | `plugin-sdk/plugin-test-contracts` | Допоміжні засоби контрактів для реєстрації Plugin, маніфесту пакета, публічного артефакту, runtime API, побічних ефектів імпорту та прямого імпорту | + | `plugin-sdk/plugin-test-runtime` | Фікстури Plugin runtime, реєстру, реєстрації провайдерів, setup-wizard і runtime TaskFlow для тестів | + | `plugin-sdk/provider-test-contracts` | Допоміжні засоби контрактів для runtime провайдерів, автентифікації, виявлення, онбордингу, каталогу, web-search/fetch і майстра | + | `plugin-sdk/test-env` | Фікстури середовища тестування, fetch/мережі, live-test, тимчасової файлової системи й керування часом | + | `plugin-sdk/test-fixtures` | Загальні тестові фікстури для CLI, sandbox, skill, повідомлень агента, системних подій, термінала, розбиття на чанки, auth-token і типізованих кейсів | + | `plugin-sdk/migration` | Допоміжні засоби елементів провайдера міграції, такі як `createMigrationItem`, константи причин, маркери статусу елементів, засоби редагування й `summarizeMigrationItems` | + | `plugin-sdk/migration-runtime` | Допоміжні засоби runtime міграції, такі як `copyMigrationFileItem` і `writeMigrationReport` | - - | Підшлях | Основні експорти | + + | Підшлях | Ключові експорти | | --- | --- | | `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` | Спільні допоміжні засоби setup wizard, запити 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` | Допоміжні функції конфігурації/шлюзу дій для кількох облікових записів, допоміжні функції резервного переходу до облікового запису за замовчуванням | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні функції нормалізації ідентифікатора облікового запису | - | `plugin-sdk/account-resolution` | Допоміжні функції пошуку облікового запису та резервного переходу до типового значення | - | `plugin-sdk/account-helpers` | Вузькі допоміжні функції списку облікових записів/дій з обліковими записами | + | `plugin-sdk/account-core` | Допоміжні засоби для конфігурації/шлюзу дій багатьох облікових записів і резервного використання типового облікового запису | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації ідентифікаторів облікових записів | + | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису та резервного використання типового значення | + | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списку облікових записів/дій з обліковими записами | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігурації каналу та узагальнений конструктор | + | `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігурації каналу та універсальний побудовник | | `plugin-sdk/channel-config-schema-legacy` | Застарілі схеми конфігурації bundled-channel лише для сумісності з bundled | - | `plugin-sdk/telegram-command-config` | Допоміжні функції нормалізації/валідації користувацьких команд Telegram із резервною підтримкою bundled-contract | - | `plugin-sdk/command-gating` | Вузькі допоміжні функції шлюзу авторизації команд | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервною сумісністю bundled-contract | + | `plugin-sdk/command-gating` | Вузькі допоміжні засоби шлюзу авторизації команд | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні функції життєвого циклу/фіналізації чернеткового потоку | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні функції маршрутів вхідних повідомлень і конструктора envelope | - | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні функції запису та диспетчеризації вхідних відповідей | - | `plugin-sdk/messaging-targets` | Допоміжні функції розбору/зіставлення цілей | - | `plugin-sdk/outbound-media` | Спільні допоміжні функції завантаження вихідних медіа | - | `plugin-sdk/outbound-send-deps` | Легковаговий пошук залежностей надсилання вихідних повідомлень для адаптерів каналів | - | `plugin-sdk/outbound-runtime` | Допоміжні функції доставки вихідних повідомлень, ідентичності, делегата надсилання, сесії, форматування та планування payload | - | `plugin-sdk/poll-runtime` | Вузькі допоміжні функції нормалізації poll | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні функції життєвого циклу thread-binding і адаптера | - | `plugin-sdk/agent-media-payload` | Застарілий конструктор payload медіа агента | - | `plugin-sdk/conversation-runtime` | Допоміжні функції прив’язки conversation/thread, pairing і configured-binding | - | `plugin-sdk/runtime-config-snapshot` | Допоміжна функція знімка конфігурації середовища виконання | - | `plugin-sdk/runtime-group-policy` | Допоміжні функції визначення group-policy для середовища виконання | - | `plugin-sdk/channel-status` | Спільні допоміжні функції знімка/зведення статусу каналу | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/фіналізації чернеткового потоку | + | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації вхідних повідомлень і побудови envelope | + | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису й диспетчеризації вхідних відповідей | + | `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей | + | `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа | + | `plugin-sdk/outbound-send-deps` | Полегшений пошук залежностей надсилання вихідних повідомлень для адаптерів каналів | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби доставки вихідних повідомлень, ідентичності, делегування надсилання, сесії, форматування й планування payload | + | `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації опитувань | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу прив’язок потоків і адаптерів | + | `plugin-sdk/agent-media-payload` | Застарілий побудовник payload медіа агента | + | `plugin-sdk/conversation-runtime` | Допоміжні засоби прив’язки розмов/потоків, pairing і налаштованих прив’язок | + | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації runtime | + | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення групової політики runtime | + | `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/підсумку статусу каналу | | `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу | - | `plugin-sdk/channel-config-writes` | Допоміжні функції авторизації запису конфігурації каналу | + | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації каналу | | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти Plugin каналу | - | `plugin-sdk/allowlist-config-edit` | Допоміжні функції редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Спільні допоміжні функції рішень щодо group-access | - | `plugin-sdk/direct-dm` | Спільні допоміжні функції автентифікації/захисту direct-DM | - | `plugin-sdk/interactive-runtime` | Допоміжні функції семантичного представлення повідомлень, доставки та застарілих інтерактивних відповідей. Див. [Представлення повідомлень](/uk/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | Барель сумісності для debounce вхідних повідомлень, зіставлення згадок, допоміжних функцій mention-policy та envelope | - | `plugin-sdk/channel-inbound-debounce` | Вузькі допоміжні функції debounce вхідних повідомлень | - | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні функції mention-policy, маркерів згадок і тексту згадок без ширшої поверхні середовища виконання вхідних повідомлень | - | `plugin-sdk/channel-envelope` | Вузькі допоміжні функції форматування вхідних envelope | - | `plugin-sdk/channel-location` | Допоміжні функції контексту та форматування розташування каналу | - | `plugin-sdk/channel-logging` | Допоміжні функції логування каналу для відкидання вхідних повідомлень і збоїв typing/ack | + | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist | + | `plugin-sdk/group-access` | Спільні допоміжні засоби рішень щодо групового доступу | + | `plugin-sdk/direct-dm` | Спільні допоміжні засоби автентифікації/захисту прямих DM | + | `plugin-sdk/interactive-runtime` | Допоміжні засоби семантичного подання повідомлень, доставки та застарілих інтерактивних відповідей. Див. [Подання повідомлень](/uk/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | Сумісний barrel для debounce вхідних повідомлень, зіставлення згадок, допоміжних засобів політики згадок і envelope | + | `plugin-sdk/channel-inbound-debounce` | Вузькі допоміжні засоби debounce вхідних повідомлень | + | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби політики згадок, маркерів згадок і тексту згадок без ширшої поверхні inbound runtime | + | `plugin-sdk/channel-envelope` | Вузькі допоміжні засоби форматування inbound envelope | + | `plugin-sdk/channel-location` | Допоміжні засоби контексту й форматування розташування каналу | + | `plugin-sdk/channel-logging` | Допоміжні засоби журналювання каналу для відкинутих вхідних повідомлень і збоїв typing/ack | | `plugin-sdk/channel-send-result` | Типи результатів відповіді | - | `plugin-sdk/channel-actions` | Допоміжні функції дій з повідомленнями каналу, а також застарілі допоміжні функції native schema, збережені для сумісності Plugin | - | `plugin-sdk/channel-targets` | Допоміжні функції розбору/зіставлення цілей | - | `plugin-sdk/channel-contract` | Типи контрактів каналу | - | `plugin-sdk/channel-feedback` | Зв’язування feedback/reaction | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні функції secret-contract, як-от `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей secret | + | `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями каналу, а також застарілі допоміжні засоби нативних схем, збережені для сумісності Plugin | + | `plugin-sdk/channel-route` | Спільні допоміжні засоби нормалізації маршрутів, визначення цілей на основі парсера, перетворення thread-id у рядок, dedupe/compact ключів маршрутів, типів parsed-target і порівняння маршрутів/цілей | + | `plugin-sdk/channel-targets` | Допоміжні засоби розбору цілей; виклики порівняння маршрутів мають використовувати `plugin-sdk/channel-route` | + | `plugin-sdk/channel-contract` | Типи контрактів каналів | + | `plugin-sdk/channel-feedback` | Підключення feedback/reaction | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби secret-contract, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` і типи secret target | - - | Підшлях | Основні експорти | + + | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/lmstudio` | Підтримуваний фасад провайдера LM Studio для налаштування, виявлення каталогу та підготовки моделі в середовищі виконання | - | `plugin-sdk/lmstudio-runtime` | Підтримуваний фасад середовища виконання LM Studio для типових параметрів локального сервера, виявлення моделей, заголовків запитів і допоміжних функцій для завантажених моделей | - | `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` | Допоміжні функції визначення API-key у середовищі виконання для Plugin провайдера | - | `plugin-sdk/provider-auth-api-key` | Допоміжні функції онбордингу/запису профілю API-key, як-от `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Стандартний конструктор результату автентифікації OAuth | - | `plugin-sdk/provider-auth-login` | Спільні допоміжні функції інтерактивного входу для Plugin провайдера | - | `plugin-sdk/provider-env-vars` | Допоміжні функції пошуку auth env var провайдера | + | `plugin-sdk/lmstudio` | Підтримуваний фасад провайдера LM Studio для налаштування, виявлення каталогу та підготовки моделей runtime | + | `plugin-sdk/lmstudio-runtime` | Підтримуваний фасад runtime LM Studio для типових значень локального сервера, виявлення моделей, заголовків запитів і допоміжних засобів для завантажених моделей | + | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted провайдерів | + | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI | + | `plugin-sdk/cli-backend` | Типові значення бекенда CLI + константи watchdog | + | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключів у runtime для Plugins провайдерів | + | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю API-ключа, такі як `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Стандартний побудовник результату автентифікації OAuth | + | `plugin-sdk/provider-auth-login` | Спільні інтерактивні допоміжні засоби входу для Plugins провайдерів | + | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку змінних середовища для автентифікації провайдерів | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори replay-policy, допоміжні функції endpoint провайдера та допоміжні функції нормалізації model-id, як-от `normalizeNativeXaiModelId` | - | `plugin-sdk/provider-catalog-runtime` | Хук середовища виконання каталогу провайдера та шви реєстру plugin-provider для контрактних тестів | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники політик replay, допоміжні засоби кінцевих точок провайдерів і допоміжні засоби нормалізації model-id, такі як `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-catalog-runtime` | Хук runtime каталогу провайдерів і шви реєстру plugin-provider для контрактних тестів | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Загальні допоміжні функції HTTP/можливостей endpoint провайдера, помилки HTTP провайдера та допоміжні функції multipart form для аудіотранскрипції | - | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні функції контракту config/selection для web-fetch, як-от `enablePluginInConfig` і `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Допоміжні функції реєстрації/кешу провайдера web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні функції config/credential для web-search для провайдерів, яким не потрібне вбудовування enable Plugin | - | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні функції контракту config/credential для web-search, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setters/getters облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні функції реєстрації/кешу/середовища виконання провайдера web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні функції сумісності xAI, як-от `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/можливостей кінцевих точок провайдерів, помилки HTTP провайдерів і допоміжні засоби multipart form для транскрибування аудіо | + | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контрактів config/selection для web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешу провайдерів web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби config/credentials для web-search для провайдерів, яким не потрібне вбудування увімкнення Plugin | + | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контрактів config/credentials для web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і setter/getter для credentials з обмеженою областю дії | + | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешу/runtime провайдерів web-search | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні допоміжні функції wrapper для Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Допоміжні функції транспорту нативного провайдера, як-от guarded fetch, перетворення transport message і writable потоки transport event | - | `plugin-sdk/provider-onboard` | Допоміжні функції patch конфігурації онбордингу | - | `plugin-sdk/global-singleton` | Допоміжні функції singleton/map/cache, локальних для процесу | - | `plugin-sdk/group-activation` | Вузькі допоміжні функції режиму активації групи та розбору команд | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоку та спільні допоміжні засоби обгорток для Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Нативні допоміжні засоби транспорту провайдера, такі як guarded fetch, трансформації транспортних повідомлень і потоки подій транспорту з можливістю запису | + | `plugin-sdk/provider-onboard` | Допоміжні засоби патчів конфігурації онбордингу | + | `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache | + | `plugin-sdk/group-activation` | Вузькі допоміжні засоби режиму активації груп і розбору команд | - | Підшлях | Основні експорти | + | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні функції реєстру команд, включно з форматуванням меню динамічних аргументів, допоміжні функції авторизації відправника | - | `plugin-sdk/command-status` | Конструктори повідомлень команд/довідки, як-от `buildCommandsMessagePaginated` і `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Допоміжні функції визначення затверджувача та автентифікації дій у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні функції профілю/фільтра затвердження native exec | - | `plugin-sdk/approval-delivery-runtime` | Адаптери можливостей/доставки native approval | - | `plugin-sdk/approval-gateway-runtime` | Спільна допоміжна функція визначення Gateway approval | - | `plugin-sdk/approval-handler-adapter-runtime` | Легковагові допоміжні функції завантаження адаптера native approval для гарячих точок входу каналу | - | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні функції середовища виконання approval handler; віддавайте перевагу вужчим швам adapter/gateway, коли їх достатньо | - | `plugin-sdk/approval-native-runtime` | Допоміжні функції цілі native approval + прив’язки облікового запису | - | `plugin-sdk/approval-reply-runtime` | Допоміжні функції payload відповіді для затвердження exec/Plugin | - | `plugin-sdk/approval-runtime` | Допоміжні функції payload затвердження exec/Plugin, допоміжні функції маршрутизації/середовища виконання native approval і допоміжні функції структурованого відображення approval, як-от `formatApprovalDisplayPath` | - | `plugin-sdk/reply-dedupe` | Вузькі допоміжні функції скидання дедуплікації вхідних відповідей | - | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні функції тестування контрактів каналу без широкого testing barrel | - | `plugin-sdk/command-auth-native` | Нативна автентифікація команд, форматування меню динамічних аргументів і допоміжні функції native session-target | - | `plugin-sdk/command-detection` | Спільні допоміжні функції виявлення команд | - | `plugin-sdk/command-primitives-runtime` | Легковагові предикати тексту команд для гарячих шляхів каналу | - | `plugin-sdk/command-surface` | Допоміжні функції нормалізації command-body і command-surface | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, включно з форматуванням меню динамічних аргументів, допоміжні засоби авторизації відправника | + | `plugin-sdk/command-status` | Побудовники повідомлень команд/довідки, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення схвалювача й автентифікації дій у тому самому чаті | + | `plugin-sdk/approval-client-runtime` | Нативні допоміжні засоби профілю/фільтра схвалення exec | + | `plugin-sdk/approval-delivery-runtime` | Нативні адаптери можливостей/доставки схвалень | + | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення approval Gateway | + | `plugin-sdk/approval-handler-adapter-runtime` | Полегшені нативні допоміжні засоби завантаження адаптера схвалення для гарячих точок входу каналів | + | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime обробника схвалень; віддавайте перевагу вужчим швам adapter/gateway, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Нативні допоміжні засоби цілей схвалення + прив’язки облікових записів | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді для схвалення exec/plugin | + | `plugin-sdk/approval-runtime` | Допоміжні засоби payload для схвалення exec/plugin, нативні допоміжні засоби маршрутизації/runtime схвалень і структуровані допоміжні засоби відображення схвалень, такі як `formatApprovalDisplayPath` | + | `plugin-sdk/reply-dedupe` | Вузькі допоміжні засоби скидання дедуплікації вхідних відповідей | + | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні засоби тестування контрактів каналів без широкого testing barrel | + | `plugin-sdk/command-auth-native` | Нативна автентифікація команд, форматування меню динамічних аргументів і нативні допоміжні засоби session-target | + | `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд | + | `plugin-sdk/command-primitives-runtime` | Полегшені предикати тексту команд для гарячих шляхів каналів | + | `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команд і поверхні команд | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні функції збирання secret-contract для поверхонь secret каналу/Plugin | - | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні функції `coerceSecretRef` і типізації SecretRef для розбору secret-contract/config | - | `plugin-sdk/security-runtime` | Спільні допоміжні функції trust, DM gating, external-content, редагування чутливого тексту, порівняння secret за сталий час і збирання secret | - | `plugin-sdk/ssrf-policy` | Допоміжні функції allowlist хостів і політики SSRF для приватної мережі | - | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні функції pinned-dispatcher без широкої поверхні infra runtime | - | `plugin-sdk/ssrf-runtime` | Допоміжні функції pinned-dispatcher, fetch із захистом SSRF, помилки SSRF і політики SSRF | - | `plugin-sdk/secret-input` | Допоміжні функції розбору secret input | - | `plugin-sdk/webhook-ingress` | Допоміжні функції запиту/цілі Webhook і приведення raw websocket/body | - | `plugin-sdk/webhook-request-guards` | Допоміжні функції розміру body/timeout запиту | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-contract для поверхонь секретів channel/plugin | + | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору secret-contract/config | + | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, шлюзування DM, зовнішнього вмісту, редагування чутливого тексту, порівняння секретів у сталий час і збирання секретів | + | `plugin-sdk/ssrf-policy` | Допоміжні засоби allowlist хостів і політики SSRF для приватних мереж | + | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої поверхні infra runtime | + | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом від SSRF, помилка SSRF і допоміжні засоби політики SSRF | + | `plugin-sdk/secret-input` | Допоміжні засоби розбору введення секретів | + | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів/цілей Webhook і приведення raw websocket/body | + | `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру тіла запиту/тайм-ауту | - - | Підшлях | Основні експорти | + + | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/runtime` | Широкі допоміжні функції середовища виконання/логування/резервного копіювання/встановлення Plugin | - | `plugin-sdk/runtime-env` | Вузькі допоміжні функції env середовища виконання, logger, timeout, retry і backoff | - | `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових значень, розбору URL CDP і допоміжних функцій автентифікації browser-control | - | `plugin-sdk/channel-runtime-context` | Загальні допоміжні функції реєстрації та пошуку runtime-context каналу | + | `plugin-sdk/runtime` | Широкі допоміжні засоби для runtime/логування/резервного копіювання/встановлення Plugins | + | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби для змінних середовища runtime, логера, тайм-аутів, повторних спроб і backoff | + | `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових значень, розбору URL CDP і допоміжних засобів автентифікації browser-control | + | `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку channel runtime-context | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні функції команд/хуків/http/interactive Plugin | - | `plugin-sdk/hook-runtime` | Спільні допоміжні функції конвеєра Webhook/внутрішніх хуків | - | `plugin-sdk/lazy-runtime` | Допоміжні функції lazy import/binding середовища виконання, як-от `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні функції exec процесу | - | `plugin-sdk/cli-runtime` | Допоміжні функції форматування CLI, wait, version, invocation аргументів і lazy command-group | - | `plugin-sdk/gateway-runtime` | Допоміжні функції клієнта Gateway, CLI RPC Gateway, помилок протоколу Gateway та patch статусу каналу | - | `plugin-sdk/config-types` | Поверхня конфігурації лише для типів для форм конфігурації Plugin, як-от `OpenClawConfig` і типів конфігурації каналу/провайдера | - | `plugin-sdk/plugin-config-runtime` | Допоміжні функції пошуку plugin-config у середовищі виконання, як-от `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` | - | `plugin-sdk/config-mutation` | Допоміжні функції транзакційної мутації конфігурації, як-от `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` | - | `plugin-sdk/runtime-config-snapshot` | Допоміжні функції знімка конфігурації поточного процесу, як-от `getRuntimeConfig`, `getRuntimeConfigSnapshot` і setters знімків для тестів | - | `plugin-sdk/telegram-command-config` | Допоміжні функції нормалізації назв/описів команд Telegram і перевірок дублікатів/конфліктів, навіть коли поверхня контракту bundled Telegram недоступна | - | `plugin-sdk/text-autolink-runtime` | Виявлення autolink посилань на файли без широкого barrel `text-runtime` | - | `plugin-sdk/approval-runtime` | Допоміжні функції затвердження exec/Plugin, конструктори approval-capability, допоміжні функції auth/profile, допоміжні функції native routing/runtime і форматування структурованого шляху відображення approval | - | `plugin-sdk/reply-runtime` | Спільні допоміжні функції середовища виконання для вхідних повідомлень/відповідей, chunking, dispatch, Heartbeat, планувальник відповідей | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції dispatch/finalize відповідей і conversation-label | - | `plugin-sdk/reply-history` | Спільні допоміжні функції та маркери історії відповідей для короткого вікна, як-от `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/хуків/http/інтерактивної взаємодії Plugin | + | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline для Webhook/внутрішніх хуків | + | `plugin-sdk/lazy-runtime` | Допоміжні засоби лінивого імпорту/прив’язування runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Допоміжні засоби виконання процесів | + | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування, версій, виклику аргументів і лінивих груп команд | + | `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта Gateway, Gateway CLI RPC, помилок протоколу Gateway і патчів статусу каналу | + | `plugin-sdk/config-types` | Поверхня конфігурації лише з типами для форм конфігурації Plugin, таких як `OpenClawConfig` і типи конфігурації каналу/провайдера | + | `plugin-sdk/plugin-config-runtime` | Допоміжні засоби пошуку конфігурації Plugin у runtime, такі як `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` | + | `plugin-sdk/config-mutation` | Допоміжні засоби транзакційної мутації конфігурації, такі як `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` | + | `plugin-sdk/runtime-config-snapshot` | Допоміжні засоби знімка поточної конфігурації процесу, такі як `getRuntimeConfig`, `getRuntimeConfigSnapshot` і сетери тестових знімків | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня контракту bundled Telegram недоступна | + | `plugin-sdk/text-autolink-runtime` | Виявлення автопосилань на посилання файлів без широкого barrel `text-runtime` | + | `plugin-sdk/approval-runtime` | Допоміжні засоби схвалення exec/plugin, побудовники можливостей схвалення, допоміжні засоби auth/profile, нативні допоміжні засоби маршрутизації/runtime і структуроване форматування шляху відображення схвалення | + | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби runtime для inbound/reply, розбиття на чанки, диспетчеризації, Heartbeat, планувальника відповіді | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби диспетчеризації/фіналізації відповіді та ярликів розмов | + | `plugin-sdk/reply-history` | Спільні допоміжні засоби коротковіконної історії відповідей і маркери, такі як `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Вузькі допоміжні функції chunking тексту/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні функції шляху сховища сесій, session-key, updated-at і мутації сховища | - | `plugin-sdk/cron-store-runtime` | Допоміжні функції шляху/load/save сховища Cron | - | `plugin-sdk/state-paths` | Допоміжні функції шляхів директорій state/OAuth | - | `plugin-sdk/routing` | Допоміжні функції маршруту/ключа сесії/прив’язки облікового запису, як-от `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні допоміжні функції зведення статусу каналу/облікового запису, типові значення runtime-state і допоміжні функції метаданих проблем | - | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні функції target resolver | - | `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-payload` | Витягування нормалізованих payload з об’єктів результатів tool | - | `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів tool | - | `plugin-sdk/temp-path` | Спільні допоміжні функції шляхів тимчасового завантаження | - | `plugin-sdk/logging-core` | Допоміжні функції logger підсистеми та редагування | - | `plugin-sdk/markdown-table-runtime` | Допоміжні функції режиму та конвертації таблиць Markdown | - | `plugin-sdk/model-session-runtime` | Допоміжні функції перевизначення моделі/сесії, як-от `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` | - | `plugin-sdk/talk-config-runtime` | Допоміжні функції визначення конфігурації провайдера talk | - | `plugin-sdk/json-store` | Невеликі допоміжні функції читання/запису стану JSON | - | `plugin-sdk/file-lock` | Допоміжні функції реентерабельного file-lock | - | `plugin-sdk/persistent-dedupe` | Допоміжні функції кешу дедуплікації на диску | - | `plugin-sdk/acp-runtime` | Допоміжні функції середовища виконання/сесії ACP і dispatch відповідей | - | `plugin-sdk/acp-binding-resolve-runtime` | Розв’язання прив’язки ACP лише для читання без імпортів запуску життєвого циклу | - | `plugin-sdk/agent-config-primitives` | Вузькі примітиви schema конфігурації середовища виконання агента | - | `plugin-sdk/boolean-param` | Читач вільного boolean параметра | - | `plugin-sdk/dangerous-name-runtime` | Допоміжні функції розв’язання збігів небезпечних назв | - | `plugin-sdk/device-bootstrap` | Допоміжні функції початкової ініціалізації пристрою та pairing token | - | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних функцій passive-channel, статусу й ambient proxy | - | `plugin-sdk/models-provider-runtime` | Допоміжні функції відповідей команди `/models`/провайдера | - | `plugin-sdk/skill-commands-runtime` | Допоміжні функції списку команд Skills | - | `plugin-sdk/native-command-registry` | Допоміжні функції реєстру/build/serialize нативних команд | - | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness агента: типи harness, допоміжні функції steer/abort активного запуску, допоміжні функції мосту інструментів OpenClaw, допоміжні функції політики tool для runtime-plan, класифікація результатів terminal, допоміжні функції форматування/деталізації прогресу tool і утиліти результатів спроб | - | `plugin-sdk/provider-zai-endpoint` | Допоміжні функції виявлення endpoint Z.A.I | - | `plugin-sdk/async-lock-runtime` | Допоміжна функція локального для процесу async lock для невеликих файлів runtime state | - | `plugin-sdk/channel-activity-runtime` | Допоміжна функція telemetry активності каналу | - | `plugin-sdk/concurrency-runtime` | Допоміжна функція обмеженої конкурентності async задач | - | `plugin-sdk/dedupe-runtime` | Допоміжні функції кешу дедуплікації в пам’яті | - | `plugin-sdk/delivery-queue-runtime` | Допоміжна функція drain черги очікуваної вихідної доставки | - | `plugin-sdk/file-access-runtime` | Допоміжні функції безпечних шляхів до локальних файлів і джерел медіа | - | `plugin-sdk/heartbeat-runtime` | Допоміжні функції подій і видимості Heartbeat | - | `plugin-sdk/number-runtime` | Допоміжна функція приведення чисел | - | `plugin-sdk/secure-random-runtime` | Допоміжні функції безпечних token/UUID | - | `plugin-sdk/system-event-runtime` | Допоміжні функції черги системних подій | - | `plugin-sdk/transport-ready-runtime` | Допоміжна функція очікування готовності транспорту | - | `plugin-sdk/infra-runtime` | Застарілий shim сумісності; використовуйте наведені вище сфокусовані підшляхи середовища виконання | - | `plugin-sdk/collection-runtime` | Невеликі допоміжні функції обмеженого кешу | - | `plugin-sdk/diagnostic-runtime` | Допоміжні функції прапорців, подій і trace-context діагностики | - | `plugin-sdk/error-runtime` | Допоміжні функції графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Допоміжні функції обгорнутого fetch, proxy і pinned lookup | + | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби розбиття тексту/Markdown на чанки | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби для шляху сховища сесій, ключа сесії, updated-at і мутації сховища | + | `plugin-sdk/cron-store-runtime` | Допоміжні засоби для шляху/завантаження/збереження сховища Cron | + | `plugin-sdk/state-paths` | Допоміжні засоби шляхів до каталогів state/OAuth | + | `plugin-sdk/routing` | Допоміжні засоби маршрутів/ключів сесій/прив’язки облікових записів, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумків статусу каналу/облікового запису, типових значень runtime-state і метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілей | + | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків | + | `plugin-sdk/request-url` | Видобування рядкових URL з вхідних даних, подібних до fetch/request | + | `plugin-sdk/run-command` | Таймований виконавець команд із нормалізованими результатами stdout/stderr | + | `plugin-sdk/param-readers` | Поширені зчитувачі параметрів інструментів/CLI | + | `plugin-sdk/tool-payload` | Видобування нормалізованих payload з об’єктів результатів інструментів | + | `plugin-sdk/tool-send` | Видобування канонічних полів цілі надсилання з аргументів інструмента | + | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів для тимчасових завантажень | + | `plugin-sdk/logging-core` | Допоміжні засоби логера підсистеми та редагування | + | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму таблиць Markdown і перетворення | + | `plugin-sdk/model-session-runtime` | Допоміжні засоби перевизначення моделі/сесії, такі як `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` | + | `plugin-sdk/talk-config-runtime` | Допоміжні засоби визначення конфігурації провайдера talk | + | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису стану JSON | + | `plugin-sdk/file-lock` | Допоміжні засоби повторно вхідного блокування файлів | + | `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу дедуплікації на диску | + | `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/сесій ACP і диспетчеризації відповідей | + | `plugin-sdk/acp-binding-resolve-runtime` | Визначення прив’язки ACP лише для читання без імпортів запуску життєвого циклу | + | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime агента | + | `plugin-sdk/boolean-param` | Нестрогий зчитувач булевих параметрів | + | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення збігів небезпечних імен | + | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токенів прив’язки | + | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, статусу й ambient proxy | + | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповідей команд/провайдерів `/models` | + | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби виведення списку команд Skills | + | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/побудови/серіалізації нативних команд | + | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness агента: типи harness, допоміжні засоби steer/abort активного запуску, допоміжні засоби мосту інструментів OpenClaw, допоміжні засоби політик інструментів runtime-plan, класифікація результатів термінала, допоміжні засоби форматування/деталізації прогресу інструментів і утиліти результатів спроб | + | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення кінцевих точок Z.A.I | + | `plugin-sdk/async-lock-runtime` | Допоміжний засіб process-local async lock для невеликих файлів стану runtime | + | `plugin-sdk/channel-activity-runtime` | Допоміжний засіб телеметрії активності каналу | + | `plugin-sdk/concurrency-runtime` | Допоміжний засіб обмеженої конкурентності асинхронних задач | + | `plugin-sdk/dedupe-runtime` | Допоміжні засоби кешу дедуплікації в пам’яті | + | `plugin-sdk/delivery-queue-runtime` | Допоміжний засіб зливу черги очікуваної вихідної доставки | + | `plugin-sdk/file-access-runtime` | Допоміжні засоби безпечних шляхів до локальних файлів і джерел медіа | + | `plugin-sdk/heartbeat-runtime` | Допоміжні засоби подій і видимості Heartbeat | + | `plugin-sdk/number-runtime` | Допоміжний засіб приведення числових значень | + | `plugin-sdk/secure-random-runtime` | Допоміжні засоби безпечних токенів/UUID | + | `plugin-sdk/system-event-runtime` | Допоміжні засоби черги системних подій | + | `plugin-sdk/transport-ready-runtime` | Допоміжний засіб очікування готовності транспорту | + | `plugin-sdk/infra-runtime` | Застарілий shim сумісності; використовуйте наведені вище сфокусовані підшляхи runtime | + | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу | + | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних прапорців, подій і trace-context | + | `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch, proxy і pinned lookup | | `plugin-sdk/runtime-fetch` | Runtime fetch з урахуванням dispatcher без імпортів proxy/guarded-fetch | - | `plugin-sdk/response-limit-runtime` | Читач обмеженого response body без широкої поверхні media runtime | - | `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки conversation без маршрутизації configured binding або pairing stores | - | `plugin-sdk/session-store-runtime` | Допоміжні функції session-store без широких імпортів запису/обслуговування конфігурації | + | `plugin-sdk/response-limit-runtime` | Зчитувач обмеженого тіла відповіді без широкої поверхні media runtime | + | `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки розмови без маршрутизації налаштованих прив’язок або сховищ pairing | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища сесій без широких імпортів запису/обслуговування конфігурації | | `plugin-sdk/context-visibility-runtime` | Визначення видимості контексту та фільтрація додаткового контексту без широких імпортів config/security | - | `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні функції приведення й нормалізації primitive record/string без імпортів markdown/logging | - | `plugin-sdk/host-runtime` | Допоміжні функції нормалізації hostname і хоста SCP | - | `plugin-sdk/retry-runtime` | Допоміжні функції конфігурації retry і виконавця retry | - | `plugin-sdk/agent-runtime` | Допоміжні функції директорії/ідентичності/робочого простору агента | - | `plugin-sdk/directory-runtime` | Запит/dedup директорії на основі конфігурації | + | `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення та нормалізації примітивних записів/рядків без імпортів markdown/logging | + | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації імен хостів і хостів SCP | + | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації повторних спроб і виконавця повторних спроб | + | `plugin-sdk/agent-runtime` | Допоміжні засоби каталогів/ідентичності/робочого простору агента | + | `plugin-sdk/directory-runtime` | Запит/dedup каталогу на основі конфігурації | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - | Підшлях | Основні експорти | + | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні функції fetch/transform/store медіа, а також конструктори payload медіа | - | `plugin-sdk/media-store` | Вузькі допоміжні функції media store, як-от `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні функції failover генерації медіа, вибору кандидатів і повідомлень про відсутню модель | - | `plugin-sdk/media-understanding` | Типи провайдера media understanding, а також експорти допоміжних функцій для зображень/аудіо, орієнтованих на провайдера | - | `plugin-sdk/text-runtime` | Спільні допоміжні функції text/markdown/logging, як-от видалення видимого для асистента тексту, допоміжні функції render/chunking/table для Markdown, допоміжні функції редагування, допоміжні функції тегів директив і утиліти безпечного тексту | - | `plugin-sdk/text-chunking` | Допоміжна функція chunking вихідного тексту | - | `plugin-sdk/speech` | Типи провайдера speech, а також експорти допоміжних функцій директив, реєстру, валідації та speech, орієнтованих на провайдера | - | `plugin-sdk/speech-core` | Спільні типи провайдера speech, а також експорти допоміжних функцій реєстру, директив, нормалізації та speech | - | `plugin-sdk/realtime-transcription` | Типи провайдера realtime transcription, допоміжні функції реєстру та спільна допоміжна функція сесії WebSocket | - | `plugin-sdk/realtime-voice` | Типи провайдера 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 і встановлення маршруту | - | `plugin-sdk/webhook-path` | Допоміжні функції нормалізації шляху Webhook | - | `plugin-sdk/web-media` | Спільні допоміжні функції завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK | - | `plugin-sdk/testing` | Публічні допоміжні функції тестування extension, включно з моками реєстру/runtime Plugin, захопленням реєстрації провайдера, допоміжними функціями майстра налаштування, фікстурами fetch/env/temp/time, допоміжними функціями schema/media/live-test, `installCommonResolveTargetErrorCases`, `writeSkill`, `createTestRegistry` і завантаженням env для live generation. Допоміжні функції extension `*.test-support.ts` мають залишатися тут або на сфокусованих підшляхах SDK, а не в core internals | - | `plugin-sdk/plugin-test-api` | Мінімальна допоміжна функція `createTestPluginApi` для прямих модульних тестів реєстрації Plugin без імпорту містків допоміжних функцій тестування репозиторію | - | `plugin-sdk/channel-test-helpers` | Орієнтовані на канал допоміжні функції тестування для життєвого циклу запуску облікового запису, перевірок директорії, threading конфігурації надсилання, моків runtime, проблем статусу, вихідної доставки та реєстрації хуків | - | `plugin-sdk/plugin-test-contracts` | Допоміжні функції контрактів для пакета Plugin, реєстрації, публічного артефакту, прямого імпорту, API runtime та побічного ефекту імпорту | - | `plugin-sdk/provider-test-contracts` | Допоміжні функції контрактів для runtime провайдера, auth, discovery, onboard, catalog, wizard, web-search/fetch і stream | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також побудовники payload медіа | + | `plugin-sdk/media-store` | Вузькі допоміжні засоби сховища медіа, такі як `saveMediaBuffer` | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації медіа, вибір кандидатів і повідомлення про відсутні моделі | + | `plugin-sdk/media-understanding` | Типи провайдерів для розуміння медіа, а також експорти допоміжних засобів для зображень/аудіо, орієнтованих на провайдерів | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби для тексту/Markdown/логування, такі як видалення видимого для асистента тексту, допоміжні засоби рендерингу/розбиття на чанки/таблиць Markdown, засоби редагування, допоміжні засоби тегів директив і утиліти безпечного тексту | + | `plugin-sdk/text-chunking` | Допоміжний засіб розбиття вихідного тексту на чанки | + | `plugin-sdk/speech` | Типи провайдерів мовлення, а також експорти директив, реєстру, валідації та допоміжних засобів мовлення, орієнтовані на провайдерів | + | `plugin-sdk/speech-core` | Спільні типи провайдерів мовлення, експорти реєстру, директив, нормалізації та допоміжних засобів мовлення | + | `plugin-sdk/realtime-transcription` | Типи провайдерів транскрибування в реальному часі, допоміжні засоби реєстру та спільний допоміжний засіб сесії WebSocket | + | `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 і встановлення маршрутів | + | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляхів Webhook | + | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа | + | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів plugin SDK | + | `plugin-sdk/testing` | Загальнодоступні допоміжні засоби тестування extension, зокрема моки реєстру/runtime Plugin, захоплення реєстрації провайдерів, допоміжні засоби setup-wizard, фікстури fetch/env/temp/time, допоміжні засоби schema/media/live-test, `installCommonResolveTargetErrorCases`, `writeSkill`, `createTestRegistry` і завантаження env для live generation. Допоміжні засоби extension `*.test-support.ts` мають залишатися тут або на сфокусованих підшляхах SDK, а не у внутрішніх модулях core | + | `plugin-sdk/plugin-test-api` | Мінімальний допоміжний засіб `createTestPluginApi` для модульних тестів прямої реєстрації Plugin без імпорту мостів допоміжних засобів тестування репозиторію | + | `plugin-sdk/channel-test-helpers` | Орієнтовані на канали допоміжні засоби тестування життєвого циклу запуску облікових записів, перевірок каталогів, потоковості send-config, моків runtime, проблем статусу, вихідної доставки та реєстрації хуків | + | `plugin-sdk/plugin-test-contracts` | Допоміжні засоби контрактів пакета Plugin, реєстрації, публічного артефакту, прямого імпорту, runtime API і побічних ефектів імпорту | + | `plugin-sdk/provider-test-contracts` | Допоміжні засоби контрактів runtime провайдера, auth, discovery, onboard, catalog, wizard, web-search/fetch і stream | + | `plugin-sdk/test-fixtures` | Загальні фікстури захоплення runtime CLI, контексту sandbox, записувача skill, agent-message, system-event, terminal-text, chunking, auth-token і типізованих кейсів | - - | Підшлях | Основні експорти | + + | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/memory-core` | Поверхня допоміжних функцій bundled memory-core для менеджера/конфігурації/файлів/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Фасад середовища виконання індексу/пошуку Memory | - | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста Memory | - | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста Memory, доступ до реєстру, локальний провайдер і загальні допоміжні функції batch/remote | - | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста Memory | - | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста Memory | - | `plugin-sdk/memory-core-host-multimodal` | Допоміжні функції multimodal хоста Memory | - | `plugin-sdk/memory-core-host-query` | Допоміжні функції query хоста Memory | - | `plugin-sdk/memory-core-host-secret` | Допоміжні функції secret хоста Memory | - | `plugin-sdk/memory-core-host-events` | Допоміжні функції журналу подій хоста Memory | - | `plugin-sdk/memory-core-host-status` | Допоміжні функції статусу хоста Memory | - | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні функції CLI runtime хоста Memory | - | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні функції core runtime хоста Memory | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні функції файлів/runtime хоста Memory | - | `plugin-sdk/memory-host-core` | Нейтральний до вендора псевдонім для допоміжних функцій core runtime хоста Memory | - | `plugin-sdk/memory-host-events` | Нейтральний до вендора псевдонім для допоміжних функцій журналу подій хоста Memory | - | `plugin-sdk/memory-host-files` | Нейтральний до вендора псевдонім для допоміжних функцій файлів/runtime хоста Memory | - | `plugin-sdk/memory-host-markdown` | Спільні допоміжні функції managed-markdown для plugin, суміжних із memory | - | `plugin-sdk/memory-host-search` | Фасад середовища виконання Active Memory для доступу до search-manager | - | `plugin-sdk/memory-host-status` | Нейтральний до вендора псевдонім для допоміжних функцій статусу хоста Memory | - | `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` | Контракти ембедингів хоста пам’яті, доступ до реєстру, локальний провайдер і загальні допоміжні засоби пакетної/віддаленої обробки | + | `plugin-sdk/memory-core-host-engine-qmd` | Експорти engine QMD хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті | + | `plugin-sdk/memory-core-host-multimodal` | Допоміжні засоби мультимодального хоста пам’яті | + | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | + | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | + | `plugin-sdk/memory-core-host-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 Active Memory для доступу до search-manager | + | `plugin-sdk/memory-host-status` | Нейтральний до постачальника псевдонім для допоміжних засобів статусу хоста пам’яті | + | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled memory-lancedb | - | 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-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `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/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Застарілі шви сумісності/допоміжних функцій bundled channel. Нові plugins мають імпортувати загальні підшляхи SDK або локальні barrel модуля plugin. | - | Допоміжні функції auth/plugin для конкретних сценаріїв | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `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-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `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/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Застарілі шви сумісності/допоміжні шви bundled channel. Нові Plugins мають імпортувати загальні підшляхи SDK або локальні barrel Plugin. | + | Допоміжні засоби auth/специфічні для Plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Допоміжні шви функцій/Plugins bundled; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | @@ -319,4 +321,4 @@ x-i18n: - [Огляд Plugin SDK](/uk/plugins/sdk-overview) - [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення plugins](/uk/plugins/building-plugins) +- [Створення Plugins](/uk/plugins/building-plugins) diff --git a/docs/uk/plugins/sdk-testing.md b/docs/uk/plugins/sdk-testing.md index e79d5191b..0f421515a 100644 --- a/docs/uk/plugins/sdk-testing.md +++ b/docs/uk/plugins/sdk-testing.md @@ -7,37 +7,43 @@ sidebarTitle: Testing summary: Утиліти та шаблони тестування для Plugin OpenClaw title: Тестування Plugin x-i18n: - generated_at: "2026-04-28T00:03:38Z" + generated_at: "2026-04-28T00:34:57Z" model: gpt-5.4 provider: openai - source_hash: 2c2aa1506f6f115168c980d76785db6b8531c6565219ac07b35f43319b0a5bbd + source_hash: b5c96065868b3c8fcd30ef3e51fb7c13e73d5742c8f1cc66bc93eb089c0d1a76 source_path: plugins/sdk-testing.md workflow: 15 --- -Довідник з утиліт тестування, шаблонів і примусового застосування lint для Plugin OpenClaw. +Довідник з утиліт тестування, шаблонів і застосування lint для Plugin OpenClaw. - **Шукаєте приклади тестів?** Практичні посібники містять готові приклади тестів: - [Тести Plugin каналу](/uk/plugins/sdk-channel-plugins#step-6-test) і - [Тести Plugin провайдера](/uk/plugins/sdk-provider-plugins#step-6-test). + **Шукаєте приклади тестів?** Покрокові посібники містять готові приклади тестів: + [Тести channel Plugin](/uk/plugins/sdk-channel-plugins#step-6-test) і + [Тести provider Plugin](/uk/plugins/sdk-provider-plugins#step-6-test). ## Утиліти тестування **Загальний імпорт:** `openclaw/plugin-sdk/testing` -**Імпорт мока API Plugin:** `openclaw/plugin-sdk/plugin-test-api` +**Імпорт мока Plugin API:** `openclaw/plugin-sdk/plugin-test-api` -**Імпорт контракту каналу:** `openclaw/plugin-sdk/channel-contract-testing` +**Імпорт channel contract:** `openclaw/plugin-sdk/channel-contract-testing` -**Імпорт допоміжного засобу тестування каналу:** `openclaw/plugin-sdk/channel-test-helpers` +**Імпорт channel test helper:** `openclaw/plugin-sdk/channel-test-helpers` -**Імпорт контракту Plugin:** `openclaw/plugin-sdk/plugin-test-contracts` +**Імпорт plugin contract:** `openclaw/plugin-sdk/plugin-test-contracts` -**Імпорт контракту провайдера:** `openclaw/plugin-sdk/provider-test-contracts` +**Імпорт plugin runtime test:** `openclaw/plugin-sdk/plugin-test-runtime` -Підшлях testing експортує вузький набір допоміжних засобів для авторів Plugin: +**Імпорт provider contract:** `openclaw/plugin-sdk/provider-test-contracts` + +**Імпорт environment/network test:** `openclaw/plugin-sdk/test-env` + +**Імпорт generic fixture:** `openclaw/plugin-sdk/test-fixtures` + +Підшлях testing експортує вузький набір helper-утиліт для авторів Plugin: ```typescript import { @@ -49,55 +55,69 @@ import { createTestPluginApi } from "openclaw/plugin-sdk/plugin-test-api"; import { expectChannelInboundContextContract } from "openclaw/plugin-sdk/channel-contract-testing"; import { createStartAccountContext } from "openclaw/plugin-sdk/channel-test-helpers"; import { describePluginRegistrationContract } from "openclaw/plugin-sdk/plugin-test-contracts"; +import { registerSingleProviderPlugin } from "openclaw/plugin-sdk/plugin-test-runtime"; import { describeOpenAIProviderRuntimeContract } from "openclaw/plugin-sdk/provider-test-contracts"; +import { withEnv, withFetchPreconnect } from "openclaw/plugin-sdk/test-env"; +import { createCliRuntimeCapture, typedCases } from "openclaw/plugin-sdk/test-fixtures"; ``` ### Доступні експорти -| Export | Purpose | -| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -| `createTestPluginApi` | Побудувати мінімальний мок API Plugin для прямих модульних тестів реєстрації. Імпортуйте з `plugin-sdk/plugin-test-api` | -| `expectChannelInboundContextContract` | Перевірити форму вхідного контексту каналу. Імпортуйте з `plugin-sdk/channel-contract-testing` | -| `installChannelOutboundPayloadContractSuite` | Встановити набір контрактних випадків для вихідного payload каналу. Імпортуйте з `plugin-sdk/channel-contract-testing` | -| `createStartAccountContext` | Побудувати контексти життєвого циклу облікового запису каналу. Імпортуйте з `plugin-sdk/channel-test-helpers` | -| `describePluginRegistrationContract` | Встановити перевірки контракту реєстрації Plugin. Імпортуйте з `plugin-sdk/plugin-test-contracts` | -| `describeOpenAIProviderRuntimeContract` | Встановити перевірки контракту середовища виконання для сімейства провайдерів. Імпортуйте з `plugin-sdk/provider-test-contracts` | -| `installCommonResolveTargetErrorCases` | Спільні тестові випадки для обробки помилок під час визначення цілі | -| `shouldAckReaction` | Перевірити, чи має канал додавати реакцію підтвердження | -| `removeAckReactionAfterReply` | Видалити реакцію підтвердження після доставки відповіді | -| `createTestRegistry` | Побудувати фікстуру реєстру Plugin каналу | -| `createEmptyPluginRegistry` | Побудувати порожню фікстуру реєстру Plugin | -| `setActivePluginRegistry` | Встановити фікстуру реєстру для тестів середовища виконання Plugin | -| `createRequestCaptureJsonFetch` | Перехоплювати JSON-запити fetch у тестах допоміжних засобів для медіа | -| `withFetchPreconnect` | Запускати тести fetch з установленими хуками preconnect | -| `withEnv` / `withEnvAsync` | Тимчасово підміняти змінні середовища | -| `createTempHomeEnv` / `withTempDir` | Створювати ізольовані файлові фікстури для тестів | -| `createMockServerResponse` | Створювати мінімальний мок відповіді HTTP-сервера | -| `registerSingleProviderPlugin` | Реєструвати один Plugin провайдера в smoke-тестах завантажувача | -| `registerProviderPlugin` | Захоплювати всі типи провайдерів з одного Plugin | -| `registerProviderPlugins` | Захоплювати реєстрації провайдерів у кількох Plugin | -| `requireRegisteredProvider` | Перевіряти, що колекція провайдерів містить ідентифікатор | -| `runProviderCatalog` | Виконувати хук каталогу провайдера з тестовими залежностями | -| `resolveProviderWizardOptions` | Визначати варіанти майстра налаштування провайдера в контрактних тестах | -| `resolveProviderModelPickerEntries` | Визначати елементи засобу вибору моделей провайдера в контрактних тестах | -| `buildProviderPluginMethodChoice` | Будувати ідентифікатори варіантів майстра провайдера для перевірок | -| `setProviderWizardProvidersResolverForTest` | Впроваджувати провайдерів майстра провайдера для ізольованих тестів | -| `createProviderUsageFetch` | Побудувати фікстури fetch для використання провайдера | -| `useFrozenTime` / `useRealTime` | Заморожувати й відновлювати таймери для тестів, чутливих до часу | -| `createRuntimeEnv` | Побудувати змокане середовище виконання CLI/Plugin | -| `createTestWizardPrompter` | Побудувати змоканий prompter майстра налаштування | -| `createPluginSetupWizardStatus` | Побудувати допоміжні засоби стану налаштування для Plugin каналу | -| `createRuntimeTaskFlow` | Створювати ізольований стан виконання TaskFlow | -| `typedCases` | Зберігати literal-типи для таблично-керованих тестів | +| Export | Purpose | +| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | +| `createTestPluginApi` | Створює мінімальний мок Plugin API для прямих unit-тестів реєстрації. Імпортуйте з `plugin-sdk/plugin-test-api` | +| `expectChannelInboundContextContract` | Перевіряє форму вхідного channel-контексту. Імпортуйте з `plugin-sdk/channel-contract-testing` | +| `installChannelOutboundPayloadContractSuite` | Додає contract-випадки для вихідного payload channel. Імпортуйте з `plugin-sdk/channel-contract-testing` | +| `createStartAccountContext` | Створює контексти життєвого циклу channel-акаунта. Імпортуйте з `plugin-sdk/channel-test-helpers` | +| `describePluginRegistrationContract` | Додає перевірки contract реєстрації Plugin. Імпортуйте з `plugin-sdk/plugin-test-contracts` | +| `registerSingleProviderPlugin` | Реєструє один provider Plugin у smoke-тестах loader. Імпортуйте з `plugin-sdk/plugin-test-runtime` | +| `registerProviderPlugin` | Захоплює всі типи provider з одного Plugin. Імпортуйте з `plugin-sdk/plugin-test-runtime` | +| `registerProviderPlugins` | Захоплює реєстрації provider у кількох Plugin. Імпортуйте з `plugin-sdk/plugin-test-runtime` | +| `requireRegisteredProvider` | Перевіряє, що колекція provider містить id. Імпортуйте з `plugin-sdk/plugin-test-runtime` | +| `createRuntimeEnv` | Створює змокане середовище виконання CLI/Plugin. Імпортуйте з `plugin-sdk/plugin-test-runtime` | +| `createPluginSetupWizardStatus` | Створює helper-утиліти стану налаштування для channel Plugin. Імпортуйте з `plugin-sdk/plugin-test-runtime` | +| `describeOpenAIProviderRuntimeContract` | Додає перевірки runtime contract для сімейства provider. Імпортуйте з `plugin-sdk/provider-test-contracts` | +| `installCommonResolveTargetErrorCases` | Спільні test-випадки для обробки помилок розв’язання цілі | +| `shouldAckReaction` | Перевіряє, чи повинен channel додавати реакцію ack | +| `removeAckReactionAfterReply` | Видаляє реакцію ack після доставки відповіді | +| `createTestRegistry` | Створює fixture реєстру channel Plugin | +| `createEmptyPluginRegistry` | Створює порожню fixture реєстру Plugin | +| `setActivePluginRegistry` | Встановлює fixture реєстру для runtime-тестів Plugin | +| `createRequestCaptureJsonFetch` | Захоплює JSON fetch-запити в тестах helper-утиліт медіа. Імпортуйте з `plugin-sdk/test-env` | +| `withFetchPreconnect` | Запускає fetch-тести з установленими hook-ами preconnect. Імпортуйте з `plugin-sdk/test-env` | +| `withEnv` / `withEnvAsync` | Тимчасово змінює змінні середовища. Імпортуйте з `plugin-sdk/test-env` | +| `createTempHomeEnv` / `withTempDir` | Створює ізольовані fixture файлової системи для тестів. Імпортуйте з `plugin-sdk/test-env` | +| `createMockServerResponse` | Створює мінімальний мок HTTP server response. Імпортуйте з `plugin-sdk/test-env` | +| `createCliRuntimeCapture` | Захоплює вивід середовища виконання CLI в тестах. Імпортуйте з `plugin-sdk/test-fixtures` | +| `createSandboxTestContext` | Створює тестові контексти sandbox. Імпортуйте з `plugin-sdk/test-fixtures` | +| `writeSkill` | Записує fixture Skills. Імпортуйте з `plugin-sdk/test-fixtures` | +| `makeAgentAssistantMessage` | Створює fixture повідомлень транскрипту агента. Імпортуйте з `plugin-sdk/test-fixtures` | +| `peekSystemEvents` / `resetSystemEventsForTest` | Переглядає й скидає fixture системних подій. Імпортуйте з `plugin-sdk/test-fixtures` | +| `sanitizeTerminalText` | Очищає текст термінала для перевірок. Імпортуйте з `plugin-sdk/test-fixtures` | +| `countLines` / `hasBalancedFences` | Перевіряє форму chunking-виводу. Імпортуйте з `plugin-sdk/test-fixtures` | +| `runProviderCatalog` | Виконує hook каталогу provider з тестовими залежностями | +| `resolveProviderWizardOptions` | Розв’язує варіанти setup wizard provider у contract-тестах | +| `resolveProviderModelPickerEntries` | Розв’язує записи model-picker provider у contract-тестах | +| `buildProviderPluginMethodChoice` | Створює id вибору wizard для provider Plugin для перевірок | +| `setProviderWizardProvidersResolverForTest` | Інжектує provider для provider wizard в ізольованих тестах | +| `createProviderUsageFetch` | Створює fixture fetch використання provider | +| `useFrozenTime` / `useRealTime` | Заморожує та відновлює таймери для тестів, чутливих до часу. Імпортуйте з `plugin-sdk/test-env` | +| `createTestWizardPrompter` | Створює змоканий prompter setup wizard | +| `createRuntimeTaskFlow` | Створює ізольований стан TaskFlow середовища виконання | +| `typedCases` | Зберігає literal-типи для table-driven тестів. Імпортуйте з `plugin-sdk/test-fixtures` | -Набори контрактних тестів для вбудованих Plugin також використовують підшляхи SDK testing для допоміжних засобів фікстур реєстру, маніфесту, публічного артефакту та середовища виконання, призначених лише для тестів. Набори лише для core, які залежать від інвентаря вбудованого OpenClaw, залишаються в `src/plugins/contracts`. -Нові тести розширень слід тримати на `openclaw/plugin-sdk/testing` або в більш вузькому -задокументованому підшляху SDK, як-от `plugin-sdk/plugin-test-api` або +Contract-suite для вбудованих Plugin також використовують testing-підшляхи SDK для +допоміжних test-only fixture реєстру, manifest, public-artifact і runtime. Core-only +suite, які залежать від вбудованого inventory OpenClaw, залишаються в `src/plugins/contracts`. +Нові тести extension слід тримати на `openclaw/plugin-sdk/testing` або на вужчому +задокументованому підшляху SDK, такому як `plugin-sdk/plugin-test-api` або `plugin-sdk/channel-contract-testing`, `plugin-sdk/channel-test-helpers`, -`plugin-sdk/plugin-test-contracts` чи `plugin-sdk/provider-test-contracts`, -а не імпортувати безпосередньо файли репозиторію `src/**` або мости репозиторію `test/helpers/plugins/*`. +`plugin-sdk/plugin-test-contracts`, `plugin-sdk/plugin-test-runtime`, +`plugin-sdk/provider-test-contracts`, `plugin-sdk/test-env` чи +`plugin-sdk/test-fixtures`, замість +імпорту файлів repo `src/**` або мостів repo `test/helpers/plugins/*` напряму. -### Типи +### Types Підшлях testing також повторно експортує типи, корисні у файлах тестів: @@ -112,10 +132,10 @@ import type { } from "openclaw/plugin-sdk/testing"; ``` -## Тестування визначення цілі +## Тестування розв’язання цілі Використовуйте `installCommonResolveTargetErrorCases`, щоб додати стандартні випадки помилок для -визначення цілі каналу: +розв’язання цілі channel: ```typescript import { describe } from "vitest"; @@ -124,13 +144,13 @@ import { installCommonResolveTargetErrorCases } from "openclaw/plugin-sdk/testin describe("my-channel target resolution", () => { installCommonResolveTargetErrorCases({ resolveTarget: ({ to, mode, allowFrom }) => { - // Your channel's target resolution logic + // Логіка розв’язання цілі вашого channel return myChannelResolveTarget({ to, mode, allowFrom }); }, implicitAllowFrom: ["user1", "user2"], }); - // Add channel-specific test cases + // Додайте специфічні для channel test-випадки it("should resolve @username targets", () => { // ... }); @@ -139,26 +159,28 @@ describe("my-channel target resolution", () => { ## Шаблони тестування -### Тестування контрактів реєстрації +### Тестування contract реєстрації -Модульні тести, які передають власноруч написаний мок `api` у `register(api)`, не перевіряють -шлюзи приймання завантажувача OpenClaw. Додайте принаймні один smoke-тест на основі завантажувача -для кожної поверхні реєстрації, від якої залежить ваш Plugin, особливо для хуків і +Unit-тести, які передають власноруч написаний мок `api` у `register(api)`, не перевіряють +acceptance gate loader OpenClaw. Додайте принаймні один smoke-тест на основі loader +для кожної поверхні реєстрації, від якої залежить ваш Plugin, особливо для hook-ів і ексклюзивних можливостей, таких як пам’ять. -Справжній завантажувач не допускає реєстрацію Plugin, якщо бракує обов’язкових метаданих або якщо +Справжній loader завершує реєстрацію Plugin помилкою, якщо бракує обов’язкових метаданих або якщо Plugin викликає API можливості, якою він не володіє. Наприклад, -`api.registerHook(...)` вимагає ім’я хука, а -`api.registerMemoryCapability(...)` вимагає, щоб маніфест Plugin або експортована точка входу оголошували `kind: "memory"`. +`api.registerHook(...)` вимагає назву hook, а +`api.registerMemoryCapability(...)` вимагає, щоб manifest Plugin або експортована +точка входу оголошували `kind: "memory"`. -### Тестування доступу до конфігурації середовища виконання +### Тестування доступу до runtime config -Для тестування вбудованих Plugin каналів надавайте перевагу спільному моку середовища виконання Plugin з `openclaw/plugin-sdk/channel-test-helpers`. Його застарілі моки `runtime.config.loadConfig()` і -`runtime.config.writeConfigFile(...)` за замовчуванням викидають помилки, щоб тести виявляли нове +Надавайте перевагу спільному моку runtime Plugin з `openclaw/plugin-sdk/channel-test-helpers` +під час тестування вбудованих channel Plugin. Його застарілі моки `runtime.config.loadConfig()` і +`runtime.config.writeConfigFile(...)` типово викидають помилку, щоб тести виявляли нове використання API сумісності. Перевизначайте ці моки лише тоді, коли тест явно покриває застарілу поведінку сумісності. -### Модульне тестування Plugin каналу +### Unit-тестування channel Plugin ```typescript import { describe, it, expect, vi } from "vitest"; @@ -194,7 +216,7 @@ describe("my-channel plugin", () => { }); ``` -### Модульне тестування Plugin провайдера +### Unit-тестування provider Plugin ```typescript import { describe, it, expect } from "vitest"; @@ -222,9 +244,9 @@ describe("my-provider plugin", () => { }); ``` -### Мокання середовища виконання Plugin +### Мокання runtime Plugin -Для коду, який використовує `createPluginRuntimeStore`, змокуйте середовище виконання в тестах: +Для коду, який використовує `createPluginRuntimeStore`, мокуйте runtime у тестах: ```typescript import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; @@ -255,9 +277,9 @@ store.setRuntime(mockRuntime); store.clearRuntime(); ``` -### Тестування з підмінами для окремих екземплярів +### Тестування з per-instance stub -Надавайте перевагу підмінам для окремих екземплярів замість мутації прототипу: +Надавайте перевагу per-instance stub замість мутації prototype: ```typescript // Preferred: per-instance stub @@ -268,9 +290,9 @@ client.sendMessage = vi.fn().mockResolvedValue({ id: "msg-1" }); // MyChannelClient.prototype.sendMessage = vi.fn(); ``` -## Контрактні тести (Plugin у репозиторії) +## Contract-тести (Plugin у репозиторії) -Вбудовані Plugin мають контрактні тести, які перевіряють належність реєстрації: +Вбудовані Plugin мають contract-тести, які перевіряють належність реєстрації: ```bash pnpm test -- src/plugins/contracts/ @@ -278,12 +300,12 @@ pnpm test -- src/plugins/contracts/ Ці тести перевіряють: -- Які Plugin реєструють які провайдери -- Які Plugin реєструють які мовленнєві провайдери +- Які Plugin реєструють які provider +- Які Plugin реєструють які speech provider - Коректність форми реєстрації -- Відповідність контракту середовища виконання +- Відповідність runtime contract -### Запуск тестів з обмеженою областю +### Запуск scoped-тестів Для конкретного Plugin: @@ -291,7 +313,7 @@ pnpm test -- src/plugins/contracts/ pnpm test -- /my-channel/ ``` -Лише для контрактних тестів: +Лише для contract-тестів: ```bash pnpm test -- src/plugins/contracts/shape.contract.test.ts @@ -299,20 +321,20 @@ pnpm test -- src/plugins/contracts/auth.contract.test.ts pnpm test -- src/plugins/contracts/runtime.contract.test.ts ``` -## Примусове застосування lint (Plugin у репозиторії) +## Застосування lint (Plugin у репозиторії) -`pnpm check` примусово застосовує три правила для Plugin у репозиторії: +`pnpm check` застосовує три правила для Plugin у репозиторії: -1. **Без монолітних імпортів із кореня** -- кореневий barrel `openclaw/plugin-sdk` заборонено -2. **Без прямих імпортів із `src/`** -- Plugin не можуть імпортувати `../../src/` напряму -3. **Без самоімпортів** -- Plugin не можуть імпортувати власний підшлях `plugin-sdk/` +1. **Без монолітних імпортів із root** -- root barrel `openclaw/plugin-sdk` відхиляється +2. **Без прямих імпортів `src/`** -- Plugin не можуть напряму імпортувати `../../src/` +3. **Без self-import** -- Plugin не можуть імпортувати власний підшлях `plugin-sdk/` -Зовнішні Plugin не підпадають під дію цих правил lint, але дотримуватися тих самих +На зовнішні Plugin ці правила lint не поширюються, але дотримуватися тих самих шаблонів рекомендується. -## Конфігурація тестування +## Конфігурація тестів -OpenClaw використовує Vitest із порогами покриття V8. Для тестів Plugin: +OpenClaw використовує Vitest із порогами coverage V8. Для тестів Plugin: ```bash # Run all tests @@ -328,7 +350,7 @@ pnpm test -- /my-channel/ -t "resolves account" pnpm test:coverage ``` -Якщо локальні запуски спричиняють навантаження на пам’ять: +Якщо локальні запуски спричиняють тиск на пам’ять: ```bash OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test @@ -336,7 +358,7 @@ OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test ## Пов’язане -- [Огляд SDK](/uk/plugins/sdk-overview) -- угоди щодо імпорту -- [Plugin каналів SDK](/uk/plugins/sdk-channel-plugins) -- інтерфейс Plugin каналу -- [Plugin провайдерів SDK](/uk/plugins/sdk-provider-plugins) -- хуки Plugin провайдера +- [Огляд SDK](/uk/plugins/sdk-overview) -- правила імпорту +- [Channel Plugins SDK](/uk/plugins/sdk-channel-plugins) -- інтерфейс channel Plugin +- [Provider Plugins SDK](/uk/plugins/sdk-provider-plugins) -- hook-и provider Plugin - [Створення Plugin](/uk/plugins/building-plugins) -- посібник для початку роботи diff --git a/docs/uk/providers/deepinfra.md b/docs/uk/providers/deepinfra.md new file mode 100644 index 000000000..391744d3d --- /dev/null +++ b/docs/uk/providers/deepinfra.md @@ -0,0 +1,90 @@ +--- +read_when: + - Вам потрібен один API-ключ для найкращих LLM з відкритим кодом + - Ви хочете запускати моделі через API DeepInfra в OpenClaw +summary: Використовуйте уніфікований API DeepInfra для доступу до найпопулярніших моделей з відкритим кодом і frontier-моделей в OpenClaw +x-i18n: + generated_at: "2026-04-28T00:35:00Z" + model: gpt-5.4 + provider: openai + source_hash: 22a178e7ac582e094f82f5779a9a963e0bf77b1b19820f74725255b6be0b0593 + source_path: providers/deepinfra.md + workflow: 15 +--- + +# DeepInfra + +DeepInfra надає **уніфікований API**, який маршрутизує запити до найпопулярніших моделей з відкритим кодом і frontier-моделей через одну +кінцеву точку та API-ключ. Він сумісний з OpenAI, тому більшість SDK OpenAI працюють, якщо змінити base URL. + +## Отримання API-ключа + +1. Перейдіть на [https://deepinfra.com/](https://deepinfra.com/) +2. Увійдіть або створіть обліковий запис +3. Перейдіть до Dashboard / Keys і згенеруйте новий API-ключ або використайте автоматично створений + +## Налаштування CLI + +```bash +openclaw onboard --deepinfra-api-key +``` + +Або встановіть змінну середовища: + +```bash +export DEEPINFRA_API_KEY="" # pragma: allowlist secret +``` + +## Фрагмент конфігурації + +```json5 +{ + env: { DEEPINFRA_API_KEY: "" }, // pragma: allowlist secret + agents: { + defaults: { + model: { primary: "deepinfra/deepseek-ai/DeepSeek-V3.2" }, + }, + }, +} +``` + +## Підтримувані поверхні OpenClaw + +Вбудований plugin реєструє всі поверхні DeepInfra, які відповідають поточним +контрактам провайдерів OpenClaw: + +| Поверхня | Модель за замовчуванням | Конфігурація/інструмент OpenClaw | +| ------------------------ | ---------------------------------- | ------------------------------------------------------- | +| Чат / провайдер моделі | `deepseek-ai/DeepSeek-V3.2` | `agents.defaults.model` | +| Генерація/редагування зображень | `black-forest-labs/FLUX-1-schnell` | `image_generate`, `agents.defaults.imageGenerationModel` | +| Розуміння медіа | `moonshotai/Kimi-K2.5` для зображень | розуміння вхідних зображень | +| Мовлення в текст | `openai/whisper-large-v3-turbo` | транскрибування вхідного аудіо | +| Текст у мовлення | `hexgrad/Kokoro-82M` | `messages.tts.provider: "deepinfra"` | +| Генерація відео | `Pixverse/Pixverse-T2V` | `video_generate`, `agents.defaults.videoGenerationModel` | +| Ембедінги пам’яті | `BAAI/bge-m3` | `agents.defaults.memorySearch.provider: "deepinfra"` | + +DeepInfra також надає reranking, класифікацію, object-detection та інші +власні типи моделей. OpenClaw наразі не має першокласних контрактів +провайдерів для цих категорій, тому цей plugin поки що їх не реєструє. + +## Доступні моделі + +OpenClaw динамічно виявляє доступні моделі DeepInfra під час запуску. Використовуйте +`/models deepinfra`, щоб переглянути повний список доступних моделей. + +Будь-яку модель, доступну на [DeepInfra.com](https://deepinfra.com/), можна використовувати з префіксом `deepinfra/`: + +``` +deepinfra/MiniMaxAI/MiniMax-M2.5 +deepinfra/deepseek-ai/DeepSeek-V3.2 +deepinfra/moonshotai/Kimi-K2.5 +deepinfra/zai-org/GLM-5.1 +...та багато інших +``` + +## Примітки + +- Посилання на моделі мають формат `deepinfra//` (наприклад, `deepinfra/Qwen/Qwen3-Max`). +- Модель за замовчуванням: `deepinfra/deepseek-ai/DeepSeek-V3.2` +- Base URL: `https://api.deepinfra.com/v1/openai` +- Власна генерація відео використовує `https://api.deepinfra.com/v1/inference/`. diff --git a/docs/uk/providers/models.md b/docs/uk/providers/models.md index f821ae5c7..9b061bee8 100644 --- a/docs/uk/providers/models.md +++ b/docs/uk/providers/models.md @@ -1,27 +1,27 @@ --- read_when: - Ви хочете вибрати провайдера моделі - - Ви хочете швидкі приклади налаштування для автентифікації LLM і вибору моделі + - Вам потрібні приклади швидкого налаштування для автентифікації LLM і вибору моделі summary: Провайдери моделей (LLM), які підтримує OpenClaw -title: Швидкий старт для провайдерів моделей +title: Швидкий старт для провайдера моделей x-i18n: - generated_at: "2026-04-24T03:48:30Z" + generated_at: "2026-04-28T00:35:18Z" model: gpt-5.4 provider: openai - source_hash: b824a664e0e7a7a5b0ea640ea7329ea3d1e3d12b85d9310231c76014b2ae01cc + source_hash: 3f71f9ab34df2b545128bfeed3cab82f31b741d4a66263113068568ce6b77cd6 source_path: providers/models.md workflow: 15 --- # Провайдери моделей -OpenClaw може використовувати багато провайдерів LLM. Виберіть одного, пройдіть автентифікацію, а потім задайте модель за замовчуванням +OpenClaw може використовувати багато провайдерів LLM. Виберіть одного, пройдіть автентифікацію, а потім установіть модель за замовчуванням у форматі `provider/model`. ## Швидкий старт (два кроки) 1. Пройдіть автентифікацію у провайдера (зазвичай через `openclaw onboard`). -2. Задайте модель за замовчуванням: +2. Установіть модель за замовчуванням: ```json5 { @@ -38,9 +38,10 @@ OpenClaw може використовувати багато провайдер - [Chutes](/uk/providers/chutes) - [ComfyUI](/uk/providers/comfy) - [Cloudflare AI Gateway](/uk/providers/cloudflare-ai-gateway) +- [DeepInfra](/uk/providers/deepinfra) - [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) @@ -59,9 +60,9 @@ OpenClaw може використовувати багато провайдер ## Додаткові варіанти вбудованих провайдерів -- `anthropic-vertex` - неявна підтримка Anthropic у Google Vertex, коли доступні облікові дані Vertex; окремий варіант автентифікації під час onboarding не потрібен +- `anthropic-vertex` - неявна підтримка Anthropic у Google Vertex, якщо доступні облікові дані Vertex; окремий варіант автентифікації під час onboarding не потрібен - `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-flash-preview`; використовуйте `openclaw onboard --auth-choice google-gemini-cli` або `openclaw models auth login --provider google-gemini-cli --set-default` +- `google-gemini-cli` - неофіційний OAuth-потік Gemini CLI; вимагає локального встановлення `gemini` (`brew install gemini-cli` або `npm install -g @google/gemini-cli`); модель за замовчуванням `google-gemini-cli/gemini-3-flash-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). @@ -69,5 +70,5 @@ OpenClaw може використовувати багато провайдер ## Пов’язане - [Вибір моделі](/uk/concepts/model-providers) -- [Model failover](/uk/concepts/model-failover) -- [Models CLI](/uk/cli/models) +- [Перемикання моделей при відмові](/uk/concepts/model-failover) +- [CLI моделей](/uk/cli/models) diff --git a/docs/uk/reference/api-usage-costs.md b/docs/uk/reference/api-usage-costs.md index 06527f0f1..7f3e11850 100644 --- a/docs/uk/reference/api-usage-costs.md +++ b/docs/uk/reference/api-usage-costs.md @@ -2,70 +2,69 @@ read_when: - Ви хочете зрозуміти, які функції можуть викликати платні API - Вам потрібно перевірити ключі, витрати та видимість використання - - Ви пояснюєте звітування про витрати у /status або /usage -summary: Перевірте, що може витрачати кошти, які ключі використовуються та як переглянути використання + - Ви пояснюєте звітність про витрати у `/status` або `/usage` +summary: Перевірте, що може витрачати гроші, які ключі використовуються та як переглядати використання title: Використання API та витрати x-i18n: - generated_at: "2026-04-27T01:11:39Z" + generated_at: "2026-04-28T00:35:33Z" model: gpt-5.4 provider: openai - source_hash: d61fb753442d3be6987877c296238c350d81fcaa8f785f3f33c23463b7831836 + source_hash: 5638007a77a93701ce4ed9139a6c4377c951e2d69941423c3e1b19b5bd52d5d5 source_path: reference/api-usage-costs.md workflow: 15 --- # Використання API та витрати -У цьому документі перелічено **функції, які можуть використовувати API-ключі**, і де відображаються їхні витрати. Він зосереджений на -функціях OpenClaw, які можуть генерувати використання провайдера або платні виклики API. +У цьому документі перелічено **функції, які можуть викликати API-ключі**, і де відображаються їхні витрати. Основна увага приділена +функціям OpenClaw, які можуть генерувати використання провайдера або платні виклики API. ## Де відображаються витрати (чат + CLI) -**Миттєвий знімок вартості за сеанс** +**Знімок вартості для сесії** -- `/status` показує поточну модель сеансу, використання контексту та токени останньої відповіді. +- `/status` показує поточну модель сесії, використання контексту та токени останньої відповіді. - Якщо модель використовує **автентифікацію через API-ключ**, `/status` також показує **орієнтовну вартість** останньої відповіді. -- Якщо метадані живого сеансу обмежені, `/status` може відновити лічильники - токенів/кешу та мітку активної моделі середовища виконання з останнього запису - про використання в транскрипті. Наявні ненульові живі значення все ще мають - пріоритет, а підсумки транскрипту розміру запиту можуть мати перевагу, якщо - збережені підсумки відсутні або менші. +- Якщо live-метадані сесії неповні, `/status` може відновити лічильники + токенів/кешу та мітку активної runtime-моделі з останнього запису використання в транскрипті. + Наявні ненульові live-значення все одно мають пріоритет, а підсумки транскрипту + розміру prompt можуть переважати, коли збережені підсумки відсутні або менші. -**Нижній колонтитул вартості для кожного повідомлення** +**Нижній колонтитул вартості для повідомлення** -- `/usage full` додає нижній колонтитул використання до кожної відповіді, включно з **орієнтовною вартістю** (лише для API-ключа). -- `/usage tokens` показує лише токени; потоки OAuth/токенів у стилі підписки та CLI приховують вартість у доларах. -- Примітка щодо Gemini CLI: коли CLI повертає вивід JSON, OpenClaw зчитує використання з - `stats`, нормалізує `stats.cached` у `cacheRead` і виводить вхідні токени з - `stats.input_tokens - stats.cached`, коли це потрібно. +- `/usage full` додає нижній колонтитул використання до кожної відповіді, включно з **орієнтовною вартістю** (лише для API-ключів). +- `/usage tokens` показує лише токени; OAuth/токен-потоки у стилі підписки та CLI-потоки приховують вартість у доларах. +- Примітка щодо Gemini CLI: коли CLI повертає вихід у JSON, OpenClaw читає використання з + `stats`, нормалізує `stats.cached` у `cacheRead` і за потреби виводить вхідні токени + з `stats.input_tokens - stats.cached`. Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw -знову дозволене, тому OpenClaw вважає повторне використання Claude CLI та використання `claude -p` +знову дозволене, тому OpenClaw вважає повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. -Anthropic досі не надає оцінку вартості в доларах для кожного повідомлення, яку OpenClaw міг би +Anthropic усе ще не надає оцінку вартості в доларах для окремого повідомлення, яку OpenClaw міг би показувати в `/usage full`. -**Вікна використання CLI (квоти провайдера)** +**Вікна використання CLI (квоти провайдерів)** - `openclaw status --usage` і `openclaw channels list` показують **вікна використання** - провайдера (знімки квот, а не витрати на окремі повідомлення). -- Зручний для людини вивід нормалізується до `X% left` для всіх провайдерів. + провайдера (знімки квот, а не вартість окремих повідомлень). +- Зрозумілий для людини вивід нормалізується до `X% left` для всіх провайдерів. - Поточні провайдери вікон використання: Anthropic, GitHub Copilot, Gemini CLI, - OpenAI Codex, MiniMax, Xiaomi та z.ai. -- Примітка щодо MiniMax: його сирі поля `usage_percent` / `usagePercent` означають - залишок квоти, тому OpenClaw інвертує їх перед відображенням. Поля на основі кількості - все ще мають пріоритет, якщо вони присутні. Якщо провайдер повертає `model_remains`, OpenClaw надає перевагу - запису моделі чату, за потреби виводить мітку вікна з часових міток - і включає назву моделі до мітки плану. -- Автентифікація використання для цих вікон квот надходить із специфічних для провайдера хуків, коли вони доступні; - інакше OpenClaw використовує резервний варіант — підбір облікових даних OAuth/API-ключа - з профілів автентифікації, змінних середовища або конфігурації. + OpenAI Codex, MiniMax, Xiaomi і z.ai. +- Примітка щодо MiniMax: його сирі поля `usage_percent` / `usagePercent` означають залишок + квоти, тому OpenClaw інвертує їх перед показом. Поля на основі лічильників усе одно мають перевагу, + якщо вони присутні. Якщо провайдер повертає `model_remains`, OpenClaw надає перевагу запису моделі чату, + за потреби виводить мітку вікна з часових позначок і + включає назву моделі до мітки плану. +- Автентифікація для цих вікон квот надходить із хуків, специфічних для провайдера, коли вони доступні; + інакше OpenClaw повертається до пошуку відповідних облікових даних OAuth/API-ключів + у профілях автентифікації, змінних середовища або конфігурації. -Див. [Використання токенів і витрати](/uk/reference/token-use) для подробиць і прикладів. +Докладніше й приклади див. у [Використання токенів і витрати](/uk/reference/token-use). ## Як виявляються ключі -OpenClaw може отримувати облікові дані з: +OpenClaw може підхоплювати облікові дані з: - **Профілів автентифікації** (для кожного агента, зберігаються в `auth-profiles.json`). - **Змінних середовища** (наприклад, `OPENAI_API_KEY`, `BRAVE_API_KEY`, `FIRECRAWL_API_KEY`). @@ -76,24 +75,24 @@ OpenClaw може отримувати облікові дані з: ## Функції, які можуть витрачати ключі -### 1) Основні відповіді моделі (чат + інструменти) +### 1) Відповіді основної моделі (чат + інструменти) Кожна відповідь або виклик інструмента використовує **поточного провайдера моделі** (OpenAI, Anthropic тощо). Це -основне джерело використання та витрат. +основне джерело використання і витрат. -Сюди також входять розміщені провайдери в стилі підписки, які все одно виставляють рахунки поза +Сюди також входять хостингові провайдери у стилі підписки, які все одно виставляють рахунки поза локальним UI OpenClaw, наприклад **OpenAI Codex**, **Alibaba Cloud Model Studio -Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan** та -шлях входу Claude від Anthropic у OpenClaw з увімкненим **Extra Usage**. +Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan** і +шлях входу Anthropic OpenClaw Claude з увімкненим **Extra Usage**. -Див. [Моделі](/uk/providers/models) для конфігурації цін і [Використання токенів і витрати](/uk/reference/token-use) для відображення. +Див. [Моделі](/uk/providers/models) для конфігурації ціноутворення та [Використання токенів і витрати](/uk/reference/token-use) для відображення. ### 2) Розуміння медіа (аудіо/зображення/відео) Вхідні медіа можуть бути підсумовані/транскрибовані до запуску відповіді. Для цього використовуються API моделей/провайдерів. -- Аудіо: OpenAI / Groq / Deepgram / Google / Mistral. -- Зображення: OpenAI / OpenRouter / Anthropic / Google / MiniMax / Moonshot / Qwen / Z.AI. +- Аудіо: OpenAI / Groq / Deepgram / DeepInfra / Google / Mistral. +- Зображення: OpenAI / OpenRouter / Anthropic / DeepInfra / Google / MiniMax / Moonshot / Qwen / Z.AI. - Відео: Google / Qwen / Moonshot. Див. [Розуміння медіа](/uk/nodes/media-understanding). @@ -102,36 +101,37 @@ Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan** та Спільні можливості генерації також можуть витрачати ключі провайдерів: -- Генерація зображень: OpenAI / Google / fal / MiniMax -- Генерація відео: Qwen +- Генерація зображень: OpenAI / Google / DeepInfra / fal / MiniMax +- Генерація відео: DeepInfra / Qwen -Генерація зображень може визначати типовий провайдер із автентифікацією, якщо +Генерація зображень може визначати стандартний провайдер із підтримкою автентифікації, якщо `agents.defaults.imageGenerationModel` не задано. Генерація відео наразі -потребує явного `agents.defaults.videoGenerationModel`, наприклад +вимагає явного `agents.defaults.videoGenerationModel`, наприклад `qwen/wan2.6-t2v`. Див. [Генерація зображень](/uk/tools/image-generation), [Qwen Cloud](/uk/providers/qwen) -та [Моделі](/uk/concepts/models). +і [Моделі](/uk/concepts/models). ### 4) Ембедінги пам’яті + семантичний пошук -Семантичний пошук у пам’яті використовує **API ембедінгів**, якщо налаштовано віддалені провайдери: +Семантичний пошук у пам’яті використовує **API ембедінгів**, коли налаштовано віддалених провайдерів: - `memorySearch.provider = "openai"` → ембедінги OpenAI - `memorySearch.provider = "gemini"` → ембедінги Gemini - `memorySearch.provider = "voyage"` → ембедінги Voyage - `memorySearch.provider = "mistral"` → ембедінги Mistral -- `memorySearch.provider = "lmstudio"` → ембедінги LM Studio (локально/самостійний хостинг) -- `memorySearch.provider = "ollama"` → ембедінги Ollama (локально/самостійний хостинг; зазвичай без оплати розміщеного API) -- Необов’язковий резервний перехід до віддаленого провайдера, якщо локальні ембедінги не спрацьовують +- `memorySearch.provider = "deepinfra"` → ембедінги DeepInfra +- `memorySearch.provider = "lmstudio"` → ембедінги LM Studio (локально/self-hosted) +- `memorySearch.provider = "ollama"` → ембедінги Ollama (локально/self-hosted; зазвичай без витрат на хостинговий API) +- Необов’язковий резервний перехід на віддаленого провайдера, якщо локальні ембедінги не спрацюють -Ви можете залишити все локально за допомогою `memorySearch.provider = "local"` (без використання API). +Ви можете залишити все локально з `memorySearch.provider = "local"` (без використання API). Див. [Пам’ять](/uk/concepts/memory). ### 5) Інструмент вебпошуку -`web_search` може спричиняти списання за використання залежно від вашого провайдера: +`web_search` може спричиняти витрати на використання залежно від вашого провайдера: - **Brave Search API**: `BRAVE_API_KEY` або `plugins.entries.brave.config.webSearch.apiKey` - **Exa**: `EXA_API_KEY` або `plugins.entries.exa.config.webSearch.apiKey` @@ -140,35 +140,35 @@ Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan** та - **Grok (xAI)**: `XAI_API_KEY` або `plugins.entries.xai.config.webSearch.apiKey` - **Kimi (Moonshot)**: `KIMI_API_KEY`, `MOONSHOT_API_KEY` або `plugins.entries.moonshot.config.webSearch.apiKey` - **MiniMax Search**: `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`, `MINIMAX_API_KEY` або `plugins.entries.minimax.config.webSearch.apiKey` -- **Ollama Web Search**: без ключа для доступного локального хоста Ollama із виконаним входом; прямий пошук через `https://ollama.com` використовує `OLLAMA_API_KEY`, а хости, захищені автентифікацією, можуть повторно використовувати звичайну bearer-автентифікацію провайдера Ollama +- **Ollama Web Search**: без ключа для доступного локального хоста Ollama з виконаним входом; прямий пошук через `https://ollama.com` використовує `OLLAMA_API_KEY`, а хости із захищеною автентифікацією можуть повторно використовувати звичайну bearer-автентифікацію провайдера Ollama - **Perplexity Search API**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY` або `plugins.entries.perplexity.config.webSearch.apiKey` - **Tavily**: `TAVILY_API_KEY` або `plugins.entries.tavily.config.webSearch.apiKey` - **DuckDuckGo**: резервний варіант без ключа (без оплати API, але неофіційний і на основі HTML) -- **SearXNG**: `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl` (без ключа/самостійний хостинг; без оплати розміщеного API) +- **SearXNG**: `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl` (без ключа/self-hosted; без витрат на хостинговий API) -Застарілі шляхи провайдера `tools.web.search.*` усе ще завантажуються через тимчасовий шар сумісності, але це вже не рекомендована поверхня конфігурації. +Застарілі шляхи провайдерів `tools.web.search.*` усе ще завантажуються через тимчасовий шар сумісності, але вони більше не є рекомендованою поверхнею конфігурації. -**Безплатний кредит Brave Search:** Кожен план Brave включає \$5/місяць поновлюваного -безплатного кредиту. План Search коштує \$5 за 1 000 запитів, тож цей кредит покриває +**Безкоштовний кредит Brave Search:** Кожен тариф Brave включає безкоштовний +кредит на \$5/місяць, що поновлюється. Тариф Search коштує \$5 за 1 000 запитів, тож цей кредит покриває 1 000 запитів/місяць без оплати. Установіть свій ліміт використання в панелі керування Brave, -щоб уникнути неочікуваних списань. +щоб уникнути неочікуваних витрат. Див. [Вебінструменти](/uk/tools/web). -### 5) Інструмент отримання вебсторінок (Firecrawl) +### 5) Інструмент web fetch (Firecrawl) -`web_fetch` може викликати **Firecrawl**, якщо присутній API-ключ: +`web_fetch` може викликати **Firecrawl**, якщо наявний API-ключ: - `FIRECRAWL_API_KEY` або `plugins.entries.firecrawl.config.webFetch.apiKey` -Якщо Firecrawl не налаштовано, інструмент використовує резервний варіант — пряме отримання плюс вбудований Plugin `web-readability` (без платного API). Вимкніть `plugins.entries.web-readability.enabled`, щоб пропустити локальне витягування Readability. +Якщо Firecrawl не налаштовано, інструмент переходить до прямого fetch плюс вбудований plugin `web-readability` (без платного API). Вимкніть `plugins.entries.web-readability.enabled`, щоб пропустити локальне витягування Readability. Див. [Вебінструменти](/uk/tools/web). ### 6) Знімки використання провайдера (status/health) -Деякі команди статусу викликають **кінцеві точки використання провайдера**, щоб показувати вікна квот або стан автентифікації. -Зазвичай це виклики з малим обсягом, але вони все одно звертаються до API провайдера: +Деякі команди status викликають **endpoint використання провайдера**, щоб відображати вікна квот або стан автентифікації. +Зазвичай це виклики з невеликим обсягом, але вони все одно звертаються до API провайдера: - `openclaw status --usage` - `openclaw models status --json` @@ -177,21 +177,21 @@ Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan** та ### 7) Підсумовування захисту Compaction -Захист Compaction може підсумовувати історію сеансу за допомогою **поточної моделі**, що -викликає API провайдера під час роботи. +Захист Compaction може підсумовувати історію сесії за допомогою **поточної моделі**, що +викликає API провайдера під час виконання. -Див. [Керування сеансом + Compaction](/uk/reference/session-management-compaction). +Див. [Керування сесіями + Compaction](/uk/reference/session-management-compaction). -### 8) Сканування / перевірка моделі +### 8) Сканування / перевірка моделей -`openclaw models scan` може перевіряти моделі OpenRouter і використовує `OPENROUTER_API_KEY`, коли +`openclaw models scan` може перевіряти моделі OpenRouter і використовує `OPENROUTER_API_KEY`, якщо перевірку ввімкнено. Див. [CLI моделей](/uk/cli/models). ### 9) Talk (мовлення) -Режим Talk може викликати **ElevenLabs**, якщо налаштовано: +Режим Talk може викликати **ElevenLabs**, якщо його налаштовано: - `ELEVENLABS_API_KEY` або `talk.providers.elevenlabs.apiKey` @@ -200,12 +200,12 @@ Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan** та ### 10) Skills (сторонні API) Skills можуть зберігати `apiKey` у `skills.entries..apiKey`. Якщо skill використовує цей ключ для зовнішніх -API, це може спричиняти витрати відповідно до провайдера цього skill. +API, це може спричинити витрати відповідно до провайдера цього skill. Див. [Skills](/uk/tools/skills). ## Пов’язане - [Використання токенів і витрати](/uk/reference/token-use) -- [Кешування запитів](/uk/reference/prompt-caching) +- [Кешування prompt](/uk/reference/prompt-caching) - [Відстеження використання](/uk/concepts/usage-tracking) diff --git a/docs/uk/reference/memory-config.md b/docs/uk/reference/memory-config.md index bed5be3c4..0a9decb95 100644 --- a/docs/uk/reference/memory-config.md +++ b/docs/uk/reference/memory-config.md @@ -1,127 +1,131 @@ --- read_when: - - Ви хочете налаштувати провайдерів пошуку в пам’яті або моделі ембедингів + - Ви хочете налаштувати provider пошуку пам’яті або моделі embedding - Ви хочете налаштувати бекенд QMD - - Ви хочете налаштувати гібридний пошук, MMR або часовий спад - - Ви хочете увімкнути мультимодальну індексацію пам’яті + - Ви хочете налаштувати hybrid search, MMR або temporal decay + - Ви хочете ввімкнути multimodal indexing пам’яті sidebarTitle: Memory config -summary: Усі параметри конфігурації для пошуку в пам’яті, провайдерів ембедингів, QMD, гібридного пошуку та мультимодальної індексації -title: Довідник з конфігурації пам’яті +summary: Усі параметри конфігурації для пошуку пам’яті, provider embedding, QMD, hybrid search і multimodal indexing +title: Довідник конфігурації пам’яті x-i18n: - generated_at: "2026-04-27T23:44:59Z" + generated_at: "2026-04-28T00:35:50Z" model: gpt-5.4 provider: openai - source_hash: c2daa2774b4c8aef5fea8994d9b6cc807b8318f24f1e5c977de5d2cad8aefbc7 + source_hash: ae4993c3b6579be3086997bbd0938e81ce52cfb3b8964674630ab52e59cb1528 source_path: reference/memory-config.md workflow: 15 --- -На цій сторінці перелічено всі параметри конфігурації для пошуку в пам’яті OpenClaw. Для концептуальних оглядів дивіться: +На цій сторінці перелічено всі параметри конфігурації для пошуку пам’яті OpenClaw. Для концептуальних оглядів дивіться: Як працює пам’ять. - Стандартний бекенд SQLite. + Типовий бекенд SQLite. - Локально-орієнтований sidecar. + Локальний sidecar із пріоритетом local-first. - - Конвеєр пошуку та налаштування. + + Конвеєр пошуку й налаштування. - Підагент пам’яті для інтерактивних сеансів. + Субагент пам’яті для інтерактивних сесій. -Усі налаштування пошуку в пам’яті розміщені в `agents.defaults.memorySearch` у `openclaw.json`, якщо не зазначено інше. +Усі налаштування пошуку пам’яті розміщені в `agents.defaults.memorySearch` у `openclaw.json`, якщо не вказано інше. -Якщо ви шукаєте перемикач функції **active memory** і конфігурацію підагента, вони розміщені в `plugins.entries.active-memory`, а не в `memorySearch`. +Якщо ви шукаєте перемикач функції **Active Memory** і конфігурацію субагента, вони розміщені в `plugins.entries.active-memory`, а не в `memorySearch`. -Active Memory використовує двоетапну модель: +Active Memory використовує двоетапну модель перевірки: -1. plugin має бути увімкнений і націлений на поточний ідентифікатор агента -2. запит має бути прийнятним інтерактивним постійним сеансом чату +1. Plugin має бути ввімкнений і націлений на поточний id агента +2. запит має належати до допустимої інтерактивної постійної сесії чату -Дивіться [Active Memory](/uk/concepts/active-memory), щоб дізнатися про модель активації, конфігурацію, якою керує plugin, збереження транскриптів і безпечний шаблон розгортання. +Дивіться [Active Memory](/uk/concepts/active-memory), щоб дізнатися про модель активації, конфігурацію під керуванням Plugin, збереження транскрипту й безпечний шаблон розгортання. --- -## Вибір провайдера +## Вибір provider -| Ключ | Тип | Типове значення | Опис | -| ---------- | --------- | --------------- | ------------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | автоматично визначається | Ідентифікатор адаптера ембедингів: `bedrock`, `gemini`, `github-copilot`, `local`, `mistral`, `ollama`, `openai`, `voyage` | -| `model` | `string` | типове значення провайдера | Назва моделі ембедингів | -| `fallback` | `string` | `"none"` | Ідентифікатор резервного адаптера, якщо основний завершується помилкою | -| `enabled` | `boolean` | `true` | Увімкнути або вимкнути пошук у пам’яті | +| Key | Type | Default | Description | +| ---------- | --------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- | +| `provider` | `string` | auto-detected | ID адаптера embedding: `bedrock`, `deepinfra`, `gemini`, `github-copilot`, `local`, `mistral`, `ollama`, `openai`, `voyage` | +| `model` | `string` | provider default | Назва моделі embedding | +| `fallback` | `string` | `"none"` | ID резервного адаптера, якщо основний завершується помилкою | +| `enabled` | `boolean` | `true` | Увімкнути або вимкнути пошук пам’яті | ### Порядок автовизначення -Коли `provider` не задано, OpenClaw вибирає перший доступний варіант: +Коли `provider` не задано, OpenClaw вибирає перший доступний: Вибирається, якщо налаштовано `memorySearch.local.modelPath` і файл існує. - Вибирається, якщо можна визначити токен GitHub Copilot (змінна середовища або профіль автентифікації). + Вибирається, якщо вдається розв’язати токен GitHub Copilot (змінна середовища або auth profile). - Вибирається, якщо можна визначити ключ OpenAI. + Вибирається, якщо вдається розв’язати ключ OpenAI. - Вибирається, якщо можна визначити ключ Gemini. + Вибирається, якщо вдається розв’язати ключ Gemini. - Вибирається, якщо можна визначити ключ Voyage. + Вибирається, якщо вдається розв’язати ключ Voyage. - Вибирається, якщо можна визначити ключ Mistral. + Вибирається, якщо вдається розв’язати ключ Mistral. + + + Вибирається, якщо вдається розв’язати ключ DeepInfra. - Вибирається, якщо ланцюжок облікових даних AWS SDK успішно визначається (роль екземпляра, ключі доступу, профіль, SSO, web identity або спільна конфігурація). + Вибирається, якщо ланцюг облікових даних AWS SDK успішно розв’язується (роль екземпляра, ключі доступу, profile, SSO, web identity або спільна конфігурація). -`ollama` підтримується, але не визначається автоматично (вкажіть його явно). +`ollama` підтримується, але не визначається автоматично (задайте його явно). -### Визначення API-ключа +### Розв’язання API-ключа -Для віддалених ембедингів потрібен API-ключ. Натомість Bedrock використовує типовий ланцюжок облікових даних AWS SDK (ролі екземпляра, SSO, ключі доступу). +Віддалені embedding потребують API-ключа. Натомість Bedrock використовує типовий ланцюг облікових даних AWS SDK (ролі екземпляра, SSO, ключі доступу). -| Провайдер | Змінна середовища | Ключ конфігурації | -| -------------- | -------------------------------------------------- | -------------------------------- | -| Bedrock | ланцюжок облікових даних AWS | API-ключ не потрібен | -| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` | -| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | Профіль автентифікації через вхід із пристрою | -| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` | -| Ollama | `OLLAMA_API_KEY` (заповнювач) | -- | -| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` | -| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` | +| Provider | Env var | Config key | +| -------------- | -------------------------------------------------- | ----------------------------------- | +| Bedrock | Ланцюг облікових даних AWS | API-ключ не потрібен | +| DeepInfra | `DEEPINFRA_API_KEY` | `models.providers.deepinfra.apiKey` | +| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` | +| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | Auth profile через device login | +| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` | +| Ollama | `OLLAMA_API_KEY` (заповнювач) | -- | +| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` | +| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` | -OAuth Codex покриває лише chat/completions і не задовольняє запити на ембединги. +OAuth Codex покриває лише chat/completions і не задовольняє запити embedding. --- -## Конфігурація віддаленої кінцевої точки +## Конфігурація віддаленої endpoint -Для користувацьких OpenAI-сумісних кінцевих точок або перевизначення типових значень провайдера: +Для користувацьких endpoint, сумісних з OpenAI, або перевизначення типових налаштувань provider: - Користувацька базова URL-адреса API. + Користувацька базова URL API. Перевизначити API-ключ. - Додаткові HTTP-заголовки (об’єднуються з типовими значеннями провайдера). + Додаткові HTTP-заголовки (об’єднуються з типовими значеннями provider). ```json5 @@ -143,28 +147,28 @@ OAuth Codex покриває лише chat/completions і не задоволь --- -## Конфігурація для окремих провайдерів +## Конфігурація для конкретних provider - | Ключ | Тип | Типове значення | Опис | - | ---------------------- | -------- | --------------------- | ------------------------------------------ | + | Key | Type | Default | Description | + | ---------------------- | -------- | ---------------------- | ------------------------------------------ | | `model` | `string` | `gemini-embedding-001` | Також підтримує `gemini-embedding-2-preview` | - | `outputDimensionality` | `number` | `3072` | Для Embedding 2: 768, 1536 або 3072 | + | `outputDimensionality` | `number` | `3072` | Для Embedding 2: 768, 1536 або 3072 | - Зміна моделі або `outputDimensionality` запускає автоматичну повну повторну індексацію. + Зміна `model` або `outputDimensionality` запускає автоматичну повну переіндексацію. - - OpenAI-сумісні кінцеві точки ембедингів можуть використовувати специфічні для провайдера поля запиту `input_type`. Це корисно для асиметричних моделей ембедингів, які вимагають різних міток для ембедингів запитів і документів. + + Endpoint embedding, сумісні з OpenAI, можуть використовувати специфічні для provider поля запиту `input_type`. Це корисно для асиметричних моделей embedding, які потребують різних міток для embedding запиту та документа. - | Ключ | Тип | Типове значення | Опис | - | ------------------- | -------- | --------------- | ----------------------------------------------------- | - | `inputType` | `string` | не задано | Спільний `input_type` для ембедингів запитів і документів | - | `queryInputType` | `string` | не задано | `input_type` під час запиту; перевизначає `inputType` | - | `documentInputType` | `string` | не задано | `input_type` для індексу/документа; перевизначає `inputType` | + | Key | Type | Default | Description | + | ------------------- | -------- | ------- | ------------------------------------------------------- | + | `inputType` | `string` | unset | Спільний `input_type` для embedding запиту й документа | + | `queryInputType` | `string` | unset | `input_type` під час запиту; перевизначає `inputType` | + | `documentInputType` | `string` | unset | `input_type` для індексу/документа; перевизначає `inputType` | ```json5 { @@ -185,11 +189,11 @@ OAuth Codex покриває лише chat/completions і не задоволь } ``` - Зміна цих значень впливає на ідентичність кешу ембедингів для пакетної індексації провайдера, і після цього слід виконати повторну індексацію пам’яті, якщо висхідна модель по-різному обробляє ці мітки. + Зміна цих значень впливає на ідентичність кешу embedding для пакетної індексації provider, і після цього слід виконати переіндексацію пам’яті, якщо висхідна модель по-різному обробляє ці мітки. - Bedrock використовує типовий ланцюжок облікових даних AWS SDK — API-ключі не потрібні. Якщо OpenClaw працює на EC2 з роллю екземпляра, для якої ввімкнено Bedrock, достатньо просто вказати провайдера та модель: + Bedrock використовує типовий ланцюг облікових даних AWS SDK — API-ключі не потрібні. Якщо OpenClaw працює на EC2 із роллю екземпляра, для якої ввімкнено Bedrock, просто задайте provider і model: ```json5 { @@ -204,29 +208,29 @@ OAuth Codex покриває лише chat/completions і не задоволь } ``` - | Ключ | Тип | Типове значення | Опис | - | ---------------------- | -------- | ----------------------------- | ----------------------------- | - | `model` | `string` | `amazon.titan-embed-text-v2:0` | Будь-який ідентифікатор моделі ембедингів Bedrock | - | `outputDimensionality` | `number` | типове значення моделі | Для Titan V2: 256, 512 або 1024 | + | Key | Type | Default | Description | + | ---------------------- | -------- | ------------------------------ | ------------------------------- | + | `model` | `string` | `amazon.titan-embed-text-v2:0` | Будь-який ID моделі embedding Bedrock | + | `outputDimensionality` | `number` | model default | Для Titan V2: 256, 512 або 1024 | - **Підтримувані моделі** (з визначенням сімейства та типовими розмірностями): + **Підтримувані моделі** (з визначенням сімейства й типовими вимірами): - | Model ID | Провайдер | Типові розмірності | Налаштовувані розмірності | - | ------------------------------------------ | ---------- | ------------------ | ------------------------- | - | `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 | - | `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | - | `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | - | `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | - | `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 | - | `cohere.embed-english-v3` | Cohere | 1024 | -- | - | `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | - | `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 | - | `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | - | `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | + | Model ID | Provider | Default Dims | Configurable Dims | + | ------------------------------------------ | ---------- | ------------ | -------------------- | + | `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256, 512, 1024 | + | `amazon.titan-embed-text-v1` | Amazon | 1536 | -- | + | `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- | + | `amazon.titan-embed-image-v1` | Amazon | 1024 | -- | + | `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256, 384, 1024, 3072 | + | `cohere.embed-english-v3` | Cohere | 1024 | -- | + | `cohere.embed-multilingual-v3` | Cohere | 1024 | -- | + | `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 | + | `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- | + | `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- | Варіанти з суфіксом пропускної здатності (наприклад, `amazon.titan-embed-text-v1:2:8k`) успадковують конфігурацію базової моделі. - **Автентифікація:** автентифікація Bedrock використовує стандартний порядок визначення облікових даних AWS SDK: + **Автентифікація:** автентифікація Bedrock використовує стандартний порядок розв’язання облікових даних AWS SDK: 1. Змінні середовища (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`) 2. Кеш токенів SSO @@ -234,9 +238,9 @@ OAuth Codex покриває лише chat/completions і не задоволь 4. Спільні файли облікових даних і конфігурації 5. Облікові дані метаданих ECS або EC2 - Регіон визначається з `AWS_REGION`, `AWS_DEFAULT_REGION`, `baseUrl` провайдера `amazon-bedrock` або за замовчуванням використовується `us-east-1`. + Регіон розв’язується з `AWS_REGION`, `AWS_DEFAULT_REGION`, `baseUrl` provider `amazon-bedrock` або типово дорівнює `us-east-1`. - **Дозволи IAM:** роль IAM або користувач повинні мати: + **Дозволи IAM:** роль або користувач IAM повинні мати: ```json { @@ -246,69 +250,69 @@ OAuth Codex покриває лише chat/completions і не задоволь } ``` - Для принципу найменших привілеїв обмежте `InvokeModel` конкретною моделлю: + Для принципу мінімально необхідних привілеїв обмежте `InvokeModel` конкретною моделлю: ``` arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0 ``` - - | Ключ | Тип | Типове значення | Опис | - | --------------------- | ------------------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `local.modelPath` | `string` | автоматично завантажується | Шлях до файлу моделі GGUF | - | `local.modelCacheDir` | `string` | типове значення node-llama-cpp | Каталог кешу для завантажених моделей | - | `local.contextSize` | `number \| "auto"` | `4096` | Розмір вікна контексту для контексту ембедингів. 4096 покриває типові фрагменти (128–512 токенів), водночас обмежуючи VRAM, не пов’язану з вагами. На обмежених хостах зменшуйте до 1024–2048. `"auto"` використовує натренований максимум моделі — не рекомендовано для моделей 8B+ (Qwen3-Embedding-8B: 40 960 токенів → ~32 ГБ VRAM проти ~8.8 ГБ при 4096). | + + | Key | Type | Default | Description | + | --------------------- | ------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `local.modelPath` | `string` | auto-downloaded | Шлях до файла моделі GGUF | + | `local.modelCacheDir` | `string` | node-llama-cpp default | Каталог кешу для завантажених моделей | + | `local.contextSize` | `number \| "auto"` | `4096` | Розмір контекстного вікна для контексту embedding. 4096 покриває типові chunk-и (128–512 токенів), водночас обмежуючи VRAM, не пов’язану з вагами. На обмежених хостах зменшуйте до 1024–2048. `"auto"` використовує максимальне значення, на якому навчено модель — не рекомендується для моделей 8B+ (Qwen3-Embedding-8B: 40 960 токенів → ~32 GB VRAM проти ~8.8 GB при 4096). | - Типова модель: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 ГБ, завантажується автоматично). Потрібна нативна збірка: `pnpm approve-builds`, а потім `pnpm rebuild node-llama-cpp`. + Типова модель: `embeddinggemma-300m-qat-Q8_0.gguf` (~0.6 GB, завантажується автоматично). Потребує нативної збірки: `pnpm approve-builds`, потім `pnpm rebuild node-llama-cpp`. - Використовуйте окремий CLI, щоб перевірити той самий шлях провайдера, який використовує Gateway: + Використовуйте окремий CLI, щоб перевірити той самий шлях provider, який використовує Gateway: ```bash openclaw memory status --deep --agent main openclaw memory index --force --agent main ``` - Якщо `provider` має значення `auto`, `local` вибирається лише тоді, коли `local.modelPath` вказує на наявний локальний файл. Посилання на моделі `hf:` і HTTP(S) усе ще можна використовувати явно з `provider: "local"`, але вони не змушують `auto` вибрати local, доки модель не стане доступною на диску. + Якщо `provider` має значення `auto`, `local` вибирається лише тоді, коли `local.modelPath` вказує на наявний локальний файл. Посилання на моделі `hf:` і HTTP(S) усе ще можна явно використовувати з `provider: "local"`, але вони не змушують `auto` вибирати local до того, як модель стане доступною на диску. -### Тайм-аут вбудованих ембедингів +### Тайм-аут inline embedding - Перевизначити тайм-аут для вбудованих пакетів ембедингів під час індексації пам’яті. + Перевизначає тайм-аут для inline batch embedding під час індексації пам’яті. -Якщо значення не задано, використовується типове значення провайдера: 600 секунд для локальних/самостійно розміщених провайдерів, таких як `local`, `ollama` і `lmstudio`, та 120 секунд для хостингових провайдерів. Збільшіть це значення, якщо локальні CPU-обмежені пакети ембедингів працюють коректно, але повільно. +Якщо не задано, використовується типове значення provider: 600 секунд для локальних/self-hosted provider, таких як `local`, `ollama` і `lmstudio`, і 120 секунд для хостованих provider. Збільшуйте це значення, коли локальні batch embedding, обмежені CPU, працюють коректно, але повільно. --- -## Конфігурація гібридного пошуку +## Конфігурація hybrid search -Усе знаходиться в `memorySearch.query.hybrid`: +Усе розміщено в `memorySearch.query.hybrid`: -| Ключ | Тип | Типове значення | Опис | -| --------------------- | --------- | --------------- | ----------------------------------- | -| `enabled` | `boolean` | `true` | Увімкнути гібридний пошук BM25 + векторний пошук | -| `vectorWeight` | `number` | `0.7` | Вага для векторних оцінок (0-1) | -| `textWeight` | `number` | `0.3` | Вага для оцінок BM25 (0-1) | -| `candidateMultiplier` | `number` | `4` | Множник розміру пулу кандидатів | +| Key | Type | Default | Description | +| --------------------- | --------- | ------- | ---------------------------------- | +| `enabled` | `boolean` | `true` | Увімкнути hybrid search BM25 + vector | +| `vectorWeight` | `number` | `0.7` | Вага для оцінок vector (0-1) | +| `textWeight` | `number` | `0.3` | Вага для оцінок BM25 (0-1) | +| `candidateMultiplier` | `number` | `4` | Множник розміру пулу кандидатів | - - | Ключ | Тип | Типове значення | Опис | - | ------------- | --------- | --------------- | ---------------------------------------- | - | `mmr.enabled` | `boolean` | `false` | Увімкнути повторне ранжування MMR | - | `mmr.lambda` | `number` | `0.7` | 0 = максимальна різноманітність, 1 = максимальна релевантність | + + | Key | Type | Default | Description | + | ------------- | --------- | ------- | ------------------------------------ | + | `mmr.enabled` | `boolean` | `false` | Увімкнути повторне ранжування MMR | + | `mmr.lambda` | `number` | `0.7` | 0 = максимальна різноманітність, 1 = максимальна релевантність | - - | Ключ | Тип | Типове значення | Опис | - | ---------------------------- | --------- | --------------- | ----------------------------- | - | `temporalDecay.enabled` | `boolean` | `false` | Увімкнути буст за актуальністю | - | `temporalDecay.halfLifeDays` | `number` | `30` | Оцінка зменшується вдвічі кожні N днів | + + | Key | Type | Default | Description | + | ---------------------------- | --------- | ------- | ------------------------- | + | `temporalDecay.enabled` | `boolean` | `false` | Увімкнути буст нещодавності | + | `temporalDecay.halfLifeDays` | `number` | `30` | Оцінка зменшується вдвічі кожні N днів | - Для evergreen-файлів (`MEMORY.md`, файлів без дати в `memory/`) спад ніколи не застосовується. + Evergreen-файли (`MEMORY.md`, файли без дати в `memory/`) ніколи не піддаються згасанню. @@ -338,8 +342,8 @@ OAuth Codex покриває лише chat/completions і не задоволь ## Додаткові шляхи пам’яті -| Ключ | Тип | Опис | -| ----------- | ---------- | -------------------------------------- | +| Key | Type | Description | +| ------------ | ---------- | ---------------------------------------- | | `extraPaths` | `string[]` | Додаткові каталоги або файли для індексації | ```json5 @@ -354,21 +358,21 @@ OAuth Codex покриває лише chat/completions і не задоволь } ``` -Шляхи можуть бути абсолютними або відносними до робочого простору. Каталоги скануються рекурсивно на наявність файлів `.md`. Обробка символьних посилань залежить від активного бекенда: вбудований рушій ігнорує символьні посилання, тоді як QMD дотримується поведінки базового сканера QMD. +Шляхи можуть бути абсолютними або відносними до workspace. Каталоги скануються рекурсивно на наявність файлів `.md`. Обробка symlink залежить від активного бекенду: вбудований рушій ігнорує symlink, тоді як QMD дотримується поведінки базового сканера QMD. -Для пошуку транскриптів між агентами в межах агента використовуйте `agents.list[].memorySearch.qmd.extraCollections` замість `memory.qmd.paths`. Ці додаткові колекції мають ту саму форму `{ path, name, pattern? }`, але об’єднуються для кожного агента й можуть зберігати явно задані спільні назви, коли шлях вказує за межі поточного робочого простору. Якщо той самий визначений шлях з’являється і в `memory.qmd.paths`, і в `memorySearch.qmd.extraCollections`, QMD зберігає перший запис і пропускає дублікат. +Для пошуку transcript між агентами в межах agent-scoped використовуйте `agents.list[].memorySearch.qmd.extraCollections` замість `memory.qmd.paths`. Ці додаткові collection мають ту саму форму `{ path, name, pattern? }`, але об’єднуються для кожного агента окремо й можуть зберігати явні спільні назви, коли шлях указує за межі поточного workspace. Якщо той самий розв’язаний шлях з’являється і в `memory.qmd.paths`, і в `memorySearch.qmd.extraCollections`, QMD зберігає перший запис і пропускає дублікат. --- -## Мультимодальна пам’ять (Gemini) +## Multimodal memory (Gemini) Індексуйте зображення й аудіо разом із Markdown за допомогою Gemini Embedding 2: -| Ключ | Тип | Типове значення | Опис | -| ------------------------- | ---------- | --------------- | ----------------------------------- | -| `multimodal.enabled` | `boolean` | `false` | Увімкнути мультимодальну індексацію | -| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` або `["all"]` | -| `multimodal.maxFileBytes` | `number` | `10000000` | Максимальний розмір файлу для індексації | +| Key | Type | Default | Description | +| ------------------------- | ---------- | ---------- | -------------------------------------- | +| `multimodal.enabled` | `boolean` | `false` | Увімкнути multimodal indexing | +| `multimodal.modalities` | `string[]` | -- | `["image"]`, `["audio"]` або `["all"]` | +| `multimodal.maxFileBytes` | `number` | `10000000` | Максимальний розмір файла для індексації | Застосовується лише до файлів у `extraPaths`. Типові корені пам’яті залишаються лише для Markdown. Потрібен `gemini-embedding-2-preview`. `fallback` має бути `"none"`. @@ -378,118 +382,118 @@ OAuth Codex покриває лише chat/completions і не задоволь --- -## Кеш ембедингів +## Кеш embedding -| Ключ | Тип | Типове значення | Опис | -| ------------------ | --------- | --------------- | -------------------------------- | -| `cache.enabled` | `boolean` | `false` | Кешувати ембединги фрагментів у SQLite | -| `cache.maxEntries` | `number` | `50000` | Максимальна кількість кешованих ембедингів | +| Key | Type | Default | Description | +| ------------------ | --------- | ------- | -------------------------------- | +| `cache.enabled` | `boolean` | `false` | Кешувати embedding chunk-ів у SQLite | +| `cache.maxEntries` | `number` | `50000` | Максимальна кількість кешованих embedding | -Запобігає повторному створенню ембедингів для незмінного тексту під час повторної індексації або оновлень транскриптів. +Запобігає повторному embedding незміненого тексту під час переіндексації або оновлення transcript. --- ## Пакетна індексація -| Ключ | Тип | Типове значення | Опис | -| ----------------------------- | --------- | --------------- | ------------------------- | -| `remote.nonBatchConcurrency` | `number` | `4` | Паралельні вбудовані ембединги | -| `remote.batch.enabled` | `boolean` | `false` | Увімкнути API пакетних ембедингів | -| `remote.batch.concurrency` | `number` | `2` | Паралельні пакетні завдання | -| `remote.batch.wait` | `boolean` | `true` | Чекати завершення пакета | -| `remote.batch.pollIntervalMs` | `number` | -- | Інтервал опитування | -| `remote.batch.timeoutMinutes` | `number` | -- | Тайм-аут пакета | +| Key | Type | Default | Description | +| ----------------------------- | --------- | ------- | -------------------------- | +| `remote.nonBatchConcurrency` | `number` | `4` | Паралельні inline embedding | +| `remote.batch.enabled` | `boolean` | `false` | Увімкнути API пакетного embedding | +| `remote.batch.concurrency` | `number` | `2` | Паралельні пакетні завдання | +| `remote.batch.wait` | `boolean` | `true` | Чекати завершення пакета | +| `remote.batch.pollIntervalMs` | `number` | -- | Інтервал опитування | +| `remote.batch.timeoutMinutes` | `number` | -- | Тайм-аут пакета | -Доступно для `openai`, `gemini` і `voyage`. Пакетний режим OpenAI зазвичай є найшвидшим і найдешевшим для великих зворотних заповнень. +Доступно для `openai`, `gemini` і `voyage`. Пакетний режим OpenAI зазвичай є найшвидшим і найдешевшим для великих backfill. -`remote.nonBatchConcurrency` керує вбудованими викликами ембедингів, які використовуються локальними/самостійно розміщеними провайдерами та хостинговими провайдерами, коли пакетні API провайдера не активні. Для непакетної індексації Ollama типово використовує `1`, щоб не перевантажувати менші локальні хости; на потужніших машинах встановіть вище значення. +`remote.nonBatchConcurrency` керує inline-викликами embedding, які використовують локальні/self-hosted provider і хостовані provider, коли пакетні API provider не активні. Для Ollama типове значення для non-batch indexing — `1`, щоб не перевантажувати менші локальні хости; на потужніших машинах установіть більше значення. -Це окремо від `sync.embeddingBatchTimeoutSeconds`, який керує тайм-аутом для вбудованих викликів ембедингів. +Це окремо від `sync.embeddingBatchTimeoutSeconds`, який керує тайм-аутом для inline-викликів embedding. --- -## Пошук у пам’яті сеансів (експериментально) +## Пошук пам’яті сесії (експериментально) -Індексуйте транскрипти сеансів і показуйте їх через `memory_search`: +Індексуйте transcript сесії та показуйте їх через `memory_search`: -| Ключ | Тип | Типове значення | Опис | -| ----------------------------- | ---------- | --------------- | -------------------------------------- | -| `experimental.sessionMemory` | `boolean` | `false` | Увімкнути індексацію сеансів | -| `sources` | `string[]` | `["memory"]` | Додайте `"sessions"`, щоб включити транскрипти | -| `sync.sessions.deltaBytes` | `number` | `100000` | Поріг байтів для повторної індексації | -| `sync.sessions.deltaMessages` | `number` | `50` | Поріг повідомлень для повторної індексації | +| Key | Type | Default | Description | +| ----------------------------- | ---------- | ------------ | --------------------------------------- | +| `experimental.sessionMemory` | `boolean` | `false` | Увімкнути індексацію сесій | +| `sources` | `string[]` | `["memory"]` | Додайте `"sessions"`, щоб включити transcript | +| `sync.sessions.deltaBytes` | `number` | `100000` | Поріг байтів для переіндексації | +| `sync.sessions.deltaMessages` | `number` | `50` | Поріг повідомлень для переіндексації | -Індексація сеансів є опціональною та виконується асинхронно. Результати можуть бути трохи застарілими. Журнали сеансів зберігаються на диску, тому вважайте доступ до файлової системи межею довіри. +Індексація сесій є opt-in і виконується асинхронно. Результати можуть бути трохи застарілими. Журнали сесій зберігаються на диску, тому вважайте доступ до файлової системи межею довіри. --- ## Прискорення векторів SQLite (sqlite-vec) -| Ключ | Тип | Типове значення | Опис | -| ---------------------------- | --------- | --------------- | ------------------------------- | -| `store.vector.enabled` | `boolean` | `true` | Використовувати sqlite-vec для векторних запитів | -| `store.vector.extensionPath` | `string` | вбудовано | Перевизначити шлях до sqlite-vec | +| Key | Type | Default | Description | +| ---------------------------- | --------- | ------- | --------------------------------- | +| `store.vector.enabled` | `boolean` | `true` | Використовувати sqlite-vec для векторних запитів | +| `store.vector.extensionPath` | `string` | bundled | Перевизначити шлях до sqlite-vec | -Коли sqlite-vec недоступний, OpenClaw автоматично переходить на косинусну схожість у процесі. +Коли sqlite-vec недоступний, OpenClaw автоматично повертається до in-process cosine similarity. --- -## Сховище індексу +## Зберігання індексу -| Ключ | Тип | Типове значення | Опис | -| ------------------- | -------- | ------------------------------------ | ----------------------------------------- | -| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Розташування індексу (підтримує токен `{agentId}`) | -| `store.fts.tokenizer` | `string` | `unicode61` | Токенізатор FTS5 (`unicode61` або `trigram`) | +| Key | Type | Default | Description | +| --------------------- | -------- | ------------------------------------- | ------------------------------------------- | +| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | Розташування індексу (підтримує токен `{agentId}`) | +| `store.fts.tokenizer` | `string` | `unicode61` | Токенізатор FTS5 (`unicode61` або `trigram`) | --- -## Конфігурація бекенда QMD +## Конфігурація бекенду QMD Установіть `memory.backend = "qmd"`, щоб увімкнути його. Усі налаштування QMD розміщені в `memory.qmd`: -| Ключ | Тип | Типове значення | Опис | -| ------------------------ | --------- | --------------- | ------------------------------------------------------------------------------------ | -| `command` | `string` | `qmd` | Шлях до виконуваного файла QMD; вкажіть абсолютний шлях, якщо `PATH` сервісу відрізняється від вашої оболонки | -| `searchMode` | `string` | `search` | Команда пошуку: `search`, `vsearch`, `query` | -| `includeDefaultMemory` | `boolean` | `true` | Автоматично індексувати `MEMORY.md` + `memory/**/*.md` | -| `paths[]` | `array` | -- | Додаткові шляхи: `{ name, path, pattern? }` | -| `sessions.enabled` | `boolean` | `false` | Індексувати транскрипти сеансів | -| `sessions.retentionDays` | `number` | -- | Термін зберігання транскриптів | -| `sessions.exportDir` | `string` | -- | Каталог експорту | +| Key | Type | Default | Description | +| ------------------------ | --------- | -------- | ------------------------------------------------------------------------------------- | +| `command` | `string` | `qmd` | Шлях до виконуваного файла QMD; установіть абсолютний шлях, якщо `PATH` сервісу відрізняється від вашої оболонки | +| `searchMode` | `string` | `search` | Команда пошуку: `search`, `vsearch`, `query` | +| `includeDefaultMemory` | `boolean` | `true` | Автоматично індексувати `MEMORY.md` + `memory/**/*.md` | +| `paths[]` | `array` | -- | Додаткові шляхи: `{ name, path, pattern? }` | +| `sessions.enabled` | `boolean` | `false` | Індексувати transcript сесій | +| `sessions.retentionDays` | `number` | -- | Термін зберігання transcript | +| `sessions.exportDir` | `string` | -- | Каталог експорту | -`searchMode: "search"` є лише лексичним/BM25-режимом. Для цього режиму OpenClaw не виконує перевірки готовності семантичних векторів або обслуговування ембедингів QMD, зокрема під час `memory status --deep`; для `vsearch` і `query`, як і раніше, потрібні готовність векторів QMD та ембединги. +`searchMode: "search"` — це лише лексичний/BM25-режим. OpenClaw не виконує перевірки готовності семантичного vector-пошуку або обслуговування embedding QMD для цього режиму, зокрема під час `memory status --deep`; режими `vsearch` і `query`, як і раніше, потребують готовності vector у QMD та embedding. -OpenClaw надає перевагу актуальним формам колекцій QMD і запитів MCP, але зберігає сумісність зі старішими випусками QMD, за потреби намагаючись використовувати сумісні прапорці шаблонів колекцій і старіші назви інструментів MCP. Коли QMD повідомляє про підтримку кількох фільтрів колекцій, колекції з тим самим джерелом шукаються одним процесом QMD; старіші збірки QMD зберігають сумісний шлях із поодинокою колекцією. Те саме джерело означає, що довготривалі колекції пам’яті групуються разом, тоді як колекції транскриптів сеансів залишаються окремою групою, щоб диверсифікація джерел і далі мала обидва входи. +OpenClaw надає перевагу актуальним формам collection і MCP query у QMD, але зберігає працездатність зі старішими випусками QMD, за потреби пробуючи сумісні прапорці шаблонів collection і старіші назви інструментів MCP. Коли QMD повідомляє про підтримку кількох фільтрів collection, collection з одного source шукаються одним процесом QMD; старіші збірки QMD зберігають сумісний шлях із обробкою по одній collection. Same-source означає, що collection довготривалої пам’яті групуються разом, тоді як collection transcript сесій залишаються окремою групою, щоб диверсифікація джерел усе ще мала обидва входи. -Перевизначення моделей QMD залишаються на боці QMD, а не в конфігурації OpenClaw. Якщо вам потрібно глобально перевизначити моделі QMD, установіть змінні середовища, такі як `QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` і `QMD_GENERATE_MODEL`, у середовищі виконання Gateway. +Перевизначення моделей QMD залишаються на боці QMD, а не в конфігурації OpenClaw. Якщо вам потрібно глобально перевизначити моделі QMD, установіть змінні середовища, такі як `QMD_EMBED_MODEL`, `QMD_RERANK_MODEL` і `QMD_GENERATE_MODEL`, у runtime-середовищі Gateway. - | Ключ | Тип | Типове значення | Опис | - | ------------------------- | --------- | --------------- | ------------------------------------ | - | `update.interval` | `string` | `5m` | Інтервал оновлення | - | `update.debounceMs` | `number` | `15000` | Затримка згладжування змін файлів | - | `update.onBoot` | `boolean` | `true` | Оновлювати під час запуску | - | `update.waitForBootSync` | `boolean` | `false` | Блокувати запуск до завершення оновлення | - | `update.embedInterval` | `string` | -- | Окрема частота ембедингів | - | `update.commandTimeoutMs` | `number` | -- | Тайм-аут для команд QMD | - | `update.updateTimeoutMs` | `number` | -- | Тайм-аут для операцій оновлення QMD | - | `update.embedTimeoutMs` | `number` | -- | Тайм-аут для операцій ембедингів QMD | + | Key | Type | Default | Description | + | ------------------------- | --------- | ------- | ------------------------------------- | + | `update.interval` | `string` | `5m` | Інтервал оновлення | + | `update.debounceMs` | `number` | `15000` | Debounce змін файлів | + | `update.onBoot` | `boolean` | `true` | Оновлювати під час запуску | + | `update.waitForBootSync` | `boolean` | `false` | Блокувати запуск до завершення оновлення | + | `update.embedInterval` | `string` | -- | Окрема частота для embedding | + | `update.commandTimeoutMs` | `number` | -- | Тайм-аут для команд QMD | + | `update.updateTimeoutMs` | `number` | -- | Тайм-аут для операцій оновлення QMD | + | `update.embedTimeoutMs` | `number` | -- | Тайм-аут для операцій embedding QMD | - - | Ключ | Тип | Типове значення | Опис | - | ------------------------- | -------- | --------------- | ---------------------------- | - | `limits.maxResults` | `number` | `6` | Максимальна кількість результатів пошуку | - | `limits.maxSnippetChars` | `number` | -- | Обмеження довжини фрагмента | - | `limits.maxInjectedChars` | `number` | -- | Обмеження загальної кількості вставлених символів | - | `limits.timeoutMs` | `number` | `4000` | Тайм-аут пошуку | + + | Key | Type | Default | Description | + | ------------------------- | -------- | ------- | -------------------------- | + | `limits.maxResults` | `number` | `6` | Максимум результатів пошуку | + | `limits.maxSnippetChars` | `number` | -- | Обмежити довжину snippet | + | `limits.maxInjectedChars` | `number` | -- | Обмежити загальну кількість injected chars | + | `limits.timeoutMs` | `number` | `4000` | Тайм-аут пошуку | - Керує тим, які сеанси можуть отримувати результати пошуку QMD. Та сама схема, що й у [`session.sendPolicy`](/uk/gateway/config-agents#session): + Керує тим, які сесії можуть отримувати результати пошуку QMD. Та сама схема, що й у [`session.sendPolicy`](/uk/gateway/config-agents#session): ```json5 { @@ -504,19 +508,19 @@ OpenClaw надає перевагу актуальним формам коле } ``` - Типова конфігурація в постачанні дозволяє прямі сеанси та сеанси каналів, водночас і далі забороняючи групи. + Типова конфігурація в поставці дозволяє direct- і channel-сесії, але все одно забороняє групи. - Типове значення — лише DM. `match.keyPrefix` відповідає нормалізованому ключу сеансу; `match.rawKeyPrefix` відповідає сирому ключу, включно з `agent::`. + Типове значення — лише DM. `match.keyPrefix` відповідає нормалізованому ключу сесії; `match.rawKeyPrefix` відповідає сирому ключу, включно з `agent::`. `memory.citations` застосовується до всіх бекендів: - | Значення | Поведінка | + | Value | Behavior | | ---------------- | --------------------------------------------------- | - | `auto` (типово) | Додавати нижній колонтитул `Source: ` у фрагменти | + | `auto` (типово) | Додавати нижній колонтитул `Source: ` у snippet | | `on` | Завжди додавати нижній колонтитул | - | `off` | Пропускати нижній колонтитул (шлях усе одно внутрішньо передається агенту) | + | `off` | Не додавати нижній колонтитул (шлях усе одно внутрішньо передається агенту) | @@ -548,17 +552,17 @@ OpenClaw надає перевагу актуальним формам коле Dreaming налаштовується в `plugins.entries.memory-core.config.dreaming`, а не в `agents.defaults.memorySearch`. -Dreaming працює як один запланований прохід і використовує внутрішні фази light/deep/REM як деталь реалізації. +Dreaming працює як один запланований цикл і використовує внутрішні фази light/deep/REM як деталь реалізації. -Щоб дізнатися про концептуальну поведінку та slash-команди, дивіться [Dreaming](/uk/concepts/dreaming). +Для опису концептуальної поведінки та slash-команд дивіться [Dreaming](/uk/concepts/dreaming). ### Налаштування користувача -| Ключ | Тип | Типове значення | Опис | -| ---------- | --------- | --------------- | --------------------------------------------------- | -| `enabled` | `boolean` | `false` | Повністю увімкнути або вимкнути Dreaming | -| `frequency` | `string` | `0 3 * * *` | Необов’язкова Cron-частота для повного проходу Dreaming | -| `model` | `string` | типова модель | Необов’язкове перевизначення моделі підагента Dream Diary | +| Key | Type | Default | Description | +| ----------- | --------- | ------------- | ------------------------------------------------- | +| `enabled` | `boolean` | `false` | Повністю ввімкнути або вимкнути Dreaming | +| `frequency` | `string` | `0 3 * * *` | Необов’язкова частота Cron для повного циклу Dreaming | +| `model` | `string` | default model | Необов’язкове перевизначення моделі субагента Dream Diary | ### Приклад @@ -587,12 +591,12 @@ Dreaming працює як один запланований прохід і в - Dreaming записує машинний стан у `memory/.dreams/`. - Dreaming записує зрозумілий людині наративний вивід у `DREAMS.md` (або наявний `dreams.md`). -- `dreaming.model` використовує наявний trust gate підагента plugin; перед увімкненням установіть `plugins.entries.memory-core.subagent.allowModelOverride: true`. -- Політика фаз light/deep/REM і пороги є внутрішньою поведінкою, а не користувацькою конфігурацією. +- `dreaming.model` використовує наявний trust gate субагента Plugin; перед його ввімкненням установіть `plugins.entries.memory-core.subagent.allowModelOverride: true`. +- Політика фаз light/deep/REM і порогові значення є внутрішньою поведінкою, а не користувацькою конфігурацією. ## Пов’язане -- [Довідник із конфігурації](/uk/gateway/configuration-reference) +- [Довідник конфігурації](/uk/gateway/configuration-reference) - [Огляд пам’яті](/uk/concepts/memory) -- [Пошук у пам’яті](/uk/concepts/memory-search) +- [Пошук пам’яті](/uk/concepts/memory-search) diff --git a/docs/uk/reference/test.md b/docs/uk/reference/test.md index 9921b1b81..d1ebaedb8 100644 --- a/docs/uk/reference/test.md +++ b/docs/uk/reference/test.md @@ -4,52 +4,52 @@ read_when: summary: Як запускати тести локально (vitest) і коли використовувати режими force/coverage title: Тести x-i18n: - generated_at: "2026-04-27T12:55:28Z" + generated_at: "2026-04-28T00:35:54Z" model: gpt-5.4 provider: openai - source_hash: 3e7fa9987f47d4953a32c3d9e29ca23d90a7ef459e36386a90e0cd0f90c99c96 + source_hash: 9b32904204717ae35dda88d74eba225c173fecbe6230209b066795419857cdee source_path: reference/test.md workflow: 15 --- -- Повний набір для тестування (набори, live, Docker): [Тестування](/uk/help/testing) +- Повний набір для тестування (набори, live, Docker): [Testing](/uk/help/testing) -- `pnpm test:force`: завершує будь-який завислий процес gateway, що утримує типовий control port, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб серверні тести не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив зайнятим порт 18789. -- `pnpm test:coverage`: запускає набір unit-тестів із V8 coverage (через `vitest.unit.config.ts`). Це coverage gate для unit-тестів завантажених файлів, а не all-file coverage для всього репозиторію. Пороги становлять 70% для lines/functions/statements і 55% для branches. Оскільки `coverage.all` має значення false, gate вимірює файли, завантажені набором unit coverage, замість того щоб вважати всі вихідні файли split-lane непокритими. +- `pnpm test:force`: завершує будь-який завислий процес gateway, який утримує типовий control port, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб серверні тести не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив порт 18789 зайнятим. +- `pnpm test:coverage`: запускає набір unit-тестів з V8 coverage (через `vitest.unit.config.ts`). Це перевірка unit coverage для завантажених файлів, а не coverage всіх файлів у всьому репозиторії. Порогові значення: 70% для lines/functions/statements і 55% для branches. Оскільки `coverage.all` має значення false, перевірка вимірює файли, завантажені набором unit coverage, замість того, щоб вважати всі файли вихідного коду в розділених lanes непокритими. - `pnpm test:coverage:changed`: запускає unit coverage лише для файлів, змінених відносно `origin/main`. -- `pnpm test:changed`: дешевий розумний запуск змінених тестів. Він запускає точні цілі на основі прямих змін тестів, сусідніх файлів `*.test.ts`, явних зіставлень вихідних файлів і локального графа імпортів. Широкі зміни конфігурації/пакетів пропускаються, якщо вони не зіставляються з точними тестами. -- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: явний широкий запуск змінених тестів. Використовуйте його, коли редагування test harness/config/package має повертатися до ширшої поведінки змінених тестів Vitest. -- `pnpm changed:lanes`: показує архітектурні lanes, які запускаються через diff відносно `origin/main`. -- `pnpm check:changed`: запускає розумний gate перевірки змін для diff відносно `origin/main`. Він виконує typecheck, lint і guard-команди для порушених архітектурних lanes, але не запускає тести Vitest. Для доказу тестів використовуйте `pnpm test:changed` або явний `pnpm test `. -- `pnpm test`: спрямовує явні цілі файлів/каталогів через scoped lanes Vitest. Запуски без цілей використовують фіксовані shard-групи й розгортаються до leaf configs для локального паралельного виконання; група extension завжди розгортається до shard-конфігів для кожного extension замість одного гігантського root-project процесу. -- Запуски обгортки тестів завершуються коротким підсумком `[test] passed|failed|skipped ... in ...`. Власний рядок тривалості Vitest залишається деталізацією для кожного shard. -- Повні, extension і shard-запуски за шаблоном include оновлюють локальні дані таймінгу в `.artifacts/vitest-shard-timings.json`; подальші запуски всіх конфігурацій використовують ці таймінги для балансування повільних і швидких shard. Include-pattern CI shards додають ім’я shard до ключа таймінгу, що зберігає видимість відфільтрованих таймінгів shard без заміни даних таймінгу всієї конфігурації. Установіть `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт таймінгу. -- Вибрані тестові файли `plugin-sdk` і `commands` тепер спрямовуються через окремі легкі lanes, які зберігають лише `test/setup.ts`, залишаючи ресурсоємні runtime-випадки у наявних lanes. -- Вихідні файли із сусідніми тестами спочатку зіставляються з цим сусіднім тестом, а вже потім переходять до ширших glob-шаблонів каталогу. Редагування допоміжних файлів у `test/helpers/channels` і `test/helpers/plugins` використовують локальний граф імпортів для запуску тестів-імпортерів замість широкого запуску кожного shard, коли шлях залежності є точним. -- `auto-reply` тепер також розбито на три окремі конфіги (`core`, `top-level`, `reply`), тож harness відповідей більше не домінує над легшими тестами верхнього рівня для status/token/helper. -- Базова конфігурація Vitest тепер за замовчуванням використовує `pool: "threads"` і `isolate: false`, а спільний неізольований runner увімкнено в конфігах по всьому репозиторію. +- `pnpm test:changed`: дешева розумна перевірка changed test run. Вона запускає точні цілі на основі прямих змін у тестах, сусідніх файлів `*.test.ts`, явних зіставлень вихідного коду та локального import graph. Широкі зміни config/package пропускаються, якщо вони не зіставляються з точними тестами. +- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: явний широкий changed test run. Використовуйте його, коли зміна test harness/config/package має повернутися до ширшої поведінки changed-test у Vitest. +- `pnpm changed:lanes`: показує архітектурні lanes, запущені diff відносно `origin/main`. +- `pnpm check:changed`: запускає розумну перевірку changed check gate для diff відносно `origin/main`. Вона запускає typecheck, lint і guard-команди для заторкнутих архітектурних lanes, але не запускає тести Vitest. Для доказу тестами використовуйте `pnpm test:changed` або явний `pnpm test `. +- `pnpm test`: маршрутизує явні цілі файлів/каталогів через scoped Vitest lanes. Нетаргетовані запуски використовують фіксовані shard groups і розгортаються до leaf configs для локального паралельного виконання; група extension завжди розгортається до shard configs для кожного extension, а не в один гігантський процес root-project. +- Запуски test wrapper завершуються коротким підсумком `[test] passed|failed|skipped ... in ...`. Власний рядок тривалості Vitest залишається деталізацією для кожного shard. +- Повні, extension і include-pattern shard-запуски оновлюють локальні дані часу в `.artifacts/vitest-shard-timings.json`; пізніші whole-config запуски використовують ці дані часу для балансування повільних і швидких shards. Include-pattern CI shards додають ім’я shard до ключа часу, що зберігає видимість timings відфільтрованих shards без заміни даних часу whole-config. Задайте `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт timings. +- Вибрані тестові файли `plugin-sdk` і `commands` тепер маршрутизуються через окремі легкі lanes, які зберігають лише `test/setup.ts`, залишаючи важкі runtime-випадки на наявних lanes. +- Вихідні файли із сусідніми тестами зіставляються із цим сусіднім тестом перед переходом до ширших glob-шаблонів каталогу. Зміни helper у `test/helpers/channels`, `src/plugin-sdk/test-helpers` і `src/plugins/contracts` використовують локальний import graph, щоб запускати тести, які їх імпортують, замість широкого запуску кожного shard, коли шлях залежності є точним. +- `auto-reply` тепер також розділено на три окремі configs (`core`, `top-level`, `reply`), щоб harness reply не домінував над легшими тестами top-level status/token/helper. +- Базова конфігурація Vitest тепер типово використовує `pool: "threads"` і `isolate: false`, із ввімкненим спільним non-isolated runner у всіх configs репозиторію. - `pnpm test:channels` запускає `vitest.channels.config.ts`. -- `pnpm test:extensions` і `pnpm test extensions` запускають усі shard для extension/plugin. Важкі channel plugins, browser plugin і OpenAI запускаються як окремі shards; інші групи плагінів залишаються пакетованими. Використовуйте `pnpm test extensions/` для одного lane вбудованого плагіна. -- `pnpm test:perf:imports`: вмикає звітування Vitest про тривалість імпорту й розбивку імпортів, водночас і далі використовує scoped lane routing для явних цілей файлів/каталогів. -- `pnpm test:perf:imports:changed`: те саме профілювання імпортів, але лише для файлів, змінених відносно `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований шлях changed-mode із нативним запуском root-project для того самого закоміченого git diff. -- `pnpm test:perf:changed:bench -- --worktree` порівнює поточний набір змін worktree без попереднього коміту. +- `pnpm test:extensions` і `pnpm test extensions` запускають усі shards extension/plugin. Важкі channel plugins, browser plugin і OpenAI працюють як окремі shards; інші групи plugin залишаються згрупованими. Використовуйте `pnpm test extensions/` для одного lane вбудованого plugin. +- `pnpm test:perf:imports`: вмикає звітування Vitest про import-duration + import-breakdown, водночас використовуючи маршрутизацію scoped lanes для явних цілей файлів/каталогів. +- `pnpm test:perf:imports:changed`: той самий профайлінг import, але лише для файлів, змінених відносно `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` виконує benchmark маршрутизованого changed-mode шляху проти нативного запуску root-project для того самого закоміченого git diff. +- `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного набору змін worktree без попереднього коміту. - `pnpm test:perf:profile:main`: записує CPU profile для головного потоку Vitest (`.artifacts/vitest-main-profile`). - `pnpm test:perf:profile:runner`: записує CPU + heap profiles для unit runner (`.artifacts/vitest-runner-profile`). -- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожен leaf config Vitest із повного набору та записує згруповані дані тривалості разом з JSON/log-артефактами для кожної конфігурації. Агент Test Performance використовує це як базову лінію перед спробами виправити повільні тести. -- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: порівнює згруповані звіти після змін, спрямованих на продуктивність. -- Інтеграція Gateway: увімкнення за запитом через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`. -- `pnpm test:e2e`: запускає smoke-тести gateway end-to-end (multi-instance WS/HTTP/node pairing). За замовчуванням використовує `threads` + `isolate: false` з адаптивною кількістю workers у `vitest.e2e.config.ts`; налаштовуйте через `OPENCLAW_E2E_WORKERS=` і встановлюйте `OPENCLAW_E2E_VERBOSE=1` для докладних логів. -- `pnpm test:live`: запускає live-тести провайдерів (minimax/zai). Потребує API-ключів і `LIVE=1` (або специфічного для провайдера `*_LIVE_TEST=1`), щоб зняти пропуск. -- `pnpm test:docker:all`: збирає спільний live-test image, один раз пакує OpenClaw як npm tarball, збирає/повторно використовує bare Node/Git runner image плюс functional image, який установлює цей tarball у `/app`, а потім запускає Docker smoke lanes з `OPENCLAW_SKIP_DOCKER_BUILD=1` через weighted scheduler. Bare image (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) використовується для lanes встановлення/оновлення/залежностей плагінів; ці lanes монтують попередньо зібраний tarball замість використання скопійованих вихідних кодів репозиторію. Functional image (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) використовується для звичайних lanes функціональності зібраного застосунку. `scripts/package-openclaw-for-docker.mjs` — єдиний локальний/CI пакувальник пакетів, який перевіряє tarball і `dist/postinstall-inventory.json`, перш ніж Docker почне їх використовувати. Визначення Docker lanes живуть у `scripts/lib/docker-e2e-scenarios.mjs`; логіка планувальника — у `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. `node scripts/test-docker-all.mjs --plan-json` виводить CI-план, що належить планувальнику, для вибраних lanes, типів образів, потреб package/live-image і перевірок облікових даних без побудови чи запуску Docker. `OPENCLAW_DOCKER_ALL_PARALLELISM=` керує кількістю слотів процесів і за замовчуванням дорівнює 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=` керує tail pool, чутливим до провайдерів, і за замовчуванням також дорівнює 10. Обмеження важких lanes за замовчуванням: `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; обмеження провайдерів за замовчуванням — один важкий lane на провайдера через `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` і `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Використовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` для потужніших хостів. Якщо один lane перевищує ефективне обмеження ваги чи ресурсів на хості з низьким паралелізмом, він усе одно може стартувати з порожнього pool і працюватиме самостійно, доки не звільнить ресурси. Запуски lanes за замовчуванням розводяться на 2 секунди, щоб уникнути локальних штормів створення в Docker daemon; перевизначайте через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=`. Runner за замовчуванням виконує попередню перевірку Docker, очищає застарілі контейнери OpenClaw E2E, виводить статус активних lanes кожні 30 секунд, ділить кеші CLI tool провайдерів між сумісними lanes, за замовчуванням один раз повторює тимчасові збої live-провайдерів (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=`) і зберігає таймінги lanes у `.artifacts/docker-tests/lane-timings.json` для впорядкування «найдовші спочатку» у наступних запусках. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб вивести маніфест lanes без запуску Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=` для налаштування виводу статусу або `OPENCLAW_DOCKER_ALL_TIMINGS=0`, щоб вимкнути повторне використання таймінгів. Використовуйте `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` для лише детермінованих/локальних lanes або `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` для лише lanes live-провайдерів; псевдоніми пакетів: `pnpm test:docker:local:all` і `pnpm test:docker:live:all`. Режим лише live об’єднує основні й tail live lanes в один pool з порядком «найдовші спочатку», щоб кошики провайдерів могли спільно пакувати завдання Claude, Codex і Gemini. Runner припиняє планувати нові pooled lanes після першого збою, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, а кожен lane має резервний тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; вибрані live/tail lanes мають жорсткіші обмеження на рівні lane. Команди налаштування Docker для CLI backend мають власний тайм-аут через `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (типово 180). Логи для кожного lane, `summary.json`, `failures.json` і таймінги фаз записуються в `.artifacts/docker-tests//`; використовуйте `pnpm test:docker:timings `, щоб переглянути повільні lanes, і `pnpm test:docker:rerun `, щоб вивести дешеві цільові команди повторного запуску. -- `pnpm test:docker:browser-cdp-snapshot`: збирає E2E-контейнер джерела на базі Chromium, запускає raw CDP плюс ізольований Gateway, виконує `browser doctor --deep` і перевіряє, що CDP role snapshots містять URL посилань, clickables, підняті курсором, iframe refs і метадані frame. -- Live Docker probes для CLI backend можна запускати як цільові lanes, наприклад `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume` або `pnpm test:docker:live-cli-backend:codex:mcp`. Claude і Gemini мають відповідні псевдоніми `:resume` і `:mcp`. -- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, входить через Open WebUI, перевіряє `/api/models`, а потім виконує справжній проксійований чат через `/api/chat/completions`. Потребує придатного ключа live-моделі (наприклад, OpenAI у `~/.profile`), завантажує зовнішній образ Open WebUI і не очікується, що він буде таким стабільним у CI, як звичайні unit/e2e набори. -- `pnpm test:docker:mcp-channels`: запускає seeded контейнер Gateway і другий контейнер клієнта, який стартує `openclaw mcp serve`, а потім перевіряє routed discovery розмов, читання transcript, metadata вкладень, поведінку черги live events, маршрутизацію outbound send і сповіщення про канал + дозволи в стилі Claude через справжній міст stdio. Перевірка сповіщень Claude читає raw stdio MCP frames безпосередньо, щоб smoke відображав те, що міст реально виводить. +- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожен leaf config повного набору Vitest і записує згруповані дані тривалості плюс JSON/log-артефакти для кожного config. Агент продуктивності тестів використовує це як baseline перед спробами виправити повільні тести. +- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: порівнює згруповані звіти після зміни, орієнтованої на продуктивність. +- Інтеграція gateway: opt-in через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`. +- `pnpm test:e2e`: запускає smoke-тести end-to-end для gateway (multi-instance WS/HTTP/node pairing). Типово використовує `threads` + `isolate: false` з адаптивними workers у `vitest.e2e.config.ts`; налаштовуйте через `OPENCLAW_E2E_WORKERS=` і задайте `OPENCLAW_E2E_VERBOSE=1` для докладних логів. +- `pnpm test:live`: запускає live-тести постачальників (minimax/zai). Потрібні API-ключі та `LIVE=1` (або специфічний для постачальника `*_LIVE_TEST=1`), щоб прибрати пропуск. +- `pnpm test:docker:all`: збирає спільний образ live-test, один раз пакує OpenClaw як npm tarball, збирає/повторно використовує базовий образ runner на Node/Git плюс функціональний образ, який встановлює цей tarball у `/app`, а потім запускає Docker smoke lanes з `OPENCLAW_SKIP_DOCKER_BUILD=1` через зважений планувальник. Базовий образ (`OPENCLAW_DOCKER_E2E_BARE_IMAGE`) використовується для lanes installer/update/plugin-dependency; ці lanes монтують попередньо зібраний tarball замість використання скопійованих вихідних кодів репозиторію. Функціональний образ (`OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`) використовується для звичайних lanes функціональності зібраного застосунку. `scripts/package-openclaw-for-docker.mjs` — це єдиний локальний/CI packer пакета, який перевіряє tarball і `dist/postinstall-inventory.json` перед тим, як Docker його використає. Визначення Docker lanes містяться в `scripts/lib/docker-e2e-scenarios.mjs`; логіка planner — у `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. `node scripts/test-docker-all.mjs --plan-json` виводить CI-план, яким володіє scheduler, для вибраних lanes, типів образів, потреб package/live-image і перевірок облікових даних без збирання чи запуску Docker. `OPENCLAW_DOCKER_ALL_PARALLELISM=` керує слотами процесів і типово дорівнює 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=` керує pool для чутливого до постачальників tail і типово також дорівнює 10. Обмеження для важких lanes типово: `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; обмеження постачальників типово — один важкий lane на постачальника через `OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4` і `OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4`. Для більших хостів використовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`. Якщо один lane перевищує ефективне обмеження ваги або ресурсів на хості з низьким паралелізмом, він усе одно може стартувати з порожнього pool і працюватиме самостійно, доки не звільнить ресурси. Старт lanes типово розноситься на 2 секунди, щоб уникнути локальних штормів створення Docker daemon; перевизначте це через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=`. Runner типово виконує preflight Docker, очищає застарілі контейнери OpenClaw E2E, кожні 30 секунд виводить статус активних lanes, спільно використовує кеші CLI-інструментів постачальників між сумісними lanes, один раз за замовчуванням повторює транзитні збої live-постачальників (`OPENCLAW_DOCKER_ALL_LIVE_RETRIES=`) і зберігає timings lanes у `.artifacts/docker-tests/lane-timings.json` для порядку longest-first у наступних запусках. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб надрукувати маніфест lanes без запуску Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=` для налаштування виводу статусу або `OPENCLAW_DOCKER_ALL_TIMINGS=0`, щоб вимкнути повторне використання timings. Використовуйте `OPENCLAW_DOCKER_ALL_LIVE_MODE=skip` для лише детермінованих/локальних lanes або `OPENCLAW_DOCKER_ALL_LIVE_MODE=only` лише для lanes live-постачальників; package-аліаси: `pnpm test:docker:local:all` і `pnpm test:docker:live:all`. Режим лише live об’єднує main і tail live lanes в один pool longest-first, щоб кошики постачальників могли разом упаковувати роботу Claude, Codex і Gemini. Runner припиняє планувати нові pooled lanes після першої помилки, якщо не задано `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, і кожен lane має резервний timeout 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; окремі live/tail lanes використовують жорсткіші обмеження для кожного lane. Команди налаштування Docker для CLI backend мають окремий timeout через `OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS` (типово 180). Логи для кожного lane, `summary.json`, `failures.json` і timings фаз записуються в `.artifacts/docker-tests//`; використовуйте `pnpm test:docker:timings `, щоб переглянути повільні lanes, і `pnpm test:docker:rerun `, щоб вивести дешеві таргетовані команди повторного запуску. +- `pnpm test:docker:browser-cdp-snapshot`: збирає вихідний E2E-контейнер із Chromium, запускає сирий CDP плюс ізольований Gateway, виконує `browser doctor --deep` і перевіряє, що role snapshots CDP містять URL-адреси посилань, clickables, підняті курсором, iframe refs і метадані frame. +- Live Docker probes для CLI backend можна запускати як сфокусовані lanes, наприклад `pnpm test:docker:live-cli-backend:codex`, `pnpm test:docker:live-cli-backend:codex:resume` або `pnpm test:docker:live-cli-backend:codex:mcp`. Claude і Gemini мають відповідні аліаси `:resume` і `:mcp`. +- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, виконує вхід через Open WebUI, перевіряє `/api/models`, а потім виконує справжній проксований chat через `/api/chat/completions`. Потребує придатного live-ключа моделі (наприклад, OpenAI у `~/.profile`), завантажує зовнішній образ Open WebUI і не очікується як CI-stable на відміну від звичайних unit/e2e наборів. +- `pnpm test:docker:mcp-channels`: запускає ініціалізований контейнер Gateway і другий контейнер клієнта, який стартує `openclaw mcp serve`, а потім перевіряє виявлення маршрутованих розмов, читання transcript, метадані вкладень, поведінку live event queue, маршрутизацію вихідного надсилання та сповіщення про channel + permissions у стилі Claude через справжній міст stdio. Перевірка сповіщень Claude читає сирі stdio MCP frames безпосередньо, щоб smoke відображав те, що міст реально надсилає. ## Локальний PR gate -Для локальних перевірок land/gate PR запускайте: +Для локальних перевірок перед land/gate PR виконайте: - `pnpm check:changed` - `pnpm check` @@ -58,12 +58,12 @@ x-i18n: - `pnpm test` - `pnpm check:docs` -Якщо `pnpm test` нестабільно працює на завантаженому хості, повторіть запуск один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test `. Для хостів з обмеженою пам’яттю використовуйте: +Якщо `pnpm test` флейкиться на завантаженому хості, перезапустіть один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test `. Для хостів з обмеженою пам’яттю використовуйте: - `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test` - `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed` -## Бенч затримки моделі (локальні ключі) +## Model latency bench (локальні ключі) Скрипт: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts) @@ -78,7 +78,7 @@ x-i18n: - minimax median 1279ms (min 1114, max 2431) - opus median 2454ms (min 1224, max 3170) -## Бенч запуску CLI +## CLI startup bench Скрипт: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts) @@ -100,47 +100,47 @@ x-i18n: - `pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu` - `pnpm tsx scripts/bench-cli-startup.ts --json` -Набори: +Набори preset: - `startup`: `--version`, `--help`, `health`, `health --json`, `status --json`, `status` - `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `tasks --json`, `tasks list --json`, `tasks audit --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port` -- `all`: обидва набори +- `all`: обидва набори preset -Вивід містить `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і підсумки max RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують профілі V8 для кожного запуску, тож вимірювання часу й захоплення профілів використовують один і той самий harness. +Вивід містить `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і підсумки max RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують профілі V8 для кожного запуску, тож вимірювання часу й захоплення профілів використовують той самий harness. -Умовні позначення збереженого виводу: +Умовні позначення для збереженого виводу: -- `pnpm test:startup:bench:smoke` записує цільовий smoke-артефакт у `.artifacts/cli-startup-bench-smoke.json` -- `pnpm test:startup:bench:save` записує артефакт повного набору в `.artifacts/cli-startup-bench-all.json`, використовуючи `runs=5` і `warmup=1` -- `pnpm test:startup:bench:update` оновлює закомічений baseline fixture у `test/fixtures/cli-startup-bench.json`, використовуючи `runs=5` і `warmup=1` +- `pnpm test:startup:bench:smoke` записує таргетований smoke-артефакт у `.artifacts/cli-startup-bench-smoke.json` +- `pnpm test:startup:bench:save` записує артефакт повного набору в `.artifacts/cli-startup-bench-all.json` з `runs=5` і `warmup=1` +- `pnpm test:startup:bench:update` оновлює закомічений baseline fixture у `test/fixtures/cli-startup-bench.json` з `runs=5` і `warmup=1` Закомічений fixture: - `test/fixtures/cli-startup-bench.json` -- Оновлюйте через `pnpm test:startup:bench:update` -- Порівнюйте поточні результати з fixture через `pnpm test:startup:bench:check` +- Оновлення через `pnpm test:startup:bench:update` +- Порівняння поточних результатів із fixture через `pnpm test:startup:bench:check` ## Onboarding E2E (Docker) -Docker необов’язковий; це потрібно лише для containerized smoke-тестів onboarding. +Docker необов’язковий; це потрібно лише для containerized smoke-тестів онбордингу. -Повний cold-start flow у чистому Linux-контейнері: +Повний cold-start потік у чистому Linux-контейнері: ```bash scripts/e2e/onboard-docker.sh ``` -Цей скрипт проводить інтерактивний wizard через pseudo-tty, перевіряє файли config/workspace/session, потім запускає gateway і виконує `openclaw health`. +Цей скрипт керує інтерактивним майстром через pseudo-tty, перевіряє файли config/workspace/session, потім запускає gateway і виконує `openclaw health`. -## QR import smoke (Docker) +## Smoke-тест імпорту QR (Docker) -Гарантує, що підтримуваний допоміжний засіб runtime QR завантажується в підтримуваних Docker Node runtimes (Node 24 за замовчуванням, Node 22 сумісний): +Гарантує, що підтримуваний helper середовища виконання QR завантажується в підтримуваних середовищах виконання Docker Node (типово Node 24, сумісно з Node 22): ```bash pnpm test:docker:qr ``` -## Пов’язано +## Пов’язане -- [Тестування](/uk/help/testing) -- [Live-тестування](/uk/help/testing-live) +- [Testing](/uk/help/testing) +- [Testing live](/uk/help/testing-live) diff --git a/docs/uk/tools/image-generation.md b/docs/uk/tools/image-generation.md index e0f878f83..6b08d78fc 100644 --- a/docs/uk/tools/image-generation.md +++ b/docs/uk/tools/image-generation.md @@ -4,30 +4,36 @@ read_when: - Налаштування провайдерів і моделей для генерації зображень - Розуміння параметрів інструмента image_generate sidebarTitle: Image generation -summary: Генеруйте та редагуйте зображення через image_generate у OpenAI, Google, fal, MiniMax, ComfyUI, OpenRouter, LiteLLM, xAI, Vydra +summary: Генеруйте та редагуйте зображення через image_generate у OpenAI, Google, fal, MiniMax, ComfyUI, DeepInfra, OpenRouter, LiteLLM, xAI, Vydra title: Генерація зображень x-i18n: - generated_at: "2026-04-26T05:36:22Z" + generated_at: "2026-04-28T00:36:04Z" model: gpt-5.4 provider: openai - source_hash: c57d32667eed3d6449628f6f663359ece089233ed0fde5258e2b2e4713192758 + source_hash: 2237ad82279d8daf28d70a550727a5900d7a820a0c9ba09de8b7bae5b6575401 source_path: tools/image-generation.md workflow: 15 --- -Інструмент `image_generate` дає агенту змогу створювати та редагувати зображення за допомогою налаштованих вами провайдерів. Згенеровані зображення автоматично доставляються як медіавкладення у відповіді агента. +Інструмент `image_generate` дає агенту змогу створювати та редагувати зображення за допомогою +налаштованих провайдерів. Згенеровані зображення автоматично доставляються як +медіавкладення у відповіді агента. -Інструмент з’являється, лише якщо доступний принаймні один провайдер генерації зображень. Якщо ви не бачите `image_generate` серед інструментів вашого агента, налаштуйте `agents.defaults.imageGenerationModel`, встановіть API-ключ провайдера або увійдіть через OpenAI Codex OAuth. +Інструмент з’являється лише тоді, коли доступний принаймні один провайдер +генерації зображень. Якщо ви не бачите `image_generate` серед інструментів +вашого агента, налаштуйте `agents.defaults.imageGenerationModel`, задайте API-ключ провайдера +або увійдіть за допомогою OpenAI Codex OAuth. ## Швидкий старт - - Встановіть API-ключ принаймні для одного провайдера (наприклад, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`) або увійдіть через OpenAI Codex OAuth. + + Задайте API-ключ принаймні для одного провайдера (наприклад `OPENAI_API_KEY`, + `GEMINI_API_KEY`, `OPENROUTER_API_KEY`) або увійдіть за допомогою OpenAI Codex OAuth. - + ```json5 { agents: { @@ -41,49 +47,66 @@ x-i18n: } ``` - Codex OAuth використовує те саме посилання на модель `openai/gpt-image-2`. Коли налаштовано OAuth-профіль `openai-codex`, OpenClaw спрямовує запити на зображення через цей OAuth-профіль замість того, щоб спочатку намагатися використати `OPENAI_API_KEY`. Явна конфігурація `models.providers.openai` (API-ключ, власний/Azure base URL) знову вмикає маршрут прямого OpenAI Images API. + Codex OAuth використовує те саме посилання на модель `openai/gpt-image-2`. Коли + налаштовано профіль OAuth `openai-codex`, OpenClaw маршрутизує запити + на зображення через цей профіль OAuth замість того, щоб спочатку пробувати + `OPENAI_API_KEY`. Явна конфігурація `models.providers.openai` (API-ключ, + власний/Azure base URL) знову перемикає на прямий маршрут OpenAI Images API. - + _"Згенеруй зображення дружнього робота-маскота."_ - Агент автоматично викликає `image_generate`. Дозвільний список інструментів не потрібен — інструмент увімкнено за замовчуванням, коли провайдер доступний. + Агент автоматично викликає `image_generate`. Жодного allow-listing інструментів + не потрібно — його ввімкнено типово, коли доступний провайдер. -Для сумісних з OpenAI LAN-ендпоінтів, таких як LocalAI, зберігайте власний `models.providers.openai.baseUrl` і явно вмикайте `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`. Приватні та внутрішні ендпоінти зображень за замовчуванням залишаються заблокованими. +Для сумісних з OpenAI LAN-ендпойнтів, таких як LocalAI, зберігайте власний +`models.providers.openai.baseUrl` і явно вмикайте його через +`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`. Приватні та +внутрішні ендпойнти зображень типово залишаються заблокованими. -## Поширені маршрути +## Типові маршрути -| Ціль | Посилання на модель | Автентифікація | -| ---------------------------------------------------- | ------------------------------------------------- | ------------------------------------- | -| Генерація зображень OpenAI з API-оплатою | `openai/gpt-image-2` | `OPENAI_API_KEY` | -| Генерація зображень OpenAI з автентифікацією через підписку Codex | `openai/gpt-image-2` | OpenAI Codex OAuth | -| OpenAI PNG/WebP із прозорим фоном | `openai/gpt-image-1.5` | `OPENAI_API_KEY` або OpenAI Codex OAuth | -| Генерація зображень через OpenRouter | `openrouter/google/gemini-3.1-flash-image-preview` | `OPENROUTER_API_KEY` | -| Генерація зображень через LiteLLM | `litellm/gpt-image-2` | `LITELLM_API_KEY` | -| Генерація зображень Google Gemini | `google/gemini-3.1-flash-image-preview` | `GEMINI_API_KEY` або `GOOGLE_API_KEY` | +| Ціль | Посилання на модель | Auth | +| ---------------------------------------------------- | --------------------------------------------------- | -------------------------------------- | +| Генерація зображень OpenAI з оплатою через API | `openai/gpt-image-2` | `OPENAI_API_KEY` | +| Генерація зображень OpenAI з auth через підписку Codex | `openai/gpt-image-2` | OpenAI Codex OAuth | +| OpenAI PNG/WebP з прозорим фоном | `openai/gpt-image-1.5` | `OPENAI_API_KEY` або OpenAI Codex OAuth | +| Генерація зображень DeepInfra | `deepinfra/black-forest-labs/FLUX-1-schnell` | `DEEPINFRA_API_KEY` | +| Генерація зображень OpenRouter | `openrouter/google/gemini-3.1-flash-image-preview` | `OPENROUTER_API_KEY` | +| Генерація зображень LiteLLM | `litellm/gpt-image-2` | `LITELLM_API_KEY` | +| Генерація зображень Google Gemini | `google/gemini-3.1-flash-image-preview` | `GEMINI_API_KEY` або `GOOGLE_API_KEY` | -Той самий інструмент `image_generate` обробляє як генерацію з тексту, так і редагування за опорним зображенням. Використовуйте `image` для одного опорного зображення або `images` для кількох опорних зображень. Підтримувані провайдером підказки для виводу, такі як `quality`, `outputFormat` і `background`, передаються далі, коли це доступно, і позначаються як проігноровані, якщо провайдер їх не підтримує. Вбудована підтримка прозорого фону є специфічною для OpenAI; інші провайдери все одно можуть зберігати PNG alpha, якщо їхній бекенд її повертає. +Той самий інструмент `image_generate` обробляє як генерацію за текстом, так і +редагування за референсним зображенням. Використовуйте `image` для одного референсу +або `images` для кількох референсів. +Підказки щодо виводу, які підтримує провайдер, як-от `quality`, `outputFormat` і +`background`, пересилаються, коли це можливо, і позначаються як проігноровані, +коли провайдер їх не підтримує. Вбудована підтримка прозорого фону +є специфічною для OpenAI; інші провайдери все ж можуть зберігати PNG alpha, якщо +їхній backend це видає. ## Підтримувані провайдери -| Провайдер | Модель за замовчуванням | Підтримка редагування | Автентифікація | -| ---------- | -------------------------------------- | ---------------------------------- | ---------------------------------------------------- | -| ComfyUI | `workflow` | Так (1 зображення, налаштовується workflow) | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для хмари | -| fal | `fal-ai/flux/dev` | Так | `FAL_KEY` | -| Google | `gemini-3.1-flash-image-preview` | Так | `GEMINI_API_KEY` або `GOOGLE_API_KEY` | -| LiteLLM | `gpt-image-2` | Так (до 5 вхідних зображень) | `LITELLM_API_KEY` | -| MiniMax | `image-01` | Так (опорне зображення об’єкта) | `MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`) | -| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` або OpenAI Codex OAuth | -| OpenRouter | `google/gemini-3.1-flash-image-preview` | Так (до 5 вхідних зображень) | `OPENROUTER_API_KEY` | -| Vydra | `grok-imagine` | Ні | `VYDRA_API_KEY` | -| xAI | `grok-imagine-image` | Так (до 5 зображень) | `XAI_API_KEY` | +| Провайдер | Типова модель | Підтримка редагування | Auth | +| ---------- | -------------------------------------- | ---------------------------------- | ----------------------------------------------------- | +| ComfyUI | `workflow` | Так (1 зображення, налаштовується workflow) | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для хмари | +| DeepInfra | `black-forest-labs/FLUX-1-schnell` | Так (1 зображення) | `DEEPINFRA_API_KEY` | +| fal | `fal-ai/flux/dev` | Так | `FAL_KEY` | +| Google | `gemini-3.1-flash-image-preview` | Так | `GEMINI_API_KEY` або `GOOGLE_API_KEY` | +| LiteLLM | `gpt-image-2` | Так (до 5 вхідних зображень) | `LITELLM_API_KEY` | +| MiniMax | `image-01` | Так (референс об’єкта) | `MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`) | +| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` або OpenAI Codex OAuth | +| OpenRouter | `google/gemini-3.1-flash-image-preview`| Так (до 5 вхідних зображень) | `OPENROUTER_API_KEY` | +| Vydra | `grok-imagine` | Ні | `VYDRA_API_KEY` | +| xAI | `grok-imagine-image` | Так (до 5 зображень) | `XAI_API_KEY` | -Використовуйте `action: "list"`, щоб переглянути доступні провайдери та моделі під час виконання: +Використовуйте `action: "list"`, щоб переглянути доступні провайдери та моделі під час runtime: ```text /tool image_generate action=list @@ -91,30 +114,31 @@ x-i18n: ## Можливості провайдерів -| Можливість | ComfyUI | fal | Google | MiniMax | OpenAI | Vydra | xAI | -| -------------------- | -------------------- | ----------------- | -------------- | ----------------------- | -------------- | ----- | -------------- | -| Генерація (макс. кількість) | Визначається workflow | 4 | 4 | 9 | 4 | 1 | 4 | -| Редагування / опорне зображення | 1 зображення (workflow) | 1 зображення | До 5 зображень | 1 зображення (опорне зображення об’єкта) | До 5 зображень | — | До 5 зображень | -| Керування розміром | — | ✓ | ✓ | — | До 4K | — | — | -| Співвідношення сторін | — | ✓ (лише генерація) | ✓ | ✓ | — | — | ✓ | -| Роздільна здатність (1K/2K/4K) | — | ✓ | ✓ | — | — | — | 1K, 2K | +| Можливість | ComfyUI | DeepInfra | fal | Google | MiniMax | OpenAI | Vydra | xAI | +| -------------------- | ------------------ | --------- | ----------------- | -------------- | --------------------- | -------------- | ----- | -------------- | +| Генерація (макс. кількість) | Визначається workflow | 4 | 4 | 4 | 9 | 4 | 1 | 4 | +| Редагування / референс | 1 зображення (workflow) | 1 зображення | 1 зображення | До 5 зображень | 1 зображення (референс об’єкта) | До 5 зображень | — | До 5 зображень | +| Керування розміром | — | ✓ | ✓ | ✓ | — | До 4K | — | — | +| Співвідношення сторін | — | — | ✓ (лише генерація) | ✓ | ✓ | — | — | ✓ | +| Роздільність (1K/2K/4K) | — | — | ✓ | ✓ | — | — | — | 1K, 2K | ## Параметри інструмента - Запит для генерації зображення. Обов’язковий для `action: "generate"`. + Prompt для генерації зображення. Обов’язковий для `action: "generate"`. - Використовуйте `"list"`, щоб переглянути доступні провайдери та моделі під час виконання. + Використовуйте `"list"`, щоб переглянути доступні провайдери та моделі під час runtime. - Перевизначення провайдера/моделі (наприклад, `openai/gpt-image-2`). Використовуйте `openai/gpt-image-1.5` для прозорих фонів в OpenAI. + Перевизначення провайдера/моделі (наприклад `openai/gpt-image-2`). Використовуйте + `openai/gpt-image-1.5` для прозорих фонів в OpenAI. - Шлях або URL одного опорного зображення для режиму редагування. + Шлях або URL одного референсного зображення для режиму редагування. - Кілька опорних зображень для режиму редагування (до 5 у провайдерів, які це підтримують). + Кілька референсних зображень для режиму редагування (до 5 у провайдерів, які це підтримують). Підказка щодо розміру: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160`. @@ -122,25 +146,32 @@ x-i18n: Співвідношення сторін: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`. -Підказка щодо роздільної здатності. +Підказка щодо роздільності. - Підказка щодо якості, якщо провайдер її підтримує. + Підказка щодо якості, якщо провайдер це підтримує. - Підказка щодо формату виводу, якщо провайдер її підтримує. + Підказка щодо формату виводу, якщо провайдер це підтримує. - Підказка щодо фону, якщо провайдер її підтримує. Використовуйте `transparent` з `outputFormat: "png"` або `"webp"` для провайдерів, що підтримують прозорість. + Підказка щодо фону, якщо провайдер це підтримує. Використовуйте `transparent` з + `outputFormat: "png"` або `"webp"` для провайдерів, які підтримують прозорість. Кількість зображень для генерації (1–4). -Необов’язковий таймаут запиту до провайдера в мілісекундах. +Необов’язковий тайм-аут запиту до провайдера в мілісекундах. Підказка щодо імені вихідного файла. Підказки лише для OpenAI: `background`, `moderation`, `outputCompression` і `user`. -Не всі провайдери підтримують усі параметри. Коли резервний провайдер підтримує близький варіант геометрії замість точно запитаного, OpenClaw перед відправленням зіставляє запитаний розмір, співвідношення сторін або роздільну здатність із найближчим підтримуваним варіантом. Непідтримувані підказки виводу відкидаються для провайдерів, які не оголошують їх підтримку, і відображаються в результаті інструмента. Результати інструмента повідомляють про застосовані параметри; `details.normalization` фіксує будь-яке перетворення із запитаного значення в застосоване. +Не всі провайдери підтримують усі параметри. Коли резервний провайдер підтримує +близький варіант геометрії замість точно запитаного, OpenClaw зіставляє його +з найближчим підтримуваним розміром, співвідношенням сторін або роздільністю перед відправленням. +Непідтримувані підказки виводу відкидаються для провайдерів, які не заявляють +про їх підтримку, і відображаються в результаті інструмента. Результати інструмента показують +застосовані налаштування; `details.normalization` фіксує будь-яке +перетворення від запитаного до застосованого. ## Конфігурація @@ -165,64 +196,84 @@ x-i18n: } ``` -### Порядок вибору провайдера +### Порядок вибору провайдерів OpenClaw пробує провайдерів у такому порядку: -1. **Параметр `model`** із виклику інструмента (якщо агент його вказує). -2. **`imageGenerationModel.primary`** із конфігурації. -3. **`imageGenerationModel.fallbacks`** по порядку. -4. **Автовиявлення** — лише типові значення провайдерів, підкріплені автентифікацією: - - спочатку поточний провайдер за замовчуванням; - - далі решта зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів. +1. **Параметр `model`** з виклику інструмента (якщо агент його вказує). +2. **`imageGenerationModel.primary`** з конфігурації. +3. **`imageGenerationModel.fallbacks`** у заданому порядку. +4. **Автовиявлення** — лише типові провайдери з auth: + - спочатку поточний типовий провайдер; + - потім решта зареєстрованих провайдерів генерації зображень у порядку provider-id. -Якщо провайдер завершується помилкою (помилка автентифікації, ліміт швидкості тощо), автоматично пробується наступний налаштований кандидат. Якщо помиляються всі, помилка містить подробиці кожної спроби. +Якщо провайдер завершується помилкою (помилка auth, обмеження швидкості тощо), автоматично +пробується наступний налаштований кандидат. Якщо всі завершуються помилкою, повідомлення про помилку містить +деталі кожної спроби. - - Перевизначення `model` для окремого виклику пробує лише цей провайдер/цю модель і не переходить до налаштованих primary/fallback або автовиявлених провайдерів. + + Перевизначення `model` для окремого виклику пробує лише цей провайдер/модель і + не продовжує до налаштованих primary/fallback або автовиявлених провайдерів. - - Типове значення провайдера потрапляє до списку кандидатів, лише коли OpenClaw справді може автентифікувати цей провайдер. Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, щоб використовувати лише явні записи `model`, `primary` і `fallbacks`. + + Типовий провайдер потрапляє до списку кандидатів лише тоді, коли OpenClaw + справді може автентифікуватися в цього провайдера. Встановіть + `agents.defaults.mediaGenerationAutoProviderFallback: false`, щоб використовувати лише + явні записи `model`, `primary` і `fallbacks`. - - Установіть `agents.defaults.imageGenerationModel.timeoutMs` для повільних бекендів зображень. Параметр інструмента `timeoutMs` для окремого виклику перевизначає налаштоване значення за замовчуванням. + + Установіть `agents.defaults.imageGenerationModel.timeoutMs` для повільних + backend генерації зображень. Параметр інструмента `timeoutMs` для окремого виклику перевизначає + налаштоване типове значення. - - Використовуйте `action: "list"`, щоб переглянути поточно зареєстрованих провайдерів, їхні моделі за замовчуванням і підказки щодо змінних середовища для автентифікації. + + Використовуйте `action: "list"`, щоб переглянути поточно зареєстрованих провайдерів, + їхні типові моделі та підказки щодо auth env var. ### Редагування зображень -OpenAI, OpenRouter, Google, fal, MiniMax, ComfyUI і xAI підтримують редагування опорних зображень. Передайте шлях або URL опорного зображення: +OpenAI, OpenRouter, Google, DeepInfra, fal, MiniMax, ComfyUI і xAI підтримують редагування +референсних зображень. Передайте шлях або URL референсного зображення: ```text "Згенеруй акварельну версію цього фото" + image: "/path/to/photo.jpg" ``` -OpenAI, OpenRouter, Google і xAI підтримують до 5 опорних зображень через параметр `images`. fal, MiniMax і ComfyUI підтримують 1. +OpenAI, OpenRouter, Google і xAI підтримують до 5 референсних зображень через +параметр `images`. fal, MiniMax і ComfyUI підтримують 1. -## Детальніше про провайдерів +## Детальний розбір провайдерів - Для генерації зображень OpenAI за замовчуванням використовується `openai/gpt-image-2`. Якщо налаштовано OAuth-профіль `openai-codex`, OpenClaw повторно використовує той самий OAuth-профіль, що й для чат-моделей підписки Codex, і надсилає запит на зображення через бекенд Codex Responses. Застарілі базові URL Codex, такі як `https://chatgpt.com/backend-api`, канонізуються до `https://chatgpt.com/backend-api/codex` для запитів на зображення. OpenClaw **не** виконує безшумного резервного переходу до `OPENAI_API_KEY` для цього запиту — щоб примусово використовувати прямий маршрут OpenAI Images API, явно налаштуйте `models.providers.openai` з API-ключем, власним base URL або ендпоінтом Azure. + Генерація зображень OpenAI типово використовує `openai/gpt-image-2`. Якщо + налаштовано профіль OAuth `openai-codex`, OpenClaw повторно використовує той самий + профіль OAuth, який Codex використовує для моделей чату з підпискою, і надсилає + запит на зображення через backend Codex Responses. Застарілі базові URL Codex, + такі як `https://chatgpt.com/backend-api`, канонізуються до + `https://chatgpt.com/backend-api/codex` для запитів на зображення. OpenClaw + **не** виконує тихе резервне перемикання на `OPENAI_API_KEY` для такого запиту — + щоб примусово використовувати прямий маршрут OpenAI Images API, налаштуйте + `models.providers.openai` явно, вказавши API-ключ, власний base URL + або ендпойнт Azure. Моделі `openai/gpt-image-1.5`, `openai/gpt-image-1` і - `openai/gpt-image-1-mini` також можна явно вибрати. Використовуйте - `gpt-image-1.5` для PNG/WebP із прозорим фоном; поточний API + `openai/gpt-image-1-mini` усе ще можна вибрати явно. Використовуйте + `gpt-image-1.5` для виводу PNG/WebP із прозорим фоном; поточний API `gpt-image-2` відхиляє `background: "transparent"`. - `gpt-image-2` підтримує як генерацію зображень із тексту, так і - редагування за опорним зображенням через той самий інструмент - `image_generate`. OpenClaw передає до OpenAI `prompt`, `count`, `size`, `quality`, `outputFormat` - та опорні зображення. OpenAI **не** отримує - `aspectRatio` або `resolution` безпосередньо; коли це можливо, OpenClaw зіставляє - їх із підтримуваним `size`, інакше інструмент повідомляє про них як - про проігноровані перевизначення. + `gpt-image-2` підтримує як генерацію зображення за текстом, так і + редагування за референсним зображенням через той самий інструмент `image_generate`. + OpenClaw пересилає в OpenAI `prompt`, `count`, `size`, `quality`, `outputFormat` + і референсні зображення. OpenAI **не** отримує + `aspectRatio` або `resolution` напряму; коли це можливо, OpenClaw зіставляє + їх із підтримуваним `size`, інакше інструмент повідомляє про них як про + проігноровані перевизначення. - Параметри, специфічні для OpenAI, розміщені в об’єкті `openai`: + Специфічні для OpenAI параметри містяться в об’єкті `openai`: ```json { @@ -238,25 +289,25 @@ OpenAI, OpenRouter, Google і xAI підтримують до 5 опорних ``` `openai.background` приймає `transparent`, `opaque` або `auto`; - прозорий вивід потребує `outputFormat` `png` або `webp` і - моделі зображень OpenAI з підтримкою прозорості. OpenClaw спрямовує типові - запити `gpt-image-2` на прозорий фон до `gpt-image-1.5`. + прозорий вивід потребує `outputFormat` зі значенням `png` або `webp` і + модель зображень OpenAI, яка підтримує прозорість. OpenClaw маршрутизує типові + запити `gpt-image-2` із прозорим фоном на `gpt-image-1.5`. `openai.outputCompression` застосовується до виводу JPEG/WebP. - Підказка верхнього рівня `background` не прив’язана до конкретного провайдера і наразі зіставляється + Підказка верхнього рівня `background` не залежить від провайдера й наразі зіставляється з тим самим полем запиту OpenAI `background`, коли вибрано провайдера OpenAI. - Провайдери, які не оголошують підтримку фону, повертають - це значення в `ignoredOverrides` замість отримання непідтримуваного параметра. + Провайдери, які не заявляють підтримку фону, повертають + його в `ignoredOverrides` замість отримання непідтримуваного параметра. - Щоб спрямувати генерацію зображень OpenAI через розгортання Azure OpenAI + Щоб маршрутизувати генерацію зображень OpenAI через розгортання Azure OpenAI замість `api.openai.com`, див. - [ендпоінти Azure OpenAI](/uk/providers/openai#azure-openai-endpoints). + [ендпойнти Azure OpenAI](/uk/providers/openai#azure-openai-endpoints). Генерація зображень OpenRouter використовує той самий `OPENROUTER_API_KEY` і - спрямовується через image API chat completions від OpenRouter. Вибирайте - моделі зображень OpenRouter із префіксом `openrouter/`: + маршрутизується через image API chat completions від OpenRouter. Вибирайте + моделі зображень OpenRouter з префіксом `openrouter/`: ```json5 { @@ -270,17 +321,17 @@ OpenAI, OpenRouter, Google і xAI підтримують до 5 опорних } ``` - OpenClaw передає до OpenRouter `prompt`, `count`, опорні зображення та - підказки `aspectRatio` / `resolution`, сумісні з Gemini. - Поточні вбудовані скорочені позначення моделей зображень OpenRouter включають + OpenClaw пересилає в OpenRouter `prompt`, `count`, референсні зображення та + сумісні з Gemini підказки `aspectRatio` / `resolution`. + Поточні вбудовані скорочення для моделей зображень OpenRouter включають `google/gemini-3.1-flash-image-preview`, `google/gemini-3-pro-image-preview` і `openai/gpt-5.4-image-2`. Використовуйте `action: "list"`, щоб побачити, що надає ваш налаштований Plugin. - + Генерація зображень MiniMax доступна через обидва вбудовані шляхи - автентифікації MiniMax: + auth MiniMax: - `minimax/image-01` для налаштувань з API-ключем - `minimax-portal/image-01` для налаштувань OAuth @@ -292,14 +343,14 @@ OpenAI, OpenRouter, Google і xAI підтримують до 5 опорних - Моделі: `xai/grok-imagine-image`, `xai/grok-imagine-image-pro` - Кількість: до 4 - - Опорні зображення: один `image` або до п’яти `images` + - Референси: один `image` або до п’яти `images` - Співвідношення сторін: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` - - Роздільні здатності: `1K`, `2K` - - Вивід: повертається як вкладення зображень під керуванням OpenClaw + - Роздільності: `1K`, `2K` + - Вивід: повертається як керовані OpenClaw вкладення зображень - OpenClaw навмисно не надає специфічні для xAI параметри `quality`, `mask`, - `user` або додаткові співвідношення сторін, доступні лише в xAI, доки ці елементи керування не з’являться - у спільному міжпровайдерному контракті `image_generate`. + OpenClaw навмисно не надає нативні для xAI `quality`, `mask`, + `user` або додаткові співвідношення сторін, доступні лише нативно, доки ці + елементи керування не з’являться у спільному міжпровайдерному контракті `image_generate`. @@ -307,7 +358,7 @@ OpenAI, OpenRouter, Google і xAI підтримують до 5 опорних ## Приклади - + ```text /tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1 ``` @@ -334,28 +385,28 @@ openclaw infer image generate \ /tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2 ``` - + ```text /tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536 ``` - + ```text /tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024 ``` -Ті самі прапорці `--output-format` і `--background` також доступні в +Ті самі прапорці `--output-format` і `--background` доступні в `openclaw infer image edit`; `--openai-background` залишається -специфічним для OpenAI псевдонімом. Вбудовані провайдери, окрім OpenAI, сьогодні не оголошують -явного керування фоном, тому `background: "transparent"` для них позначається +специфічним для OpenAI псевдонімом. Вбудовані провайдери, крім OpenAI, наразі не +заявляють явного керування фоном, тому для них `background: "transparent"` позначається як проігнороване. ## Пов’язане - [Огляд інструментів](/uk/tools) — усі доступні інструменти агента -- [ComfyUI](/uk/providers/comfy) — налаштування локального workflow ComfyUI і Comfy Cloud +- [ComfyUI](/uk/providers/comfy) — налаштування локального workflow ComfyUI та Comfy Cloud - [fal](/uk/providers/fal) — налаштування провайдера зображень і відео fal - [Google (Gemini)](/uk/providers/google) — налаштування провайдера зображень Gemini - [MiniMax](/uk/providers/minimax) — налаштування провайдера зображень MiniMax @@ -363,4 +414,4 @@ openclaw infer image generate \ - [Vydra](/uk/providers/vydra) — налаштування зображень, відео та мовлення Vydra - [xAI](/uk/providers/xai) — налаштування Grok для зображень, відео, пошуку, виконання коду та TTS - [Довідник із конфігурації](/uk/gateway/config-agents#agent-defaults) — конфігурація `imageGenerationModel` -- [Моделі](/uk/concepts/models) — конфігурація моделей і аварійне перемикання +- [Моделі](/uk/concepts/models) — конфігурація моделей і failover diff --git a/docs/uk/tools/media-overview.md b/docs/uk/tools/media-overview.md index 2c4407632..1a9b555d9 100644 --- a/docs/uk/tools/media-overview.md +++ b/docs/uk/tools/media-overview.md @@ -1,142 +1,149 @@ --- read_when: - Шукаєте огляд медіаможливостей OpenClaw - - Вирішуєте, якого медіапровайдера налаштувати - - Розуміння того, як працює асинхронне генерування медіа + - Вибираєте, якого медіапровайдера налаштувати + - Розуміння того, як працює асинхронна генерація медіа sidebarTitle: Media overview -summary: Можливості розуміння зображень, відео, музики, мовлення та медіа з першого погляду +summary: Можливості роботи із зображеннями, відео, музикою, мовленням і розумінням медіа з першого погляду title: Огляд медіа x-i18n: - generated_at: "2026-04-26T05:24:11Z" + generated_at: "2026-04-28T00:36:11Z" model: gpt-5.4 provider: openai - source_hash: 70be8062c01f57bf53ab08aad4f1561e3958adc94e478224821d722fd500e09f + source_hash: 44555d723f5d4638f7ca069fed4e1ad36542a27ae935e827c37fe8425ccf225f source_path: tools/media-overview.md workflow: 15 --- OpenClaw генерує зображення, відео та музику, розуміє вхідні медіа -(зображення, аудіо, відео) і озвучує відповіді за допомогою синтезу мовлення. Усі -медіаможливості керуються інструментами: агент вирішує, коли їх використовувати, -залежно від розмови, і кожен інструмент з’являється лише тоді, коли налаштовано -принаймні одного базового провайдера. +(зображення, аудіо, відео) і озвучує відповіді за допомогою перетворення тексту на мовлення. Усі +медіаможливості керуються інструментами: агент вирішує, коли їх використовувати, залежно +від розмови, і кожен інструмент з’являється лише тоді, коли налаштовано принаймні одного +відповідного провайдера. ## Можливості - - Створюйте та редагуйте зображення з текстових запитів або еталонних зображень за допомогою + + Створюйте та редагуйте зображення з текстових prompt або еталонних зображень через `image_generate`. Синхронно — завершується в межах відповіді. - - Текст у відео, зображення у відео та відео у відео через `video_generate`. - Асинхронно — виконується у фоновому режимі та публікує результат, коли він готовий. + + Перетворення тексту у відео, зображення у відео та відео у відео через `video_generate`. + Асинхронно — виконується у фоновому режимі та публікує результат, коли все готово. - + Генеруйте музику або аудіодоріжки через `music_generate`. Асинхронно у спільних - провайдерів; шлях робочого процесу ComfyUI виконується синхронно. + провайдерів; шлях workflow ComfyUI виконується синхронно. - + Перетворюйте вихідні відповіді на озвучене аудіо за допомогою інструмента `tts` і конфігурації `messages.tts`. Синхронно. - Узагальнюйте вхідні зображення, аудіо та відео за допомогою провайдерів моделей - із підтримкою зору та спеціалізованих Plugin для розуміння медіа. + Підсумовуйте вхідні зображення, аудіо та відео за допомогою провайдерів моделей + з підтримкою vision і спеціалізованих plugin для розуміння медіа. Транскрибуйте вхідні голосові повідомлення через пакетні провайдери STT або - провайдерів потокового STT для Voice Call. + провайдери потокового STT для Voice Call. ## Матриця можливостей провайдерів -| Provider | Зображення | Відео | Музика | TTS | STT | Голос у реальному часі | Розуміння медіа | -| ----------- | :--------: | :---: | :----: | :-: | :-: | :--------------------: | :-------------: | -| Alibaba | | ✓ | | | | | | -| BytePlus | | ✓ | | | | | | -| ComfyUI | ✓ | ✓ | ✓ | | | | | -| Deepgram | | | | | ✓ | ✓ | | -| ElevenLabs | | | | ✓ | ✓ | | | -| fal | ✓ | ✓ | | | | | | -| Google | ✓ | ✓ | ✓ | ✓ | | ✓ | ✓ | -| Gradium | | | | ✓ | | | | -| Local CLI | | | | ✓ | | | | -| Microsoft | | | | ✓ | | | | -| MiniMax | ✓ | ✓ | ✓ | ✓ | | | | -| Mistral | | | | | ✓ | | | -| OpenAI | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | -| Qwen | | ✓ | | | | | | -| Runway | | ✓ | | | | | | -| SenseAudio | | | | | ✓ | | | -| Together | | ✓ | | | | | | -| Vydra | ✓ | ✓ | | ✓ | | | | -| xAI | ✓ | ✓ | | ✓ | ✓ | | ✓ | -| Xiaomi MiMo | ✓ | | | ✓ | | | ✓ | +| Провайдер | Зображення | Відео | Музика | TTS | STT | Голос у realtime | Розуміння медіа | +| ----------- | :--------: | :---: | :----: | :-: | :-: | :--------------: | :-------------: | +| Alibaba | | ✓ | | | | | | +| BytePlus | | ✓ | | | | | | +| ComfyUI | ✓ | ✓ | ✓ | | | | | +| DeepInfra | ✓ | ✓ | | ✓ | ✓ | | ✓ | +| Deepgram | | | | | ✓ | ✓ | | +| ElevenLabs | | | | ✓ | ✓ | | | +| fal | ✓ | ✓ | | | | | | +| Google | ✓ | ✓ | ✓ | ✓ | | ✓ | ✓ | +| Gradium | | | | ✓ | | | | +| Local CLI | | | | ✓ | | | | +| Microsoft | | | | ✓ | | | | +| MiniMax | ✓ | ✓ | ✓ | ✓ | | | | +| Mistral | | | | | ✓ | | | +| OpenAI | ✓ | ✓ | | ✓ | ✓ | ✓ | ✓ | +| Qwen | | ✓ | | | | | | +| Runway | | ✓ | | | | | | +| SenseAudio | | | | | ✓ | | | +| Together | | ✓ | | | | | | +| Vydra | ✓ | ✓ | | ✓ | | | | +| xAI | ✓ | ✓ | | ✓ | ✓ | | ✓ | +| Xiaomi MiMo | ✓ | | | ✓ | | | ✓ | -Розуміння медіа використовує будь-яку модель із підтримкою зору або аудіо, -зареєстровану у конфігурації вашого провайдера. У матриці вище перелічено -провайдерів зі спеціалізованою підтримкою розуміння медіа; більшість -мультимодальних провайдерів LLM (Anthropic, Google, +Розуміння медіа використовує будь-яку модель із підтримкою vision або audio, зареєстровану +у вашій конфігурації провайдерів. У матриці вище перелічено провайдерів зі спеціалізованою +підтримкою розуміння медіа; більшість мультимодальних провайдерів LLM (Anthropic, Google, OpenAI тощо) також можуть розуміти вхідні медіа, якщо їх налаштовано як активну модель відповіді. ## Асинхронно чи синхронно -| Можливість | Режим | Чому | -| ---------------- | ------------- | ----------------------------------------------------------------- | -| Зображення | Синхронний | Відповіді провайдера повертаються за секунди; завершується в межах відповіді. | -| Синтез мовлення | Синхронний | Відповіді провайдера повертаються за секунди; додається до аудіо відповіді. | -| Відео | Асинхронний | Обробка провайдером триває від 30 с до кількох хвилин. | -| Музика (спільна) | Асинхронний | Така сама характеристика обробки провайдером, як і у відео. | -| Музика (ComfyUI) | Синхронний | Локальний робочий процес виконується вбудовано на налаштованому сервері ComfyUI. | +| Можливість | Режим | Чому | +| --------------- | ------------- | ------------------------------------------------------------------ | +| Зображення | Синхронно | Відповіді провайдера повертаються за секунди; завершується в межах відповіді. | +| Text-to-speech | Синхронно | Відповіді провайдера повертаються за секунди; додається до аудіо відповіді. | +| Відео | Асинхронно | Обробка провайдером триває від 30 с до кількох хвилин. | +| Музика (спільні провайдери) | Асинхронно | Така сама характеристика обробки провайдером, як і у відео. | +| Музика (ComfyUI) | Синхронно | Локальний workflow виконується в межах відповіді на налаштованому сервері ComfyUI. | Для асинхронних інструментів OpenClaw надсилає запит провайдеру, одразу повертає -ідентифікатор завдання та відстежує завдання в журналі завдань. Агент продовжує -відповідати на інші повідомлення, поки завдання виконується. Коли провайдер -завершує роботу, OpenClaw пробуджує агента, щоб він міг опублікувати готове -медіа назад в оригінальний канал. +ідентифікатор завдання та відстежує роботу в реєстрі завдань. Агент продовжує +відповідати на інші повідомлення, поки завдання виконується. Коли провайдер завершує роботу, +OpenClaw пробуджує агента, щоб він міг опублікувати готове медіа назад у +початковий канал. ## Мовлення в текст і Voice Call -Deepgram, ElevenLabs, Mistral, OpenAI, SenseAudio та xAI можуть транскрибувати +Deepgram, DeepInfra, ElevenLabs, Mistral, OpenAI, SenseAudio і xAI можуть транскрибувати вхідне аудіо через пакетний шлях `tools.media.audio`, якщо їх налаштовано. -Channel Plugin, які попередньо перевіряють голосове повідомлення для -відсікання за згадками або розбору команд, позначають транскрибоване вкладення -у вхідному контексті, тому спільний етап розуміння медіа повторно використовує -цю транскрипцію замість повторного виклику STT для того самого аудіо. +Plugin каналів, які попередньо обробляють голосове повідомлення для перевірки згадки або +розбору команди, позначають транскрибоване вкладення у вхідному контексті, тому спільний +прохід розуміння медіа повторно використовує цю транскрипцію замість другого +виклику STT для того самого аудіо. -Deepgram, ElevenLabs, Mistral, OpenAI та xAI також реєструють провайдерів -потокового STT для Voice Call, тож живе телефонне аудіо можна переспрямувати -вибраному постачальнику без очікування завершення запису. +Deepgram, ElevenLabs, Mistral, OpenAI і xAI також реєструють провайдерів потокового STT для +Voice Call, тому живе телефонне аудіо можна пересилати вибраному +постачальнику, не чекаючи завершення запису. -## Відображення провайдерів (як постачальники розподіляються між поверхнями) +## Відображення провайдерів (як постачальники розподіляються за поверхнями) - Поверхні зображень, відео, музики, пакетного TTS, backend голосу в реальному часі та + Поверхні генерації зображень, відео, музики, пакетного TTS, backend realtime voice і розуміння медіа. - Поверхні зображень, відео, пакетного TTS, пакетного STT, потокового STT для Voice Call, backend - голосу в реальному часі та memory-embedding. + Поверхні генерації зображень, відео, пакетного TTS, пакетного STT, потокового STT для Voice Call, backend + realtime voice і ембедінгів пам’яті. + + + Поверхні маршрутизації чату/моделі, генерації/редагування зображень, text-to-video, пакетного TTS, + пакетного STT, розуміння зображень у медіа та ембедінгів пам’яті. + Власні моделі DeepInfra для rerank/classification/object-detection не + реєструються, доки OpenClaw не матиме спеціалізованих контрактів провайдерів для цих + категорій. - Зображення, відео, пошук, виконання коду, пакетний TTS, пакетний STT і потоковий - STT для Voice Call. Голос xAI Realtime є можливістю на боці upstream, але - не зареєстрований в OpenClaw, доки спільний контракт realtime-voice не зможе - його представити. + Генерація зображень, відео, пошук, виконання коду, пакетний TTS, пакетний STT і потоковий STT для Voice + Call. Realtime voice у xAI є можливістю на боці upstream, але + не реєструється в OpenClaw, доки спільний контракт realtime-voice не зможе + її подати. ## Пов’язане -- [Генерування зображень](/uk/tools/image-generation) -- [Генерування відео](/uk/tools/video-generation) -- [Генерування музики](/uk/tools/music-generation) -- [Синтез мовлення](/uk/tools/tts) +- [Генерація зображень](/uk/tools/image-generation) +- [Генерація відео](/uk/tools/video-generation) +- [Генерація музики](/uk/tools/music-generation) +- [Text-to-speech](/uk/tools/tts) - [Розуміння медіа](/uk/nodes/media-understanding) - [Аудіовузли](/uk/nodes/audio) diff --git a/docs/uk/tools/tts.md b/docs/uk/tools/tts.md index 8183073d4..d54091145 100644 --- a/docs/uk/tools/tts.md +++ b/docs/uk/tools/tts.md @@ -1,35 +1,34 @@ --- read_when: - - Увімкнення Text-to-speech для відповідей - - Налаштування провайдера TTS, ланцюжка резервних варіантів або персони + - Увімкнення text-to-speech для відповідей + - Налаштування провайдера TTS, ланцюжка fallback або персони - Використання команд або директив `/tts` sidebarTitle: Text to speech (TTS) -summary: Text-to-speech для вихідних відповідей — провайдери, персони, slash-команди та виведення для окремих каналів +summary: Text-to-speech для вихідних відповідей — провайдери, персони, slash-команди та вивід для кожного каналу title: Text-to-speech x-i18n: - generated_at: "2026-04-26T07:51:36Z" + generated_at: "2026-04-28T00:36:16Z" model: gpt-5.4 provider: openai - source_hash: 199a84fde8f7fd380667a39c448ac8158e0aab071b77be41b87431d10d8b4219 + source_hash: ec58d19fbca0ff0cd9828f32c150123cad22f053a6b4281ed40ec3d1fa41d1b2 source_path: tools/tts.md workflow: 15 --- -OpenClaw може перетворювати вихідні відповіді на аудіо через **13 speech-провайдерів** +OpenClaw може перетворювати вихідні відповіді на аудіо через **14 speech-провайдерів** і доставляти нативні голосові повідомлення у Feishu, Matrix, Telegram і WhatsApp, -аудіовкладення всюди в інших місцях, а також потоки PCM/Ulaw для telephony і Talk. +аудіовкладення всюди в інших місцях, а також потоки PCM/Ulaw для телефонії та Talk. ## Швидкий старт - OpenAI і ElevenLabs — найнадійніші hosted-варіанти. Microsoft і - Local CLI працюють без API-ключа. Див. [матрицю провайдерів](#supported-providers) - для повного списку. + OpenAI та ElevenLabs — найнадійніші хостингові варіанти. Microsoft і + Local CLI працюють без API-ключа. Повний список дивіться в [матриці провайдерів](#supported-providers). - Експортуйте env var для свого провайдера (наприклад `OPENAI_API_KEY`, - `ELEVENLABS_API_KEY`). Microsoft і Local CLI не потребують ключа. + Експортуйте env-змінну для вашого провайдера (наприклад, `OPENAI_API_KEY`, + `ELEVENLABS_API_KEY`). Для Microsoft і Local CLI ключ не потрібен. Установіть `messages.tts.auto: "always"` і `messages.tts.provider`: @@ -59,32 +58,33 @@ OpenClaw вибирає першого налаштованого провайд ## Підтримувані провайдери -| Провайдер | Автентифікація | Примітки | -| ----------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| **Azure Speech** | `AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION` (також `AZURE_SPEECH_API_KEY`, `SPEECH_KEY`, `SPEECH_REGION`) | Нативне voice-note-виведення Ogg/Opus і telephony. | -| **ElevenLabs** | `ELEVENLABS_API_KEY` або `XI_API_KEY` | Клонування голосу, багатомовність, детермінованість через `seed`. | -| **Google Gemini** | `GEMINI_API_KEY` або `GOOGLE_API_KEY` | Gemini API TTS; підтримує persona через `promptTemplate: "audio-profile-v1"`. | -| **Gradium** | `GRADIUM_API_KEY` | Виведення voice-note і telephony. | -| **Inworld** | `INWORLD_API_KEY` | Streaming TTS API. Нативний voice-note Opus і telephony PCM. | -| **Local CLI** | none | Запускає налаштовану локальну команду TTS. | -| **Microsoft** | none | Публічний neural TTS Edge через `node-edge-tts`. Best-effort, без SLA. | -| **MiniMax** | `MINIMAX_API_KEY` (або Token Plan: `MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`) | API T2A v2. За замовчуванням `speech-2.8-hd`. | -| **OpenAI** | `OPENAI_API_KEY` | Також використовується для auto-summary; підтримує persona `instructions`. | -| **OpenRouter** | `OPENROUTER_API_KEY` (може повторно використовувати `models.providers.openrouter.apiKey`) | Модель за замовчуванням `hexgrad/kokoro-82m`. | -| **Volcengine** | `VOLCENGINE_TTS_API_KEY` або `BYTEPLUS_SEED_SPEECH_API_KEY` (застарілі AppID/token: `VOLCENGINE_TTS_APPID`/`_TOKEN`) | HTTP API BytePlus Seed Speech. | -| **Vydra** | `VYDRA_API_KEY` | Спільний провайдер зображень, відео та мовлення. | -| **xAI** | `XAI_API_KEY` | Batch TTS від xAI. Нативний voice-note Opus **не** підтримується. | -| **Xiaomi MiMo** | `XIAOMI_API_KEY` | MiMo TTS через chat completions Xiaomi. | +| Провайдер | Auth | Примітки | +| ------------------ | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | +| **Azure Speech** | `AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION` (також `AZURE_SPEECH_API_KEY`, `SPEECH_KEY`, `SPEECH_REGION`) | Нативний вивід голосових нотаток Ogg/Opus і телефонії. | +| **DeepInfra** | `DEEPINFRA_API_KEY` | TTS, сумісний з OpenAI. За замовчуванням `hexgrad/Kokoro-82M`. | +| **ElevenLabs** | `ELEVENLABS_API_KEY` або `XI_API_KEY` | Клонування голосу, багатомовність, детермінованість через `seed`. | +| **Google Gemini** | `GEMINI_API_KEY` або `GOOGLE_API_KEY` | TTS Gemini API; підтримує персони через `promptTemplate: "audio-profile-v1"`. | +| **Gradium** | `GRADIUM_API_KEY` | Вивід голосових нотаток і телефонії. | +| **Inworld** | `INWORLD_API_KEY` | Streaming TTS API. Нативний Opus для голосових нотаток і PCM для телефонії. | +| **Local CLI** | none | Запускає налаштовану локальну команду TTS. | +| **Microsoft** | none | Публічний Edge neural TTS через `node-edge-tts`. Best-effort, без SLA. | +| **MiniMax** | `MINIMAX_API_KEY` (або Token Plan: `MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`) | API T2A v2. За замовчуванням `speech-2.8-hd`. | +| **OpenAI** | `OPENAI_API_KEY` | Також використовується для auto-summary; підтримує персону `instructions`. | +| **OpenRouter** | `OPENROUTER_API_KEY` (може повторно використовувати `models.providers.openrouter.apiKey`) | Типова модель `hexgrad/kokoro-82m`. | +| **Volcengine** | `VOLCENGINE_TTS_API_KEY` або `BYTEPLUS_SEED_SPEECH_API_KEY` (застарілі AppID/token: `VOLCENGINE_TTS_APPID`/`_TOKEN`) | HTTP API BytePlus Seed Speech. | +| **Vydra** | `VYDRA_API_KEY` | Спільний провайдер зображень, відео та мовлення. | +| **xAI** | `XAI_API_KEY` | Пакетний TTS xAI. Нативний Opus для голосових нотаток **не** підтримується. | +| **Xiaomi MiMo** | `XIAOMI_API_KEY` | TTS MiMo через chat completions Xiaomi. | -Якщо налаштовано кілька провайдерів, спочатку використовується вибраний, а -інші стають резервними варіантами. Auto-summary використовує `summaryModel` (або -`agents.defaults.model.primary`), тож цей провайдер також має бути автентифікований, -якщо ви залишаєте summaries увімкненими. +Якщо налаштовано кілька провайдерів, спочатку використовується вибраний, +а інші стають fallback-варіантами. Auto-summary використовує `summaryModel` (або +`agents.defaults.model.primary`), тож якщо ви залишаєте summaries увімкненими, +цей провайдер також має бути автентифікований. -Вбудований провайдер **Microsoft** використовує онлайн-сервіс neural TTS Microsoft Edge +Вбудований провайдер **Microsoft** використовує онлайновий neural TTS-сервіс Microsoft Edge через `node-edge-tts`. Це публічний вебсервіс без опублікованих -SLA або квот — вважайте його best-effort. Застарілий id провайдера `edge` +SLA або квот — вважайте його best-effort. Застарілий ідентифікатор провайдера `edge` нормалізується до `microsoft`, а `openclaw doctor --fix` переписує збережену конфігурацію; у нових конфігураціях завжди слід використовувати `microsoft`. @@ -92,7 +92,7 @@ SLA або квот — вважайте його best-effort. Застаріл ## Конфігурація Конфігурація TTS розміщується в `messages.tts` у `~/.openclaw/openclaw.json`. Виберіть -пресет і адаптуйте блок провайдера: +preset і адаптуйте блок провайдера: @@ -148,7 +148,7 @@ SLA або квот — вважайте його best-effort. Застаріл apiKey: "${GEMINI_API_KEY}", model: "gemini-3.1-flash-tts-preview", voiceName: "Kore", - // Необов’язкові підказки стилю природною мовою: + // Необов’язкові запити стилю природною мовою: // audioProfile: "Говори спокійним тоном ведучого подкасту.", // speakerName: "Alex", }, @@ -370,11 +370,11 @@ SLA або квот — вважайте його best-effort. Застаріл -### Перевизначення голосу для окремого агента +### Перевизначення голосу для кожного agent -Використовуйте `agents.list[].tts`, коли один агент має говорити з іншим провайдером, -голосом, моделлю, persona або режимом auto-TTS. Блок агента виконує глибоке злиття поверх -`messages.tts`, тож облікові дані провайдера можуть залишатися в глобальній конфігурації провайдера: +Використовуйте `agents.list[].tts`, коли один agent має говорити з іншим провайдером, +голосом, моделлю, персоною або режимом auto-TTS. Блок agent виконує глибоке злиття поверх +`messages.tts`, тому облікові дані провайдера можуть залишатися в глобальній конфігурації провайдера: ```json5 { @@ -402,22 +402,22 @@ SLA або квот — вважайте його best-effort. Застаріл } ``` -Щоб закріпити persona для окремого агента, задайте `agents.list[].tts.persona` разом із конфігурацією -провайдера — це перевизначає глобальне `messages.tts.persona` лише для цього агента. +Щоб зафіксувати персону для конкретного agent, встановіть `agents.list[].tts.persona` разом із +конфігурацією провайдера — це перевизначає глобальне `messages.tts.persona` лише для цього agent. Порядок пріоритету для автоматичних відповідей, `/tts audio`, `/tts status` і -інструмента агента `tts`: +інструмента agent `tts`: 1. `messages.tts` -2. активне `agents.list[].tts` +2. активний `agents.list[].tts` 3. перевизначення каналу, коли канал підтримує `channels..tts` 4. перевизначення облікового запису, коли канал передає `channels..accounts..tts` -5. локальні параметри `/tts` для цього хоста -6. вбудовані директиви `[[tts:...]]`, коли [перевизначення моделей](#model-driven-directives) увімкнені +5. локальні налаштування `/tts` для цього host +6. вбудовані директиви `[[tts:...]]`, коли [керовані моделлю перевизначення](#model-driven-directives) увімкнено -Перевизначення каналу й облікового запису використовують ту саму структуру, що й `messages.tts`, і -виконують глибоке злиття поверх попередніх рівнів, тож спільні облікові дані провайдера можуть залишатися в -`messages.tts`, а канал або обліковий запис бота змінює лише голос, модель, persona +Перевизначення каналу й облікового запису використовують ту саму форму, що й `messages.tts`, і +виконують глибоке злиття поверх попередніх шарів, тому спільні облікові дані провайдера можуть залишатися в +`messages.tts`, тоді як канал або обліковий запис бота змінює лише voice, model, persona або режим auto: ```json5 @@ -448,12 +448,12 @@ SLA або квот — вважайте його best-effort. Застаріл ## Персони -**Persona** — це стабільна голосова ідентичність, яку можна детерміновано -застосовувати між провайдерами. Вона може надавати перевагу одному провайдеру, визначати нейтральний до провайдера намір prompt -і містити специфічні для провайдера прив’язки для голосів, моделей, prompt-шаблонів, -seed і налаштувань голосу. +**Персона** — це стабільна мовленнєва ідентичність, яку можна детерміновано +застосовувати в різних провайдерів. Вона може надавати перевагу одному провайдеру, визначати +нейтральний щодо провайдера намір prompt і містити прив’язки, специфічні для провайдера, для голосів, моделей, prompt- +templates, seeds і voice settings. -### Мінімальна persona +### Мінімальна персона ```json5 { @@ -463,7 +463,7 @@ seed і налаштувань голосу. persona: "narrator", personas: { narrator: { - label: "Narrator", + label: "Оповідач", provider: "elevenlabs", providers: { elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL", modelId: "eleven_multilingual_v2" }, @@ -475,7 +475,7 @@ seed і налаштувань голосу. } ``` -### Повна persona (нейтральний до провайдера prompt) +### Повна персона (нейтральний щодо провайдера prompt) ```json5 { @@ -486,17 +486,17 @@ seed і налаштувань голосу. personas: { alfred: { label: "Alfred", - description: "Сухуватий, теплий британський голос оповідача-дворецького.", + description: "Сухий, теплий британський голос оповідача-дворецького.", provider: "google", fallbackPolicy: "preserve-persona", prompt: { - profile: "Блискучий британський дворецький. Сухуватий, дотепний, теплий, чарівний, емоційно виразний, ніколи не безликий.", - scene: "Тиха нічна бібліотека. Оповідь у ближній мікрофон для довіреного оператора.", - sampleContext: "Мовець відповідає на приватний технічний запит коротко, впевнено й із сухуватою теплотою.", + profile: "Блискучий британський дворецький. Сухий, дотепний, теплий, чарівний, емоційно виразний, ніколи не загальний.", + scene: "Тихий пізньовечірній кабінет. Оповідь біля мікрофона для довіреного оператора.", + sampleContext: "Мовець відповідає на приватний технічний запит стисло, впевнено й із сухою теплотою.", style: "Вишуканий, стриманий, з легкою усмішкою.", accent: "Британська англійська.", pacing: "Розмірений, із короткими драматичними паузами.", - constraints: ["Не зачитувати вголос значення конфігурації.", "Не пояснювати persona."], + constraints: ["Не зачитувати вголос значення конфігурації.", "Не пояснювати персону."], }, providers: { google: { @@ -525,113 +525,113 @@ seed і налаштувань голосу. } ``` -### Визначення persona +### Визначення персони -Активна persona вибирається детерміновано: +Активна персона вибирається детерміновано: -1. локальна перевага `/tts persona `, якщо задано. -2. `messages.tts.persona`, якщо задано. -3. Без persona. +1. локальне налаштування `/tts persona `, якщо встановлено. +2. `messages.tts.persona`, якщо встановлено. +3. Персона відсутня. -Вибір провайдера працює за принципом explicit-first: +Вибір провайдера виконується за принципом explicit-first: 1. Прямі перевизначення (CLI, gateway, Talk, дозволені директиви TTS). -2. локальна перевага `/tts provider `. -3. `provider` активної persona. +2. Локальне налаштування `/tts provider `. +3. `provider` активної персони. 4. `messages.tts.provider`. -5. auto-select реєстру. +5. Auto-select реєстру. -Для кожної спроби провайдера OpenClaw об’єднує конфігурації в такому порядку: +Для кожної спроби з провайдером OpenClaw об’єднує конфігурації в такому порядку: 1. `messages.tts.providers.` 2. `messages.tts.personas..providers.` 3. Довірені перевизначення запиту -4. Дозволені перевизначення згенерованих моделлю директив TTS +4. Дозволені перевизначення директив TTS, згенерованих моделлю -### Як провайдери використовують prompt-и persona +### Як провайдери використовують prompt персони -Поля prompt persona (`profile`, `scene`, `sampleContext`, `style`, `accent`, -`pacing`, `constraints`) є **нейтральними до провайдера**. Кожен провайдер сам вирішує, -як їх використовувати: +Поля prompt персони (`profile`, `scene`, `sampleContext`, `style`, `accent`, +`pacing`, `constraints`) є **нейтральними щодо провайдера**. Кожен провайдер сам вирішує, як +їх використовувати: - Обгортає поля prompt persona у структуру prompt Gemini TTS **лише тоді**, - коли ефективна конфігурація провайдера Google задає `promptTemplate: "audio-profile-v1"` - або `personaPrompt`. Старіші поля `audioProfile` і `speakerName` - усе ще додаються на початок як текст prompt, специфічний для Google. Вбудовані аудіотеги, такі як - `[whispers]` або `[laughs]` всередині блоку `[[tts:text]]`, зберігаються - всередині транскрипту Gemini; OpenClaw не генерує ці теги. + Обгортає поля prompt персони в структуру prompt Gemini TTS **лише коли** + ефективна конфігурація провайдера Google встановлює `promptTemplate: "audio-profile-v1"` + або `personaPrompt`. Старіші поля `audioProfile` і `speakerName` усе ще + додаються на початок як текст prompt, специфічний для Google. Вбудовані audio-теги, такі як + `[whispers]` або `[laughs]` усередині блоку `[[tts:text]]`, зберігаються + в transcript Gemini; OpenClaw не генерує ці теги. - Відображає поля prompt persona в поле запиту `instructions` **лише тоді**, - коли не налаштовано явне `instructions` для OpenAI. Явне `instructions` + Відображає поля prompt персони в поле запиту `instructions` **лише коли** + не налаштовано явне `instructions` для OpenAI. Явне `instructions` завжди має пріоритет. - Використовують лише специфічні для провайдера прив’язки persona в - `personas..providers.`. Поля prompt persona ігноруються, - якщо провайдер не реалізує власне відображення prompt persona. + Використовують лише прив’язки персони, специфічні для провайдера, у + `personas..providers.`. Поля prompt персони ігноруються, + якщо провайдер не реалізує власне зіставлення persona-prompt. -### Політика резервного переходу +### Політика fallback -`fallbackPolicy` керує поведінкою, коли persona **не має прив’язки** для -провайдера, який намагаються використати: +`fallbackPolicy` керує поведінкою, коли персона **не має прив’язки** для +провайдера, що перевіряється: | Політика | Поведінка | -| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| `preserve-persona` | **За замовчуванням.** Нейтральні до провайдера поля prompt залишаються доступними; провайдер може використовувати їх або ігнорувати. | -| `provider-defaults` | Persona пропускається під час підготовки prompt для цієї спроби; провайдер використовує свої нейтральні значення за замовчуванням, тоді як резервний перехід до інших провайдерів триває. | -| `fail` | Пропустити цю спробу провайдера з `reasonCode: "not_configured"` і `personaBinding: "missing"`. Резервні провайдери все одно будуть спробовані. | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `preserve-persona` | **За замовчуванням.** Нейтральні щодо провайдера поля prompt залишаються доступними; провайдер може використовувати їх або ігнорувати. | +| `provider-defaults` | Персона виключається з підготовки prompt для цієї спроби; провайдер використовує свої нейтральні значення за замовчуванням, поки fallback до інших провайдерів триває. | +| `fail` | Пропускає цю спробу провайдера з `reasonCode: "not_configured"` і `personaBinding: "missing"`. Fallback-провайдери все одно будуть перевірятися. | -Увесь запит TTS завершується невдачею лише тоді, коли **кожен** спробуваний провайдер пропущено -або він завершився невдачею. +Увесь запит TTS завершується помилкою лише тоді, коли **кожен** перевірений провайдер пропущено +або він завершився помилкою. ## Директиви, керовані моделлю -За замовчуванням асистент **може** видавати директиви `[[tts:...]]` для перевизначення -голосу, моделі або швидкості для однієї відповіді, а також необов’язковий -блок `[[tts:text]]...[[/tts:text]]` для виразних підказок, які мають з’являтися +За замовчуванням assistant **може** виводити директиви `[[tts:...]]` для перевизначення +voice, model або speed для однієї відповіді, а також необов’язковий +блок `[[tts:text]]...[[/tts:text]]` для виразних підказок, які мають з’явитися лише в аудіо: ```text -Here you go. +Ось. [[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]] -[[tts:text]](laughs) Read the song once more.[[/tts:text]] +[[tts:text]](сміється) Прочитай пісню ще раз.[[/tts:text]] ``` -Коли `messages.tts.auto` має значення `"tagged"`, **директиви обов’язкові** для запуску -аудіо. Під час потокової доставки блоків директиви видаляються з видимого тексту до того, -як канал його побачить, навіть якщо вони розбиті між сусідніми блоками. +Коли `messages.tts.auto` має значення `"tagged"`, для запуску +аудіо **обов’язково потрібні директиви**. Потокова доставка блоків прибирає директиви з видимого тексту до того, як +канал їх побачить, навіть якщо вони розбиті між сусідніми блоками. -`provider=...` ігнорується, якщо `modelOverrides.allowProvider: true` не задано. Коли -відповідь оголошує `provider=...`, інші ключі в цій директиві розбираються -лише цим провайдером; непідтримувані ключі видаляються і повідомляються як попередження +`provider=...` ігнорується, якщо не встановлено `modelOverrides.allowProvider: true`. Коли +відповідь оголошує `provider=...`, інші ключі в цій директиві аналізуються +лише цим провайдером; непідтримувані ключі видаляються й повідомляються як попередження директив TTS. **Доступні ключі директив:** -- `provider` (id зареєстрованого провайдера; потребує `allowProvider: true`) +- `provider` (ідентифікатор зареєстрованого провайдера; потребує `allowProvider: true`) - `voice` / `voiceName` / `voice_name` / `google_voice` / `voiceId` - `model` / `google_model` - `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost` - `vol` / `volume` (гучність MiniMax, 0–10) - `pitch` (цілочисельний pitch MiniMax, від −12 до 12; дробові значення відкидаються) -- `emotion` (тег емоції Volcengine) +- `emotion` (тег emotion у Volcengine) - `applyTextNormalization` (`auto|on|off`) - `languageCode` (ISO 639-1) - `seed` -**Повністю вимкнути перевизначення моделей:** +**Повністю вимкнути перевизначення моделі:** ```json5 { messages: { tts: { modelOverrides: { enabled: false } } } } ``` -**Дозволити перемикання провайдера, зберігаючи налаштовуваність інших параметрів:** +**Дозволити перемикання провайдера, залишаючи інші параметри налаштовуваними:** ```json5 { messages: { tts: { modelOverrides: { enabled: true, allowProvider: true, allowSeed: false } } } } @@ -639,8 +639,8 @@ Here you go. ## Slash-команди -Єдина команда `/tts`. У Discord OpenClaw також реєструє `/voice`, тому що -`/tts` є вбудованою командою Discord — текстове `/tts ...` усе одно працює. +Єдина команда `/tts`. У Discord OpenClaw також реєструє `/voice`, оскільки +`/tts` — це вбудована команда Discord — текстова форма `/tts ...` усе одно працює. ```text /tts off | on | status @@ -654,122 +654,123 @@ Here you go. ``` -Команди вимагають авторизованого відправника (діють правила allowlist/owner) і мають бути -увімкнені або `commands.text`, або реєстрація нативних команд. +Команди потребують авторизованого відправника (діють правила allowlist/owner) і +має бути ввімкнено або `commands.text`, або нативну реєстрацію команд. Примітки щодо поведінки: -- `/tts on` записує локальну перевагу TTS як `always`; `/tts off` записує її як `off`. -- `/tts chat on|off|default` записує перевизначення auto-TTS на рівні сесії для поточного чату. -- `/tts persona ` записує локальну перевагу persona; `/tts persona off` очищує її. -- `/tts latest` читає останню відповідь асистента з поточної транскрипції сесії і одноразово надсилає її як аудіо. Він зберігає лише hash цієї відповіді в записі сесії, щоб придушити дубльовані голосові надсилання. +- `/tts on` записує локальне налаштування TTS як `always`; `/tts off` записує його як `off`. +- `/tts chat on|off|default` записує session-scoped перевизначення auto-TTS для поточного чату. +- `/tts persona ` записує локальне налаштування персони; `/tts persona off` очищує його. +- `/tts latest` зчитує останню відповідь assistant із transcript поточного сеансу й один раз надсилає її як аудіо. Він зберігає лише hash цієї відповіді в записі сеансу, щоб придушити дублікати голосових надсилань. - `/tts audio` генерує одноразову аудіовідповідь (**не** вмикає TTS). -- `limit` і `summary` зберігаються в **локальних prefs**, а не в основній конфігурації. -- `/tts status` включає діагностику резервних переходів для останньої спроби — `Fallback: -> `, `Attempts: ...` і деталізацію для кожної спроби (`provider:outcome(reasonCode) latency`). -- `/status` показує активний режим TTS, а також налаштовані провайдер, модель, голос і очищені метадані користувацької кінцевої точки, коли TTS увімкнено. +- `limit` і `summary` зберігаються в **локальних налаштуваннях**, а не в основній конфігурації. +- `/tts status` включає діагностику fallback для останньої спроби — `Fallback: -> `, `Attempts: ...` і подробиці для кожної спроби (`provider:outcome(reasonCode) latency`). +- `/status` показує активний режим TTS, а також налаштовані провайдер, модель, голос і санітизовані метадані custom endpoint, коли TTS увімкнено. -## Налаштування окремого користувача +## Налаштування для кожного користувача -Slash-команди записують локальні перевизначення до `prefsPath`. За замовчуванням це -`~/.openclaw/settings/tts.json`; перевизначайте через env var `OPENCLAW_TTS_PREFS` +Slash-команди записують локальні перевизначення в `prefsPath`. За замовчуванням це +`~/.openclaw/settings/tts.json`; перевизначити можна через env-змінну `OPENCLAW_TTS_PREFS` або `messages.tts.prefsPath`. -| Збережене поле | Ефект | -| -------------- | ---------------------------------------------- | +| Збережене поле | Ефект | +| -------------- | ------------------------------------------ | | `auto` | Локальне перевизначення auto-TTS (`always`, `off`, …) | -| `provider` | Локальне перевизначення основного провайдера | -| `persona` | Локальне перевизначення persona | -| `maxLength` | Поріг summary (типово `1500` chars) | -| `summarize` | Перемикач summary (типово `true`) | +| `provider` | Локальне перевизначення основного провайдера | +| `persona` | Локальне перевизначення персони | +| `maxLength` | Поріг summary (типово `1500` символів) | +| `summarize` | Перемикач summary (типово `true`) | -Вони перевизначають ефективну конфігурацію з `messages.tts` плюс активний -блок `agents.list[].tts` для цього хоста. +Вони перевизначають ефективну конфігурацію з `messages.tts` разом з активним +блоком `agents.list[].tts` для цього host. -## Формати виведення (фіксовані) +## Формати виводу (фіксовані) -Доставка голосу TTS визначається можливостями каналу. Плагіни каналів оголошують, -чи має TTS у стилі voice запитувати у провайдерів нативну ціль `voice-note` чи +Доставка голосу TTS визначається можливостями каналу. Plugins каналів оголошують, +чи має TTS у стилі voice просити провайдерів про нативну ціль `voice-note`, чи зберігати звичайний синтез `audio-file` і лише позначати сумісний вивід для голосової доставки. -- **Канали з підтримкою voice-note**: для відповідей voice-note перевага надається Opus (`opus_48000_64` від ElevenLabs, `opus` від OpenAI). - - 48kHz / 64kbps — хороший компроміс для голосових повідомлень. -- **Feishu / WhatsApp**: коли відповідь voice-note створюється як MP3/WebM/WAV/M4A - або інший імовірний аудіофайл, плагін каналу транскодує її в 48kHz +- **Канали з підтримкою voice-note**: відповіді у форматі voice-note віддають перевагу Opus (`opus_48000_64` від ElevenLabs, `opus` від OpenAI). + - 48 кГц / 64 кбіт/с — хороший компроміс для голосових повідомлень. +- **Feishu / WhatsApp**: коли відповідь у форматі voice-note створюється як MP3/WebM/WAV/M4A + або інший імовірний аудіофайл, Plugin каналу перекодовує її в 48 кГц Ogg/Opus за допомогою `ffmpeg` перед надсиланням нативного голосового повідомлення. WhatsApp надсилає - результат через payload `audio` Baileys з `ptt: true` і - `audio/ogg; codecs=opus`. Якщо конвертація не вдається, Feishu отримує оригінальний - файл як вкладення; надсилання WhatsApp завершується помилкою, а не публікує несумісний + результат через payload Baileys `audio` з `ptt: true` і + `audio/ogg; codecs=opus`. Якщо конвертація завершується помилкою, Feishu отримує початковий + файл як вкладення; надсилання WhatsApp завершується помилкою замість публікації несумісного payload PTT. -- **BlueBubbles**: зберігає синтез провайдера на звичайному шляху `audio-file`; виходи MP3 - і CAF позначаються для доставки як голосове memo iMessage. +- **BlueBubbles**: залишає синтез провайдера на звичайному шляху audio-file; виводи MP3 + і CAF позначаються для доставки голосових нотаток iMessage. - **Інші канали**: MP3 (`mp3_44100_128` від ElevenLabs, `mp3` від OpenAI). - - 44.1kHz / 128kbps — баланс за замовчуванням для чіткості мовлення. -- **MiniMax**: MP3 (модель `speech-2.8-hd`, частота дискретизації 32kHz) для звичайних аудіовкладень. Для цілей voice-note, оголошених каналом, OpenClaw транскодує MP3 MiniMax у 48kHz Opus за допомогою `ffmpeg` перед доставкою, коли канал оголошує підтримку транскодування. -- **Xiaomi MiMo**: MP3 за замовчуванням або WAV, якщо налаштовано. Для цілей voice-note, оголошених каналом, OpenClaw транскодує вихід Xiaomi у 48kHz Opus за допомогою `ffmpeg` перед доставкою, коли канал оголошує підтримку транскодування. + - 44,1 кГц / 128 кбіт/с — типовий баланс для чіткості мовлення. +- **MiniMax**: MP3 (модель `speech-2.8-hd`, частота дискретизації 32 кГц) для звичайних аудіовкладень. Для оголошених каналом цілей voice-note OpenClaw перекодовує MP3 MiniMax у 48 кГц Opus за допомогою `ffmpeg` перед доставкою, коли канал оголошує підтримку перекодування. +- **Xiaomi MiMo**: MP3 за замовчуванням або WAV, якщо налаштовано. Для оголошених каналом цілей voice-note OpenClaw перекодовує вивід Xiaomi у 48 кГц Opus за допомогою `ffmpeg` перед доставкою, коли канал оголошує підтримку перекодування. - **Local CLI**: використовує налаштований `outputFormat`. Цілі voice-note - конвертуються в Ogg/Opus, а виведення для telephony — у raw 16 kHz mono PCM + конвертуються в Ogg/Opus, а вивід для телефонії — у сирий 16 кГц моно PCM за допомогою `ffmpeg`. -- **Google Gemini**: Gemini API TTS повертає raw 24kHz PCM. OpenClaw обгортає його у WAV для аудіовкладень, транскодує в 48kHz Opus для цілей voice-note і повертає PCM безпосередньо для Talk/telephony. -- **Gradium**: WAV для аудіовкладень, Opus для цілей voice-note і `ulaw_8000` на 8 kHz для telephony. -- **Inworld**: MP3 для звичайних аудіовкладень, нативний `OGG_OPUS` для цілей voice-note і raw `PCM` на 22050 Hz для Talk/telephony. -- **xAI**: MP3 за замовчуванням; `responseFormat` може бути `mp3`, `wav`, `pcm`, `mulaw` або `alaw`. OpenClaw використовує batch REST endpoint TTS від xAI і повертає завершене аудіовкладення; streaming TTS WebSocket xAI не використовується цим шляхом провайдера. Нативний формат voice-note Opus цим шляхом не підтримується. +- **Google Gemini**: Gemini API TTS повертає сирий 24 кГц PCM. OpenClaw обгортає його у WAV для аудіовкладень, перекодовує в 48 кГц Opus для цілей voice-note і повертає PCM напряму для Talk/телефонії. +- **Gradium**: WAV для аудіовкладень, Opus для цілей voice-note і `ulaw_8000` на 8 кГц для телефонії. +- **Inworld**: MP3 для звичайних аудіовкладень, нативний `OGG_OPUS` для цілей voice-note і сирий `PCM` на 22050 Гц для Talk/телефонії. +- **xAI**: MP3 за замовчуванням; `responseFormat` може бути `mp3`, `wav`, `pcm`, `mulaw` або `alaw`. OpenClaw використовує пакетну REST-кінцеву точку TTS xAI і повертає повністю готове аудіовкладення; потоковий WebSocket TTS xAI цим шляхом провайдера не використовується. Нативний формат voice-note Opus цим шляхом не підтримується. - **Microsoft**: використовує `microsoft.outputFormat` (типово `audio-24khz-48kbitrate-mono-mp3`). - - Вбудований транспорт приймає `outputFormat`, але не всі формати доступні в сервісі. - - Значення формату виведення відповідають форматам виведення Microsoft Speech (зокрема Ogg/WebM Opus). + - Вбудований transport приймає `outputFormat`, але не всі формати доступні в сервісі. + - Значення формату виводу відповідають форматам виводу Microsoft Speech (зокрема Ogg/WebM Opus). - `sendVoice` у Telegram приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні гарантовані голосові повідомлення Opus. - - Якщо налаштований формат виведення Microsoft не спрацьовує, OpenClaw повторює спробу з MP3. + - Якщо налаштований формат виводу Microsoft завершується помилкою, OpenClaw повторює спробу з MP3. -Формати виведення OpenAI/ElevenLabs фіксовані для кожного каналу (див. вище). +Формати виводу OpenAI/ElevenLabs фіксовані для кожного каналу (див. вище). -## Поведінка Auto-TTS +## Поведінка auto-TTS Коли `messages.tts.auto` увімкнено, OpenClaw: - Пропускає TTS, якщо відповідь уже містить медіа або директиву `MEDIA:`. - Пропускає дуже короткі відповіді (менше 10 символів). -- Узагальнює довгі відповіді, коли summaries увімкнені, використовуючи +- Узагальнює довгі відповіді, якщо summaries увімкнено, використовуючи `summaryModel` (або `agents.defaults.model.primary`). - Додає згенероване аудіо до відповіді. -- У `mode: "final"` все одно надсилає TTS лише як аудіо для streamed final replies - після завершення текстового потоку; згенероване медіа проходить ту саму нормалізацію медіа каналу, що й звичайні вкладення відповіді. +- У режимі `mode: "final"` усе одно надсилає TTS лише як аудіо для фінальних потокових відповідей + після завершення текстового потоку; згенеровані медіадані проходять ту саму + нормалізацію медіа каналу, що й звичайні вкладення відповіді. Якщо відповідь перевищує `maxLength`, а summary вимкнено (або немає API-ключа для -моделі summary), аудіо пропускається і надсилається звичайна текстова відповідь. +моделі summary), аудіо пропускається й надсилається звичайна текстова відповідь. ```text -Reply -> TTS enabled? - no -> send text - yes -> has media / MEDIA: / short? - yes -> send text - no -> length > limit? - no -> TTS -> attach audio - yes -> summary enabled? - no -> send text - yes -> summarize -> TTS -> attach audio +Відповідь -> TTS увімкнено? + ні -> надіслати текст + так -> є медіа / MEDIA: / коротка? + так -> надіслати текст + ні -> довжина > ліміт? + ні -> TTS -> додати аудіо + так -> summary увімкнено? + ні -> надіслати текст + так -> summary -> TTS -> додати аудіо ``` -## Формати виведення за каналами +## Формати виводу за каналом -| Ціль | Формат | -| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| Feishu / Matrix / Telegram / WhatsApp | Для відповідей voice-note перевага надається **Opus** (`opus_48000_64` від ElevenLabs, `opus` від OpenAI). 48 kHz / 64 kbps балансує чіткість і розмір. | -| Інші канали | **MP3** (`mp3_44100_128` від ElevenLabs, `mp3` від OpenAI). 44.1 kHz / 128 kbps — стандарт для мовлення. | -| Talk / telephony | Нативний для провайдера **PCM** (Inworld 22050 Hz, Google 24 kHz) або `ulaw_8000` від Gradium для telephony. | +| Ціль | Формат | +| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| Feishu / Matrix / Telegram / WhatsApp | Відповіді у форматі voice-note віддають перевагу **Opus** (`opus_48000_64` від ElevenLabs, `opus` від OpenAI). 48 кГц / 64 кбіт/с балансує чіткість і розмір. | +| Інші канали | **MP3** (`mp3_44100_128` від ElevenLabs, `mp3` від OpenAI). 44,1 кГц / 128 кбіт/с — типовий варіант для мовлення. | +| Talk / телефонія | Нативний для провайдера **PCM** (Inworld 22050 Гц, Google 24 кГц) або `ulaw_8000` від Gradium для телефонії. | -Примітки за провайдерами: +Примітки для окремих провайдерів: -- **Транскодування Feishu / WhatsApp:** коли відповідь voice-note надходить як MP3/WebM/WAV/M4A, плагін каналу транскодує її в 48 kHz Ogg/Opus за допомогою `ffmpeg`. WhatsApp надсилає через Baileys з `ptt: true` і `audio/ogg; codecs=opus`. Якщо конвертація не вдається: Feishu повертається до вкладення оригінального файла; надсилання WhatsApp завершується помилкою, а не публікує несумісний payload PTT. -- **MiniMax / Xiaomi MiMo:** MP3 за замовчуванням (32 kHz для MiniMax `speech-2.8-hd`); транскодується в 48 kHz Opus для цілей voice-note через `ffmpeg`. -- **Local CLI:** використовує налаштований `outputFormat`. Цілі voice-note конвертуються в Ogg/Opus, а виведення для telephony — у raw 16 kHz mono PCM. -- **Google Gemini:** повертає raw 24 kHz PCM. OpenClaw обгортає його у WAV для вкладень, транскодує в 48 kHz Opus для цілей voice-note, повертає PCM безпосередньо для Talk/telephony. -- **Inworld:** MP3-вкладення, нативний `OGG_OPUS` voice-note, raw `PCM` 22050 Hz для Talk/telephony. -- **xAI:** MP3 за замовчуванням; `responseFormat` може бути `mp3|wav|pcm|mulaw|alaw`. Використовує batch REST endpoint xAI — streaming WebSocket TTS **не** використовується. Нативний формат voice-note Opus **не** підтримується. -- **Microsoft:** використовує `microsoft.outputFormat` (типово `audio-24khz-48kbitrate-mono-mp3`). `sendVoice` у Telegram приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні гарантовані голосові повідомлення Opus. Якщо налаштований формат Microsoft не спрацьовує, OpenClaw повторює спробу з MP3. +- **Перекодування Feishu / WhatsApp:** Коли відповідь у форматі voice-note надходить як MP3/WebM/WAV/M4A, Plugin каналу перекодовує її у 48 кГц Ogg/Opus за допомогою `ffmpeg`. WhatsApp надсилає через Baileys з `ptt: true` і `audio/ogg; codecs=opus`. Якщо конвертація завершується помилкою: Feishu повертається до вкладення початкового файла; надсилання WhatsApp завершується помилкою замість публікації несумісного payload PTT. +- **MiniMax / Xiaomi MiMo:** Типово MP3 (32 кГц для MiniMax `speech-2.8-hd`); перекодовується в 48 кГц Opus для цілей voice-note через `ffmpeg`. +- **Local CLI:** Використовує налаштований `outputFormat`. Цілі voice-note конвертуються в Ogg/Opus, а вивід для телефонії — у сирий 16 кГц моно PCM. +- **Google Gemini:** Повертає сирий 24 кГц PCM. OpenClaw обгортає його у WAV для вкладень, перекодовує в 48 кГц Opus для цілей voice-note, повертає PCM напряму для Talk/телефонії. +- **Inworld:** MP3-вкладення, нативний `OGG_OPUS` для voice-note, сирий `PCM` 22050 Гц для Talk/телефонії. +- **xAI:** MP3 за замовчуванням; `responseFormat` може бути `mp3|wav|pcm|mulaw|alaw`. Використовує пакетну кінцеву точку REST xAI — потоковий WebSocket TTS **не** використовується. Нативний формат voice-note Opus **не** підтримується. +- **Microsoft:** Використовує `microsoft.outputFormat` (типово `audio-24khz-48kbitrate-mono-mp3`). `sendVoice` у Telegram приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні гарантовані голосові повідомлення Opus. Якщо налаштований формат Microsoft завершується помилкою, OpenClaw повторює спробу з MP3. -Формати виведення OpenAI та ElevenLabs фіксовані для кожного каналу, як наведено вище. +Формати виводу OpenAI та ElevenLabs фіксовані для кожного каналу, як указано вище. ## Довідник полів @@ -779,199 +780,198 @@ Reply -> TTS enabled? Режим auto-TTS. `inbound` надсилає аудіо лише після вхідного голосового повідомлення; `tagged` надсилає аудіо лише тоді, коли відповідь містить директиви `[[tts:...]]` або блок `[[tts:text]]`. - Застарілий перемикач. `openclaw doctor --fix` переносить його до `auto`. + Застарілий перемикач. `openclaw doctor --fix` переносить його в `auto`. `"all"` включає відповіді інструментів/блоків на додачу до фінальних відповідей. - id speech-провайдера. Якщо не задано, OpenClaw використовує першого налаштованого провайдера в порядку auto-select реєстру. Застаріле `provider: "edge"` переписується на `"microsoft"` командою `openclaw doctor --fix`. + Ідентифікатор speech-провайдера. Якщо не задано, OpenClaw використовує першого налаштованого провайдера в порядку auto-select реєстру. Застаріле `provider: "edge"` переписується в `"microsoft"` за допомогою `openclaw doctor --fix`. - id активної persona з `personas`. Нормалізується до нижнього регістру. + Ідентифікатор активної персони з `personas`. Нормалізується до нижнього регістру. - Стабільна голосова ідентичність. Поля: `label`, `description`, `provider`, `fallbackPolicy`, `prompt`, `providers.`. Див. [Персони](#personas). + Стабільна мовленнєва ідентичність. Поля: `label`, `description`, `provider`, `fallbackPolicy`, `prompt`, `providers.`. Див. [Персони](#personas). - Дешева модель для auto-summary; за замовчуванням `agents.defaults.model.primary`. Приймає `provider/model` або налаштований псевдонім моделі. + Дешева модель для auto-summary; типово `agents.defaults.model.primary`. Приймає `provider/model` або налаштований псевдонім моделі. - Дозволяє моделі виводити директиви TTS. `enabled` за замовчуванням має значення `true`; `allowProvider` за замовчуванням має значення `false`. + Дозволяє моделі виводити директиви TTS. `enabled` типово дорівнює `true`; `allowProvider` типово дорівнює `false`. - Налаштування, якими володіє провайдер, з ключем id speech-провайдера. Застарілі прямі блоки (`messages.tts.openai`, `.elevenlabs`, `.microsoft`, `.edge`) переписуються командою `openclaw doctor --fix`; у commit додавайте лише `messages.tts.providers.`. + Налаштування, що належать провайдеру, з ключем за ідентифікатором speech-провайдера. Застарілі прямі блоки (`messages.tts.openai`, `.elevenlabs`, `.microsoft`, `.edge`) переписуються `openclaw doctor --fix`; комітьте лише `messages.tts.providers.`. - Жорстке обмеження кількості символів для вхідного TTS. `/tts audio` завершується помилкою при перевищенні. + Жорсткий ліміт символів для вхідного тексту TTS. `/tts audio` завершується помилкою, якщо його перевищено. Тайм-аут запиту в мілісекундах. - Перевизначає локальний JSON-шлях prefs (provider/limit/summary). За замовчуванням `~/.openclaw/settings/tts.json`. + Перевизначає шлях до JSON локальних налаштувань (provider/limit/summary). Типово `~/.openclaw/settings/tts.json`. Env: `AZURE_SPEECH_KEY`, `AZURE_SPEECH_API_KEY` або `SPEECH_KEY`. - Регіон Azure Speech (наприклад `eastus`). Env: `AZURE_SPEECH_REGION` або `SPEECH_REGION`. + Регіон Azure Speech (наприклад, `eastus`). Env: `AZURE_SPEECH_REGION` або `SPEECH_REGION`. Необов’язкове перевизначення endpoint Azure Speech (псевдонім `baseUrl`). - Azure voice ShortName. За замовчуванням `en-US-JennyNeural`. - Код мови SSML. За замовчуванням `en-US`. - Azure `X-Microsoft-OutputFormat` для стандартного аудіо. За замовчуванням `audio-24khz-48kbitrate-mono-mp3`. - Azure `X-Microsoft-OutputFormat` для виведення voice-note. За замовчуванням `ogg-24khz-16bit-mono-opus`. + ShortName голосу Azure. Типово `en-US-JennyNeural`. + Код мови SSML. Типово `en-US`. + Azure `X-Microsoft-OutputFormat` для стандартного аудіо. Типово `audio-24khz-48kbitrate-mono-mp3`. + Azure `X-Microsoft-OutputFormat` для виводу voice-note. Типово `ogg-24khz-16bit-mono-opus`. - Повертається до `ELEVENLABS_API_KEY` або `XI_API_KEY`. - id моделі (наприклад `eleven_multilingual_v2`, `eleven_v3`). - id голосу ElevenLabs. + Використовує як fallback `ELEVENLABS_API_KEY` або `XI_API_KEY`. + Ідентифікатор моделі (наприклад, `eleven_multilingual_v2`, `eleven_v3`). + Ідентифікатор голосу ElevenLabs. - `stability`, `similarityBoost`, `style` (кожне `0..1`), `useSpeakerBoost` (`true|false`), `speed` (`0.5..2.0`, `1.0` = нормально). + `stability`, `similarityBoost`, `style` (кожне `0..1`), `useSpeakerBoost` (`true|false`), `speed` (`0.5..2.0`, `1.0` = звичайна). Режим нормалізації тексту. - 2-літерний ISO 639-1 (наприклад `en`, `de`). + 2-літерний ISO 639-1 (наприклад, `en`, `de`). Ціле число `0..4294967295` для best-effort детермінованості. - Перевизначення базового URL API ElevenLabs. + Перевизначає базову URL-адресу API ElevenLabs. - Повертається до `GEMINI_API_KEY` / `GOOGLE_API_KEY`. Якщо пропущено, TTS може повторно використати `models.providers.google.apiKey` до повернення до env. - Модель Gemini TTS. За замовчуванням `gemini-3.1-flash-tts-preview`. - Назва вбудованого голосу Gemini. За замовчуванням `Kore`. Псевдонім: `voice`. - Підказка стилю природною мовою, що додається перед промовленим текстом. - Необов’язкова мітка мовця, що додається перед промовленим текстом, коли ваш prompt використовує іменованого мовця. - Установіть `audio-profile-v1`, щоб обгорнути поля prompt активної persona в детерміновану структуру prompt Gemini TTS. - Додатковий текст prompt persona, специфічний для Google, який додається до Director's Notes шаблону. + Використовує як fallback `GEMINI_API_KEY` / `GOOGLE_API_KEY`. Якщо пропущено, TTS може повторно використати `models.providers.google.apiKey` перед fallback до env. + Модель Gemini TTS. Типово `gemini-3.1-flash-tts-preview`. + Назва вбудованого голосу Gemini. Типово `Kore`. Псевдонім: `voice`. + Запит стилю природною мовою, що додається перед озвучуваним текстом. + Необов’язкова мітка мовця, що додається перед озвучуваним текстом, коли ваш prompt використовує іменованого мовця. + Установіть `audio-profile-v1`, щоб обгорнути поля prompt активної персони в детерміновану структуру prompt Gemini TTS. + Додатковий текст prompt персони, специфічний для Google, який додається до Director's Notes шаблону. Приймається лише `https://generativelanguage.googleapis.com`. Env: `GRADIUM_API_KEY`. - За замовчуванням `https://api.gradium.ai`. - За замовчуванням Emma (`YTpq7expH9539ERJ`). + Типово `https://api.gradium.ai`. + Типово Emma (`YTpq7expH9539ERJ`). Env: `INWORLD_API_KEY`. - За замовчуванням `https://api.inworld.ai`. - За замовчуванням `inworld-tts-1.5-max`. Також: `inworld-tts-1.5-mini`, `inworld-tts-1-max`, `inworld-tts-1`. - За замовчуванням `Sarah`. - Температура семплінгу `0..2`. + Типово `https://api.inworld.ai`. + Типово `inworld-tts-1.5-max`. Також: `inworld-tts-1.5-mini`, `inworld-tts-1-max`, `inworld-tts-1`. + Типово `Sarah`. + Температура семплювання `0..2`. Локальний виконуваний файл або рядок команди для CLI TTS. - Аргументи команди. Підтримує плейсхолдери `{{Text}}`, `{{OutputPath}}`, `{{OutputDir}}`, `{{OutputBase}}`. - Очікуваний формат виведення CLI. За замовчуванням `mp3` для аудіовкладень. - Тайм-аут команди в мілісекундах. За замовчуванням `120000`. + Аргументи команди. Підтримує placeholders `{{Text}}`, `{{OutputPath}}`, `{{OutputDir}}`, `{{OutputBase}}`. + Очікуваний формат виводу CLI. Типово `mp3` для аудіовкладень. + Тайм-аут команди в мілісекундах. Типово `120000`. Необов’язковий робочий каталог команди. Необов’язкові перевизначення середовища для команди. - Дозволити використання мовлення Microsoft. - Назва neural-голосу Microsoft (наприклад `en-US-MichelleNeural`). - Код мови (наприклад `en-US`). - Формат виведення Microsoft. За замовчуванням `audio-24khz-48kbitrate-mono-mp3`. Не всі формати підтримуються вбудованим транспортом на базі Edge. - Рядки відсотків (наприклад `+10%`, `-5%`). - Записувати JSON subtitles поруч з аудіофайлом. - URL proxy для запитів мовлення Microsoft. + Дозволяє використання Microsoft speech. + Назва neural-голосу Microsoft (наприклад, `en-US-MichelleNeural`). + Код мови (наприклад, `en-US`). + Формат виводу Microsoft. Типово `audio-24khz-48kbitrate-mono-mp3`. Не всі формати підтримуються вбудованим transport на базі Edge. + Рядки відсотків (наприклад, `+10%`, `-5%`). + Записує JSON-субтитри поруч з аудіофайлом. + URL-адреса proxy для запитів speech Microsoft. Перевизначення тайм-ауту запиту (мс). - Застарілий псевдонім. Запустіть `openclaw doctor --fix`, щоб переписати збережену конфігурацію на `providers.microsoft`. + Застарілий псевдонім. Запустіть `openclaw doctor --fix`, щоб переписати збережену конфігурацію в `providers.microsoft`. - Повертається до `MINIMAX_API_KEY`. Автентифікація Token Plan через `MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY` або `MINIMAX_CODING_API_KEY`. - За замовчуванням `https://api.minimax.io`. Env: `MINIMAX_API_HOST`. - За замовчуванням `speech-2.8-hd`. Env: `MINIMAX_TTS_MODEL`. - За замовчуванням `English_expressive_narrator`. Env: `MINIMAX_TTS_VOICE_ID`. - `0.5..2.0`. За замовчуванням `1.0`. - `(0, 10]`. За замовчуванням `1.0`. - Ціле число `-12..12`. За замовчуванням `0`. Дробові значення відкидаються перед запитом. + Використовує як fallback `MINIMAX_API_KEY`. Auth Token Plan через `MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY` або `MINIMAX_CODING_API_KEY`. + Типово `https://api.minimax.io`. Env: `MINIMAX_API_HOST`. + Типово `speech-2.8-hd`. Env: `MINIMAX_TTS_MODEL`. + Типово `English_expressive_narrator`. Env: `MINIMAX_TTS_VOICE_ID`. + `0.5..2.0`. Типово `1.0`. + `(0, 10]`. Типово `1.0`. + Ціле число `-12..12`. Типово `0`. Дробові значення відкидаються перед запитом. - Повертається до `OPENAI_API_KEY`. - id моделі OpenAI TTS (наприклад `gpt-4o-mini-tts`). - Назва голосу (наприклад `alloy`, `cedar`). - Явне поле OpenAI `instructions`. Коли задано, поля prompt persona **не** відображаються автоматично. + Використовує як fallback `OPENAI_API_KEY`. + Ідентифікатор моделі OpenAI TTS (наприклад, `gpt-4o-mini-tts`). + Назва голосу (наприклад, `alloy`, `cedar`). + Явне поле OpenAI `instructions`. Коли встановлено, поля prompt персони **не** зіставляються автоматично. - Перевизначає endpoint OpenAI TTS. Порядок визначення: config → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`. Значення, відмінні від стандартного, вважаються OpenAI-сумісними endpoint-ами TTS, тому дозволяються користувацькі назви моделей і голосів. + Перевизначає endpoint OpenAI TTS. Порядок визначення: config → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`. Нестандартні значення розглядаються як OpenAI-сумісні endpoints TTS, тому приймаються власні назви моделей і голосів. Env: `OPENROUTER_API_KEY`. Може повторно використовувати `models.providers.openrouter.apiKey`. - За замовчуванням `https://openrouter.ai/api/v1`. Застаріле `https://openrouter.ai/v1` нормалізується. - За замовчуванням `hexgrad/kokoro-82m`. Псевдонім: `modelId`. - За замовчуванням `af_alloy`. Псевдонім: `voiceId`. - За замовчуванням `mp3`. + Типово `https://openrouter.ai/api/v1`. Застаріле `https://openrouter.ai/v1` нормалізується. + Типово `hexgrad/kokoro-82m`. Псевдонім: `modelId`. + Типово `af_alloy`. Псевдонім: `voiceId`. + Типово `mp3`. Нативне для провайдера перевизначення швидкості. Env: `VOLCENGINE_TTS_API_KEY` або `BYTEPLUS_SEED_SPEECH_API_KEY`. - За замовчуванням `seed-tts-1.0`. Env: `VOLCENGINE_TTS_RESOURCE_ID`. Використовуйте `seed-tts-2.0`, коли ваш проєкт має entitlement на TTS 2.0. - Заголовок app key. За замовчуванням `aGjiRDfUWi`. Env: `VOLCENGINE_TTS_APP_KEY`. + Типово `seed-tts-1.0`. Env: `VOLCENGINE_TTS_RESOURCE_ID`. Використовуйте `seed-tts-2.0`, коли ваш проєкт має entitlement TTS 2.0. + Заголовок app key. Типово `aGjiRDfUWi`. Env: `VOLCENGINE_TTS_APP_KEY`. Перевизначає HTTP endpoint TTS Seed Speech. Env: `VOLCENGINE_TTS_BASE_URL`. - Тип голосу. За замовчуванням `en_female_anna_mars_bigtts`. Env: `VOLCENGINE_TTS_VOICE`. + Тип голосу. Типово `en_female_anna_mars_bigtts`. Env: `VOLCENGINE_TTS_VOICE`. Нативне для провайдера співвідношення швидкості. - Нативний для провайдера тег емоції. - Застарілі поля Volcengine Speech Console. Env: `VOLCENGINE_TTS_APPID`, `VOLCENGINE_TTS_TOKEN`, `VOLCENGINE_TTS_CLUSTER` (за замовчуванням `volcano_tts`). + Нативний для провайдера тег emotion. + Застарілі поля Volcengine Speech Console. Env: `VOLCENGINE_TTS_APPID`, `VOLCENGINE_TTS_TOKEN`, `VOLCENGINE_TTS_CLUSTER` (типово `volcano_tts`). Env: `XAI_API_KEY`. - За замовчуванням `https://api.x.ai/v1`. Env: `XAI_BASE_URL`. - За замовчуванням `eve`. Live voices: `ara`, `eve`, `leo`, `rex`, `sal`, `una`. - Код мови BCP-47 або `auto`. За замовчуванням `en`. - За замовчуванням `mp3`. + Типово `https://api.x.ai/v1`. Env: `XAI_BASE_URL`. + Типово `eve`. Live-голоси: `ara`, `eve`, `leo`, `rex`, `sal`, `una`. + Код мови BCP-47 або `auto`. Типово `en`. + Типово `mp3`. Нативне для провайдера перевизначення швидкості. Env: `XIAOMI_API_KEY`. - За замовчуванням `https://api.xiaomimimo.com/v1`. Env: `XIAOMI_BASE_URL`. - За замовчуванням `mimo-v2.5-tts`. Env: `XIAOMI_TTS_MODEL`. Також підтримується `mimo-v2-tts`. - За замовчуванням `mimo_default`. Env: `XIAOMI_TTS_VOICE`. - За замовчуванням `mp3`. Env: `XIAOMI_TTS_FORMAT`. - Необов’язкова інструкція стилю природною мовою, що надсилається як повідомлення користувача; не озвучується. + Типово `https://api.xiaomimimo.com/v1`. Env: `XIAOMI_BASE_URL`. + Типово `mimo-v2.5-tts`. Env: `XIAOMI_TTS_MODEL`. Також підтримує `mimo-v2-tts`. + Типово `mimo_default`. Env: `XIAOMI_TTS_VOICE`. + Типово `mp3`. Env: `XIAOMI_TTS_FORMAT`. + Необов’язкова інструкція стилю природною мовою, яка надсилається як повідомлення користувача; не озвучується. -## Інструмент агента +## Інструмент agent -Інструмент `tts` перетворює текст на мовлення і повертає аудіовкладення для +Інструмент `tts` перетворює текст на мовлення й повертає аудіовкладення для доставки у відповіді. У Feishu, Matrix, Telegram і WhatsApp аудіо доставляється як голосове повідомлення, а не як файлове вкладення. Feishu і -WhatsApp можуть транскодувати не-Opus виведення TTS на цьому шляху, коли `ffmpeg` -доступний. +WhatsApp можуть перекодовувати вивід TTS, що не є Opus, цим шляхом, коли доступний `ffmpeg`. WhatsApp надсилає аудіо через Baileys як голосову нотатку PTT (`audio` з -`ptt: true`) і надсилає видимий текст **окремо** від аудіо PTT, тому що +`ptt: true`) і надсилає видимий текст **окремо** від аудіо PTT, оскільки клієнти не завжди коректно відображають підписи до голосових нотаток. Інструмент приймає необов’язкові поля `channel` і `timeoutMs`; `timeoutMs` — це -тайм-аут запиту до провайдера на рівні окремого виклику в мілісекундах. +тайм-аут запиту до провайдера для кожного виклику в мілісекундах. ## Gateway RPC -| Метод | Призначення | +| Метод | Призначення | | ----------------- | ---------------------------------------- | -| `tts.status` | Прочитати поточний стан TTS і останню спробу. | -| `tts.enable` | Установити локальну auto-перевагу в `always`. | -| `tts.disable` | Установити локальну auto-перевагу в `off`. | -| `tts.convert` | Одноразове перетворення text → audio. | -| `tts.setProvider` | Установити локальну перевагу провайдера. | -| `tts.setPersona` | Установити локальну перевагу persona. | -| `tts.providers` | Перелічити налаштованих провайдерів і їхній стан. | +| `tts.status` | Зчитати поточний стан TTS і останню спробу. | +| `tts.enable` | Установити локальне налаштування auto на `always`. | +| `tts.disable` | Установити локальне налаштування auto на `off`. | +| `tts.convert` | Одноразове перетворення текст → аудіо. | +| `tts.setProvider` | Установити локальне налаштування провайдера. | +| `tts.setPersona` | Установити локальне налаштування персони. | +| `tts.providers` | Перелічити налаштованих провайдерів і стан. | ## Посилання на сервіси - [Посібник OpenAI з text-to-speech](https://platform.openai.com/docs/guides/text-to-speech) -- [Довідник OpenAI Audio API](https://platform.openai.com/docs/api-reference/audio) +- [Довідник API OpenAI Audio](https://platform.openai.com/docs/api-reference/audio) - [Azure Speech REST text-to-speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech) - [Провайдер Azure Speech](/uk/providers/azure-speech) - [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech) @@ -982,7 +982,7 @@ WhatsApp надсилає аудіо через Baileys як голосову н - [Volcengine TTS HTTP API](/uk/providers/volcengine#text-to-speech) - [Синтез мовлення Xiaomi MiMo](/uk/providers/xiaomi#text-to-speech) - [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts) -- [Формати виведення Microsoft Speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) +- [Формати виводу Microsoft Speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) - [xAI text to speech](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest) ## Пов’язане @@ -991,4 +991,4 @@ WhatsApp надсилає аудіо через Baileys як голосову н - [Генерація музики](/uk/tools/music-generation) - [Генерація відео](/uk/tools/video-generation) - [Slash-команди](/uk/tools/slash-commands) -- [Плагін голосових викликів](/uk/plugins/voice-call) +- [Plugin Voice call](/uk/plugins/voice-call) diff --git a/docs/uk/tools/video-generation.md b/docs/uk/tools/video-generation.md index 3cbbda64c..4c8493a29 100644 --- a/docs/uk/tools/video-generation.md +++ b/docs/uk/tools/video-generation.md @@ -1,40 +1,39 @@ --- read_when: - - Створення відео через агента - - Налаштування провайдерів і моделей для генерації відео + - Генерування відео через агента + - Налаштування провайдерів і моделей генерації відео - Розуміння параметрів інструмента `video_generate` sidebarTitle: Video generation -summary: Створюйте відео за допомогою `video_generate` з тексту, зображень або посилань на відео через 14 бекендів провайдерів +summary: Генеруйте відео через `video_generate` з тексту, зображення або посилань на відео в 14 бекендах провайдерів title: Генерація відео x-i18n: - generated_at: "2026-04-26T05:36:23Z" + generated_at: "2026-04-28T00:36:38Z" model: gpt-5.4 provider: openai - source_hash: b70f4d47318c822f06d979308a0e1fce87de40be9c213f64b4c815dcedba944b + source_hash: 7270b98c8f1f791555913de6c7ce119032b616083b62786a17f692fbd4aab1e6 source_path: tools/video-generation.md workflow: 15 --- -Агенти OpenClaw можуть створювати відео з текстових запитів, еталонних зображень або -наявних відео. Підтримуються чотирнадцять бекендів провайдерів, кожен із -різними варіантами моделей, режимами введення та наборами функцій. Агент -автоматично вибирає відповідного провайдера на основі вашої конфігурації та -доступних API-ключів. +Агенти OpenClaw можуть генерувати відео з текстових prompt, еталонних зображень або +наявних відео. Підтримується п’ятнадцять бекендів провайдерів, кожен із +різними варіантами моделей, режимами введення та наборами можливостей. Агент автоматично вибирає +потрібного провайдера на основі вашої конфігурації та доступних API-ключів. Інструмент `video_generate` з’являється лише тоді, коли доступний принаймні один провайдер -генерації відео. Якщо ви його не бачите серед інструментів агента, задайте +генерації відео. Якщо ви не бачите його серед інструментів агента, задайте API-ключ провайдера або налаштуйте `agents.defaults.videoGenerationModel`. -OpenClaw розглядає генерацію відео як три режими виконання: +OpenClaw розглядає генерацію відео як три режими середовища виконання: -- `generate` — запити text-to-video без еталонних медіафайлів. -- `imageToVideo` — запит містить одне або кілька еталонних зображень. -- `videoToVideo` — запит містить одне або кілька еталонних відео. +- `generate` — запити text-to-video без еталонних медіа. +- `imageToVideo` — запит містить одне або більше еталонних зображень. +- `videoToVideo` — запит містить одне або більше еталонних відео. -Провайдери можуть підтримувати будь-яку підмножину цих режимів. Інструмент -перевіряє активний режим перед надсиланням і показує підтримувані режими в `action=list`. +Провайдери можуть підтримувати будь-яку підмножину цих режимів. Інструмент перевіряє +активний режим перед надсиланням і повідомляє про підтримувані режими в `action=list`. ## Швидкий старт @@ -47,16 +46,16 @@ OpenClaw розглядає генерацію відео як три режим ``` - + ```bash openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview" ``` - > Згенеруй 5-секундне кінематографічне відео з дружнім лобстером, який катається на серфі на заході сонця. + > Згенеруй 5-секундне кінематографічне відео дружнього лобстера, який катається на серфі на заході сонця. - Агент автоматично викликає `video_generate`. Дозволяти інструмент - окремо не потрібно. + Агент автоматично викликає `video_generate`. Дозволений список інструментів + не потрібен. @@ -66,37 +65,37 @@ OpenClaw розглядає генерацію відео як три режим Генерація відео є асинхронною. Коли агент викликає `video_generate` у сесії: -1. OpenClaw надсилає запит провайдеру й одразу повертає ідентифікатор завдання. +1. OpenClaw надсилає запит провайдеру й одразу повертає ідентифікатор задачі. 2. Провайдер обробляє завдання у фоновому режимі (зазвичай від 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності). 3. Коли відео готове, OpenClaw пробуджує ту саму сесію внутрішньою подією завершення. -4. Агент публікує готове відео назад у вихідну розмову. +4. Агент публікує готове відео назад в оригінальну розмову. Поки завдання виконується, дубльовані виклики `video_generate` у тій самій -сесії повертають поточний статус завдання замість запуску ще однієї +сесії повертають поточний стан задачі замість запуску нової генерації. Використовуйте `openclaw tasks list` або `openclaw tasks show `, щоб -перевірити прогрес через CLI. +перевірити поступ із CLI. -Поза запусками агента, прив’язаними до сесії (наприклад, для прямих викликів інструмента), -інструмент повертається до вбудованої генерації та повертає фінальний шлях до медіафайлу +Поза запусками агента, прив’язаними до сесії (наприклад, прямі виклики інструмента), +інструмент повертається до вбудованої генерації та повертає остаточний шлях до медіафайлу в тому самому ході. -Згенеровані відеофайли зберігаються в керованому OpenClaw сховищі медіафайлів, якщо -провайдер повертає байти. Типове обмеження збереження для згенерованих відео відповідає -ліміту для відеомедіа, а `agents.defaults.mediaMaxMb` підвищує його для -більших рендерів. Якщо провайдер також повертає розміщений вихідний URL, OpenClaw -може передати цей URL замість помилки завдання, якщо локальне збереження -відхиляє занадто великий файл. +Згенеровані відеофайли зберігаються в керованому OpenClaw сховищі медіа, коли +провайдер повертає байти. Типове обмеження збереження згенерованого відео відповідає +ліміту відеомедіа, а `agents.defaults.mediaMaxMb` підвищує його для +більших рендерів. Якщо провайдер також повертає розміщений URL виходу, OpenClaw +може доставити цей URL замість помилки задачі, якщо локальне збереження +відхиляє завеликий файл. -### Життєвий цикл завдання +### Життєвий цикл задачі | Стан | Значення | | ----------- | ------------------------------------------------------------------------------------------------ | -| `queued` | Завдання створено, очікує, поки провайдер його прийме. | -| `running` | Провайдер обробляє запит (зазвичай від 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності). | -| `succeeded` | Відео готове; агент пробуджується та публікує його в розмові. | -| `failed` | Помилка провайдера або тайм-аут; агент пробуджується з деталями помилки. | +| `queued` | Задачу створено, вона очікує, доки провайдер її прийме. | +| `running` | Провайдер обробляє її (зазвичай від 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності). | +| `succeeded` | Відео готове; агент прокидається та публікує його в розмову. | +| `failed` | Помилка провайдера або тайм-аут; агент прокидається з відомостями про помилку. | -Перевіряйте статус через CLI: +Перевірка стану з CLI: ```bash openclaw tasks list @@ -104,55 +103,57 @@ openclaw tasks show openclaw tasks cancel ``` -Якщо для поточної сесії завдання відео вже має стан `queued` або `running`, -`video_generate` повертає статус наявного завдання замість запуску нового. -Використовуйте `action: "status"`, щоб перевірити явно без запуску нової +Якщо для поточної сесії задача відео вже має стан `queued` або `running`, +`video_generate` повертає стан наявної задачі замість запуску нової. +Використовуйте `action: "status"`, щоб явно перевірити стан без запуску нової генерації. ## Підтримувані провайдери -| Провайдер | Модель за замовчуванням | Текст | Еталонне зображення | Еталонне відео | Автентифікація | -| --------------------- | -------------------------------- | :---: | --------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- | -| Alibaba | `wan2.6-t2v` | ✓ | Так (віддалений URL) | Так (віддалений URL) | `MODELSTUDIO_API_KEY` | -| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | До 2 зображень (лише моделі I2V; перший і останній кадр) | — | `BYTEPLUS_API_KEY` | -| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | До 2 зображень (перший і останній кадр через role) | — | `BYTEPLUS_API_KEY` | -| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | До 9 еталонних зображень | До 3 відео | `BYTEPLUS_API_KEY` | -| ComfyUI | `workflow` | ✓ | 1 зображення | — | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` | -| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 зображення; до 9 із Seedance reference-to-video | До 3 відео з Seedance reference-to-video | `FAL_KEY` | -| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 зображення | 1 відео | `GEMINI_API_KEY` | -| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 зображення | — | `MINIMAX_API_KEY` або MiniMax OAuth | -| OpenAI | `sora-2` | ✓ | 1 зображення | 1 відео | `OPENAI_API_KEY` | -| Qwen | `wan2.6-t2v` | ✓ | Так (віддалений URL) | Так (віддалений URL) | `QWEN_API_KEY` | -| Runway | `gen4.5` | ✓ | 1 зображення | 1 відео | `RUNWAYML_API_SECRET` | -| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 зображення | — | `TOGETHER_API_KEY` | -| Vydra | `veo3` | ✓ | 1 зображення (`kling`) | — | `VYDRA_API_KEY` | -| xAI | `grok-imagine-video` | ✓ | 1 зображення першого кадру або до 7 `reference_image` | 1 відео | `XAI_API_KEY` | +| Провайдер | Типова модель | Текст | Еталонне зображення | Еталонне відео | Автентифікація | +| --------------------- | ------------------------------ | :---: | ---------------------------------------------------- | ----------------------------------------------- | --------------------------------------- | +| Alibaba | `wan2.6-t2v` | ✓ | Так (віддалений URL) | Так (віддалений URL) | `MODELSTUDIO_API_KEY` | +| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | До 2 зображень (лише моделі I2V; перший і останній кадр) | — | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | До 2 зображень (перший і останній кадр через роль) | — | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | До 9 еталонних зображень | До 3 відео | `BYTEPLUS_API_KEY` | +| ComfyUI | `workflow` | ✓ | 1 зображення | — | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` | +| DeepInfra | `Pixverse/Pixverse-T2V` | ✓ | — | — | `DEEPINFRA_API_KEY` | +| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 зображення; до 9 із Seedance reference-to-video | До 3 відео з Seedance reference-to-video | `FAL_KEY` | +| Google | `veo-3.1-fast-generate-preview`| ✓ | 1 зображення | 1 відео | `GEMINI_API_KEY` | +| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 зображення | — | `MINIMAX_API_KEY` або MiniMax OAuth | +| OpenAI | `sora-2` | ✓ | 1 зображення | 1 відео | `OPENAI_API_KEY` | +| Qwen | `wan2.6-t2v` | ✓ | Так (віддалений URL) | Так (віддалений URL) | `QWEN_API_KEY` | +| Runway | `gen4.5` | ✓ | 1 зображення | 1 відео | `RUNWAYML_API_SECRET` | +| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 зображення | — | `TOGETHER_API_KEY` | +| Vydra | `veo3` | ✓ | 1 зображення (`kling`) | — | `VYDRA_API_KEY` | +| xAI | `grok-imagine-video` | ✓ | 1 зображення першого кадру або до 7 `reference_image` | 1 відео | `XAI_API_KEY` | -Деякі провайдери приймають додаткові або альтернативні змінні середовища для API-ключів. Докладніше дивіться -на окремих [сторінках провайдерів](#related). +Деякі провайдери приймають додаткові або альтернативні змінні середовища API-ключів. Див. +окремі [сторінки провайдерів](#related) для подробиць. Запустіть `video_generate action=list`, щоб під час виконання переглянути доступних провайдерів, моделі та -режими виконання. +режими середовища виконання. ### Матриця можливостей -Явний контракт режимів, який використовують `video_generate`, контрактні тести та -спільний live sweep: +Явний контракт режимів, що використовується `video_generate`, контрактними тестами та +спільним live sweep: -| Провайдер | `generate` | `imageToVideo` | `videoToVideo` | Спільні live-режими сьогодні | -| --------- | :--------: | :------------: | :------------: | ----------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру потрібні віддалені відео-URL `http(s)` | -| BytePlus | ✓ | ✓ | — | `generate`, `imageToVideo` | -| ComfyUI | ✓ | ✓ | — | Не входить до спільного sweep; покриття, специфічне для workflow, міститься в тестах Comfy | -| fal | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` лише при використанні Seedance reference-to-video | -| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, оскільки поточний Gemini/Veo sweep на основі буфера не приймає такий ввід | -| MiniMax | ✓ | ✓ | — | `generate`, `imageToVideo` | -| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, оскільки цей шлях org/input наразі потребує доступу до inpaint/remix на боці провайдера | -| Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру потрібні віддалені відео-URL `http(s)` | -| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` виконується лише тоді, коли вибрана модель — `runway/gen4_aleph` | -| Together | ✓ | ✓ | — | `generate`, `imageToVideo` | -| Vydra | ✓ | ✓ | — | `generate`; спільний `imageToVideo` пропущено, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` вимагає віддалений URL зображення | -| xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру наразі потрібен віддалений MP4 URL | +| Провайдер | `generate` | `imageToVideo` | `videoToVideo` | Спільні live-канали сьогодні | +| --------- | :--------: | :------------: | :------------: | --------------------------------------------------------------------------------------------------------------------------------------- | +| Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` пропускається, оскільки цьому провайдеру потрібні віддалені URL відео `http(s)` | +| BytePlus | ✓ | ✓ | — | `generate`, `imageToVideo` | +| ComfyUI | ✓ | ✓ | — | Не входить до спільного sweep; покриття, специфічне для workflow, живе разом із тестами Comfy | +| DeepInfra | ✓ | — | — | `generate`; нативні схеми відео DeepInfra у комплектному контракті є text-to-video | +| fal | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` лише під час використання Seedance reference-to-video | +| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; спільний `videoToVideo` пропускається, оскільки поточний sweep Gemini/Veo на основі буфера не приймає це введення | +| MiniMax | ✓ | ✓ | — | `generate`, `imageToVideo` | +| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; спільний `videoToVideo` пропускається, оскільки цей шлях org/input зараз потребує доступу до provider-side inpaint/remix | +| Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` пропускається, оскільки цьому провайдеру потрібні віддалені URL відео `http(s)` | +| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` запускається лише тоді, коли вибрана модель — `runway/gen4_aleph` | +| Together | ✓ | ✓ | — | `generate`, `imageToVideo` | +| Vydra | ✓ | ✓ | — | `generate`; спільний `imageToVideo` пропускається, оскільки комплектний `veo3` є лише текстовим, а комплектний `kling` потребує віддалений URL зображення | +| xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` пропускається, оскільки цьому провайдеру наразі потрібен віддалений URL MP4 | ## Параметри інструмента @@ -167,32 +168,32 @@ openclaw tasks cancel Одне еталонне зображення (шлях або URL). Кілька еталонних зображень (до 9). -Необов’язкові підказки ролей для кожної позиції, паралельні об’єднаному списку зображень. +Необов’язкові підказки ролей за позиціями, паралельні до об’єднаного списку зображень. Канонічні значення: `first_frame`, `last_frame`, `reference_image`. Одне еталонне відео (шлях або URL). Кілька еталонних відео (до 4). -Необов’язкові підказки ролей для кожної позиції, паралельні об’єднаному списку відео. +Необов’язкові підказки ролей за позиціями, паралельні до об’єднаного списку відео. Канонічне значення: `reference_video`. -Одне еталонне аудіо (шлях або URL). Використовується для фонової музики або -еталону голосу, якщо провайдер підтримує аудіовхід. +Одне еталонне аудіо (шлях або URL). Використовується для фонового музичного супроводу або +еталона голосу, коли провайдер підтримує аудіовходи. Кілька еталонних аудіо (до 3). -Необов’язкові підказки ролей для кожної позиції, паралельні об’єднаному списку аудіо. +Необов’язкові підказки ролей за позиціями, паралельні до об’єднаного списку аудіо. Канонічне значення: `reference_audio`. -Підказки ролей передаються провайдеру як є. Канонічні значення походять із +Підказки ролей передаються провайдеру як є. Канонічні значення походять з об’єднання `VideoGenerationAssetRole`, але провайдери можуть приймати додаткові рядки ролей. Масиви `*Roles` не повинні містити більше записів, ніж -відповідний список еталонів; помилки на одиницю завершуються зрозумілою помилкою. -Використовуйте порожній рядок, щоб залишити слот незаповненим. Для xAI встановіть кожну роль зображення як -`reference_image`, щоб використовувати його режим генерації `reference_images`; опустіть +відповідний список еталонів; помилки на один елемент дають зрозуміле повідомлення. +Використовуйте порожній рядок, щоб залишити позицію незаданою. Для xAI встановлюйте для кожної ролі зображення +`reference_image`, щоб використовувати режим генерації `reference_images`; не вказуйте роль або використовуйте `first_frame` для image-to-video з одним зображенням. @@ -203,88 +204,88 @@ openclaw tasks cancel `480P`, `720P`, `768P` або `1080P`. - Цільова тривалість у секундах (округлюється до найближчого значення, яке підтримує провайдер). + Цільова тривалість у секундах (округлюється до найближчого значення, підтримуваного провайдером). -Підказка розміру, якщо провайдер її підтримує. +Підказка розміру, коли провайдер її підтримує. - Увімкнути згенероване аудіо у вихідному результаті, якщо підтримується. Відрізняється від `audioRef*` (вхідні дані). + Увімкнути згенероване аудіо у виході, коли це підтримується. Відрізняється від `audioRef*` (входів). -Увімкнути або вимкнути водяний знак провайдера, якщо підтримується. +Перемикає watermark провайдера, коли це підтримується. -`adaptive` — це специфічний для провайдера сигнальний маркер: він передається як є +`adaptive` — це sentinel, специфічний для провайдера: він передається як є провайдерам, які оголошують `adaptive` у своїх можливостях (наприклад, BytePlus -Seedance використовує його для автоматичного визначення співвідношення сторін із -розмірів вхідного зображення). Провайдери, які його не оголошують, показують це значення через -`details.ignoredOverrides` у результаті інструмента, щоб було видно, що його пропущено. +Seedance використовує його для автоматичного визначення співвідношення сторін за +розмірами вхідного зображення). Провайдери, які його не оголошують, показують значення через +`details.ignoredOverrides` у результаті інструмента, щоб було видно, що його проігноровано. ### Додатково - `"status"` повертає поточне завдання сесії; `"list"` перевіряє провайдерів. + `"status"` повертає поточну задачу сесії; `"list"` перевіряє провайдерів. Перевизначення провайдера/моделі (наприклад, `runway/gen4.5`). -Підказка для імені вихідного файла. +Підказка для назви вихідного файла. Необов’язковий тайм-аут запиту до провайдера в мілісекундах. Специфічні для провайдера параметри як JSON-об’єкт (наприклад, `{"seed": 42, "draft": true}`). Провайдери, які оголошують типізовану схему, перевіряють ключі та типи; невідомі - ключі або невідповідності пропускають кандидата під час fallback. Провайдери без + ключі або невідповідності пропускають кандидата під час резервного переходу. Провайдери без оголошеної схеми отримують параметри як є. Запустіть `video_generate action=list`, щоб побачити, що приймає кожен провайдер. Не всі провайдери підтримують усі параметри. OpenClaw нормалізує тривалість до -найближчого значення, яке підтримує провайдер, і переназначає трансформовані підказки геометрії, -наприклад size-to-aspect-ratio, коли fallback-провайдер надає іншу -поверхню керування. По-справжньому непідтримувані перевизначення ігноруються за принципом best effort -і повідомляються як попередження в результаті інструмента. Жорсткі обмеження можливостей -(наприклад, надто багато еталонних вхідних даних) завершуються помилкою ще до надсилання. Результати інструмента -показують застосовані налаштування; `details.normalization` фіксує будь-яке -перетворення від запитаного до застосованого. +найближчого значення, підтримуваного провайдером, і переназначає перекладені підказки геометрії, +наприклад перетворення size у aspectRatio, коли резервний провайдер надає іншу +поверхню керування. Справді непідтримувані перевизначення ігноруються по можливості +та повідомляються як попередження в результаті інструмента. Жорсткі обмеження можливостей +(наприклад, забагато еталонних входів) завершуються помилкою до надсилання. Результати інструмента +повідомляють про застосовані налаштування; `details.normalization` фіксує будь-яке +перетворення з запитаного на застосоване. -Еталонні вхідні дані вибирають режим виконання: +Еталонні входи вибирають режим середовища виконання: -- Немає еталонних медіафайлів → `generate` +- Немає еталонних медіа → `generate` - Будь-яке еталонне зображення → `imageToVideo` - Будь-яке еталонне відео → `videoToVideo` -- Еталонні аудіовхідні дані **не** змінюють визначений режим; вони застосовуються - поверх режиму, який вибирають еталонні зображення/відео, і працюють лише - з провайдерами, які оголошують `maxInputAudios`. +- Еталонні аудіовходи **не** змінюють визначений режим; вони застосовуються + поверх будь-якого режиму, який вибирають еталонні зображення/відео, і працюють + лише з провайдерами, що оголошують `maxInputAudios`. -Змішані еталонні зображення та відео не є стабільною спільною поверхнею можливостей. -Рекомендується використовувати один тип еталона на запит. +Змішані еталонні зображення й відео не є стабільною спільною поверхнею можливостей. +Для одного запиту краще використовувати один тип еталонів. -#### Fallback і типізовані параметри +#### Резервний перехід і типізовані параметри -Деякі перевірки можливостей застосовуються на рівні fallback, а не на межі -інструмента, тому запит, який перевищує ліміти основного провайдера, все ще -може виконатися на здатному fallback-провайдері: +Деякі перевірки можливостей застосовуються на рівні резервного переходу, а не на межі +інструмента, тому запит, що перевищує ліміти основного провайдера, усе ще може +виконатися на придатному резервному: -- Активний кандидат, який не оголошує `maxInputAudios` (або `0`), пропускається, якщо - запит містить еталонні аудіодані; буде спробувано наступного кандидата. -- Якщо `maxDurationSeconds` активного кандидата менше за запитане `durationSeconds` - і список `supportedDurationSeconds` не оголошено → кандидата пропускають. +- Активний кандидат, який не оголошує `maxInputAudios` (або має значення `0`), пропускається, коли + запит містить еталонні аудіо; пробується наступний кандидат. +- Активний кандидат має `maxDurationSeconds`, менший за запитаний `durationSeconds`, + і не має оголошеного списку `supportedDurationSeconds` → пропускається. - Запит містить `providerOptions`, а активний кандидат явно - оголошує типізовану схему `providerOptions` → кандидата пропускають, якщо надані ключі - відсутні в схемі або типи значень не збігаються. Провайдери без - оголошеної схеми отримують параметри як є (backward-compatible - pass-through). Провайдер може відмовитися від усіх provider options, + оголошує типізовану схему `providerOptions` → пропускається, якщо передані ключі + відсутні у схемі або типи значень не збігаються. Провайдери без + оголошеної схеми отримують параметри як є (зворотно сумісний + passthrough). Провайдер може відмовитися від усіх provider options, оголосивши порожню схему (`capabilities.providerOptions: {}`), що - призводить до того самого пропуску, що й невідповідність типів. + призводить до такого самого пропуску, як і невідповідність типів. -Перша причина пропуску в запиті записується на рівні `warn`, щоб оператори бачили, коли -їхній основний провайдер було пропущено; наступні пропуски записуються на рівні `debug`, щоб -довгі ланцюжки fallback не створювали зайвого шуму. Якщо кожного кандидата пропущено, сукупна -помилка містить причину пропуску для кожного. +Перша причина пропуску в запиті журналюється на рівні `warn`, щоб оператори бачили, коли +їхній основний провайдер було пропущено; наступні пропуски журналюються на рівні `debug`, щоб +довгі ланцюжки резервного переходу не створювали шум. Якщо пропущено кожного кандидата, агрегована +помилка містить причину пропуску для кожного з них. ## Дії | Дія | Що вона робить | | ---------- | ----------------------------------------------------------------------------------------------------------- | -| `generate` | Типова дія. Створює відео з указаного запиту та необов’язкових еталонних вхідних даних. | -| `status` | Перевіряє стан поточного відеозавдання для поточної сесії без запуску нової генерації. | +| `generate` | Типова дія. Створює відео з указаного prompt і необов’язкових еталонних входів. | +| `status` | Перевіряє стан поточної відеозадачі для поточної сесії без запуску нової генерації. | | `list` | Показує доступних провайдерів, моделі та їхні можливості. | ## Вибір моделі @@ -292,14 +293,14 @@ Seedance використовує його для автоматичного в OpenClaw визначає модель у такому порядку: 1. **Параметр інструмента `model`** — якщо агент указує його у виклику. -2. **`videoGenerationModel.primary`** із конфігурації. -3. **`videoGenerationModel.fallbacks`** по черзі. -4. **Автовизначення** — провайдери з дійсною автентифікацією, починаючи з - поточного провайдера за замовчуванням, а потім решта провайдерів в алфавітному +2. **`videoGenerationModel.primary`** з конфігурації. +3. **`videoGenerationModel.fallbacks`** у заданому порядку. +4. **Автовизначення** — провайдери, які мають дійсну автентифікацію, починаючи з + поточного типового провайдера, а потім решта провайдерів в алфавітному порядку. -Якщо провайдер завершується помилкою, автоматично виконується спроба з наступним кандидатом. Якщо всі -кандидати завершуються помилкою, помилка містить деталі кожної спроби. +Якщо провайдер завершується помилкою, автоматично пробується наступний кандидат. Якщо всі +кандидати завершуються помилкою, помилка містить подробиці кожної спроби. Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, щоб використовувати лише явні записи `model`, `primary` і `fallbacks`. @@ -331,14 +332,14 @@ OpenClaw визначає модель у такому порядку: `seedance-1-0-pro-t2v-250528`, `seedance-1-0-pro-fast-251015`, `seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`. - Моделі T2V (`*-t2v-*`) не приймають вхідні зображення; моделі I2V і + Моделі T2V (`*-t2v-*`) не приймають входи зображень; моделі I2V і загальні моделі `*-pro-*` підтримують одне еталонне зображення (перший - кадр). Передайте зображення позиційно або встановіть `role: "first_frame"`. + кадр). Передайте зображення позиційно або задайте `role: "first_frame"`. Ідентифікатори моделей T2V автоматично перемикаються на відповідний варіант I2V, коли надається зображення. Підтримувані ключі `providerOptions`: `seed` (number), `draft` (boolean — - примусово задає 480p), `camera_fixed` (boolean). + примусово 480p), `camera_fixed` (boolean). @@ -346,13 +347,13 @@ OpenClaw визначає модель у такому порядку: Ідентифікатор провайдера: `byteplus-seedance15`. Модель: `seedance-1-5-pro-251215`. - Використовує уніфікований API `content[]`. Підтримує не більше 2 вхідних зображень - (`first_frame` + `last_frame`). Усі вхідні дані мають бути віддаленими URL `https://`. - Встановіть `role: "first_frame"` / `"last_frame"` для кожного зображення або - передайте зображення позиційно. + Використовує уніфікований API `content[]`. Підтримує щонайбільше 2 вхідні зображення + (`first_frame` + `last_frame`). Усі входи мають бути віддаленими URL `https://`. + Установлюйте `role: "first_frame"` / `"last_frame"` для кожного зображення або + передавайте зображення позиційно. - `aspectRatio: "adaptive"` автоматично визначає співвідношення сторін із вхідного зображення. - `audio: true` відображається на `generate_audio`. `providerOptions.seed` + `aspectRatio: "adaptive"` автоматично визначає співвідношення з вхідного зображення. + `audio: true` перетворюється на `generate_audio`. `providerOptions.seed` (number) передається далі. @@ -363,25 +364,25 @@ OpenClaw визначає модель у такому порядку: `dreamina-seedance-2-0-fast-260128`. Використовує уніфікований API `content[]`. Підтримує до 9 еталонних зображень, - 3 еталонних відео та 3 еталонних аудіо. Усі вхідні дані мають бути віддаленими - URL `https://`. Установіть `role` для кожного ресурсу — підтримувані значення: + 3 еталонних відео та 3 еталонних аудіо. Усі входи мають бути віддаленими + URL `https://`. Задавайте `role` для кожного ресурсу — підтримувані значення: `"first_frame"`, `"last_frame"`, `"reference_image"`, `"reference_video"`, `"reference_audio"`. - `aspectRatio: "adaptive"` автоматично визначає співвідношення сторін із вхідного зображення. - `audio: true` відображається на `generate_audio`. `providerOptions.seed` + `aspectRatio: "adaptive"` автоматично визначає співвідношення з вхідного зображення. + `audio: true` перетворюється на `generate_audio`. `providerOptions.seed` (number) передається далі. - Виконання локально або в хмарі на основі workflow. Підтримує text-to-video та + Локальне або хмарне виконання на основі workflow. Підтримує text-to-video та image-to-video через налаштований граф. Використовує потік із чергою для довготривалих завдань. Більшість відеомоделей fal приймають одне еталонне зображення. Моделі Seedance 2.0 reference-to-video - приймають до 9 зображень, 3 відео та 3 еталонних аудіо, але - не більше 12 еталонних файлів загалом. + приймають до 9 зображень, 3 відео та 3 еталонних аудіо, при цьому + загальна кількість еталонних файлів не має перевищувати 12. Підтримує одне еталонне зображення або одне еталонне відео. @@ -390,39 +391,38 @@ OpenClaw визначає модель у такому порядку: Лише одне еталонне зображення. - Передається далі лише перевизначення `size`. Інші перевизначення стилю + Передається лише перевизначення `size`. Інші перевизначення стилю (`aspectRatio`, `resolution`, `audio`, `watermark`) ігноруються з попередженням. - Той самий бекенд DashScope, що й у Alibaba. Еталонні вхідні дані мають бути віддаленими + Той самий бекенд DashScope, що й у Alibaba. Еталонні входи мають бути віддаленими URL `http(s)`; локальні файли відхиляються одразу. Підтримує локальні файли через data URI. Для video-to-video потрібен - `runway/gen4_aleph`. Запуски лише з текстом підтримують співвідношення сторін - `16:9` і `9:16`. + `runway/gen4_aleph`. Текстові запуски показують співвідношення сторін `16:9` і `9:16`. Лише одне еталонне зображення. - Використовує `https://www.vydra.ai/api/v1` безпосередньо, щоб уникнути - перенаправлень, які скидають автентифікацію. `veo3` вбудовано лише як text-to-video; `kling` потребує - віддаленого URL зображення. + Використовує `https://www.vydra.ai/api/v1` безпосередньо, щоб уникнути перенаправлень, + які втрачають автентифікацію. `veo3` комплектно постачається лише як text-to-video; `kling` потребує + віддалений URL зображення. Підтримує text-to-video, image-to-video з одним зображенням першого кадру, до 7 - входів `reference_image` через xAI `reference_images`, а також потоки - віддаленого редагування/розширення відео. + входів `reference_image` через xAI `reference_images`, а також віддалені + потоки редагування/розширення відео. -## Режими можливостей провайдерів +## Режими можливостей провайдера Спільний контракт генерації відео підтримує можливості, специфічні для режиму, -а не лише плоскі агреговані ліміти. Нові реалізації провайдерів -мають надавати перевагу явним блокам режимів: +а не лише пласкі агреговані ліміти. Нові реалізації провайдерів +мають віддавати перевагу явним блокам режимів: ```typescript capabilities: { @@ -447,19 +447,19 @@ capabilities: { } ``` -Плоских агрегованих полів, таких як `maxInputImages` і `maxInputVideos`, -**недостатньо**, щоб оголосити підтримку режимів трансформації. Провайдери повинні +Пласкіх агрегованих полів, таких як `maxInputImages` і `maxInputVideos`, +**недостатньо**, щоб оголосити підтримку режимів перетворення. Провайдери мають явно оголошувати `generate`, `imageToVideo` і `videoToVideo`, щоб live- тести, контрактні тести та спільний інструмент `video_generate` могли детерміновано перевіряти підтримку режимів. -Коли одна модель у провайдера має ширшу підтримку еталонних вхідних даних, ніж +Коли одна модель у провайдера має ширшу підтримку еталонних входів, ніж решта, використовуйте `maxInputImagesByModel`, `maxInputVideosByModel` або `maxInputAudiosByModel` замість підвищення ліміту для всього режиму. ## Live-тести -Opt-in live-покриття для спільних вбудованих провайдерів: +Opt-in live-покриття для спільних комплектних провайдерів: ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts @@ -471,36 +471,36 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.liv pnpm test:live:media video ``` -Цей live-файл завантажує відсутні змінні середовища провайдерів із `~/.profile`, надає -перевагу live/env API-ключам перед збереженими профілями автентифікації за замовчуванням і запускає +Цей live-файл завантажує відсутні змінні середовища провайдерів із `~/.profile`, типово віддає +перевагу API-ключам із live/env перед збереженими auth profile і запускає безпечний для релізу smoke-тест за замовчуванням: -- `generate` для кожного провайдера у sweep, крім FAL. -- Односекундний запит про лобстера. +- `generate` для кожного провайдера в sweep, крім FAL. +- Односекундний prompt із лобстером. - Ліміт операції для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням). -FAL є opt-in, оскільки затримка черги на боці провайдера може домінувати -в часі релізу: +FAL є opt-in, оскільки затримка черги на стороні провайдера може домінувати у часі +релізу: ```bash pnpm test:live:media video --video-providers fal ``` Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені -режими трансформації, які спільний sweep може безпечно виконувати з локальними медіафайлами: +режими перетворення, які спільний sweep може безпечно перевіряти з локальними медіа: - `imageToVideo`, коли `capabilities.imageToVideo.enabled`. - `videoToVideo`, коли `capabilities.videoToVideo.enabled` і - провайдер/модель приймає локальне відео на основі буфера у спільному + провайдер/модель приймає локальне відеовведення на основі буфера в спільному sweep. -Наразі спільний live-режим `videoToVideo` охоплює лише `runway`, якщо ви +Сьогодні спільний live-канал `videoToVideo` охоплює `runway`, лише коли ви вибираєте `runway/gen4_aleph`. ## Конфігурація -Установіть модель генерації відео за замовчуванням у конфігурації OpenClaw: +Установіть типову модель генерації відео у вашій конфігурації OpenClaw: ```json5 { @@ -524,10 +524,10 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2 ## Пов’язане - [Alibaba Model Studio](/uk/providers/alibaba) -- [Фонові завдання](/uk/automation/tasks) — відстеження завдань для асинхронної генерації відео +- [Фонові задачі](/uk/automation/tasks) — відстеження задач для асинхронної генерації відео - [BytePlus](/uk/concepts/model-providers#byteplus-international) - [ComfyUI](/uk/providers/comfy) -- [Довідник із конфігурації](/uk/gateway/config-agents#agent-defaults) +- [Довідник з конфігурації](/uk/gateway/config-agents#agent-defaults) - [fal](/uk/providers/fal) - [Google (Gemini)](/uk/providers/google) - [MiniMax](/uk/providers/minimax)