From d1b5802b86811feeca49f49b52d23a30bcb13d68 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 10 Apr 2026 20:26:40 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/concepts/model-providers.md | 495 ++++++++--------- docs/uk/help/testing.md | 682 +++++++++++++----------- docs/uk/plugins/sdk-agent-harness.md | 192 +++++++ docs/uk/plugins/sdk-overview.md | 553 ++++++++++--------- docs/uk/plugins/sdk-provider-plugins.md | 354 ++++++------ docs/uk/plugins/sdk-runtime.md | 88 +-- 6 files changed, 1307 insertions(+), 1057 deletions(-) create mode 100644 docs/uk/plugins/sdk-agent-harness.md diff --git a/docs/uk/concepts/model-providers.md b/docs/uk/concepts/model-providers.md index d111e2402..f39dc7d6f 100644 --- a/docs/uk/concepts/model-providers.md +++ b/docs/uk/concepts/model-providers.md @@ -1,41 +1,41 @@ --- read_when: - Вам потрібен довідник із налаштування моделей для кожного постачальника окремо - - Вам потрібні приклади конфігурацій або команди CLI для початкового налаштування постачальників моделей -summary: Огляд постачальників моделей із прикладами конфігурацій і потоків CLI + - Вам потрібні приклади конфігурацій або команд онбордингу CLI для постачальників моделей +summary: Огляд постачальників моделей із прикладами конфігурацій + потоками CLI title: Постачальники моделей x-i18n: - generated_at: "2026-04-08T18:10:02Z" + generated_at: "2026-04-10T20:23:44Z" model: gpt-5.4 provider: openai - source_hash: 53e3141256781002bbe1d7e7b78724a18d061fcf36a203baae04a091b8c9ea1b + source_hash: f3d50795107077c7065773b5e545fae04b97f1d932a650d577b325d93bf25192 source_path: concepts/model-providers.md workflow: 15 --- # Постачальники моделей -Ця сторінка охоплює **постачальників LLM/моделей** (а не канали чату на кшталт WhatsApp/Telegram). +На цій сторінці описано **постачальників LLM/моделей** (а не канали чату, як-от WhatsApp/Telegram). Правила вибору моделей див. у [/concepts/models](/uk/concepts/models). ## Швидкі правила - Посилання на моделі використовують формат `provider/model` (приклад: `opencode/claude-opus-4-6`). -- Якщо ви задаєте `agents.defaults.models`, воно стає списком дозволених моделей. +- Якщо ви встановите `agents.defaults.models`, це стане allowlist. - Допоміжні команди CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- Резервні правила під час виконання, cooldown-перевірки та збереження перевизначень сеансу +- Резервні правила середовища виконання, перевірки cooldown і збереження session-override задокументовано в [/concepts/model-failover](/uk/concepts/model-failover). - `models.providers.*.models[].contextWindow` — це нативні метадані моделі; - `models.providers.*.models[].contextTokens` — це фактичне обмеження під час виконання. -- Плагіни постачальників можуть додавати каталоги моделей через `registerProvider({ catalog })`; + `models.providers.*.models[].contextTokens` — це фактичне обмеження середовища виконання. +- Плагіни постачальників можуть впроваджувати каталоги моделей через `registerProvider({ catalog })`; OpenClaw об’єднує цей вивід у `models.providers` перед записом `models.json`. - Маніфести постачальників можуть оголошувати `providerAuthEnvVars` і - `providerAuthAliases`, щоб загальні перевірки автентифікації на основі env і варіанти постачальників - не потребували завантаження runtime плагіна. Решта мапи env-змінних у ядрі тепер - потрібна лише для неплагінних/вбудованих постачальників і кількох випадків із загальним пріоритетом, - як-от початкове налаштування Anthropic із пріоритетом API-ключа. -- Плагіни постачальників також можуть володіти поведінкою runtime постачальника через + `providerAuthAliases`, щоб загальні перевірки автентифікації на основі env + і варіанти постачальників не потребували завантаження середовища виконання плагіна. Решта основної мапи env-змінних тепер + використовується лише для неплагінних/основних постачальників і кількох випадків + із загальним пріоритетом, таких як онбординг Anthropic із пріоритетом API-ключа. +- Плагіни постачальників також можуть володіти поведінкою середовища виконання постачальника через `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, @@ -53,175 +53,179 @@ x-i18n: `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, і `onModelSelected`. -- Примітка: `capabilities` runtime постачальника — це спільні метадані виконавця (сімейство постачальника, - особливості транскрипту/інструментів, підказки щодо транспорту/кешу). Це не те саме, - що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model), +- Примітка: runtime `capabilities` постачальника — це спільні метадані виконувача (сімейство постачальника, особливості стенограми/інструментів, підказки щодо транспорту/кешу). Це не те + саме, що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє плагін (текстовий inference, мовлення тощо). +- Вбудований постачальник `codex` працює в парі з вбудованим агентним середовищем Codex. + Використовуйте `codex/gpt-*`, коли вам потрібні керований Codex вхід, виявлення моделей, нативне + відновлення thread і виконання app-server. Звичайні посилання `openai/gpt-*` і надалі + використовують постачальника OpenAI та стандартний транспорт постачальників OpenClaw. -## Поведінка постачальника, якою володіє плагін +## Поведінка постачальників, якою володіє плагін -Тепер плагіни постачальників можуть володіти більшістю специфічної логіки постачальника, тоді як OpenClaw зберігає +Плагіни постачальників тепер можуть володіти більшістю специфічної для постачальника логіки, тоді як OpenClaw зберігає загальний цикл inference. Типовий поділ: -- `auth[].run` / `auth[].runNonInteractive`: постачальник володіє потоками початкового налаштування/входу +- `auth[].run` / `auth[].runNonInteractive`: постачальник володіє потоками онбордингу/входу для `openclaw onboard`, `openclaw models auth` і безголового налаштування - `wizard.setup` / `wizard.modelPicker`: постачальник володіє мітками вибору автентифікації, - застарілими псевдонімами, підказками щодо списку дозволених моделей для початкового налаштування і записами налаштування в пікерах онбордингу/моделей + застарілими псевдонімами, підказками allowlist для онбордингу та записами + налаштування в засобах вибору онбордингу/моделей - `catalog`: постачальник з’являється в `models.providers` - `normalizeModelId`: постачальник нормалізує застарілі/preview ідентифікатори моделей перед пошуком або канонізацією - `normalizeTransport`: постачальник нормалізує `api` / `baseUrl` сімейства транспорту - перед загальним збиранням моделі; OpenClaw спершу перевіряє відповідного постачальника, + перед загальним складанням моделі; OpenClaw спочатку перевіряє відповідного постачальника, потім інші плагіни постачальників із підтримкою хуків, доки один із них справді не змінить транспорт -- `normalizeConfig`: постачальник нормалізує конфігурацію `models.providers.` перед тим, - як runtime її використає; OpenClaw спершу перевіряє відповідного постачальника, потім інші +- `normalizeConfig`: постачальник нормалізує конфігурацію `models.providers.` перед + використанням у середовищі виконання; OpenClaw спочатку перевіряє відповідного постачальника, потім інші плагіни постачальників із підтримкою хуків, доки один із них справді не змінить конфігурацію. Якщо жоден - хук постачальника не переписує конфігурацію, вбудовані допоміжні засоби для сімейства Google - усе одно нормалізують підтримувані записи постачальників Google. -- `applyNativeStreamingUsageCompat`: постачальник застосовує сумісні переписування native streaming-usage, керовані endpoint, для конфігурованих постачальників -- `resolveConfigApiKey`: постачальник визначає автентифікацію через env-маркери для конфігурованих постачальників - без примусового завантаження повної runtime-автентифікації. `amazon-bedrock` також має - вбудований resolver AWS env-marker тут, хоча runtime-автентифікація Bedrock використовує + хук постачальника не переписує конфігурацію, вбудовані допоміжні засоби сімейства Google все одно + нормалізують підтримувані записи постачальників Google. +- `applyNativeStreamingUsageCompat`: постачальник застосовує переписування сумісності native streaming-usage на основі endpoint для конфігурованих постачальників +- `resolveConfigApiKey`: постачальник визначає автентифікацію маркерів env для конфігурованих постачальників + без примусового повного завантаження runtime-автентифікації. `amazon-bedrock` також має + тут вбудований розв’язувач маркерів AWS env, хоча runtime-автентифікація Bedrock використовує стандартний ланцюжок AWS SDK. -- `resolveSyntheticAuth`: постачальник може показувати доступність локальної/self-hosted або іншої - автентифікації на основі конфігурації без збереження секретів у відкритому вигляді -- `shouldDeferSyntheticProfileAuth`: постачальник може позначати збережені синтетичні заповнювачі профілів - як менш пріоритетні, ніж автентифікація на основі env/конфігурації +- `resolveSyntheticAuth`: постачальник може надавати доступність локальної/self-hosted або іншої + автентифікації на основі конфігурації без збереження відкритих секретів +- `shouldDeferSyntheticProfileAuth`: постачальник може позначати збережені synthetic profile + placeholders як нижчі за пріоритетом, ніж автентифікація на основі env/конфігурації - `resolveDynamicModel`: постачальник приймає ідентифікатори моделей, яких ще немає в локальному статичному каталозі -- `prepareDynamicModel`: постачальнику потрібно оновлення метаданих перед повторною спробою +- `prepareDynamicModel`: постачальнику потрібне оновлення метаданих перед повторною спробою динамічного визначення - `normalizeResolvedModel`: постачальнику потрібні переписування транспорту або base URL - `contributeResolvedModelCompat`: постачальник додає прапори сумісності для своїх - вендорських моделей, навіть коли вони надходять через інший сумісний транспорт -- `capabilities`: постачальник публікує особливості транскрипту/інструментів/сімейства постачальника -- `normalizeToolSchemas`: постачальник очищає схеми інструментів, перш ніж вбудований - виконавець їх побачить -- `inspectToolSchemas`: постачальник показує специфічні для транспорту попередження про схеми + вендорських моделей, навіть якщо вони надходять через інший сумісний транспорт +- `capabilities`: постачальник публікує особливості стенограми/інструментів/сімейства постачальника +- `normalizeToolSchemas`: постачальник очищає схеми інструментів перед тим, як вбудований + виконувач їх побачить +- `inspectToolSchemas`: постачальник показує попередження про схеми, специфічні для транспорту, після нормалізації -- `resolveReasoningOutputMode`: постачальник обирає нативні чи теговані +- `resolveReasoningOutputMode`: постачальник вибирає нативні або теговані контракти виводу reasoning -- `prepareExtraParams`: постачальник задає значення за замовчуванням або нормалізує параметри запиту для кожної моделі -- `createStreamFn`: постачальник замінює звичайний шлях потоку на повністю - власний транспорт -- `wrapStreamFn`: постачальник застосовує обгортки сумісності для заголовків/тіла/моделі запиту -- `resolveTransportTurnState`: постачальник надає нативні заголовки транспорту - або метадані на кожен хід +- `prepareExtraParams`: постачальник задає типові або нормалізує параметри запиту для кожної моделі +- `createStreamFn`: постачальник замінює звичайний шлях stream повністю + користувацьким транспортом +- `wrapStreamFn`: постачальник застосовує обгортки сумісності для заголовків/тіла запиту/моделі +- `resolveTransportTurnState`: постачальник надає нативні транспортні + заголовки або метадані для кожного ходу - `resolveWebSocketSessionPolicy`: постачальник надає нативні заголовки сесії WebSocket або політику cool-down сесії -- `createEmbeddingProvider`: постачальник володіє поведінкою embedding для пам’яті, коли вона - має належати плагіну постачальника, а не вбудованому комутатору embedding -- `formatApiKey`: постачальник форматує збережені профілі автентифікації у runtime-рядок - `apiKey`, очікуваний транспортом -- `refreshOAuth`: постачальник володіє оновленням OAuth, коли спільних - засобів оновлення `pi-ai` недостатньо -- `buildAuthDoctorHint`: постачальник додає вказівки з відновлення, коли оновлення OAuth +- `createEmbeddingProvider`: постачальник володіє поведінкою memory embedding, коли вона + належить плагіну постачальника, а не основному комутатору embedding +- `formatApiKey`: постачальник форматує збережені профілі автентифікації у runtime + рядок `apiKey`, очікуваний транспортом +- `refreshOAuth`: постачальник володіє оновленням OAuth, коли спільних оновлювачів `pi-ai` + недостатньо +- `buildAuthDoctorHint`: постачальник додає рекомендації з виправлення, коли оновлення OAuth не вдається - `matchesContextOverflowError`: постачальник розпізнає специфічні для постачальника - помилки переповнення context window, які загальні евристики пропустили б -- `classifyFailoverReason`: постачальник зіставляє специфічні для постачальника сирі помилки транспорту/API - з причинами failover, такими як rate limit або overload -- `isCacheTtlEligible`: постачальник вирішує, які upstream ідентифікатори моделей підтримують prompt-cache TTL + помилки переповнення вікна контексту, які загальні евристики пропустили б +- `classifyFailoverReason`: постачальник зіставляє специфічні для постачальника сирі транспортні/API + помилки з причинами failover, такими як rate limit або overload +- `isCacheTtlEligible`: постачальник визначає, які upstream ідентифікатори моделей підтримують prompt-cache TTL - `buildMissingAuthMessage`: постачальник замінює загальну помилку сховища автентифікації - специфічною для постачальника підказкою щодо відновлення -- `suppressBuiltInModel`: постачальник приховує застарілі upstream-рядки і може повертати - помилку, яка належить вендору, для прямих збоїв визначення -- `augmentModelCatalog`: постачальник додає синтетичні/фінальні рядки каталогу після + на специфічну для постачальника підказку з відновлення +- `suppressBuiltInModel`: постачальник приховує застарілі upstream рядки та може повертати + помилку, що належить вендору, для прямих збоїв визначення +- `augmentModelCatalog`: постачальник додає synthetic/final рядки каталогу після виявлення та об’єднання конфігурації -- `isBinaryThinking`: постачальник володіє UX бінарного thinking увімк./вимк. -- `supportsXHighThinking`: постачальник вмикає `xhigh` для вибраних моделей -- `resolveDefaultThinkingLevel`: постачальник володіє політикою `/think` за замовчуванням для +- `isBinaryThinking`: постачальник володіє UX для бінарного вмикання/вимикання thinking +- `supportsXHighThinking`: постачальник додає вибраним моделям підтримку `xhigh` +- `resolveDefaultThinkingLevel`: постачальник володіє типовою політикою `/think` для сімейства моделей -- `applyConfigDefaults`: постачальник застосовує глобальні значення за замовчуванням, специфічні для постачальника, +- `applyConfigDefaults`: постачальник застосовує глобальні типові значення, специфічні для постачальника, під час матеріалізації конфігурації на основі режиму автентифікації, env або сімейства моделей -- `isModernModelRef`: постачальник володіє зіставленням бажаних live/smoke моделей +- `isModernModelRef`: постачальник володіє зіставленням бажаних моделей для live/smoke - `prepareRuntimeAuth`: постачальник перетворює налаштовані облікові дані на короткоживучий runtime-токен -- `resolveUsageAuth`: постачальник визначає облікові дані використання/квот для `/usage` - і пов’язаних поверхонь статусу/звітності -- `fetchUsageSnapshot`: постачальник володіє отриманням/розбором endpoint використання, тоді як - ядро все ще володіє оболонкою зведення та форматуванням -- `onModelSelected`: постачальник виконує побічні дії після вибору моделі, такі як - телеметрія або керування сеансом, що належить постачальнику +- `resolveUsageAuth`: постачальник визначає облікові дані usage/quota для `/usage` + та пов’язаних поверхонь стану/звітності +- `fetchUsageSnapshot`: постачальник володіє отриманням/розбором endpoint usage, тоді як + core і далі володіє оболонкою підсумку та форматуванням +- `onModelSelected`: постачальник виконує побічні ефекти після вибору моделі, такі як + телеметрія або облік сесій, що належить постачальнику Поточні вбудовані приклади: - `anthropic`: резервна сумісність уперед для Claude 4.6, підказки з відновлення автентифікації, отримання - endpoint використання, метадані cache-TTL/сімейства постачальника та глобальні - значення конфігурації за замовчуванням з урахуванням автентифікації -- `amazon-bedrock`: визначення переповнення контексту та класифікація причин - failover для специфічних помилок Bedrock throttle/not-ready, а також - спільне сімейство повторного відтворення `anthropic-by-model` для захисту політики replay лише для Claude - на трафіку Anthropic -- `anthropic-vertex`: захист політики replay лише для Claude на трафіку - Anthropic-message + endpoint usage, метадані cache-TTL/сімейства постачальника та глобальні + типові значення конфігурації з урахуванням автентифікації +- `amazon-bedrock`: зіставлення переповнення контексту, яким володіє постачальник, і класифікація + причин failover для специфічних помилок Bedrock throttle/not-ready, а також + спільне сімейство повторного відтворення `anthropic-by-model` для захистів політики повторного відтворення + лише для Claude у трафіку Anthropic +- `anthropic-vertex`: захисти політики повторного відтворення лише для Claude в трафіку + повідомлень Anthropic - `openrouter`: наскрізні ідентифікатори моделей, обгортки запитів, підказки щодо можливостей постачальника, - очищення thought-signature Gemini на проксійованому трафіку Gemini, ін’єкція proxy - reasoning через сімейство потоків `openrouter-thinking`, пересилання метаданих - маршрутизації та політика cache-TTL -- `github-copilot`: початкове налаштування/вхід через пристрій, резервна сумісність моделей уперед, - підказки транскрипту Claude-thinking, обмін runtime-токенів і отримання endpoint - використання -- `openai`: резервна сумісність уперед для GPT-5.4, пряма нормалізація транспорту OpenAI, - підказки відсутньої автентифікації з урахуванням Codex, приглушення Spark, синтетичні - рядки каталогу OpenAI/Codex, політика thinking/live-model, нормалізація псевдонімів токенів використання - (`input` / `output` і сімейства `prompt` / `completion`), спільне сімейство потоків - `openai-responses-defaults` для нативних обгорток OpenAI/Codex, - метадані сімейства постачальника, вбудована реєстрація постачальника - генерації зображень для `gpt-image-1` і вбудована реєстрація постачальника - генерації відео для `sora-2` + санітизація Gemini thought-signature у проксійованому трафіку Gemini, впровадження proxy + reasoning через сімейство потоків `openrouter-thinking`, пересилання + метаданих маршрутизації та політика cache-TTL +- `github-copilot`: онбординг/вхід за пристроєм, резервна сумісність уперед для моделей, + підказки Claude-thinking для стенограм, обмін runtime-токенів і отримання + endpoint usage +- `openai`: резервна сумісність уперед для GPT-5.4, нормалізація прямого транспорту + OpenAI, підказки про відсутню автентифікацію з урахуванням Codex, придушення Spark, synthetic + рядки каталогу OpenAI/Codex, політика thinking/live-model, нормалізація псевдонімів usage-token + (`input` / `output` і сімейства `prompt` / `completion`), спільне + сімейство потоків `openai-responses-defaults` для нативних обгорток OpenAI/Codex, + метадані сімейства постачальника, реєстрація вбудованого постачальника генерації зображень + для `gpt-image-1` і реєстрація вбудованого постачальника генерації відео + для `sora-2` - `google` і `google-gemini-cli`: резервна сумісність уперед для Gemini 3.1, - нативна перевірка replay Gemini, очищення bootstrap replay, тегований - режим виводу reasoning, зіставлення сучасних моделей, вбудована реєстрація постачальника генерації зображень - для preview-моделей Gemini image і вбудована - реєстрація постачальника генерації відео для моделей Veo; OAuth Gemini CLI також - володіє форматуванням токенів профілю автентифікації, розбором токенів використання та отриманням - endpoint квот для поверхонь використання -- `moonshot`: спільний транспорт, нормалізація payload thinking, що належить плагіну -- `kilocode`: спільний транспорт, заголовки запитів, що належать плагіну, нормалізація payload reasoning, - очищення thought-signature proxy-Gemini і політика cache-TTL -- `zai`: резервна сумісність уперед для GLM-5, значення за замовчуванням `tool_stream`, політика cache-TTL, - політика binary-thinking/live-model і автентифікація використання + отримання квот; + нативна перевірка повторного відтворення Gemini, санітизація bootstrap replay, тегований + режим виводу reasoning, зіставлення сучасних моделей, реєстрація вбудованого постачальника + генерації зображень для моделей Gemini image-preview і вбудована + реєстрація постачальника генерації відео для моделей Veo; Gemini CLI OAuth також + володіє форматуванням токенів профілю автентифікації, розбором usage-token і отриманням + endpoint квот для поверхонь usage +- `moonshot`: спільний транспорт, нормалізація payload thinking, якою володіє плагін +- `kilocode`: спільний транспорт, заголовки запитів, якими володіє плагін, нормалізація payload reasoning, + санітизація proxy-Gemini thought-signature і політика cache-TTL +- `zai`: резервна сумісність уперед для GLM-5, типові значення `tool_stream`, політика cache-TTL, + політика binary-thinking/live-model і usage auth + отримання квот; невідомі ідентифікатори `glm-5*` синтезуються з вбудованого шаблону `glm-4.7` - `xai`: нативна нормалізація транспорту Responses, переписування псевдонімів `/fast` для - швидких варіантів Grok, значення за замовчуванням `tool_stream`, очищення схем інструментів / - payload reasoning для xAI і вбудована реєстрація постачальника генерації відео + швидких варіантів Grok, типовий `tool_stream`, очищення схем інструментів / + payload reasoning, специфічне для xAI, і реєстрація вбудованого постачальника генерації відео для `grok-imagine-video` -- `mistral`: метадані можливостей, що належать плагіну -- `opencode` і `opencode-go`: метадані можливостей, що належать плагіну, плюс - очищення thought-signature proxy-Gemini -- `alibaba`: каталог генерації відео, що належить плагіну, для прямих посилань на моделі Wan, - як-от `alibaba/wan2.6-t2v` -- `byteplus`: каталоги, що належать плагіну, плюс вбудована реєстрація постачальника генерації відео +- `mistral`: метадані можливостей, якими володіє плагін +- `opencode` і `opencode-go`: метадані можливостей, якими володіє плагін, плюс + санітизація proxy-Gemini thought-signature +- `alibaba`: каталог генерації відео, яким володіє плагін, для прямих посилань на моделі Wan, + таких як `alibaba/wan2.6-t2v` +- `byteplus`: каталоги, якими володіє плагін, плюс реєстрація вбудованого постачальника генерації відео для моделей Seedance text-to-video/image-to-video -- `fal`: вбудована реєстрація постачальника генерації відео для hosted third-party - реєстрація постачальника генерації зображень для моделей FLUX image плюс вбудована - реєстрація постачальника генерації відео для hosted third-party video models +- `fal`: реєстрація вбудованого постачальника генерації відео для розміщених сторонніх + моделей, реєстрація постачальника генерації зображень для моделей FLUX плюс вбудована + реєстрація постачальника генерації відео для розміщених сторонніх відеомоделей - `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway` і `volcengine`: - лише каталоги, що належать плагіну -- `qwen`: каталоги, що належать плагіну, для текстових моделей плюс спільні - реєстрації постачальників media-understanding і video-generation для його - мультимодальних поверхонь; генерація відео Qwen використовує стандартні відеоendpoint DashScope - з вбудованими моделями Wan, такими як `wan2.6-t2v` і `wan2.7-r2v` -- `runway`: реєстрація постачальника генерації відео, що належить плагіну, для нативних - моделей Runway на основі задач, таких як `gen4.5` -- `minimax`: каталоги, що належать плагіну, вбудована реєстрація постачальника генерації відео + лише каталоги, якими володіє плагін +- `qwen`: каталоги текстових моделей, якими володіє плагін, плюс спільні + реєстрації постачальників media-understanding і генерації відео для його + мультимодальних поверхонь; генерація відео Qwen використовує стандартні відеоendpoint-и DashScope + зі вбудованими моделями Wan, такими як `wan2.6-t2v` і `wan2.7-r2v` +- `runway`: реєстрація постачальника генерації відео, якою володіє плагін, для нативних + task-based моделей Runway, таких як `gen4.5` +- `minimax`: каталоги, якими володіє плагін, вбудована реєстрація постачальника генерації відео для відеомоделей Hailuo, вбудована реєстрація постачальника генерації зображень - для `image-01`, гібридний вибір політики replay Anthropic/OpenAI і логіка - автентифікації/знімків використання -- `together`: каталоги, що належать плагіну, плюс вбудована реєстрація постачальника генерації відео + для `image-01`, гібридний вибір політики повторного відтворення Anthropic/OpenAI + і логіка auth/snapshot usage +- `together`: каталоги, якими володіє плагін, плюс вбудована реєстрація постачальника генерації відео для відеомоделей Wan -- `xiaomi`: каталоги, що належать плагіну, плюс логіка автентифікації/знімків використання +- `xiaomi`: каталоги, якими володіє плагін, плюс логіка auth/snapshot usage -Тепер вбудований плагін `openai` володіє обома ідентифікаторами постачальника: `openai` і +Вбудований плагін `openai` тепер володіє обома ідентифікаторами постачальників: `openai` і `openai-codex`. -Це охоплює постачальників, які все ще вписуються в нормальні транспорти OpenClaw. Постачальник, -якому потрібен повністю власний виконавець запитів, — це окрема, глибша поверхня розширення. +Це охоплює постачальників, які все ще відповідають звичайним транспортам OpenClaw. Постачальник, +якому потрібен повністю користувацький виконувач запитів, — це окрема, глибша поверхня розширення. ## Ротація API-ключів @@ -231,19 +235,19 @@ x-i18n: - `_API_KEYS` (список через кому або крапку з комою) - `_API_KEY` (основний ключ) - `_API_KEY_*` (нумерований список, наприклад `_API_KEY_1`) -- Для постачальників Google `GOOGLE_API_KEY` також включено як резервний варіант. +- Для постачальників Google `GOOGLE_API_KEY` також включається як запасний варіант. - Порядок вибору ключів зберігає пріоритет і усуває дублікати значень. - Запити повторюються з наступним ключем лише у відповідях із rate limit (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, - `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання). -- Збої, не пов’язані з rate limit, завершуються негайно; ротація ключів не виконується. -- Коли всі кандидатні ключі зазнають невдачі, повертається фінальна помилка з останньої спроби. + `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт usage). +- Збої, не пов’язані з rate limit, завершуються одразу; ротація ключів не виконується. +- Якщо всі кандидатні ключі не спрацювали, повертається остання помилка з останньої спроби. ## Вбудовані постачальники (каталог pi-ai) -OpenClaw постачається з каталогом pi‑ai. Для цих постачальників **не потрібна** -конфігурація `models.providers`; достатньо налаштувати автентифікацію та вибрати модель. +OpenClaw постачається з каталогом pi‑ai. Ці постачальники **не** +потребують конфігурації `models.providers`; просто налаштуйте автентифікацію й виберіть модель. ### OpenAI @@ -252,18 +256,18 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення) - Приклади моделей: `openai/gpt-5.4`, `openai/gpt-5.4-pro` - CLI: `openclaw onboard --auth-choice openai-api-key` -- Транспорт за замовчуванням — `auto` (спочатку WebSocket, резервно SSE) -- Перевизначення для кожної моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- Warm-up OpenAI Responses WebSocket за замовчуванням увімкнено через `params.openaiWsWarmup` (`true`/`false`) +- Типовий транспорт — `auto` (спочатку WebSocket, запасний варіант SSE) +- Перевизначення для окремої моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) +- Warm-up 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` +- `/fast` і `params.fastMode` зіставляють прямі запити Responses `openai/*` із `service_tier=priority` на `api.openai.com` - Використовуйте `params.serviceTier`, якщо вам потрібен явний рівень замість спільного перемикача `/fast` - Приховані заголовки атрибуції OpenClaw (`originator`, `version`, - `User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не + `User-Agent`) застосовуються лише до нативного трафіку OpenAI до `api.openai.com`, а не до загальних OpenAI-сумісних проксі - Нативні маршрути OpenAI також зберігають `store` Responses, підказки prompt-cache і - формування payload сумісності reasoning OpenAI; проксі-маршрути цього не роблять -- `openai/gpt-5.3-codex-spark` навмисно приглушено в OpenClaw, оскільки live API OpenAI його відхиляє; Spark вважається доступним лише для Codex + формування payload для сумісності reasoning OpenAI; проксі-маршрути цього не роблять +- `openai/gpt-5.3-codex-spark` навмисно приглушено в OpenClaw, оскільки live API OpenAI його відхиляє; Spark вважається лише Codex ```json5 { @@ -278,9 +282,9 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Необов’язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (одне перевизначення) - Приклад моделі: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком, автентифікованим API-ключем і OAuth, надісланим на `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) -- Примітка Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож OpenClaw вважає повторне використання Claude CLI і `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. -- Токен налаштування Anthropic усе ще доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, якщо вони доступні. +- Прямі публічні запити Anthropic також підтримують спільний перемикач `/fast` і `params.fastMode`, зокрема для трафіку з автентифікацією через API-ключ і OAuth, надісланого на `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) +- Примітка Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволено, тому OpenClaw вважає повторне використання Claude CLI і `claude -p` дозволеними для цієї інтеграції, якщо Anthropic не опублікує нову політику. +- Anthropic setup-token і надалі доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw віддає перевагу повторному використанню Claude CLI і `claude -p`, коли це можливо. ```json5 { @@ -294,16 +298,16 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Автентифікація: OAuth (ChatGPT) - Приклад моделі: `openai-codex/gpt-5.4` - CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex` -- Транспорт за замовчуванням — `auto` (спочатку WebSocket, резервно SSE) -- Перевизначення для кожної моделі через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) +- Типовий транспорт — `auto` (спочатку WebSocket, запасний варіант SSE) +- Перевизначення для окремої моделі через `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-сумісних проксі -- Використовує той самий перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` -- `openai-codex/gpt-5.3-codex-spark` залишається доступною, коли каталог OAuth Codex її показує; залежить від entitlement -- `openai-codex/gpt-5.4` зберігає нативні `contextWindow = 1050000` і типові для runtime `contextTokens = 272000`; перевизначте обмеження runtime через `models.providers.openai-codex.models[].contextTokens` -- Примітка щодо політики: OAuth OpenAI Codex явно підтримується для зовнішніх інструментів/процесів, таких як OpenClaw. +- Має той самий спільний перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` +- `openai-codex/gpt-5.3-codex-spark` і далі доступний, коли каталог Codex OAuth його показує; залежить від entitlement +- `openai-codex/gpt-5.4` зберігає нативні `contextWindow = 1050000` і типові runtime `contextTokens = 272000`; перевизначте runtime-ліміт через `models.providers.openai-codex.models[].contextTokens` +- Примітка щодо політики: OAuth OpenAI Codex явно підтримується для зовнішніх інструментів/робочих процесів, таких як OpenClaw. ```json5 { @@ -325,9 +329,9 @@ OpenClaw постачається з каталогом pi‑ai. Для цих ### Інші розміщені варіанти у стилі підписки -- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud плюс зіставлення endpoint Alibaba DashScope і Coding Plan -- [MiniMax](/uk/providers/minimax): доступ MiniMax Coding Plan через OAuth або API-ключ -- [GLM Models](/uk/providers/glm): Z.AI Coding Plan або загальні API endpoint +- [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud плюс зіставлення endpoint-ів Alibaba DashScope і Coding Plan +- [MiniMax](/uk/providers/minimax): доступ через OAuth або API-ключ MiniMax Coding Plan +- [GLM Models](/uk/providers/glm): endpoint-и Z.AI Coding Plan або загальні API ### OpenCode @@ -347,31 +351,31 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Постачальник: `google` - Автентифікація: `GEMINI_API_KEY` -- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення) +- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, запасний варіант `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення) - Приклади моделей: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - Сумісність: застаріла конфігурація OpenClaw з `google/gemini-3.1-flash-preview` нормалізується до `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` - Прямі запуски Gemini також приймають `agents.defaults.models["google/"].params.cachedContent` - (або застаріле `cached_content`) для пересилання нативного для постачальника - дескриптора `cachedContents/...`; збіги кешу Gemini відображаються як OpenClaw `cacheRead` + (або застарілий `cached_content`) для пересилання нативного для постачальника + дескриптора `cachedContents/...`; cache hit-и Gemini відображаються як OpenClaw `cacheRead` ### Google Vertex і Gemini CLI - Постачальники: `google-vertex`, `google-gemini-cli` -- Автентифікація: Vertex використовує gcloud ADC; Gemini CLI використовує власний OAuth-потік -- Обережно: OAuth Gemini CLI в OpenClaw — це неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікових записів Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. -- OAuth Gemini CLI постачається як частина вбудованого плагіна `google`. +- Автентифікація: Vertex використовує gcloud ADC; Gemini CLI використовує свій потік OAuth +- Увага: Gemini CLI OAuth в OpenClaw — це неофіційна інтеграція. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. +- Gemini CLI OAuth постачається як частина вбудованого плагіна `google`. - Спочатку встановіть Gemini CLI: - `brew install gemini-cli` - або `npm install -g @google/gemini-cli` - Увімкнення: `openclaw plugins enable google` - Вхід: `openclaw models auth login --provider google-gemini-cli --set-default` - - Модель за замовчуванням: `google-gemini-cli/gemini-3-flash-preview` + - Типова модель: `google-gemini-cli/gemini-3-flash-preview` - Примітка: вам **не потрібно** вставляти client id або secret у `openclaw.json`. Потік входу CLI зберігає - токени в профілях автентифікації на хості gateway. - - Якщо після входу запити не працюють, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway. - - JSON-відповіді Gemini CLI аналізуються з `response`; використання резервно береться з - `stats`, а `stats.cached` нормалізується в OpenClaw `cacheRead`. + токени в профілях автентифікації на хості шлюзу. + - Якщо після входу запити не працюють, встановіть `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості шлюзу. + - JSON-відповіді Gemini CLI розбираються з `response`; usage резервно береться з + `stats`, а `stats.cached` нормалізується до OpenClaw `cacheRead`. ### Z.AI (GLM) @@ -396,37 +400,38 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Приклад моделі: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` - Base URL: `https://api.kilo.ai/api/gateway/` -- Статичний резервний каталог постачається з `kilocode/kilo/auto`; live - виявлення `https://api.kilo.ai/api/gateway/models` може додатково розширити runtime-каталог. +- Статичний запасний каталог постачається з `kilocode/kilo/auto`; live + виявлення `https://api.kilo.ai/api/gateway/models` може додатково розширити runtime + каталог. - Точна upstream-маршрутизація за `kilocode/kilo/auto` належить Kilo Gateway, а не жорстко закодована в OpenClaw. -Деталі налаштування див. у [/providers/kilocode](/uk/providers/kilocode). +Докладніше про налаштування див. у [/providers/kilocode](/uk/providers/kilocode). ### Інші вбудовані плагіни постачальників - OpenRouter: `openrouter` (`OPENROUTER_API_KEY`) - Приклад моделі: `openrouter/auto` -- OpenClaw застосовує задокументовані OpenRouter заголовки атрибуції застосунку лише тоді, коли +- OpenClaw застосовує задокументовані заголовки атрибуції застосунку OpenRouter лише тоді, коли запит справді спрямовано на `openrouter.ai` -- Специфічні для OpenRouter маркери Anthropic `cache_control` так само обмежені +- Специфічні для OpenRouter маркери Anthropic `cache_control` так само обмежуються перевіреними маршрутами OpenRouter, а не довільними URL проксі -- OpenRouter залишається на проксі-подібному OpenAI-сумісному шляху, тому нативне +- OpenRouter і далі працює на шляху проксі-стилю, сумісному з OpenAI, тож нативне формування запитів лише для OpenAI (`serviceTier`, Responses `store`, - підказки prompt-cache, payload сумісності reasoning OpenAI) не пересилається -- Посилання OpenRouter на основі Gemini зберігають лише очищення thought-signature proxy-Gemini; - нативна перевірка replay Gemini і bootstrap-переписування залишаються вимкненими + підказки prompt-cache, payload-и сумісності reasoning OpenAI) не пересилається +- Посилання OpenRouter на базі Gemini зберігають лише шлях санітизації proxy-Gemini thought-signature; + нативна перевірка повторного відтворення Gemini та переписування bootstrap залишаються вимкненими - Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`) - Приклад моделі: `kilocode/kilo/auto` -- Посилання Kilo на основі Gemini зберігають той самий шлях очищення thought-signature - proxy-Gemini; `kilocode/kilo/auto` та інші підказки про непідтримку proxy-reasoning - пропускають ін’єкцію proxy reasoning +- Посилання Kilo на базі Gemini зберігають той самий шлях + санітизації proxy-Gemini thought-signature; `kilocode/kilo/auto` та інші підказки + без підтримки proxy-reasoning пропускають впровадження proxy reasoning - MiniMax: `minimax` (API-ключ) і `minimax-portal` (OAuth) - Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` - Приклад моделі: `minimax/MiniMax-M2.7` або `minimax-portal/MiniMax-M2.7` -- Початкове налаштування/API-ключ MiniMax записує явні визначення моделі M2.7 з - `input: ["text", "image"]`; вбудований каталог постачальника зберігає chat-посилання - лише текстовими, доки конфігурацію цього постачальника не буде матеріалізовано +- Онбординг MiniMax/налаштування API-ключа записує явні визначення моделі M2.7 з + `input: ["text", "image"]`; вбудований каталог постачальника зберігає chat refs + лише текстовими, доки не буде матеріалізовано конфігурацію цього постачальника - Moonshot: `moonshot` (`MOONSHOT_API_KEY`) - Приклад моделі: `moonshot/kimi-k2.5` - Kimi Coding: `kimi` (`KIMI_API_KEY` або `KIMICODE_API_KEY`) @@ -455,32 +460,32 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Нативні вбудовані запити xAI використовують шлях xAI Responses - `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast` - - `tool_stream` за замовчуванням увімкнений; задайте - `agents.defaults.models["xai/"].params.tool_stream` як `false`, щоб - вимкнути його + - `tool_stream` типово ввімкнено; установіть + `agents.defaults.models["xai/"].params.tool_stream` у `false`, щоб + його вимкнути - Mistral: `mistral` (`MISTRAL_API_KEY`) - Приклад моделі: `mistral/mistral-large-latest` - CLI: `openclaw onboard --auth-choice mistral-api-key` - Groq: `groq` (`GROQ_API_KEY`) - Cerebras: `cerebras` (`CEREBRAS_API_KEY`) - - Моделі GLM на Cerebras використовують ідентифікатори `zai-glm-4.7` і `zai-glm-4.6`. - - OpenAI-сумісний base URL: `https://api.cerebras.ai/v1`. + - Моделі GLM у Cerebras використовують ідентифікатори `zai-glm-4.7` і `zai-glm-4.6`. + - Base URL, сумісний з OpenAI: `https://api.cerebras.ai/v1`. - GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`) - Приклад моделі Hugging Face Inference: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. Див. [Hugging Face (Inference)](/uk/providers/huggingface). -## Постачальники через `models.providers` (custom/base URL) +## Постачальники через `models.providers` (користувацький/base URL) -Використовуйте `models.providers` (або `models.json`), щоб додати **власних** постачальників або -OpenAI/Anthropic‑сумісні проксі. +Використовуйте `models.providers` (або `models.json`), щоб додати **користувацьких** постачальників або +OpenAI/Anthropic-сумісні проксі. -Багато з наведених нижче вбудованих плагінів постачальників уже публікують каталог за замовчуванням. +Багато з наведених нижче вбудованих плагінів постачальників уже публікують типовий каталог. Використовуйте явні записи `models.providers.` лише тоді, коли хочете перевизначити -base URL, заголовки або список моделей за замовчуванням. +типовий base URL, заголовки або список моделей. ### Moonshot AI (Kimi) -Moonshot постачається як вбудований плагін постачальника. Використовуйте вбудованого постачальника -за замовчуванням і додавайте явний запис `models.providers.moonshot` лише тоді, коли +Moonshot постачається як вбудований плагін постачальника. Типово використовуйте вбудованого постачальника, +і додавайте явний запис `models.providers.moonshot` лише тоді, коли потрібно перевизначити base URL або метадані моделі: - Постачальник: `moonshot` @@ -541,7 +546,7 @@ Kimi Coding використовує Anthropic-сумісний endpoint Moonsho Volcano Engine (火山引擎) надає доступ до Doubao та інших моделей у Китаї. -- Постачальник: `volcengine` (для coding: `volcengine-plan`) +- Постачальник: `volcengine` (coding: `volcengine-plan`) - Автентифікація: `VOLCANO_ENGINE_API_KEY` - Приклад моделі: `volcengine-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice volcengine-api-key` @@ -554,13 +559,13 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши } ``` -Початкове налаштування за замовчуванням використовує поверхню coding, але загальний каталог `volcengine/*` +Онбординг типово використовує coding surface, але загальний каталог `volcengine/*` реєструється одночасно. -У пікерах моделей під час початкового налаштування/конфігурування вибір автентифікації Volcengine віддає перевагу і рядкам +У засобах вибору моделей для онбордингу/налаштування вибір автентифікації Volcengine віддає перевагу і рядкам `volcengine/*`, і `volcengine-plan/*`. Якщо ці моделі ще не завантажено, -OpenClaw повертається до нефільтрованого каталогу замість того, щоб показувати порожній -пікер у межах постачальника. +OpenClaw повертається до нефільтрованого каталогу замість показу порожнього +засобу вибору в межах постачальника. Доступні моделі: @@ -570,7 +575,7 @@ OpenClaw повертається до нефільтрованого катал - `volcengine/glm-4-7-251222` (GLM 4.7) - `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K) -Моделі для coding (`volcengine-plan`): +Coding-моделі (`volcengine-plan`): - `volcengine-plan/ark-code-latest` - `volcengine-plan/doubao-seed-code` @@ -582,7 +587,7 @@ OpenClaw повертається до нефільтрованого катал BytePlus ARK надає міжнародним користувачам доступ до тих самих моделей, що й Volcano Engine. -- Постачальник: `byteplus` (для coding: `byteplus-plan`) +- Постачальник: `byteplus` (coding: `byteplus-plan`) - Автентифікація: `BYTEPLUS_API_KEY` - Приклад моделі: `byteplus-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice byteplus-api-key` @@ -595,13 +600,13 @@ BytePlus ARK надає міжнародним користувачам дост } ``` -Початкове налаштування за замовчуванням використовує поверхню coding, але загальний каталог `byteplus/*` +Онбординг типово використовує coding surface, але загальний каталог `byteplus/*` реєструється одночасно. -У пікерах моделей під час початкового налаштування/конфігурування вибір автентифікації BytePlus віддає перевагу і рядкам +У засобах вибору моделей для онбордингу/налаштування вибір автентифікації BytePlus віддає перевагу і рядкам `byteplus/*`, і `byteplus-plan/*`. Якщо ці моделі ще не завантажено, -OpenClaw повертається до нефільтрованого каталогу замість того, щоб показувати порожній -пікер у межах постачальника. +OpenClaw повертається до нефільтрованого каталогу замість показу порожнього +засобу вибору в межах постачальника. Доступні моделі: @@ -609,7 +614,7 @@ OpenClaw повертається до нефільтрованого катал - `byteplus/kimi-k2-5-260127` (Kimi K2.5) - `byteplus/glm-4-7-251222` (GLM 4.7) -Моделі для coding (`byteplus-plan`): +Coding-моделі (`byteplus-plan`): - `byteplus-plan/ark-code-latest` - `byteplus-plan/doubao-seed-code` @@ -647,36 +652,36 @@ Synthetic надає Anthropic-сумісні моделі через поста ### MiniMax -MiniMax налаштовується через `models.providers`, оскільки використовує власні endpoint: +MiniMax налаштовується через `models.providers`, оскільки використовує користувацькі endpoint-и: -- OAuth MiniMax (Global): `--auth-choice minimax-global-oauth` -- OAuth MiniMax (CN): `--auth-choice minimax-cn-oauth` -- API-ключ MiniMax (Global): `--auth-choice minimax-global-api` -- API-ключ MiniMax (CN): `--auth-choice minimax-cn-api` +- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` +- MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` +- MiniMax API-ключ (Global): `--auth-choice minimax-global-api` +- MiniMax API-ключ (CN): `--auth-choice minimax-cn-api` - Автентифікація: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` -Деталі налаштування, варіанти моделей і фрагменти конфігурації див. у [/providers/minimax](/uk/providers/minimax). +Докладніше про налаштування, варіанти моделей і фрагменти конфігурації див. у [/providers/minimax](/uk/providers/minimax). -На Anthropic-сумісному streaming-шляху MiniMax OpenClaw вимикає thinking за -замовчуванням, якщо ви явно його не задасте, а `/fast on` переписує +На Anthropic-сумісному streaming path MiniMax OpenClaw типово вимикає thinking, +якщо ви не ввімкнете його явно, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. Поділ можливостей, якими володіє плагін: -- Значення за замовчуванням для тексту/чату залишаються на `minimax/MiniMax-M2.7` +- Типові значення text/chat залишаються на `minimax/MiniMax-M2.7` - Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01` -- Розуміння зображень — це `MiniMax-VL-01`, що належить плагіну, на обох шляхах автентифікації MiniMax +- Розуміння зображень — це `MiniMax-VL-01`, яким володіє плагін, на обох шляхах автентифікації MiniMax - Вебпошук залишається на ідентифікаторі постачальника `minimax` ### Ollama -Ollama постачається як вбудований плагін постачальника і використовує нативний API Ollama: +Ollama постачається як вбудований плагін постачальника й використовує нативний API Ollama: - Постачальник: `ollama` - Автентифікація: не потрібна (локальний сервер) - Приклад моделі: `ollama/llama3.3` -- Установлення: [https://ollama.com/download](https://ollama.com/download) +- Встановлення: [https://ollama.com/download](https://ollama.com/download) ```bash # Встановіть Ollama, потім завантажте модель: @@ -691,26 +696,26 @@ ollama pull llama3.3 } ``` -Ollama локально виявляється за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте -його через `OLLAMA_API_KEY`, а вбудований плагін постачальника додає Ollama безпосередньо в -`openclaw onboard` і пікер моделей. Деталі початкового налаштування, cloud/local режиму та власної конфігурації див. у [/providers/ollama](/uk/providers/ollama). +Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте це через +`OLLAMA_API_KEY`, а вбудований плагін постачальника додає Ollama безпосередньо до +`openclaw onboard` і засобу вибору моделей. Докладніше про онбординг, режим cloud/local і користувацьку конфігурацію див. у [/providers/ollama](/uk/providers/ollama). ### vLLM vLLM постачається як вбудований плагін постачальника для локальних/self-hosted -серверів, сумісних з OpenAI: +OpenAI-сумісних серверів: - Постачальник: `vllm` - Автентифікація: необов’язкова (залежить від вашого сервера) -- Base URL за замовчуванням: `http://127.0.0.1:8000/v1` +- Типовий base URL: `http://127.0.0.1:8000/v1` -Щоб увімкнути автоматичне локальне виявлення (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації): +Щоб увімкнути локальне auto-discovery (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації): ```bash export VLLM_API_KEY="vllm-local" ``` -Потім задайте модель (замініть на один з ідентифікаторів, які повертає `/v1/models`): +Потім установіть модель (замініть на один з ідентифікаторів, які повертає `/v1/models`): ```json5 { @@ -720,25 +725,25 @@ export VLLM_API_KEY="vllm-local" } ``` -Деталі див. у [/providers/vllm](/uk/providers/vllm). +Докладніше див. у [/providers/vllm](/uk/providers/vllm). ### SGLang SGLang постачається як вбудований плагін постачальника для швидких self-hosted -серверів, сумісних з OpenAI: +OpenAI-сумісних серверів: - Постачальник: `sglang` - Автентифікація: необов’язкова (залежить від вашого сервера) -- Base URL за замовчуванням: `http://127.0.0.1:30000/v1` +- Типовий base URL: `http://127.0.0.1:30000/v1` -Щоб увімкнути автоматичне локальне виявлення (підійде будь-яке значення, якщо ваш сервер не +Щоб увімкнути локальне auto-discovery (підійде будь-яке значення, якщо ваш сервер не вимагає автентифікації): ```bash export SGLANG_API_KEY="sglang-local" ``` -Потім задайте модель (замініть на один з ідентифікаторів, які повертає `/v1/models`): +Потім установіть модель (замініть на один з ідентифікаторів, які повертає `/v1/models`): ```json5 { @@ -748,7 +753,7 @@ export SGLANG_API_KEY="sglang-local" } ``` -Деталі див. у [/providers/sglang](/uk/providers/sglang). +Докладніше див. у [/providers/sglang](/uk/providers/sglang). ### Локальні проксі (LM Studio, vLLM, LiteLLM тощо) @@ -771,7 +776,7 @@ export SGLANG_API_KEY="sglang-local" models: [ { id: "my-local-model", - name: "Local Model", + name: "Локальна модель", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, @@ -787,21 +792,21 @@ export SGLANG_API_KEY="sglang-local" Примітки: -- Для власних постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` необов’язкові. - Якщо їх не вказано, OpenClaw використовує такі значення за замовчуванням: +- Для користувацьких постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими. + Якщо їх не вказано, OpenClaw типово використовує: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- Рекомендовано: задавайте явні значення, що відповідають обмеженням вашого проксі/моделі. -- Для `api: "openai-completions"` на ненативних endpoint (будь-який непорожній `baseUrl`, хост якого не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникати помилок постачальника 400 для непідтримуваних ролей `developer`. -- Маршрути проксі-подібного OpenAI-сумісного типу також пропускають нативне формування запитів лише для OpenAI: +- Рекомендовано: установлюйте явні значення, що відповідають лімітам вашого проксі/моделі. +- Для `api: "openai-completions"` на ненативних endpoint-ах (будь-який непорожній `baseUrl`, хост якого не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникнути помилок постачальника 400 для непідтримуваних ролей `developer`. +- Маршрути проксі-стилю, сумісні з OpenAI, також пропускають нативне формування запитів лише для OpenAI: без `service_tier`, без Responses `store`, без підказок prompt-cache, без - формування payload сумісності reasoning OpenAI і без прихованих заголовків + формування payload для сумісності reasoning OpenAI і без прихованих заголовків атрибуції OpenClaw. -- Якщо `baseUrl` порожній/не вказаний, OpenClaw зберігає типову поведінку OpenAI (яка вказує на `api.openai.com`). -- З міркувань безпеки явне `compat.supportsDeveloperRole: true` все одно перевизначається на ненативних endpoint `openai-completions`. +- Якщо `baseUrl` порожній або не вказаний, OpenClaw зберігає типову поведінку OpenAI (яка спрямовується на `api.openai.com`). +- З міркувань безпеки явне `compat.supportsDeveloperRole: true` усе одно перевизначається на ненативних endpoint-ах `openai-completions`. ## Приклади CLI @@ -811,11 +816,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -Див. також: [/gateway/configuration](/uk/gateway/configuration), де наведено повні приклади конфігурації. +Див. також: [/gateway/configuration](/uk/gateway/configuration) для повних прикладів конфігурації. ## Пов’язане - [Models](/uk/concepts/models) — конфігурація моделей і псевдоніми -- [Model Failover](/uk/concepts/model-failover) — ланцюжки резервного перемикання та поведінка повторних спроб -- [Configuration Reference](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделі -- [Providers](/uk/providers) — посібники з налаштування для кожного постачальника +- [Model Failover](/uk/concepts/model-failover) — ланцюжки резервування та поведінка повторних спроб +- [Configuration Reference](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделей +- [Providers](/uk/providers) — посібники з налаштування для окремих постачальників diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 6b0225981..53bbb0e12 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,29 +1,29 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресійних тестів для помилок моделей/провайдерів - - Налагодження поведінки gateway та агента -summary: 'Набір для тестування: модульні/e2e/live набори, ранери Docker і що охоплює кожен тест' + - Додавання регресій для помилок моделі/провайдера + - Налагодження поведінки gateway + агента +summary: 'Набір для тестування: unit/e2e/live набори, Docker-раннери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-10T12:52:31Z" + generated_at: "2026-04-10T20:23:45Z" model: gpt-5.4 provider: openai - source_hash: 40f29e8db015921a0b6a928517b28440d49b5fb63701e68cb66a1297063012ab + source_hash: e24030b221699c7695ab5c87409a2646b7c5d014780a3482410c3375be8e3bd8 source_path: help/testing.md workflow: 15 --- # Тестування -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір раннерів Docker. +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-раннерів. Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює) -- Які команди запускати для типових робочих процесів (локально, перед push, налагодження) +- Які команди запускати для типових сценаріїв (локально, перед push, налагодження) - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів -- Як додавати регресійні тести для реальних проблем із моделями/провайдерами +- Як додавати регресії для реальних проблем із моделями/провайдерами ## Швидкий старт @@ -31,11 +31,11 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm test` - Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` -- Прямий цикл спостереження Vitest: `pnpm test:watch` -- Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Під час ітерацій над однією помилкою спочатку віддавайте перевагу цільовим запускам. +- Прямий цикл Vitest watch: `pnpm test:watch` +- Пряме націлення на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Під час ітерацій над однією помилкою спершу віддавайте перевагу цільовим запускам. - QA-сайт на базі Docker: `pnpm qa:lab:up` -- QA-ланка на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- QA-сценарій на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` Коли ви змінюєте тести або хочете більшої впевненості: @@ -45,164 +45,164 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): - Live-набір (моделі + gateway tool/image probes): `pnpm test:live` -- Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Порада: коли вам потрібен лише один збійний випадок, звужуйте live-тести за допомогою змінних середовища allowlist, описаних нижче. +Порада: коли вам потрібен лише один проблемний кейс, звужуйте live-тести через змінні середовища allowlist, описані нижче. -## Спеціальні QA-раннери +## QA-специфічні раннери -Ці команди використовуються поряд з основними наборами тестів, коли вам потрібен реалізм qa-lab: +Ці команди використовуються поряд з основними тестовими наборами, коли вам потрібен реалізм qa-lab: - `pnpm openclaw qa suite` - Запускає QA-сценарії з репозиторію безпосередньо на хості. - - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими gateway workers, до 64 workers або кількості вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати кількість workers, або `--concurrency 1` для старішої послідовної ланки. + - За замовчуванням запускає кілька вибраних сценаріїв паралельно в ізольованих gateway workers, до 64 workers або кількості вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати кількість workers, або `--concurrency 1` для старішого послідовного режиму. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. + - Запускає той самий QA-набір у тимчасовій Multipass Linux VM. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски перенаправляють підтримувані QA auth inputs, які практичні для guest: - ключі провайдерів на основі env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. + - Live-запуски передають у guest підтримувані QA-автентифікаційні входи, які практично використовувати там: + ключі провайдерів із env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через змонтований workspace. - - Записує звичайний QA-звіт і зведення, а також логи Multipass у + - Записує звичайний QA-звіт + summary, а також логи Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. + - Запускає QA-сайт на базі Docker для операторської QA-роботи. -## Набори тестів (що де запускається) +## Тестові набори (що де запускається) -Сприймайте набори як «зростаючий реалізм» (і зростаючу нестабільність/вартість): +Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): ### Unit / integration (типово) - Команда: `pnpm test` -- Конфіг: десять послідовних shard-запусків (`vitest.full-*.config.ts`) по наявних scoped Vitest projects -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і внесені до allowlist node-тести `ui`, що покриваються `vitest.unit.config.ts` +- Config: десять послідовних shard-запусків (`vitest.full-*.config.ts`) по наявних scoped Vitest projects +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelisted `ui` node-тести, охоплені `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - In-process integration-тести (gateway auth, routing, tooling, parsing, config) - - Детерміновані регресії для відомих помилок + - Детерміновані регресії для відомих багів - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним -- Примітка щодо projects: - - Ненацілений `pnpm test` тепер запускає одинадцять менших shard-конфігів (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного великого native root-project процесу. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - - `pnpm test --watch` як і раніше використовує граф projects native root `vitest.config.ts`, оскільки цикл спостереження з кількома shards непрактичний. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає витрат на запуск повного root project. - - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable source/test files; редагування config/setup, як і раніше, повертаються до ширшого повторного запуску root-project. - - Вибрані тести `plugin-sdk` і `commands` також маршрутизуються через окремі легкі lanes, які пропускають `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy files залишаються в наявних lanes. - - Вибрані helper source files `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними сусідніми тестами в цих легких lanes, щоб редагування helper не перезапускали повний важкий набір для цього каталогу. - - `auto-reply` тепер має три окремі buckets: top-level core helpers, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі harness reply перевантажувати дешеві status/chunk/token-тести. +- Примітка про projects: + - Ненацілений `pnpm test` тепер запускає одинадцять менших shard-конфігів (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного великого native root-project process. Це зменшує пікове RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. + - `pnpm test --watch` і далі використовує native root `vitest.config.ts` project graph, оскільки багатошардовий watch-цикл непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні file/directory targets через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff зачіпає лише routable source/test files; зміни config/setup, як і раніше, повертаються до широкого root-project rerun. + - Вибрані тести `plugin-sdk` і `commands` також маршрутизуються через окремі легкі lanes, які пропускають `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються в наявних lanes. + - Вибрані helper source files у `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними sibling tests у цих light lanes, щоб зміни helper не спричиняли повторний запуск усього важкого набору для цього каталогу. + - `auto-reply` тепер має три окремі buckets: top-level core helpers, top-level `reply.*` integration tests і піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі reply harness потрапляти до дешевих status/chunk/token tests. - Примітка про embedded runner: - - Коли ви змінюєте inputs для виявлення message-tool або runtime context compaction, - зберігайте обидва рівні покриття. + - Коли ви змінюєте входи виявлення message-tool або runtime context compaction, + зберігайте покриття на обох рівнях. - Додавайте сфокусовані helper-регресії для чистих меж routing/normalization. - - Також підтримуйте здоровими integration-набори embedded runner: + - Також підтримуйте в доброму стані embedded runner integration suites: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, - `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts`, і + `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - Ці набори перевіряють, що scoped ids і поведінка compaction усе ще проходять - через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є + через реальні шляхи `run.ts` / `compact.ts`; тести лише на helper-рівні не є достатньою заміною цим integration-шляхам. - Примітка про pool: - - Базовий конфіг Vitest тепер за замовчуванням використовує `threads`. - - Спільний конфіг Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e і live-конфігах. - - Root UI lane зберігає свій `jsdom` setup і optimizer, але тепер теж працює на спільному non-isolated runner. - - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільного конфіга Vitest. - - Спільний launcher `scripts/run-vitest.mjs` тепер також за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо хочете порівняти зі стандартною поведінкою V8. -- Примітка про швидку локальну ітерацію: - - `pnpm test:changed` маршрутизується через scoped lanes, коли змінені шляхи однозначно зіставляються з меншим набором. + - Базовий config Vitest тепер за замовчуванням використовує `threads`. + - Спільний config Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e і live configs. + - Root UI lane зберігає своє налаштування `jsdom` і optimizer, але тепер теж працює на спільному non-isolated runner. + - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільного config Vitest. + - Спільний launcher `scripts/run-vitest.mjs` тепер також за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. +- Примітка про швидкі локальні ітерації: + - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи однозначно відповідають меншому набору. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом workers. - - Автоматичне масштабування локальних workers тепер навмисно консервативне і також зменшується, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - - Базовий конфіг Vitest позначає файли projects/config як `forceRerunTriggers`, щоб reruns у changed-mode залишалися коректними, коли змінюється wiring тестів. - - Конфіг зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. -- Примітка про налагодження продуктивності: - - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість імпорту та вивід import-breakdown. + - Автомасштабування локальних workers тепер навмисно консервативніше і також відступає, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. + - Базовий config Vitest позначає projects/config files як `forceRerunTriggers`, щоб reruns у changed-mode залишалися коректними, коли змінюється wiring тестів. + - Config зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. +- Примітка про perf-debug: + - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість import, а також import-breakdown output. - `pnpm test:perf:imports:changed` обмежує той самий профільований вигляд файлами, зміненими відносно `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` з native root-project шляхом для цього committed diff і виводить wall time та max RSS на macOS. -- `pnpm test:perf:changed:bench -- --worktree` вимірює поточне брудне дерево, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфіг Vitest. - - `pnpm test:perf:profile:main` записує CPU-профіль main-thread для накладних витрат запуску та transform у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує CPU+heap профілі runner для unit-набору з вимкненим file parallelism. +- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` з native root-project path для цього закоміченого diff і виводить wall time та macOS max RSS. +- `pnpm test:perf:changed:bench -- --worktree` вимірює поточне брудне дерево, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root Vitest config. + - `pnpm test:perf:profile:main` записує CPU-профіль main thread для старту Vitest/Vite і transform overhead. + - `pnpm test:perf:profile:runner` записує CPU+heap-профілі runner для unit-набору з вимкненим файловим паралелізмом. ### E2E (gateway smoke) - Команда: `pnpm test:e2e` -- Конфіг: `vitest.e2e.config.ts` +- Config: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` - Типові параметри runtime: - Використовує Vitest `threads` з `isolate: false`, узгоджено з рештою репозиторію. - Використовує адаптивну кількість workers (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням працює в тихому режимі, щоб зменшити накладні витрати console I/O. + - За замовчуванням працює в тихому режимі, щоб зменшити накладні витрати на console I/O. - Корисні перевизначення: - `OPENCLAW_E2E_WORKERS=` щоб примусово встановити кількість workers (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у console. + - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний console output. - Обсяг: - End-to-end поведінка gateway з кількома інстансами - - Поверхні WebSocket/HTTP, node pairing і важче мережеве навантаження + - Поверхні WebSocket/HTTP, pairing вузлів і важчі мережеві сценарії - Очікування: - - Запускається в CI (коли увімкнено в pipeline) + - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Має більше рухомих частин, ніж unit-тести (може бути повільнішим) + - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) -### E2E: smoke для backend OpenShell +### E2E: smoke OpenShell backend - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` - Обсяг: - Запускає ізольований OpenShell gateway на хості через Docker - - Створює sandbox з тимчасового локального Dockerfile - - Перевіряє backend OpenShell у OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє поведінку remote-canonical filesystem через fs bridge sandbox + - Створює sandbox із тимчасового локального Dockerfile + - Перевіряє OpenClaw OpenShell backend через реальні `sandbox ssh-config` + SSH exec + - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge - Очікування: - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потребує локальний CLI `openshell` і працездатний Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує тестовий gateway і sandbox + - Потребує локального CLI `openshell` і працездатного Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує test gateway і sandbox - Корисні перевизначення: - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний бінарний файл CLI або wrapper script + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб вказати нестандартний CLI binary або wrapper script ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` -- Конфіг: `vitest.live.config.ts` +- Config: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts` - Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей tool calling, проблем auth і поведінки rate limit + - «Чи цей провайдер/модель справді працює _сьогодні_ з реальними обліковими даними?» + - Виявлення змін формату провайдера, особливостей tool calling, проблем автентифікації та поведінки rate limit - Очікування: - - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / використовує rate limits + - Навмисно нестабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштує грошей / використовує ліміти частоти - Краще запускати звужені підмножини, а не «все» -- Live-запуски підвантажують `~/.profile`, щоб отримати відсутні API-ключі. -- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють config/auth material у тимчасовий test home, щоб unit fixtures не могли змінити ваш реальний `~/.openclaw`. -- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення про `~/.profile` і вимикає логи bootstrap gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні startup logs. -- Ротація API-ключів (залежно від провайдера): установіть `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу при відповідях rate limit. +- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API keys. +- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють config/auth material у тимчасовий test home, щоб unit-fixtures не могли змінити ваш реальний `~/.openclaw`. +- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли свідомо хочете, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але прибирає додаткове повідомлення про `~/.profile` і приглушує логи bootstrap gateway/Bonjour chatter. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. +- Ротація API keys (залежно від провайдера): задайте `*_API_KEYS` у форматі кома/крапка з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використайте перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. - Вивід прогресу/heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдера було видно як активні навіть тоді, коли захоплення console у Vitest тихе. - - `vitest.live.config.ts` вимикає перехоплення console у Vitest, тому рядки прогресу provider/gateway транслюються негайно під час live-запусків. - - Налаштовуйте heartbeat для прямих викликів моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Live-набори тепер виводять рядки прогресу в stderr, щоб було видно активність під час довгих викликів провайдера, навіть коли захоплення console у Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення console у Vitest, тому рядки прогресу провайдера/gateway виводяться одразу під час live-запусків. + - Налаштовуйте heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Використовуйте таку таблицю рішень: +Користуйтеся цією таблицею рішень: -- Редагуєте логіку/тести: запустіть `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) -- Торкаєтесь gateway networking / WS protocol / pairing: додайте `pnpm test:e2e` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змін було багато) +- Торкаєтеся gateway networking / WS protocol / pairing: додайте `pnpm test:e2e` - Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / tool calling: запустіть звужений `pnpm test:live` -## Live: перевірка можливостей Android node +## Live: огляд можливостей Android node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яка наразі оголошена** підключеним Android node, і перевірити поведінку контракту команди. +- Мета: викликати **кожну команду, яка зараз оголошена** підключеним Android node, і перевірити поведінку контракту команд. - Обсяг: - - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не виконує pairing для застосунку). + - Попередньо підготовлене/ручне налаштування (набір не встановлює, не запускає і не виконує pairing застосунку). - Перевірка `node.invoke` у gateway для вибраного Android node, команда за командою. -- Обов’язкова попередня підготовка: - - Android app уже підключено й виконано pairing з gateway. +- Потрібна попередня підготовка: + - Android-застосунок уже підключений і paired до gateway. - Застосунок утримується на передньому плані. - Дозволи/згода на захоплення надані для можливостей, які ви очікуєте успішно пройти. - Необов’язкові перевизначення цілі: @@ -210,99 +210,99 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. - Повні відомості про налаштування Android: [Android App](/uk/platforms/android) -## Live: smoke для моделей (ключі профілів) +## Live: smoke моделей (ключі профілів) -Live-тести розділені на два рівні, щоб можна було ізолювати збої: +Live-тести поділено на два рівні, щоб ми могли ізолювати збої: -- «Direct model» показує, чи може провайдер/модель взагалі відповісти з наданим ключем. +- «Пряма модель» показує, чи провайдер/модель взагалі може відповісти з наданим ключем. - «Gateway smoke» показує, чи працює повний конвеєр gateway+agent для цієї моделі (сесії, історія, tools, sandbox policy тощо). -### Рівень 1: пряме завершення моделі без gateway +### Рівень 1: Пряме завершення моделі (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані - - Виконати невелике completion для кожної моделі (і цільові регресії, де потрібно) + - Виконати невелике завершення для кожної моделі (і цільові регресії там, де це потрібно) - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускати Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб реально запустити цей набір; інакше він буде пропущений, щоб `pnpm test:live` залишався зосередженим на gateway smoke +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запустити цей набір; інакше він буде пропущений, щоб `pnpm test:live` залишався зосередженим на gateway smoke - Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern` для запуску сучасного allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для сучасного allowlist + - `OPENCLAW_LIVE_MODELS=modern` для запуску modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Перевірки modern/all за замовчуванням мають curated high-signal limit; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для повної modern-перевірки або додатне число для меншого ліміту. + - Для modern/all sweeps за замовчуванням використовується підібране обмеження з високим сигналом; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого ліміту. - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: profile store і резервні значення з env - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** + - За замовчуванням: сховище профілів і резервні варіанти з env + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - - Відокремлює «API провайдера зламане / ключ недійсний» від «конвеєр gateway agent зламаний» - - Містить невеликі ізольовані регресії (приклад: відтворення reasoning replay + flows tool-call у OpenAI Responses/Codex Responses) + - Відокремлює «API провайдера зламаний / ключ недійсний» від «конвеєр gateway agent зламаний» + - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) -### Рівень 2: smoke gateway + dev agent (що насправді робить "@openclaw") +### Рівень 2: Gateway + smoke dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Підняти in-process gateway - - Створити/пропатчити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) - - Перебрати моделі з ключами й перевірити: + - Запустити in-process gateway + - Створити/оновити сесію `agent:dev:*` (з перевизначенням моделі для кожного запуску) + - Ітеруватися по моделях із ключами й перевіряти: - «змістовну» відповідь (без tools) - - що працює реальний виклик tool (read probe) - - необов’язкові додаткові tool probes (exec+read probe) - - що шляхи регресій OpenAI (лише tool-call → follow-up) продовжують працювати -- Деталі probe (щоб ви могли швидко пояснити збої): - - probe `read`: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce назад. - - probe `exec+read`: тест просить агента через `exec` записати nonce у тимчасовий файл, а потім через `read` зчитати його назад. - - image probe: тест прикріплює згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. + - що справжній виклик tool працює (read probe) + - необов’язкові додаткові перевірки tool (exec+read probe) + - що шляхи регресії OpenAI (лише tool-call → подальший крок) продовжують працювати +- Відомості про probes (щоб ви могли швидко пояснювати збої): + - `read` probe: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce. + - `exec+read` probe: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. + - image probe: тест прикріплює згенерований 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.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для сучасного allowlist + - За замовчуванням: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для modern allowlist - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір - - Перевірки modern/all для gateway за замовчуванням мають curated high-signal limit; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для повної modern-перевірки або додатне число для меншого ліміту. -- Як вибирати провайдерів (уникайте «усе через OpenRouter»): + - Для modern/all gateway sweeps за замовчуванням використовується підібране обмеження з високим сигналом; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого ліміту. +- Як вибирати провайдерів (щоб уникнути «всього OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) - Tool + image probes у цьому live-тесті завжди ввімкнені: - - probe `read` + probe `exec+read` (навантажувальна перевірка tools) + - `read` probe + `exec+read` probe (навантаження на tools) - image probe запускається, коли модель оголошує підтримку image input - Потік (на високому рівні): - - Тест генерує крихітний PNG з “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) + - Тест генерує маленький PNG із “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - Gateway розбирає attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - Embedded agent пересилає мультимодальне повідомлення користувача до моделі - - Перевірка: відповідь містить `cat` + код (OCR tolerance: незначні помилки допустимі) + - Перевірка: відповідь містить `cat` + код (допускається OCR tolerance: незначні помилки) -Порада: щоб побачити, що ви можете тестувати на своїй машині (і точні ідентифікатори `provider/model`), запустіть: +Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke для CLI backend (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke CLI backend (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent за допомогою локального CLI backend, не торкаючись вашого типового config. -- Типові параметри smoke для конкретного backend зберігаються у визначенні `cli-backend.ts` extension-власника. +- Мета: перевірити конвеєр Gateway + agent з використанням локального CLI backend, не торкаючись вашого типового config. +- Типові параметри smoke для конкретного backend містяться у визначенні `cli-backend.ts` відповідного extension. - Увімкнення: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускати Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Типові значення: - Типовий provider/model: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image береться з метаданих plugin CLI backend-власника. + - Поведінка command/args/image береться з метаданих plugin відповідного CLI backend. - Перевизначення (необов’язково): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати реальне image attachment (шляхи вставляються в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати справжнє image attachment (шляхи вставляються в prompt). - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` щоб передавати шляхи до image files як CLI args замість вставки в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`) щоб керувати тим, як передаються image args, коли встановлено `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` щоб надіслати другий хід і перевірити flow resume. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` щоб вимкнути типову перевірку безперервності тієї самої сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати передаванням image args, коли встановлено `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` щоб надіслати другий хід і перевірити потік resume. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` щоб вимкнути типову перевірку безперервності однієї сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -312,13 +312,13 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:live src/gateway/gateway-cli-backend.live.test.ts ``` -Рецепт Docker: +Docker-рецепт: ```bash pnpm test:docker:live-cli-backend ``` -Docker-рецепти для одного провайдера: +Docker-рецепти для окремих провайдерів: ```bash pnpm test:docker:live-cli-backend:claude @@ -330,27 +330,27 @@ pnpm test:docker:live-cli-backend:gemini Примітки: - Docker-раннер розташований у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає live smoke для CLI-backend усередині Docker image репозиторію як непривілейований користувач `node`. -- Він визначає метадані CLI smoke з extension-власника, а потім установлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований writable prefix за адресою `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 без збереження env vars Anthropic API-key. Ця subscription-ланка за замовчуванням вимикає Claude MCP/tool та image probes, оскільки Claude наразі маршрутизує використання сторонніх застосунків через виставлення рахунків за додаткове використання, а не через звичайні ліміти subscription plan. -- Live smoke CLI-backend тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик MCP tool `cron`, перевірений через gateway CLI. -- Типовий smoke для Claude також патчить сесію з Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Він запускає live smoke CLI-backend усередині Docker-образу репозиторію як непривілейований користувач `node`. +- Він визначає метадані CLI smoke із відповідного extension, а потім встановлює відповідний Linux CLI package (`@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 без збереження env-змінних API key Anthropic. Цей subscription lane за замовчуванням вимикає probes Claude MCP/tool та image, оскільки Claude наразі маршрутизує використання сторонніх застосунків через білінг extra-usage, а не звичайні ліміти subscription plan. +- Live smoke CLI-backend тепер перевіряє той самий повний потік end-to-end для Claude, Codex і Gemini: текстовий хід, хід класифікації image, потім виклик MCP tool `cron`, перевірений через gateway CLI. +- Типовий smoke для Claude також оновлює сесію з Sonnet до Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. -## Live: smoke прив’язки ACP (`/acp spawn ... --bind here`) +## Live: smoke ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний flow conversation-bind ACP з live ACP agent: +- Мета: перевірити реальний потік ACP conversation-bind із live ACP agent: - надіслати `/acp spawn --bind here` - - прив’язати синтетичну розмову message-channel на місці - - надіслати звичайне подальше повідомлення в тій самій розмові - - переконатися, що подальше повідомлення потрапляє до transcript прив’язаної сесії ACP + - прив’язати синтетичну conversation message-channel на місці + - надіслати звичайний подальший хід у тій самій conversation + - перевірити, що подальший хід потрапляє в transcript прив’язаної ACP session - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - ACP agents у Docker: `claude,codex,gemini` - ACP agent для прямого `pnpm test:live ...`: `claude` - - Синтетичний channel: контекст розмови у стилі Slack DM + - Синтетичний channel: контекст conversation у стилі Slack DM - ACP backend: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -359,8 +359,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Примітки: - - Ця ланка використовує поверхню gateway `chat.send` з admin-only synthetic originating-route fields, щоб тести могли прикріпити контекст message-channel без імітації зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного ACP harness agent. + - Цей lane використовує поверхню gateway `chat.send` з admin-only синтетичними полями originating-route, щоб тести могли прикріплювати контекст message-channel без імітації зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent плагіна `acpx` для вибраного ACP harness agent. Приклад: @@ -370,13 +370,13 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:live src/gateway/gateway-acp-bind.live.test.ts ``` -Рецепт Docker: +Docker-рецепт: ```bash pnpm test:docker:live-acp-bind ``` -Docker-рецепти для одного агента: +Docker-рецепти для окремих agent: ```bash pnpm test:docker:live-acp-bind:claude @@ -387,44 +387,89 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: - Docker-раннер розташований у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він послідовно запускає smoke прив’язки ACP для всіх підтримуваних live CLI agents: `claude`, `codex`, а потім `gemini`. +- За замовчуванням він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI agents: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він підвантажує `~/.profile`, переносить відповідний CLI auth material у контейнер, установлює `acpx` у writable npm prefix, а потім установлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. -- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env vars провайдера із завантаженого профілю доступними для дочірнього harness CLI. +- Він використовує `~/.profile`, підготовлює відповідний auth material CLI у контейнері, встановлює `acpx` у записуваний npm-префікс, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо він відсутній. +- Усередині Docker раннер установлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера із завантаженого профілю доступними для дочірнього harness CLI. + +## Live: smoke Codex app-server harness + +- Мета: перевірити harness Codex, що належить plugin, через звичайний метод gateway + `agent`: + - завантажити bundled plugin `codex` + - вибрати `OPENCLAW_AGENT_RUNTIME=codex` + - надіслати перший хід gateway agent до `codex/gpt-5.4` + - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що потік + app-server може відновитися +- Тест: `src/gateway/gateway-codex-harness.live.test.ts` +- Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` +- Типова модель: `codex/gpt-5.4` +- Необов’язковий image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Необов’язковий MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Автентифікація: `OPENAI_API_KEY` з shell/profile, а також необов’язково скопійовані + `~/.codex/auth.json` і `~/.codex/config.toml` + +Локальний рецепт: + +```bash +source ~/.profile +OPENCLAW_LIVE_CODEX_HARNESS=1 \ + OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1 \ + OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1 \ + OPENCLAW_LIVE_CODEX_HARNESS_MODEL=codex/gpt-5.4 \ + pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts +``` + +Docker-рецепт: + +```bash +source ~/.profile +pnpm test:docker:live-codex-harness +``` + +Примітки щодо Docker: + +- Docker-раннер розташований у `scripts/test-live-codex-harness-docker.sh`. +- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + автентифікації Codex CLI, якщо вони є, встановлює `@openai/codex` у записуваний змонтований npm- + префікс, готує дерево вихідного коду, а потім запускає лише live-тест Codex-harness. +- Docker за замовчуванням вмикає image та MCP/tool probes. Установіть + `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, коли вам потрібен вужчий налагоджувальний запуск. ### Рекомендовані live-рецепти -Найшвидшими та найменш нестабільними є вузькі, явні allowlist: +Вузькі, явні allowlist — найшвидші та найменш нестабільні: -- Одна модель, direct (без gateway): +- Одна модель, напряму (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` - Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool calling у кількох провайдерів: +- Tool calling для кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Фокус на Google (API-ключ Gemini + Antigravity): - - Gemini (API-ключ): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Фокус на Google (API key Gemini + Antigravity): + - Gemini (API key): `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` Примітки: -- `google/...` використовує Gemini API (API-ключ). +- `google/...` використовує Gemini API (API key). - `google-antigravity/...` використовує міст OAuth Antigravity (endpoint агента у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема auth + особливості tools). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості tools). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає хостований Gemini API від Google через HTTP (API-ключ / auth профілю); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw виконує shell-виклик локального бінарного файла `gemini`; він має власну auth і може поводитися інакше (streaming/tool support/version skew). + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (API key / автентифікація профілю); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw виконує локальний binary `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/tool support/version skew). ## Live: матриця моделей (що ми охоплюємо) -Фіксованого «списку моделей CI» немає (live є opt-in), але це **рекомендовані** моделі, які варто регулярно покривати на dev-машині з ключами. +Немає фіксованого «списку моделей для CI» (live — це opt-in), але ось **рекомендовані** моделі, які варто регулярно покривати на машині розробника з ключами. ### Сучасний smoke-набір (tool calling + image) -Це запуск «поширених моделей», який ми очікуємо зберігати працездатним: +Це запуск «поширених моделей», який ми очікуємо підтримувати робочим: - OpenAI (не-Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` @@ -434,12 +479,12 @@ pnpm test:docker:live-acp-bind:gemini - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запускати gateway smoke з tools + image: +Запуск gateway smoke з tools + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` ### Базовий рівень: tool calling (Read + необов’язковий Exec) -Виберіть принаймні одну модель для кожної родини провайдерів: +Виберіть щонайменше одну модель на кожне сімейство провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -447,153 +492,153 @@ pnpm test:docker:live-acp-bind:gemini - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (бажано мати): +Необов’язкове додаткове покриття (було б добре мати): - xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас увімкнено) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас ввімкнено) - Cerebras: `cerebras/`… (якщо у вас є доступ) - LM Studio: `lmstudio/`… (локально; tool calling залежить від режиму API) -### Vision: надсилання image (attachment → мультимодальне повідомлення) +### Vision: надсилання image (вкладення → мультимодальне повідомлення) -Додайте принаймні одну модель із підтримкою image до `OPENCLAW_LIVE_GATEWAY_MODELS` (варіанти Claude/Gemini/OpenAI з підтримкою vision тощо), щоб перевірити image probe. +Додайте щонайменше одну модель із підтримкою image до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI з підтримкою vision тощо), щоб перевірити image probe. -### Агрегатори / альтернативні gateways +### Агрегатори / альтернативні gateway Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти відповідні кандидати з підтримкою tools+image) -- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tool+image) +- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити в live-матрицю (якщо у вас є creds/config): +Інші провайдери, які можна включити до live-матриці (якщо у вас є облікові дані/config): - Вбудовані: `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` (власні endpoints): `minimax` (cloud/API), а також будь-який сумісний із OpenAI/Anthropic proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (власні endpoints): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко закодувати в документації «усі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс доступні ключі. +Порада: не намагайтеся жорстко закодувати «всі моделі» в документації. Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс доступні ключі. ## Облікові дані (ніколи не комітьте) Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: - Якщо CLI працює, live-тести мають знаходити ті самі ключі. -- Якщо live-тест каже «немає creds», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. +- Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі auth для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «ключі профілів» у live-тестах) +- Профілі автентифікації для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це мається на увазі під «profile keys» у live-тестах) - Config: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється в підготовлений live home, якщо присутній, але не є основним сховищем ключів профілів) -- Локальні live-запуски за замовчуванням копіюють активний config, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги auth CLI до тимчасового test home; підготовлені live homes пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probes не працювали у вашому реальному workspace хоста. +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але це не головне сховище profile-key) +- Локальні live-запуски за замовчуванням копіюють активний config, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасового test home; staged live homes пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probes не торкалися вашого реального workspace хоста. Якщо ви хочете покладатися на env keys (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-раннери нижче (вони можуть монтувати `~/.profile` у контейнер). -## Live: Deepgram (транскрипція аудіо) +## Deepgram live (транскрибування аудіо) - Тест: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## Live: BytePlus coding plan +## BytePlus coding plan live - Тест: `src/agents/byteplus.live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live: медіа 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 для image, video і `music_generate` - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін у надсиланні workflow comfy, polling, downloads або реєстрації plugin + - Корисно після змін у поданні workflow comfy, polling, downloads або реєстрації plugin -## Live: генерація зображень +## Image generation live - Тест: `src/image-generation/runtime.live.test.ts` - Команда: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Обсяг: - - Перелічує кожен зареєстрований plugin провайдера генерації зображень - - Завантажує відсутні env vars провайдера з вашої оболонки входу (`~/.profile`) перед перевіркою - - За замовчуванням використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки - - Пропускає провайдерів без придатних auth/profile/model - - Запускає стандартні варіанти генерації зображень через спільну runtime capability: + - Перелічує кожен зареєстрований provider plugin для image generation + - Завантажує відсутні env-змінні провайдера з вашого shell входу (`~/.profile`) перед перевіркою + - За замовчуванням віддає перевагу live/env API keys над збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials + - Пропускає провайдери без придатної автентифікації/профілю/моделі + - Запускає стандартні варіанти image generation через спільну runtime capability: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні вбудовані провайдери в покритті: +- Поточні вбудовані провайдери, які охоплено: - `openai` - `google` - Необов’язкове звуження: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env +- Необов’язкова поведінка автентифікації: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів та ігнорувати перевизначення лише з env -## 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` - Harness: `pnpm test:live:media music` - Обсяг: - - Перевіряє спільний шлях вбудованого провайдера генерації музики + - Перевіряє спільний вбудований шлях provider для music generation - Наразі охоплює Google і MiniMax - - Завантажує env vars провайдера з вашої оболонки входу (`~/.profile`) перед перевіркою - - За замовчуванням використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки - - Пропускає провайдерів без придатних auth/profile/model - - Запускає обидва оголошені runtime режими, коли вони доступні: - - `generate` з вхідними даними лише prompt + - Завантажує env-змінні провайдера з вашого shell входу (`~/.profile`) перед перевіркою + - За замовчуванням віддає перевагу live/env API keys над збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials + - Пропускає провайдери без придатної автентифікації/профілю/моделі + - Запускає обидва оголошені runtime modes, коли вони доступні: + - `generate` із вводом лише prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільної ланки: + - Поточне покриття спільного lane: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, а не ця спільна перевірка + - `comfy`: окремий live-файл Comfy, не цей спільний sweep - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env +- Необов’язкова поведінка автентифікації: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів та ігнорувати перевизначення лише з env -## Live: генерація відео +## Video generation live - Тест: `extensions/video-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Обсяг: - - Перевіряє спільний шлях вбудованого провайдера генерації відео - - Завантажує env vars провайдера з вашої оболонки входу (`~/.profile`) перед перевіркою - - За замовчуванням використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані оболонки - - Пропускає провайдерів без придатних auth/profile/model - - Запускає обидва оголошені runtime режими, коли вони доступні: - - `generate` з вхідними даними лише prompt - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний image input на основі buffer у спільній перевірці - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний video input на основі buffer у спільній перевірці - - Поточні провайдери `imageToVideo`, оголошені, але пропущені у спільній перевірці: - - `vydra`, тому що вбудований `veo3` підтримує лише текст, а вбудований `kling` вимагає віддалений URL зображення - - Покриття Vydra для конкретного провайдера: + - Перевіряє спільний вбудований шлях video-generation provider + - Завантажує env-змінні провайдера з вашого shell входу (`~/.profile`) перед перевіркою + - За замовчуванням віддає перевагу live/env API keys над збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials + - Пропускає провайдери без придатної автентифікації/профілю/моделі + - Запускає обидва оголошені runtime modes, коли вони доступні: + - `generate` із вводом лише prompt + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний image input на основі buffer у спільному sweep + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний video input на основі buffer у спільному sweep + - Поточні провайдери `imageToVideo`, оголошені, але пропущені у спільному sweep: + - `vydra`, оскільки вбудований `veo3` підтримує лише text, а вбудований `kling` вимагає віддалений image 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 зображення + - цей файл запускає `veo3` text-to-video, а також lane `kling`, який за замовчуванням використовує fixture з віддаленим image URL - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні провайдери `videoToVideo`, оголошені, але пропущені у спільній перевірці: - - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають віддалені reference URLs `http(s)` / MP4 - - `google`, тому що поточна спільна ланка Gemini/Veo використовує локальний input на основі buffer, а цей шлях не приймається в спільній перевірці - - `openai`, тому що поточна спільна ланка не гарантує org-specific доступ до video inpaint/remix + - Поточні провайдери `videoToVideo`, оголошені, але пропущені у спільному sweep: + - `alibaba`, `qwen`, `xai`, оскільки ці шляхи зараз вимагають віддалені reference URL `http(s)` / MP4 + - `google`, оскільки поточний спільний lane Gemini/Veo використовує локальний ввід на основі buffer, і цей шлях не приймається у спільному sweep + - `openai`, оскільки поточний спільний lane не гарантує організаційно-специфічний доступ до video inpaint/remix - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` -- Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env +- Необов’язкова поведінка автентифікації: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів та ігнорувати перевизначення лише з env -## Harness для live-медіа +## Media live harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори image, music і video через одну нативну для репозиторію точку входу - - Автоматично завантажує відсутні env vars провайдера з `~/.profile` - - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатну auth - - Повторно використовує `scripts/test-live.mjs`, тому поведінка heartbeat і quiet-mode залишається узгодженою + - Запускає спільні live-набори для image, music і video через один вбудований entrypoint репозиторію + - Автоматично завантажує відсутні env-змінні провайдерів із `~/.profile` + - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатну автентифікацію + - Повторно використовує `scripts/test-live.mjs`, тому heartbeat і тихий режим залишаються узгодженими - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -602,126 +647,125 @@ Live-тести знаходять облікові дані так само, я ## Docker-раннери (необов’язкові перевірки «працює в Linux») -Ці Docker-раннери поділяються на дві групи: +Ці Docker-раннери поділяються на дві категорії: -- Раннери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл з ключами профілів усередині Docker image репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (та підвантажують `~/.profile`, якщо його змонтовано). Відповідні локальні точки входу: `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker-раннери live за замовчуванням використовують менший smoke-ліміт, щоб повна Docker-перевірка залишалася практичною: - `test:docker:live-models` за замовчуванням встановлює `OPENCLAW_LIVE_MAX_MODELS=12`, а +- Раннери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише свій відповідний live-файл profile-key усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний каталог config і workspace (а також використовуючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoints — `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live-раннери за замовчуванням використовують менше smoke-обмеження, щоб повний Docker sweep залишався практичним: + `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а `test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли - вам явно потрібне більше, повне сканування. -- `test:docker:all` один раз збирає Docker image для live через `test:docker:live-build`, а потім повторно використовує його для двох Docker-ланок live. -- Контейнерні smoke-раннери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` піднімають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли + вам явно потрібне більше вичерпне сканування. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-lane live-тестів. +- Контейнерні smoke-раннери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker-раннери live-моделей також bind-mount лише потрібні каталоги auth для CLI (або всі підтримувані, якщо запуск не звужений), а потім копіюють їх до домашнього каталогу контейнера перед запуском, щоб OAuth зовнішніх CLI міг оновлювати токени без зміни сховища auth на хості: +Docker-раннери live-моделей також bind-mount лише потрібні CLI auth homes (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб зовнішній CLI OAuth міг оновлювати токени, не змінюючи auth store хоста: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- Smoke прив’язки ACP: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) -- Smoke CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) - Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) - Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) - Мережа gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Міст каналу MCP (ініціалізований Gateway + stdio bridge + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (smoke встановлення + псевдонім `/plugin` + семантика перезапуску пакета Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Міст MCP channel (seeded Gateway + stdio bridge + smoke сирого notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (install smoke + псевдонім `/plugin` + семантика restart Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -Docker-раннери live-моделей також bind-mount поточний checkout лише для читання і -розгортають його у тимчасовий workdir всередині контейнера. Це зберігає runtime -image компактним, але все одно дозволяє запускати Vitest точно на вашому -локальному source/config. -Під час розгортання пропускаються великі локальні кеші й результати збірки застосунків, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні каталоги виводу `.build` або -Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -артефактів, специфічних для машини. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб gateway live probes не запускали +Docker-раннери live-моделей також монтують поточний checkout лише для читання і +підготовлюють його у тимчасовому workdir усередині контейнера. Це зберігає runtime- +образ компактним, але все одно запускає Vitest точно на вашому локальному source/config. +На етапі підготовки пропускаються великі локальні кеші та результати збірки застосунків, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або +виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +машинно-специфічних артефактів. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes gateway не запускали реальні workers каналів Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити покриття gateway -live з цієї Docker-ланки. -`test:docker:openwebui` — це compatibility smoke вищого рівня: він запускає -контейнер gateway OpenClaw з увімкненими HTTP endpoints, сумісними з OpenAI, -запускає контейнер Open WebUI із зафіксованою версією проти цього gateway, виконує вхід через +`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway +live-покриття з цього Docker-lane. +`test:docker:openwebui` — це smoke-перевірка сумісності вищого рівня: вона запускає +контейнер OpenClaw gateway з увімкненими HTTP endpoints, сумісними з OpenAI, +запускає закріплений контейнер Open WebUI проти цього gateway, входить через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat-запит через проксі `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися завантажити -image Open WebUI, а самому Open WebUI — завершити власне cold-start налаштування. -Ця ланка очікує наявність придатного ключа live-моделі, а `OPENCLAW_PROFILE_FILE` -(`~/.profile` за замовчуванням) — основний спосіб надати його в Dockerized-запусках. +реальний chat-запит через proxy `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися витягнути +образ Open WebUI, а самому Open WebUI — завершити власне холодне початкове налаштування. +Цей lane очікує наявний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` +(`~/.profile` за замовчуванням) є основним способом надати його в Dockerized-запусках. Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він піднімає -контейнер Gateway з початковими даними, запускає другий контейнер, який викликає `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання transcript, метадані вкладень, -поведінку черги live-подій, маршрутизацію вихідних надсилань і сповіщення про канал + -дозволи у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо аналізує сирі stdio MCP frames, тому smoke перевіряє те, що міст -справді виводить, а не лише те, що випадково відображає конкретний client SDK. +реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway +контейнер, запускає другий контейнер, який піднімає `openclaw mcp serve`, а потім +перевіряє routed conversation discovery, читання transcript, метадані вкладень, +поведінку черги live events, маршрутизацію outbound send і channel + сповіщення +про дозволи у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень +безпосередньо аналізує сирі stdio MCP frames, тож smoke перевіряє те, що міст +справді випромінює, а не лише те, що випадково показує конкретний client SDK. -Ручний smoke plain-language thread ACP (не для CI): +Ручний smoke plain-language thread для ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. +- Зберігайте цей скрипт для регресійних сценаріїв і налагодження. Він може знову знадобитися для перевірки ACP thread routing, тож не видаляйте його. -Корисні env vars: +Корисні env-змінні: -- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і підвантажується перед запуском тестів -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установлень CLI усередині Docker -- Зовнішні каталоги/файли auth CLI у `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед запуском тестів +- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`), монтується в `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`), монтується в `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`), монтується в `/home/node/.profile` і використовується перед запуском тестів +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`), монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker +- Зовнішні каталоги/файли CLI auth у `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед запуском тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Можна перевизначити вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Для звужених запусків провайдерів монтуються лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Ручне перевизначення: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` для звуження запуску -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` для фільтрації провайдерів усередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1` для повторного використання наявного image `openclaw:local-live` у перезапусках, яким не потрібна перебудова -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб гарантувати, що creds беруться зі сховища профілів, а не з env -- `OPENCLAW_OPENWEBUI_MODEL=...` щоб вибрати модель, яку gateway показує для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` щоб перевизначити nonce-check prompt, що використовується у smoke Open WebUI -- `OPENWEBUI_IMAGE=...` щоб перевизначити зафіксований тег image Open WebUI +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` для фільтрації провайдерів у контейнері +- `OPENCLAW_SKIP_DOCKER_BUILD=1` для повторного використання наявного образу `openclaw:local-live` для повторних запусків, які не потребують перебудови +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані беруться зі сховища профілів (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...` для вибору моделі, яку gateway показує для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` для перевизначення prompt перевірки nonce, що використовується smoke Open WebUI +- `OPENWEBUI_IMAGE=...` для перевизначення закріпленого тега образу Open WebUI ## Перевірка документації -Після редагування документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. +Після змін у документації запускайте перевірки docs: `pnpm check:docs`. +Запускайте повну перевірку якорів Mintlify, якщо вам також потрібна перевірка заголовків у межах сторінки: `pnpm docs:check-links:anchors`. -## Offline-регресія (безпечна для CI) +## Офлайн-регресія (безпечна для CI) Це регресії «реального конвеєра» без реальних провайдерів: - Tool calling gateway (імітація OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер gateway (WS `wizard.start`/`wizard.next`, запис config + примусове застосування auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Майстер gateway (WS `wizard.start`/`wizard.next`, запис config + примусова auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності агентів (Skills) +## Оцінювання надійності агента (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агентів»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: -- Імітований tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють wiring сесій і вплив на config (`src/gateway/gateway.test.ts`). +- Імітація tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- End-to-end потоки майстра, які перевіряють прив’язку сесії та ефекти config (`src/gateway/gateway.test.ts`). -Чого все ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли Skills перелічені в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? +- **Прийняття рішень:** коли Skills перелічені в prompt, чи вибирає агент правильний Skills (або уникає нерелевантних)? - **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/args? -- **Контракти робочих процесів:** багатокрокові сценарії, які перевіряють порядок tool calls, перенесення історії сесії та межі sandbox. +- **Контракти робочих процесів:** багатокрокові сценарії, які перевіряють порядок tools, перенесення історії сесії та межі sandbox. -Майбутні оцінювання мають залишатися насамперед детермінованими: +Майбутні evals мають передусім залишатися детермінованими: -- Раннер сценаріїв із mock-провайдерами для перевірки tool calls + їх порядку, читання skill-файлів і wiring сесій. -- Невеликий набір сценаріїв, орієнтованих на Skills (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live-оцінювання (opt-in, із керуванням через env) лише після того, як буде готовий безпечний для CI набір. +- Запускач сценаріїв із mock-провайдерами для перевірки викликів tools + порядку, читання skill-файлів і прив’язки сесії. +- Невеликий набір сценаріїв, орієнтованих на skills (використати чи уникнути, gating, prompt injection). +- Необов’язкові live evals (opt-in, із контролем через env) лише після того, як буде готовий безпечний для CI набір. ## Контрактні тести (форма plugin і channel) Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму -контракту інтерфейсу. Вони перебирають усі виявлені plugins і запускають набір -перевірок форми та поведінки. Типова unit-ланка `pnpm test` навмисно -пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди окремо, -коли торкаєтесь спільних поверхонь channel або provider. +контракту інтерфейсу. Вони перебирають усі виявлені plugins і запускають набір перевірок +форми та поведінки. Типовий unit-lane `pnpm test` навмисно пропускає ці спільні файли +seam і smoke; запускайте контрактні команди явно, коли змінюєте спільні поверхні channel або provider. ### Команди @@ -740,22 +784,22 @@ image Open WebUI, а самому Open WebUI — завершити власне - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel - **threading** - Обробка ID thread -- **directory** - API directory/roster -- **group-policy** - Застосування group policy +- **directory** - API каталогу/списку учасників +- **group-policy** - Застосування групової політики ### Контракти статусу provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. - **status** - Перевірки status channel -- **registry** - Форма реєстру plugin +- **registry** - Форма registry plugin ### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт потоку auth -- **auth-choice** - Вибір/добір auth +- **auth** - Контракт потоку автентифікації +- **auth-choice** - Вибір/добір автентифікації - **catalog** - API каталогу моделей - **discovery** - Виявлення plugin - **loader** - Завантаження plugin @@ -765,21 +809,21 @@ image Open WebUI, а самому Open WebUI — завершити власне ### Коли запускати -- Після змін exports або subpaths у plugin-sdk -- Після додавання або зміни plugin channel чи provider -- Після рефакторингу реєстрації plugin або механізму виявлення +- Після зміни export або subpath у plugin-sdk +- Після додавання або змінення channel чи provider plugin +- Після рефакторингу реєстрації або виявлення plugin -Контрактні тести запускаються в CI і не потребують реальних API-ключів. +Контрактні тести запускаються в CI і не потребують реальних API keys. -## Додавання регресійних тестів (рекомендації) +## Додавання регресій (рекомендації) Коли ви виправляєте проблему provider/model, виявлену в live: -- За можливості додайте безпечну для CI регресію (імітація/stub провайдера або захоплення точної трансформації форми запиту) -- Якщо проблема за своєю природою лише live (rate limits, політики auth), залишайте live-тест вузьким і opt-in через env vars -- Віддавайте перевагу найменшому рівню, який ловить помилку: - - помилка конвертації/повторення запиту provider → тест прямих моделей - - помилка конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест gateway -- Запобіжник обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec ids сегментів обходу відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується невдачею на некласифікованих target ids, щоб нові класи не можна було пропустити непомітно. +- Якщо можливо, додайте безпечну для CI регресію (імітація/stub provider або фіксація точної трансформації форми запиту) +- Якщо проблема за своєю природою лише live-типу (rate limits, політики автентифікації), залишайте live-тест вузьким і opt-in через env-змінні +- Віддавайте перевагу найменшому рівню, який ловить баг: + - баг конвертації/повторення запиту provider → тест direct models + - баг конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест gateway +- Захисне правило обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить один вибраний target на кожен клас SecretRef із метаданих registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec id відхиляються. + - Якщо ви додаєте нове сімейство target SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. diff --git a/docs/uk/plugins/sdk-agent-harness.md b/docs/uk/plugins/sdk-agent-harness.md new file mode 100644 index 000000000..1ae8f2eb9 --- /dev/null +++ b/docs/uk/plugins/sdk-agent-harness.md @@ -0,0 +1,192 @@ +--- +read_when: + - Ви змінюєте вбудоване середовище виконання агента або реєстр каркаса + - Ви реєструєте каркас агента з вбудованого або довіреного плагіна + - Вам потрібно зрозуміти, як плагін Codex пов’язаний із постачальниками моделей +sidebarTitle: Agent Harness +summary: Експериментальна поверхня SDK для плагінів, які замінюють низькорівневий вбудований виконавець агента +title: Плагіни каркаса агента +x-i18n: + generated_at: "2026-04-10T20:23:46Z" + model: gpt-5.4 + provider: openai + source_hash: ba482dd6a2e4730c2d623b4739e2e6037cec8bb71bf7164b4e9d7ea8e43056d8 + source_path: plugins/sdk-agent-harness.md + workflow: 15 +--- + +# Плагіни каркаса агента + +**Каркас агента** — це низькорівневий виконавець одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів. + +Використовуйте цю поверхню лише для вбудованих або довірених нативних плагінів. Контракт усе ще є експериментальним, оскільки типи параметрів навмисно віддзеркалюють поточний вбудований раннер. + +## Коли використовувати каркас + +Реєструйте каркас агента, коли сімейство моделей має власне нативне середовище виконання сесій і звичайний транспорт постачальника OpenClaw є неправильною абстракцією. + +Приклади: + +- нативний сервер агента для кодування, який керує потоками та компакцією +- локальний CLI або демон, який має потоково передавати нативні події плану, міркувань і інструментів +- середовище виконання моделі, якому потрібен власний resume id на додачу до транскрипту сесії OpenClaw + +**Не** реєструйте каркас лише для того, щоб додати новий LLM API. Для звичайних HTTP або WebSocket API моделей створіть [плагін постачальника](/uk/plugins/sdk-provider-plugins). + +## Чим усе ще керує ядро + +До того, як буде вибрано каркас, OpenClaw уже визначив: + +- постачальника й модель +- стан автентифікації середовища виконання +- рівень міркувань і бюджет контексту +- файл транскрипту/сесії OpenClaw +- робочий простір, пісочницю та політику інструментів +- колбеки відповіді каналу та колбеки потокової передачі +- політику резервного перемикання моделей і перемикання живої моделі + +Цей поділ є навмисним. Каркас виконує підготовлену спробу; він не вибирає постачальників, не замінює доставлення каналу й не перемикає моделі непомітно. + +## Зареєструвати каркас + +**Імпорт:** `openclaw/plugin-sdk/agent-harness` + +```typescript +import type { AgentHarness } from "openclaw/plugin-sdk/agent-harness"; +import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; + +const myHarness: AgentHarness = { + id: "my-harness", + label: "My native agent harness", + + supports(ctx) { + return ctx.provider === "my-provider" + ? { supported: true, priority: 100 } + : { supported: false }; + }, + + async runAttempt(params) { + // Start or resume your native thread. + // Use params.prompt, params.tools, params.images, params.onPartialReply, + // params.onAgentEvent, and the other prepared attempt fields. + return await runMyNativeTurn(params); + }, +}; + +export default definePluginEntry({ + id: "my-native-agent", + name: "My Native Agent", + description: "Runs selected models through a native agent daemon.", + register(api) { + api.registerAgentHarness(myHarness); + }, +}); +``` + +## Політика вибору + +OpenClaw вибирає каркас після визначення постачальника/моделі: + +1. `OPENCLAW_AGENT_RUNTIME=` примусово вибирає зареєстрований каркас із цим id. +2. `OPENCLAW_AGENT_RUNTIME=pi` примусово вибирає вбудований каркас PI. +3. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані каркаси, чи підтримують вони визначеного постачальника/модель. +4. Якщо жоден зареєстрований каркас не підходить, OpenClaw використовує PI. + +Помилки примусово вибраного каркаса плагіна відображаються як помилки виконання. У режимі `auto` OpenClaw може повернутися до PI, якщо вибраний каркас плагіна зазнає збою до того, як хід спричинить побічні ефекти. + +Вбудований плагін Codex реєструє `codex` як id свого каркаса. Для сумісності `codex-app-server` і `app-server` також вказують на цей самий каркас, коли ви вручну задаєте `OPENCLAW_AGENT_RUNTIME`. + +## Поєднання постачальника та каркаса + +Більшість каркасів також мають реєструвати постачальника. Постачальник робить посилання на моделі, стан автентифікації, метадані моделі та вибір `/model` видимими для решти OpenClaw. Потім каркас заявляє про цей постачальник у `supports(...)`. + +Вбудований плагін Codex дотримується цього шаблону: + +- id постачальника: `codex` +- посилання на моделі для користувача: `codex/gpt-5.4`, `codex/gpt-5.2` або інша модель, повернена сервером застосунку Codex +- id каркаса: `codex` +- автентифікація: синтетична доступність постачальника, оскільки каркас Codex керує нативним входом/сесією Codex +- запит до app-server: OpenClaw надсилає до Codex голий id моделі й дозволяє каркасу працювати з нативним протоколом app-server + +Плагін Codex є додатковим. Звичайні посилання `openai/gpt-*` залишаються посиланнями постачальника OpenAI і продовжують використовувати звичайний шлях постачальника OpenClaw. Вибирайте `codex/gpt-*`, коли вам потрібні автентифікація під керуванням Codex, виявлення моделей Codex, нативні потоки та виконання через Codex app-server. `/model` може перемикатися між моделями Codex, які повертає Codex app-server, без потреби в облікових даних постачальника OpenAI. + +OpenClaw вимагає Codex app-server версії `0.118.0` або новішої. Плагін Codex перевіряє initialize handshake app-server і блокує старі або неверсіоновані сервери, щоб OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано. + +## Політика вибору каркаса + +За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, установленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані каркаси плагінів можуть претендувати на пару постачальник/модель. Якщо не підходить жоден або якщо автоматично вибраний каркас плагіна зазнає збою до створення виводу, OpenClaw повертається до PI. + +Установіть `fallback: "none"`, коли вам потрібно довести, що виконується лише каркас плагіна: + +```json +{ + "agents": { + "defaults": { + "model": "codex/gpt-5.4", + "embeddedHarness": { + "runtime": "codex", + "fallback": "none" + } + } + } +} +``` + +Перевизначення для окремого агента використовують ту саму форму: + +```json +{ + "agents": { + "defaults": { + "embeddedHarness": { + "runtime": "auto", + "fallback": "pi" + } + }, + "list": [ + { + "id": "codex-only", + "model": "codex/gpt-5.4", + "embeddedHarness": { + "runtime": "codex", + "fallback": "none" + } + } + ] + } +} +``` + +`OPENCLAW_AGENT_RUNTIME` усе ще перевизначає налаштоване середовище виконання. Використовуйте `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути резервний перехід до PI через змінну середовища. + +## Нативні сесії та дзеркало транскрипту + +Каркас може зберігати нативний id сесії, id потоку або токен відновлення на боці демона. Явно пов’язуйте цю прив’язку із сесією OpenClaw і продовжуйте віддзеркалювати видимий для користувача вивід асистента/інструментів у транскрипт OpenClaw. + +Транскрипт OpenClaw залишається шаром сумісності для: + +- видимої в каналі історії сесії +- пошуку та індексації транскрипту +- перемикання назад на вбудований каркас PI у наступному ході +- загальної поведінки `/new`, `/reset` і видалення сесії + +Якщо ваш каркас зберігає побічну прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг очистити її, коли пов’язану сесію OpenClaw скинуто. + +## Результати інструментів і медіа + +Ядро формує список інструментів OpenClaw і передає його в підготовлену спробу. Коли каркас виконує динамічний виклик інструмента, повертайте результат інструмента назад через форму результату каркаса, а не надсилайте медіа каналу самостійно. + +Це зберігає текст, зображення, відео, музику, TTS, затвердження та вивід інструментів обміну повідомленнями на тому самому шляху доставлення, що й у виконаннях на базі PI. + +## Поточні обмеження + +- Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроб/результатів усе ще містять назви `Pi` для сумісності. +- Установлення сторонніх каркасів є експериментальним. Надавайте перевагу плагінам постачальників, доки вам не знадобиться нативне середовище виконання сесій. +- Перемикання каркасів між ходами підтримується. Не перемикайте каркаси посеред ходу після того, як уже почалися нативні інструменти, затвердження, текст асистента або надсилання повідомлень. + +## Пов’язане + +- [Огляд SDK](/uk/plugins/sdk-overview) +- [Допоміжні засоби середовища виконання](/uk/plugins/sdk-runtime) +- [Плагіни постачальників](/uk/plugins/sdk-provider-plugins) +- [Постачальники моделей](/uk/concepts/model-providers) diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index 63209ac2b..13b0f10ef 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -1,33 +1,33 @@ --- read_when: - - Потрібно знати, з якого підшляху SDK імпортувати - - Потрібен довідник для всіх методів реєстрації в OpenClawPluginApi + - Вам потрібно знати, з якого підшляху SDK імпортувати + - Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi - Ви шукаєте конкретний експорт SDK sidebarTitle: SDK Overview -summary: Карта імпортів, довідник API реєстрації та архітектура SDK +summary: Карта імпорту, довідник з API реєстрації та архітектура SDK title: Огляд Plugin SDK x-i18n: - generated_at: "2026-04-09T00:38:40Z" + generated_at: "2026-04-10T20:23:45Z" model: gpt-5.4 provider: openai - source_hash: bf205af060971931df97dca4af5110ce173d2b7c12f56ad7c62d664a402f2381 + source_hash: 4bfeb5896f68e3e4ee8cf434d43a019e0d1fe5af57f5bf7a5172847c476def0c source_path: plugins/sdk-overview.md workflow: 15 --- # Огляд Plugin SDK -Plugin SDK — це типізований контракт між плагінами та ядром. Ця сторінка — -довідник про **що імпортувати** і **що можна реєструвати**. +Plugin SDK — це типізований контракт між плагінами та core. Ця сторінка є +довідником для **того, що імпортувати** і **що можна реєструвати**. - **Шукаєте покроковий посібник?** + **Шукаєте практичний посібник?** - Перший плагін? Почніть із [Getting Started](/uk/plugins/building-plugins) - - Плагін каналу? Див. [Channel Plugins](/uk/plugins/sdk-channel-plugins) - - Плагін провайдера? Див. [Provider Plugins](/uk/plugins/sdk-provider-plugins) + - Плагін каналу? Дивіться [Channel Plugins](/uk/plugins/sdk-channel-plugins) + - Плагін провайдера? Дивіться [Provider Plugins](/uk/plugins/sdk-provider-plugins) -## Правило імпорту +## Угода щодо імпорту Завжди імпортуйте з конкретного підшляху: @@ -37,45 +37,43 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` Кожен підшлях — це невеликий самодостатній модуль. Це забезпечує швидкий -запуск і запобігає проблемам із циклічними залежностями. Для специфічних для -каналів допоміжних засобів входу/збирання надавайте перевагу -`openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для +запуск і запобігає проблемам із циклічними залежностями. Для специфічних для каналу +допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для ширшої узагальнювальної поверхні та спільних допоміжних засобів, таких як `buildChannelConfigSchema`. -Не додавайте і не використовуйте зручні шви з назвами провайдерів, такі як +Не додавайте і не використовуйте зручні шари, названі на честь провайдерів, як-от `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, -`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, або допоміжні -шви з брендингом каналів. Вбудовані плагіни мають компонувати загальні -підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а ядро -має або використовувати ці локальні barrel-файли плагіна, або додавати вузький -загальний контракт SDK, якщо потреба справді є міжканальною. +`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, або +допоміжні шари з брендуванням каналів. Вбудовані плагіни мають компонувати загальні +підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а core +має або використовувати ці локальні barrel-файли плагінів, або додавати вузький загальний SDK +контракт, коли потреба справді є міжканальною. -Згенерована карта експортів усе ще містить невеликий набір допоміжних -швів для вбудованих плагінів, таких як `plugin-sdk/feishu`, -`plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і -`plugin-sdk/matrix*`. Ці підшляхи існують лише для підтримки вбудованих -плагінів і сумісності; їх навмисно не включено до загальної таблиці нижче, -і вони не є рекомендованим шляхом імпорту для нових сторонніх плагінів. +Згенерована карта експортів усе ще містить невеликий набір допоміжних шарів +для вбудованих плагінів, як-от `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Ці +підшляхи існують лише для підтримки вбудованих плагінів і сумісності; вони +навмисно не включені до загальної таблиці нижче і не є рекомендованим +шляхом імпорту для нових сторонніх плагінів. ## Довідник підшляхів -Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список -із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. +Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список із +понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. -Зарезервовані допоміжні підшляхи вбудованих плагінів усе ще з’являються в -цьому згенерованому списку. Вважайте їх деталями реалізації / поверхнями -сумісності, якщо тільки якась сторінка документації явно не просуває один із -них як публічний. +Зарезервовані допоміжні підшляхи для вбудованих плагінів усе ще з’являються в цьому +згенерованому списку. Розглядайте їх як деталі реалізації/поверхні сумісності, +якщо лише сторінка документації явно не позначає один із них як публічний. -### Вхід плагіна +### Вхідна точка плагіна -| Підшлях | Ключові експорти | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `plugin-sdk/plugin-entry` | `definePluginEntry` | +| Підшлях | Ключові експорти | +| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | -| `plugin-sdk/config-schema` | `OpenClawSchema` | -| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | +| `plugin-sdk/config-schema` | `OpenClawSchema` | +| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | @@ -84,46 +82,46 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, запити списків дозволених джерел, побудова статусу налаштування | + | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, запити allowlist, побудовники статусу налаштування | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні засоби для конфігурації/керування шлюзами дій з кількома обліковими записами, допоміжні засоби резервного використання типового облікового запису | + | `plugin-sdk/account-core` | Допоміжні засоби для конфігурації/контролю дій багатьох облікових записів, допоміжні засоби резервного використання облікового запису за замовчуванням | | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації account-id | - | `plugin-sdk/account-resolution` | Пошук облікового запису + допоміжні засоби резервного використання типового значення | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списків облікових записів / дій над обліковими записами | + | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису та резервного використання за замовчуванням | + | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списку облікових записів/дій з обліковими записами | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | Типи схеми конфігурації каналу | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервним вбудованим контрактом | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервною підтримкою вбудованого контракту | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації вхідних повідомлень і побудови envelope | - | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису та диспетчеризації вхідних повідомлень | + | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби для route вхідних повідомлень і побудови envelope | + | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису та dispatch для вхідних повідомлень | | `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей | | `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби ідентичності вихідних повідомлень / делегатів надсилання | - | `plugin-sdk/thread-bindings-runtime` | Життєвий цикл прив’язок потоків і допоміжні засоби адаптерів | - | `plugin-sdk/agent-media-payload` | Застарілий побудовник медіа payload агента | - | `plugin-sdk/conversation-runtime` | Допоміжні засоби прив’язки розмов/потоків, pairинг і налаштованих прив’язок | - | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації під час виконання | - | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення групових політик під час виконання | - | `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/зведення статусу каналу | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби для вихідної ідентичності/делегування надсилання | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу thread-binding та адаптерів | + | `plugin-sdk/agent-media-payload` | Застарілий побудовник agent media payload | + | `plugin-sdk/conversation-runtime` | Допоміжні засоби для conversation/thread binding, pairing і configured-binding | + | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб snapshot конфігурації середовища виконання | + | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення group-policy середовища виконання | + | `plugin-sdk/channel-status` | Спільні допоміжні засоби snapshot/summary статусу каналу | | `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу | | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільні преамбулні експорти плагінів каналів | - | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації списку дозволених джерел | - | `plugin-sdk/group-access` | Спільні допоміжні засоби рішень щодо доступу груп | - | `plugin-sdk/direct-dm` | Спільні допоміжні засоби автентифікації/захисту прямих DM | - | `plugin-sdk/interactive-runtime` | Допоміжні засоби нормалізації/скорочення payload інтерактивних відповідей | - | `plugin-sdk/channel-inbound` | Допоміжні засоби debounce для вхідних повідомлень, зіставлення згадок, політики згадок і envelope | - | `plugin-sdk/channel-send-result` | Типи результатів відповіді | + | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти плагінів каналів | + | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist | + | `plugin-sdk/group-access` | Спільні допоміжні засоби ухвалення рішень щодо group-access | + | `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard для direct-DM | + | `plugin-sdk/interactive-runtime` | Допоміжні засоби нормалізації/зменшення interactive reply payload | + | `plugin-sdk/channel-inbound` | Допоміжні засоби debounce вхідних повідомлень, зіставлення згадок, політики згадок та допоміжні засоби envelope | + | `plugin-sdk/channel-send-result` | Типи результатів reply | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | | `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення цілей | | `plugin-sdk/channel-contract` | Типи контракту каналу | - | `plugin-sdk/channel-feedback` | Підключення відгуків/реакцій | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби контракту секретів, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, а також типи цілей секретів | + | `plugin-sdk/channel-feedback` | Підключення feedback/reaction | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби секретного контракту, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей секретів | @@ -132,236 +130,238 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted провайдерів | | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI | - | `plugin-sdk/cli-backend` | Типові значення CLI-бекенду + константи watchdog | + | `plugin-sdk/cli-backend` | Значення за замовчуванням для бекенда CLI та константи watchdog | | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключів під час виконання для плагінів провайдерів | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю API-ключа, такі як `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Стандартний побудовник результату OAuth-автентифікації | + | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю API-ключів, такі як `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Стандартний побудовник результатів OAuth auth | | `plugin-sdk/provider-auth-login` | Спільні інтерактивні допоміжні засоби входу для плагінів провайдерів | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env var для автентифікації провайдерів | + | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку змінних середовища auth провайдерів | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники політик replay, допоміжні засоби endpoint провайдерів і нормалізації model-id, такі як `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники replay-policy, допоміжні засоби endpoint провайдерів і допоміжні засоби нормалізації model-id, такі як `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | | `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/можливостей endpoint провайдерів | | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешу провайдерів web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби конфігурації/облікових даних web-search для провайдерів, яким не потрібне підключення ввімкнення плагіна | - | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і область дії setter/getter для облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешу/виконання провайдерів web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування провайдерів web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби конфігурації/облікових даних web-search для провайдерів, яким не потрібне підключення увімкнення плагіна | + | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту конфігурації/облікових даних 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-usage` | `fetchClaudeUsage` та подібні | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоків і спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | Допоміжні засоби патчів конфігурації онбордингу | - | `plugin-sdk/global-singleton` | Допоміжні засоби локальних для процесу singleton/map/cache | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper та спільні допоміжні засоби wrapper для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-onboard` | Допоміжні засоби виправлення конфігурації онбордингу | + | `plugin-sdk/global-singleton` | Допоміжні засоби для локальних у межах процесу singleton/map/cache | - + | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, допоміжні засоби авторизації відправника | | `plugin-sdk/command-status` | Побудовники повідомлень команд/довідки, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення approver і автентифікації дій у межах того самого чату | - | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілів/фільтрів нативного схвалення виконання | - | `plugin-sdk/approval-delivery-runtime` | Адаптери нативних можливостей/доставки схвалення | - | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення шлюзу схвалення | - | `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні засоби завантаження нативного адаптера схвалення для гарячих entrypoint каналу | - | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime-обробника схвалення; надавайте перевагу вужчим швам adapter/gateway, коли їх достатньо | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби нативних цілей схвалення + прив’язки облікових записів | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповідей схвалення exec/plugin | - | `plugin-sdk/command-auth-native` | Допоміжні засоби нативної автентифікації команд + нативних цілей сеансу | + | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення approver і auth дій у тому самому чаті | + | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра native exec approval | + | `plugin-sdk/approval-delivery-runtime` | Адаптери можливостей/доставки native approval | + | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення approval gateway | + | `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні засоби завантаження адаптера native approval для гарячих entrypoint каналів | + | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime для approval handler; віддавайте перевагу вужчим adapter/gateway seams, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Допоміжні засоби для native approval target і account-binding | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді exec/plugin approval | + | `plugin-sdk/command-auth-native` | Native command auth і допоміжні засоби native session-target | | `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд | - | `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команди та command-surface | + | `plugin-sdk/command-surface` | Допоміжні засоби нормалізації command-body і command-surface | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання контракту секретів для поверхонь секретів каналу/плагіна | - | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для парсингу контракту секретів/конфігурації | - | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, обмеження DM, зовнішнього вмісту та збирання секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для списків дозволених хостів і приватних мереж | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання секретного контракту для поверхонь секретів каналів/плагінів | + | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору секретного контракту/конфігурації | + | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, DM gating, зовнішнього вмісту та збирання секретів | + | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватних мереж | | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF і політики SSRF | - | `plugin-sdk/secret-input` | Допоміжні засоби парсингу введення секретів | - | `plugin-sdk/webhook-ingress` | Допоміжні засоби запиту/цілі webhook | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру тіла запиту / тайм-аутів | + | `plugin-sdk/secret-input` | Допоміжні засоби розбору secret input | + | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів/цілей webhook | + | `plugin-sdk/webhook-request-guards` | Допоміжні засоби для розміру body запиту/timeout | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/логування/резервних копій/встановлення плагінів | - | `plugin-sdk/runtime-env` | Вужчі допоміжні засоби env runtime, логера, тайм-аутів, повторних спроб і backoff | + | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/logging/backup/plugin-install | + | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env, logger, timeout, retry і backoff | | `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку channel runtime-context | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/хуків/http/інтерактивних функцій плагіна | - | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline webhook/внутрішніх хуків | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби лінивого імпорту/прив’язки runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/хуків/http/interactive для плагінів | + | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline для webhook/internal hook | + | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy runtime import/binding, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | Допоміжні засоби виконання процесів | - | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування та версій | - | `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта шлюзу та патчів статусу каналу | + | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування і версії | + | `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта gateway і patch статусу каналу | | `plugin-sdk/config-runtime` | Допоміжні засоби завантаження/запису конфігурації | - | `plugin-sdk/telegram-command-config` | Нормалізація назв/описів команд Telegram і перевірки дублювань/конфліктів, навіть коли поверхня вбудованого контракту Telegram недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні засоби схвалення exec/plugin, побудовники можливостей схвалення, допоміжні засоби auth/profile, нативної маршрутизації/runtime | - | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби runtime для вхідних повідомлень/відповідей, chunking, dispatch, heartbeat, planner відповідей | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize для відповідей | - | `plugin-sdk/reply-history` | Спільні допоміжні засоби історії відповідей для короткого вікна, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня контракту вбудованого Telegram недоступна | + | `plugin-sdk/approval-runtime` | Допоміжні засоби exec/plugin approval, побудовники approval-capability, допоміжні засоби auth/profile, native routing/runtime | + | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби runtime для inbound/reply, chunking, dispatch, heartbeat, planner відповіді | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповіді | + | `plugin-sdk/reply-history` | Спільні допоміжні засоби short-window reply-history, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляхів до сховища сеансів + updated-at | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби для шляху сховища сесій і updated-at | | `plugin-sdk/state-paths` | Допоміжні засоби шляхів до каталогів state/OAuth | - | `plugin-sdk/routing` | Допоміжні засоби маршрутів / session-key / прив’язки облікових записів, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні допоміжні засоби зведення статусу каналу/облікового запису, типові значення стану runtime і допоміжні засоби метаданих проблем | - | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілей | + | `plugin-sdk/routing` | Допоміжні засоби route/session-key/account binding, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні допоміжні засоби summary статусу каналу/облікового запису, значення runtime-state за замовчуванням і допоміжні засоби метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби target resolver | | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків | - | `plugin-sdk/request-url` | Витягування рядкових URL із fetch/request-подібних входів | + | `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/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/json-store` | Невеликі допоміжні засоби читання/запису JSON-стану | - | `plugin-sdk/file-lock` | Реентерабельні допоміжні засоби file-lock | - | `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу дедуплікації на диску | - | `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/сеансів ACP і dispatch відповідей | + | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису JSON state | + | `plugin-sdk/file-lock` | Допоміжні засоби повторно-вхідного file-lock | + | `plugin-sdk/persistent-dedupe` | Допоміжні засоби dedupe cache з дисковим збереженням | + | `plugin-sdk/acp-runtime` | Допоміжні засоби ACP runtime/session і reply-dispatch | | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime агента | - | `plugin-sdk/boolean-param` | Читач слабко типізованих boolean-параметрів | - | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення зіставлення небезпечних імен | - | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токенів pairингу | - | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів пасивних каналів, статусу та ambient proxy | - | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповідей команди `/models` / провайдера | - | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби переліку команд Skills | - | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/build/serialize нативних команд | - | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI | + | `plugin-sdk/boolean-param` | Гнучкий зчитувач булевих параметрів | + | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення збігів для небезпечних назв | + | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою і pairing token | + | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, status і ambient proxy | + | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді для команди `/models` і провайдерів | + | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби для списку команд Skills | + | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/побудови/серіалізації native command | + | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих agent harness: типи harness, допоміжні засоби steer/abort для активного запуску, допоміжні засоби bridge інструментів OpenClaw і утиліти результатів спроб | + | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.A.I | | `plugin-sdk/infra-runtime` | Допоміжні засоби системних подій/heartbeat | | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу | | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби прапорців і подій діагностики | | `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch, proxy і pinned lookup | + | `plugin-sdk/fetch-runtime` | Обгорнутий fetch, proxy і допоміжні засоби pinned lookup | | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і SCP host | - | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації повторних спроб і виконавця повторних спроб | - | `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/робочого простору агента | - | `plugin-sdk/directory-runtime` | Запит/дедуплікація каталогів на основі конфігурації | + | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і виконавця retry | + | `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/workspace агента | + | `plugin-sdk/directory-runtime` | Запит/dedup каталогів із підтримкою конфігурації | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа плюс побудовники медіа payload | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також побудовники media payload | | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації медіа, вибір кандидатів і повідомлення про відсутні моделі | - | `plugin-sdk/media-understanding` | Типи провайдерів розуміння медіа плюс орієнтовані на провайдерів експорти допоміжних засобів для зображень/аудіо | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту/markdown/логування, такі як вилучення видимого асистенту тексту, render/chunking/table для markdown, редагування чутливих даних, допоміжні засоби тегів директив і утиліти безпечного тексту | + | `plugin-sdk/media-understanding` | Типи провайдерів media understanding, а також орієнтовані на провайдерів експорти допоміжних засобів для зображень/аудіо | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби для тексту/markdown/logging, такі як видалення тексту, видимого асистенту, допоміжні засоби render/chunking/table для markdown, допоміжні засоби редагування, допоміжні засоби тегів директив і утиліти безпечного тексту | | `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту | - | `plugin-sdk/speech` | Типи провайдерів мовлення плюс орієнтовані на провайдерів допоміжні засоби директив, реєстру та валідації | - | `plugin-sdk/speech-core` | Спільні типи провайдерів мовлення, допоміжні засоби реєстру, директив і нормалізації | - | `plugin-sdk/realtime-transcription` | Типи провайдерів транскрипції в реальному часі та допоміжні засоби реєстру | - | `plugin-sdk/realtime-voice` | Типи провайдерів голосу в реальному часі та допоміжні засоби реєстру | + | `plugin-sdk/speech` | Типи провайдерів speech, а також орієнтовані на провайдерів допоміжні засоби для директив, реєстру і валідації | + | `plugin-sdk/speech-core` | Спільні допоміжні засоби типів провайдерів speech, реєстру, директив і нормалізації | + | `plugin-sdk/realtime-transcription` | Типи провайдерів realtime transcription і допоміжні засоби реєстру | + | `plugin-sdk/realtime-voice` | Типи провайдерів realtime voice і допоміжні засоби реєстру | | `plugin-sdk/image-generation` | Типи провайдерів генерації зображень | - | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, failover, auth і допоміжні засоби реєстру | + | `plugin-sdk/image-generation-core` | Спільні допоміжні засоби типів генерації зображень, failover, auth і реєстру | | `plugin-sdk/music-generation` | Типи провайдерів/запитів/результатів генерації музики | - | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошук провайдерів і парсинг model-ref | + | `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/video-generation-core` | Спільні допоміжні засоби типів генерації відео, failover, пошуку провайдерів і розбору model-ref | + | `plugin-sdk/webhook-targets` | Допоміжні засоби реєстру webhook target і встановлення route | | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху webhook | | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK | + | `plugin-sdk/zod` | Повторно експортований `zod` для користувачів Plugin SDK | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/memory-core` | Поверхня допоміжних засобів вбудованого memory-core для manager/config/file/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Runtime facade для індексації/пошуку в пам’яті | + | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для manager/config/file/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Runtime facade для індексу/пошуку пам’яті | | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста пам’яті | | `plugin-sdk/memory-core-host-engine-embeddings` | Експорти embedding engine хоста пам’яті | | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста пам’яті | | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Допоміжні засоби мультимодального хоста пам’яті | - | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | - | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | + | `plugin-sdk/memory-core-host-multimodal` | Допоміжні засоби multimodal хоста пам’яті | + | `plugin-sdk/memory-core-host-query` | Допоміжні засоби query хоста пам’яті | + | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret хоста пам’яті | | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті | | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби CLI runtime хоста пам’яті | | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core runtime хоста пам’яті | | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Нейтральний щодо постачальника псевдонім для допоміжних засобів core runtime хоста пам’яті | - | `plugin-sdk/memory-host-events` | Нейтральний щодо постачальника псевдонім для допоміжних засобів журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Нейтральний щодо постачальника псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-core` | Нейтральний щодо вендора псевдонім для допоміжних засобів core runtime хоста пам’яті | + | `plugin-sdk/memory-host-events` | Нейтральний щодо вендора псевдонім для допоміжних засобів журналу подій хоста пам’яті | + | `plugin-sdk/memory-host-files` | Нейтральний щодо вендора псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби managed-markdown для плагінів, суміжних із пам’яттю | - | `plugin-sdk/memory-host-search` | Active memory runtime facade для доступу до search-manager | - | `plugin-sdk/memory-host-status` | Нейтральний щодо постачальника псевдонім для допоміжних засобів статусу хоста пам’яті | - | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів вбудованого memory-lancedb | + | `plugin-sdk/memory-host-search` | Активна runtime facade пам’яті для доступу до search-manager | + | `plugin-sdk/memory-host-status` | Нейтральний щодо вендора псевдонім для допоміжних засобів статусу хоста пам’яті | + | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled memory-lancedb | - - | Сімейство | Поточні підшляхи | Призначення | + + | Сімейство | Поточні підшляхи | Призначене використання | | --- | --- | --- | | 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` | Допоміжні засоби підтримки вбудованого browser plugin (`browser-support` залишається barrel-файлом сумісності) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня допоміжних засобів/runtime для вбудованого Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних засобів/runtime для вбудованого LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів для вбудованого IRC | - | Допоміжні засоби, специфічні для каналів | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шви сумісності / допоміжні засоби для вбудованих каналів | - | Допоміжні засоби, специфічні для auth/плагіна | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви допоміжних засобів для вбудованих функцій/плагінів; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Допоміжна/runtime поверхня вбудованого Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Допоміжна/runtime поверхня вбудованого LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Допоміжна поверхня вбудованого IRC | + | Допоміжні засоби, специфічні для каналів | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шари сумісності/допоміжні засоби для вбудованих каналів | + | Допоміжні засоби, специфічні для auth/плагінів | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шари допоміжних засобів для вбудованих можливостей/плагінів; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | ## API реєстрації -Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` з такими +Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими методами: ### Реєстрація можливостей -| Метод | Що він реєструє | -| ------------------------------------------------ | ------------------------------- | -| `api.registerProvider(...)` | Текстовий inference (LLM) | -| `api.registerCliBackend(...)` | Локальний CLI-бекенд inference | -| `api.registerChannel(...)` | Канал обміну повідомленнями | -| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | +| Метод | Що він реєструє | +| ------------------------------------------------ | ------------------------------------- | +| `api.registerProvider(...)` | Текстовий inference (LLM) | +| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента | +| `api.registerCliBackend(...)` | Локальний inference-бекенд CLI | +| `api.registerChannel(...)` | Канал обміну повідомленнями | +| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | | `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі | -| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сеанси в реальному часі | -| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | -| `api.registerImageGenerationProvider(...)` | Генерація зображень | -| `api.registerMusicGenerationProvider(...)` | Генерація музики | -| `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | -| `api.registerWebSearchProvider(...)` | Вебпошук | +| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сесії в реальному часі | +| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | +| `api.registerImageGenerationProvider(...)` | Генерація зображень | +| `api.registerMusicGenerationProvider(...)` | Генерація музики | +| `api.registerVideoGenerationProvider(...)` | Генерація відео | +| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | +| `api.registerWebSearchProvider(...)` | Вебпошук | ### Інструменти та команди -| Метод | Що він реєструє | -| ------------------------------ | -------------------------------------------- | +| Метод | Що він реєструє | +| ------------------------------- | --------------------------------------------- | | `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Користувацька команда (оминає LLM) | +| `api.registerCommand(def)` | Користувацька команда (оминає LLM) | ### Інфраструктура | Метод | Що він реєструє | -| --------------------------------------------- | ---------------------------------- | -| `api.registerHook(events, handler, opts?)` | Хук події | -| `api.registerHttpRoute(params)` | HTTP endpoint шлюзу | -| `api.registerGatewayMethod(name, handler)` | RPC-метод шлюзу | -| `api.registerCli(registrar, opts?)` | Підкоманда CLI | -| `api.registerService(service)` | Фоновий сервіс | -| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | -| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із пам’яттю | -| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті | +| ---------------------------------------------- | ---------------------------------- | +| `api.registerHook(events, handler, opts?)` | Хук події | +| `api.registerHttpRoute(params)` | HTTP endpoint gateway | +| `api.registerGatewayMethod(name, handler)` | RPC-метод gateway | +| `api.registerCli(registrar, opts?)` | Підкоманда CLI | +| `api.registerService(service)` | Фонова служба | +| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | +| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із пам’яттю | +| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті | -Зарезервовані простори імен адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) завжди залишаються `operator.admin`, навіть якщо плагін -намагається призначити вужчу область дії методу шлюзу. Для методів, що -належать плагіну, надавайте перевагу специфічним для плагіна префіксам. +Зарезервовані простори імен core admin (`config.*`, `exec.approvals.*`, `wizard.*`, +`update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити +вужчу область видимості для методу gateway. Для методів, що належать плагіну, +віддавайте перевагу префіксам, специфічним для плагіна. ### Метадані реєстрації CLI `api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня: -- `commands`: явні корені команд, якими володіє registrar -- `descriptors`: дескриптори команд часу парсингу, що використовуються для довідки кореневого CLI, +- `commands`: явні корені команд, що належать реєстратору +- `descriptors`: дескриптори команд на етапі розбору, які використовуються для кореневої довідки CLI, маршрутизації та лінивої реєстрації CLI плагіна -Якщо ви хочете, щоб команда плагіна залишалася ліниво завантажуваною в -звичайному шляху кореневого CLI, надайте `descriptors`, які охоплюють кожен -корінь команди верхнього рівня, що експонується цим registrar. +Якщо ви хочете, щоб команда плагіна залишалася ліниво завантажуваною у звичайному кореневому шляху CLI, +надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що експонується цим +реєстратором. ```typescript api.registerCli( @@ -381,88 +381,87 @@ api.registerCli( ); ``` -Використовуйте лише `commands`, коли вам не потрібна лінива реєстрація -кореневого CLI. Цей eager-шлях сумісності залишається підтримуваним, але він -не встановлює placeholder-и на основі дескрипторів для лінивого завантаження -під час парсингу. +Використовуйте лише `commands`, якщо вам не потрібна лінива реєстрація кореневого CLI. +Цей eager-шлях сумісності все ще підтримується, але він не встановлює +заповнювачі на основі дескрипторів для лінивого завантаження на етапі розбору. -### Реєстрація CLI-бекенду +### Реєстрація CLI-бекенда -`api.registerCliBackend(...)` дає змогу плагіну володіти типовою конфігурацією -для локального AI CLI-бекенду, такого як `codex-cli`. +`api.registerCliBackend(...)` дає змогу плагіну володіти конфігурацією за замовчуванням для локального +AI CLI-бекенда, такого як `codex-cli`. -- `id` бекенду стає префіксом провайдера в model ref на кшталт `codex-cli/gpt-5`. -- `config` бекенду використовує ту саму форму, що й `agents.defaults.cliBackends.`. -- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.` поверх - типового значення плагіна перед запуском CLI. -- Використовуйте `normalizeConfig`, коли бекенду потрібні переписування сумісності після злиття - (наприклад, для нормалізації старих форм прапорців). +- `id` бекенда стає префіксом провайдера в model ref, наприклад `codex-cli/gpt-5`. +- `config` бекенда використовує ту саму форму, що й `agents.defaults.cliBackends.`. +- Конфігурація користувача все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.` поверх + значення плагіна за замовчуванням перед запуском CLI. +- Використовуйте `normalizeConfig`, коли бекенду потрібні переписування для сумісності після об’єднання + (наприклад, нормалізація старих форм прапорців). ### Ексклюзивні слоти | Метод | Що він реєструє | -| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Context engine (одночасно активний лише один). Колбек `assemble()` отримує `availableTools` і `citationsMode`, щоб engine міг адаптувати доповнення до prompt. | -| `api.registerMemoryCapability(capability)` | Уніфіковану можливість пам’яті | +| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | Рушій контексту (одночасно активним може бути лише один). Зворотний виклик `assemble()` отримує `availableTools` і `citationsMode`, щоб рушій міг адаптувати доповнення prompt. | +| `api.registerMemoryCapability(capability)` | Єдину можливість пам’яті | | `api.registerMemoryPromptSection(builder)` | Побудовник розділу prompt пам’яті | -| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush пам’яті | +| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану скидання пам’яті | | `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті | -### Адаптери embedding для пам’яті +### Адаптери embeddings пам’яті -| Метод | Що він реєструє | -| --------------------------------------------- | -------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного плагіна | +| Метод | Що він реєструє | +| ---------------------------------------------- | ----------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embeddings пам’яті для активного плагіна | -- `registerMemoryCapability` — рекомендований API ексклюзивного memory-plugin. -- `registerMemoryCapability` також може експонувати `publicArtifacts.listArtifacts(...)`, - щоб супутні плагіни могли споживати експортовані артефакти пам’яті через - `openclaw/plugin-sdk/memory-host-core` замість звернення до приватного - макета конкретного плагіна пам’яті. +- `registerMemoryCapability` — це рекомендований API ексклюзивного memory-plugin. +- `registerMemoryCapability` також може експортувати `publicArtifacts.listArtifacts(...)`, + щоб companion plugins могли використовувати експортовані артефакти пам’яті через + `openclaw/plugin-sdk/memory-host-core` замість звернення до приватної структури + конкретного memory plugin. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` — це застаріло-сумісні API ексклюзивного memory-plugin. -- `registerMemoryEmbeddingProvider` дає змогу активному memory-plugin зареєструвати - один або кілька id адаптерів embedding (наприклад, `openai`, `gemini` або + `registerMemoryRuntime` — це сумісні зі старими версіями API ексклюзивних memory-plugin. +- `registerMemoryEmbeddingProvider` дає змогу активному memory plugin зареєструвати один + або кілька ідентифікаторів adapter embeddings (наприклад, `openai`, `gemini` або користувацький id, визначений плагіном). - Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і `agents.defaults.memorySearch.fallback`, визначається відносно цих зареєстрованих - id адаптерів. + id adapter. ### Події та життєвий цикл | Метод | Що він робить | -| ------------------------------------------- | ---------------------------- | -| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | -| `api.onConversationBindingResolved(handler)` | Колбек визначення прив’язки розмови | +| -------------------------------------------- | ---------------------------- | +| `api.on(hookName, handler, opts?)` | Типізований lifecycle hook | +| `api.onConversationBindingResolved(handler)` | Зворотний виклик binding розмови | -### Семантика рішень хуків +### Семантика рішень для хуків -- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно якийсь обробник встановить його, обробники з нижчим пріоритетом пропускаються. -- `before_tool_call`: повернення `{ block: false }` трактується як відсутність рішення (так само, як і пропуск `block`), а не як перевизначення. -- `before_install`: повернення `{ block: true }` є термінальним. Щойно якийсь обробник встановить його, обробники з нижчим пріоритетом пропускаються. -- `before_install`: повернення `{ block: false }` трактується як відсутність рішення (так само, як і пропуск `block`), а не як перевизначення. -- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно якийсь обробник візьме dispatch на себе, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються. -- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно якийсь обробник встановить його, обробники з нижчим пріоритетом пропускаються. -- `message_sending`: повернення `{ cancel: false }` трактується як відсутність рішення (так само, як і пропуск `cancel`), а не як перевизначення. +- `before_tool_call`: повернення `{ block: true }` є остаточним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються. +- `before_tool_call`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. +- `before_install`: повернення `{ block: true }` є остаточним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються. +- `before_install`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. +- `reply_dispatch`: повернення `{ handled: true, ... }` є остаточним. Щойно будь-який обробник бере на себе dispatch, обробники з нижчим пріоритетом і стандартний шлях dispatch моделі пропускаються. +- `message_sending`: повернення `{ cancel: true }` є остаточним. Щойно будь-який обробник встановлює це значення, обробники з нижчим пріоритетом пропускаються. +- `message_sending`: повернення `{ cancel: false }` вважається відсутністю рішення (так само, як пропуск `cancel`), а не перевизначенням. ### Поля об’єкта API -| Поле | Тип | Опис | -| ------------------------ | ------------------------- | ----------------------------------------------------------------------------------------- | -| `api.id` | `string` | ID плагіна | -| `api.name` | `string` | Відображувана назва | -| `api.version` | `string?` | Версія плагіна (необов’язково) | -| `api.description` | `string?` | Опис плагіна (необов’язково) | -| `api.source` | `string` | Шлях до джерела плагіна | -| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) | -| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок runtime у пам’яті, якщо доступний) | -| `api.pluginConfig` | `Record` | Конфігурація, специфічна для плагіна, з `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Логер з областю дії (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування перед повним entry | -| `api.resolvePath(input)` | `(string) => string` | Визначення шляху відносно кореня плагіна | +| Поле | Тип | Опис | +| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | +| `api.id` | `string` | Ідентифікатор плагіна | +| `api.name` | `string` | Відображувана назва | +| `api.version` | `string?` | Версія плагіна (необов’язково) | +| `api.description` | `string?` | Опис плагіна (необов’язково) | +| `api.source` | `string` | Шлях до джерела плагіна | +| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) | +| `api.config` | `OpenClawConfig` | Поточний snapshot конфігурації (активний snapshot runtime в пам’яті, якщо доступний) | +| `api.pluginConfig` | `Record` | Конфігурація, специфічна для плагіна, з `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger з обмеженою областю (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування до повного entry | +| `api.resolvePath(input)` | `(string) => string` | Визначити шлях відносно кореня плагіна | -## Внутрішнє правило модулів +## Угода щодо внутрішніх модулів Усередині вашого плагіна використовуйте локальні barrel-файли для внутрішніх імпортів: @@ -471,49 +470,45 @@ my-plugin/ api.ts # Публічні експорти для зовнішніх споживачів runtime-api.ts # Експорти runtime лише для внутрішнього використання index.ts # Точка входу плагіна - setup-entry.ts # Полегшений вхід лише для налаштування (необов’язково) + setup-entry.ts # Полегшений entry лише для налаштування (необов’язково) ``` Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/` - у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або + з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. -Публічні поверхні вбудованих плагінів, що завантажуються через facade -(`api.ts`, `runtime-api.ts`, `index.ts`, `setup-entry.ts` та подібні публічні -entry-файли), тепер віддають перевагу активному знімку конфігурації runtime, -коли OpenClaw уже запущено. Якщо знімка runtime ще немає, вони переходять до -резервного використання визначеного файла конфігурації на диску. +Фасадно-завантажувані публічні поверхні вбудованих плагінів (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` та подібні публічні entry-файли) тепер віддають перевагу +активному snapshot конфігурації runtime, коли OpenClaw уже запущено. Якщо snapshot runtime +ще не існує, вони повертаються до визначеного файлу конфігурації на диску. -Плагіни провайдерів також можуть експонувати вузький локальний barrel-файл -контракту плагіна, коли допоміжний засіб навмисно є специфічним для провайдера -і ще не належить до загального підшляху SDK. Поточний вбудований приклад: -провайдер Anthropic тримає свої допоміжні засоби потоку Claude у власному -публічному шві `api.ts` / `contract-api.ts` замість просування логіки -beta-header Anthropic і `service_tier` до загального контракту -`plugin-sdk/*`. +Плагіни провайдерів також можуть експонувати вузький локальний контрактний barrel плагіна, коли +допоміжний засіб навмисно є специфічним для провайдера і ще не належить до загального підшляху SDK. +Поточний вбудований приклад: провайдер Anthropic зберігає свої допоміжні засоби потоків Claude +у власному публічному seam `api.ts` / `contract-api.ts` замість того, щоб просувати логіку +Anthropic beta-header і `service_tier` у загальний контракт `plugin-sdk/*`. Інші поточні вбудовані приклади: - `@openclaw/openai-provider`: `api.ts` експортує побудовники провайдерів, - допоміжні засоби типових моделей і побудовники провайдерів realtime -- `@openclaw/openrouter-provider`: `api.ts` експортує побудовник провайдера та + допоміжні засоби моделей за замовчуванням і побудовники realtime-провайдерів +- `@openclaw/openrouter-provider`: `api.ts` експортує побудовник провайдера, а також допоміжні засоби онбордингу/конфігурації - Production-код розширень також має уникати імпортів - `openclaw/plugin-sdk/`. Якщо допоміжний засіб справді є спільним, - перенесіть його до нейтрального підшляху SDK, такого як - `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої - поверхні, орієнтованої на можливості, замість зв’язування двох плагінів між собою. + Production-код розширень також має уникати імпортів `openclaw/plugin-sdk/`. + Якщо допоміжний засіб справді є спільним, винесіть його в нейтральний підшлях SDK, + такий як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншу + поверхню, орієнтовану на можливість, замість жорсткого зв’язування двох плагінів. -## Пов’язане +## Пов’язані матеріали -- [Entry Points](/uk/plugins/sdk-entrypoints) — параметри `definePluginEntry` і `defineChannelPluginEntry` -- [Runtime Helpers](/uk/plugins/sdk-runtime) — повний довідник простору імен `api.runtime` -- [Setup and Config](/uk/plugins/sdk-setup) — пакування, маніфести, схеми конфігурації -- [Testing](/uk/plugins/sdk-testing) — утиліти тестування та правила lint -- [SDK Migration](/uk/plugins/sdk-migration) — міграція з застарілих поверхонь -- [Plugin Internals](/uk/plugins/architecture) — поглиблена архітектура та модель можливостей +- [Точки входу](/uk/plugins/sdk-entrypoints) — параметри `definePluginEntry` і `defineChannelPluginEntry` +- [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) — повний довідник простору імен `api.runtime` +- [Налаштування і конфігурація](/uk/plugins/sdk-setup) — пакування, маніфести, схеми конфігурації +- [Тестування](/uk/plugins/sdk-testing) — утиліти тестування та правила lint +- [Міграція SDK](/uk/plugins/sdk-migration) — міграція з застарілих поверхонь +- [Внутрішня будова плагінів](/uk/plugins/architecture) — детальна архітектура і модель можливостей diff --git a/docs/uk/plugins/sdk-provider-plugins.md b/docs/uk/plugins/sdk-provider-plugins.md index 8b98532c4..43f15c053 100644 --- a/docs/uk/plugins/sdk-provider-plugins.md +++ b/docs/uk/plugins/sdk-provider-plugins.md @@ -1,32 +1,39 @@ --- read_when: - Ви створюєте новий плагін постачальника моделей - - Ви хочете додати до OpenClaw OpenAI-сумісний проксі або власну LLM - - Вам потрібно зрозуміти автентифікацію постачальників, каталоги та runtime hooks + - Ви хочете додати до OpenClaw сумісний з OpenAI проксі або власну LLM + - Вам потрібно зрозуміти автентифікацію постачальника, каталоги та хуки середовища виконання sidebarTitle: Provider Plugins summary: Покроковий посібник зі створення плагіна постачальника моделей для OpenClaw title: Створення плагінів постачальників x-i18n: - generated_at: "2026-04-08T18:09:13Z" + generated_at: "2026-04-10T20:23:46Z" model: gpt-5.4 provider: openai - source_hash: 38d9af522dc19e49c81203a83a4096f01c2398b1df771c848a30ad98f251e9e1 + source_hash: b81b80627fd594e2dc889c95359df665ebbbb85c74c231a226219dcb556f193b source_path: plugins/sdk-provider-plugins.md workflow: 15 --- # Створення плагінів постачальників -Цей посібник покроково пояснює, як створити плагін постачальника, який додає -до OpenClaw постачальника моделей (LLM). Наприкінці у вас буде постачальник із каталогом моделей, -автентифікацією через API key та динамічним визначенням моделей. +Цей посібник описує створення плагіна постачальника, який додає постачальника +моделей (LLM) до OpenClaw. Наприкінці у вас буде постачальник із каталогом +моделей, автентифікацією через API-ключ і динамічним визначенням моделей. - Якщо ви раніше не створювали жодного плагіна OpenClaw, спочатку прочитайте - [Getting Started](/uk/plugins/building-plugins), щоб ознайомитися з базовою + Якщо ви ще не створювали жодного плагіна OpenClaw, спочатку прочитайте + [Початок роботи](/uk/plugins/building-plugins), щоб ознайомитися з базовою структурою пакета та налаштуванням маніфесту. + + Плагіни постачальників додають моделі до стандартного циклу інференсу OpenClaw. Якщо модель + має працювати через нативний демон агента, який керує потоками, компакцією або подіями + інструментів, поєднайте постачальника з [agent harness](/uk/plugins/sdk-agent-harness) + замість того, щоб виносити деталі протоколу демона в core. + + ## Покроковий приклад @@ -90,12 +97,12 @@ x-i18n: Маніфест оголошує `providerAuthEnvVars`, щоб OpenClaw міг виявляти - облікові дані без завантаження runtime вашого плагіна. Додайте `providerAuthAliases`, + облікові дані без завантаження середовища виконання вашого плагіна. Додайте `providerAuthAliases`, якщо варіант постачальника має повторно використовувати автентифікацію іншого ідентифікатора постачальника. `modelSupport` - необов’язковий і дозволяє OpenClaw автоматично завантажувати ваш плагін постачальника зі скорочених - ідентифікаторів моделей, таких як `acme-large`, ще до появи runtime hooks. Якщо ви публікуєте - постачальника у ClawHub, ці поля `openclaw.compat` і `openclaw.build` - обов’язкові в `package.json`. + є необов’язковим і дає OpenClaw змогу автоматично завантажувати ваш плагін постачальника зі скорочених + ідентифікаторів моделей, як-от `acme-large`, ще до появи хуків середовища виконання. Якщо ви публікуєте + постачальника на ClawHub, поля `openclaw.compat` і `openclaw.build` + у `package.json` є обов’язковими. @@ -175,9 +182,9 @@ x-i18n: `openclaw onboard --acme-ai-api-key ` і вибрати `acme-ai/acme-large` як свою модель. - Для вбудованих постачальників, які реєструють лише одного текстового постачальника з автентифікацією через API key - плюс один runtime на основі каталогу, віддавайте перевагу вужчому - допоміжному засобу `defineSingleProviderPluginEntry(...)`: + Для вбудованих постачальників, які реєструють лише одного текстового постачальника з + автентифікацією через API-ключ плюс одне середовище виконання на основі каталогу, краще використовувати вужчий + помічник `defineSingleProviderPluginEntry(...)`: ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -212,24 +219,25 @@ x-i18n: }); ``` - Якщо ваш потік автентифікації також має оновлювати `models.providers.*`, aliases і - модель агента за замовчуванням під час онбордингу, використовуйте готові helper-функції з - `openclaw/plugin-sdk/provider-onboard`. Найвужчі helper-функції: + Якщо під час онбордингу ваш потік автентифікації також має змінювати `models.providers.*`, псевдоніми та + модель агента за замовчуванням, використовуйте готові помічники з + `openclaw/plugin-sdk/provider-onboard`. Найвужчі помічники — `createDefaultModelPresetAppliers(...)`, `createDefaultModelsPresetAppliers(...)` і `createModelCatalogPresetAppliers(...)`. - Якщо власний endpoint постачальника підтримує потокові блоки використання на - звичайному транспорті `openai-completions`, віддавайте перевагу спільним helper-функціям каталогу з - `openclaw/plugin-sdk/provider-catalog-shared` замість жорсткого кодування перевірок - ідентифікатора постачальника. `supportsNativeStreamingUsageCompat(...)` і - `applyProviderNativeStreamingUsageCompat(...)` визначають підтримку з карти можливостей endpoint, тож власні endpoint Moonshot/DashScope-типу - також можуть бути увімкнені, навіть якщо плагін використовує власний ідентифікатор постачальника. + Коли нативна кінцева точка постачальника підтримує потокові блоки використання у + стандартному транспорті `openai-completions`, віддавайте перевагу спільним помічникам каталогу з + `openclaw/plugin-sdk/provider-catalog-shared` замість жорстко закодованих перевірок ідентифікатора постачальника. + `supportsNativeStreamingUsageCompat(...)` і + `applyProviderNativeStreamingUsageCompat(...)` визначають підтримку за картою можливостей кінцевої точки, + тому нативні кінцеві точки на кшталт Moonshot/DashScope теж можуть увімкнути цю можливість, + навіть якщо плагін використовує власний ідентифікатор постачальника. - Якщо ваш постачальник приймає довільні ідентифікатори моделей (як проксі чи маршрутизатор), + Якщо ваш постачальник приймає довільні ідентифікатори моделей (як проксі або маршрутизатор), додайте `resolveDynamicModel`: ```typescript @@ -252,16 +260,16 @@ x-i18n: ``` Якщо для визначення потрібен мережевий виклик, використовуйте `prepareDynamicModel` для асинхронного - прогріву — після завершення `resolveDynamicModel` буде запущено знову. + прогріву — після його завершення `resolveDynamicModel` виконається знову. - - Більшості постачальників потрібні лише `catalog` + `resolveDynamicModel`. Додавайте hooks - поступово, коли вони стають потрібними вашому постачальнику. + + Більшості постачальників потрібні лише `catalog` + `resolveDynamicModel`. Додавайте хуки + поступово, у міру потреб вашого постачальника. - Спільні builder-функції helper-ів тепер покривають найпоширеніші сімейства - replay/tool-compat, тому плагінам зазвичай не потрібно вручну підключати кожен hook окремо: + Спільні генератори-помічники тепер охоплюють найпоширеніші сімейства сумісності replay/tool, + тому плагінам зазвичай не потрібно вручну підключати кожен хук окремо: ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -281,17 +289,17 @@ x-i18n: }); ``` - Доступні сьогодні сімейства replay: + Наразі доступні такі сімейства replay: - | Family | Що воно підключає | + | Сімейство | Що воно підключає | | --- | --- | - | `openai-compatible` | Спільна політика replay у стилі OpenAI для OpenAI-сумісних транспортів, зокрема очищення tool-call-id, виправлення порядку assistant-first і загальна валідація Gemini-turn там, де цього потребує транспорт | - | `anthropic-by-model` | Політика replay з урахуванням Claude, що вибирається за `modelId`, тому транспорти Anthropic-message отримують очищення thinking-block, специфічне для Claude, лише коли визначена модель справді є ідентифікатором Claude | - | `google-gemini` | Власна політика replay Gemini плюс очищення bootstrap replay і режим tagged reasoning-output | - | `passthrough-gemini` | Очищення thought-signature Gemini для моделей Gemini, що працюють через OpenAI-сумісні проксі-транспорти; не вмикає власну валідацію replay Gemini або переписування bootstrap | - | `hybrid-anthropic-openai` | Гібридна політика для постачальників, які поєднують поверхні моделей Anthropic-message і OpenAI-compatible в одному плагіні; необов’язкове видалення thinking-block лише для Claude залишається обмеженим стороною Anthropic | + | `openai-compatible` | Спільна політика replay у стилі OpenAI для сумісних з OpenAI транспортів, включно з очищенням ідентифікаторів викликів інструментів, виправленнями порядку assistant-first і загальною валідацією Gemini-turn там, де це потрібно транспорту | + | `anthropic-by-model` | Політика replay з урахуванням Claude, що вибирається за `modelId`, тому транспорти Anthropic-message отримують специфічне очищення thinking-block для Claude лише тоді, коли визначена модель справді є ідентифікатором Claude | + | `google-gemini` | Нативна політика replay для Gemini плюс очищення bootstrap replay і режим reasoning-output з тегами | + | `passthrough-gemini` | Очищення thought-signature для моделей Gemini, що працюють через сумісні з OpenAI проксі-транспорти; не вмикає нативну валідацію replay Gemini або переписування bootstrap | + | `hybrid-anthropic-openai` | Гібридна політика для постачальників, які поєднують поверхні моделей Anthropic-message і сумісні з OpenAI в одному плагіні; необов’язкове відкидання thinking-block лише для Claude залишається обмеженим стороною Anthropic | - Реальні вбудовані приклади: + Реальні приклади вбудованих плагінів: - `google` і `google-gemini-cli`: `google-gemini` - `openrouter`, `kilocode`, `opencode` і `opencode-go`: `passthrough-gemini` @@ -299,19 +307,19 @@ x-i18n: - `minimax`: `hybrid-anthropic-openai` - `moonshot`, `ollama`, `xai` і `zai`: `openai-compatible` - Доступні сьогодні сімейства stream: + Наразі доступні такі сімейства stream: - | Family | Що воно підключає | + | Сімейство | Що воно підключає | | --- | --- | - | `google-thinking` | Нормалізація payload thinking Gemini на спільному шляху stream | - | `kilocode-thinking` | Обгортка міркування Kilo на спільному шляху проксі-stream, де `kilo/auto` та непідтримувані ідентифікатори міркування проксі пропускають інжектований thinking | - | `moonshot-thinking` | Відображення бінарного payload native-thinking Moonshot із config + рівня `/think` | - | `minimax-fast-mode` | Переписування моделі MiniMax fast-mode на спільному шляху stream | - | `openai-responses-defaults` | Спільні власні обгортки OpenAI/Codex Responses: заголовки attribution, `/fast`/`serviceTier`, verbosity тексту, власний web search Codex, формування payload для сумісності reasoning і керування контекстом Responses | - | `openrouter-thinking` | Обгортка reasoning OpenRouter для маршрутів проксі, з централізованою обробкою пропусків для непідтримуваних моделей і `auto` | - | `tool-stream-default-on` | Обгортка `tool_stream`, увімкнена за замовчуванням, для таких постачальників, як Z.AI, які хочуть потокову передачу інструментів, якщо її явно не вимкнено | + | `google-thinking` | Нормалізація payload thinking Gemini у спільному шляху stream | + | `kilocode-thinking` | Обгортка reasoning Kilo у спільному шляху проксі-stream, де `kilo/auto` і непідтримувані ідентифікатори reasoning проксі пропускають інжектований thinking | + | `moonshot-thinking` | Відображення бінарного payload native-thinking Moonshot із конфігурації та рівня `/think` | + | `minimax-fast-mode` | Переписування моделей MiniMax fast-mode у спільному шляху stream | + | `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: заголовки атрибуції, `/fast`/`serviceTier`, деталізація тексту, нативний вебпошук Codex, формування payload для сумісності reasoning і керування контекстом Responses | + | `openrouter-thinking` | Обгортка reasoning OpenRouter для проксі-маршрутів, де пропуски для непідтримуваних моделей і `auto` централізовано обробляються | + | `tool-stream-default-on` | Обгортка `tool_stream`, увімкнена за замовчуванням, для постачальників на кшталт Z.AI, які хочуть потокову передачу інструментів, якщо її явно не вимкнено | - Реальні вбудовані приклади: + Реальні приклади вбудованих плагінів: - `google` і `google-gemini-cli`: `google-thinking` - `kilocode`: `kilocode-thinking` @@ -321,80 +329,81 @@ x-i18n: - `openrouter`: `openrouter-thinking` - `zai`: `tool-stream-default-on` - `openclaw/plugin-sdk/provider-model-shared` також експортує enum сімейств replay - разом зі спільними helper-функціями, на основі яких побудовано ці сімейства. Поширені публічні експорти - включають: + `openclaw/plugin-sdk/provider-model-shared` також експортує enum сімейств + replay, а також спільні помічники, з яких побудовані ці сімейства. Серед + поширених публічних експортів: - `ProviderReplayFamily` - `buildProviderReplayFamilyHooks(...)` - - спільні builder-функції replay, як-от `buildOpenAICompatibleReplayPolicy(...)`, + - спільні генератори replay, такі як `buildOpenAICompatibleReplayPolicy(...)`, `buildAnthropicReplayPolicyForModel(...)`, `buildGoogleGeminiReplayPolicy(...)` і `buildHybridAnthropicOrOpenAIReplayPolicy(...)` - - helper-функції replay Gemini, як-от `sanitizeGoogleGeminiReplayHistory(...)` + - помічники replay для Gemini, такі як `sanitizeGoogleGeminiReplayHistory(...)` і `resolveTaggedReasoningOutputMode()` - - helper-функції для endpoint/моделей, як-от `resolveProviderEndpoint(...)`, + - помічники для endpoint/моделей, такі як `resolveProviderEndpoint(...)`, `normalizeProviderId(...)`, `normalizeGooglePreviewModelId(...)` і `normalizeNativeXaiModelId(...)` - `openclaw/plugin-sdk/provider-stream` надає як builder сімейств, - так і публічні helper-обгортки, які ці сімейства повторно використовують. Поширені публічні експорти - включають: + `openclaw/plugin-sdk/provider-stream` надає як генератор сімейств, так і + публічні помічники-обгортки, які ці сімейства повторно використовують. Серед + поширених публічних експортів: - `ProviderStreamFamily` - `buildProviderStreamFamilyHooks(...)` - `composeProviderStreamWrappers(...)` - - спільні обгортки OpenAI/Codex, як-от + - спільні обгортки OpenAI/Codex, такі як `createOpenAIAttributionHeadersWrapper(...)`, `createOpenAIFastModeWrapper(...)`, `createOpenAIServiceTierWrapper(...)`, `createOpenAIResponsesContextManagementWrapper(...)` і `createCodexNativeWebSearchWrapper(...)` - - спільні обгортки проксі/постачальників, як-от `createOpenRouterWrapper(...)`, + - спільні обгортки проксі/постачальників, такі як `createOpenRouterWrapper(...)`, `createToolStreamWrapper(...)` і `createMinimaxFastModeWrapper(...)` - Деякі helper-функції для stream навмисно залишаються локальними для конкретного постачальника. Поточний вбудований - приклад: `@openclaw/anthropic-provider` експортує + Деякі помічники stream навмисно залишаються локальними для постачальника. Поточний + вбудований приклад: `@openclaw/anthropic-provider` експортує `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і - builder-функції нижчого рівня для обгорток Anthropic зі свого публічного інтерфейсу `api.ts` / - `contract-api.ts`. Ці helper-функції залишаються специфічними для Anthropic, оскільки - вони також кодують обробку бета-версій Claude OAuth і обмеження `context1m`. + низькорівневі генератори обгорток Anthropic зі свого публічного шва `api.ts` / + `contract-api.ts`. Ці помічники залишаються специфічними для Anthropic, оскільки + вони також кодують обробку Claude OAuth beta і gating для `context1m`. - Інші вбудовані постачальники також залишають локальними обгортки, специфічні для транспорту, коли - цю поведінку неможливо чисто розділити між сімействами. Поточний приклад: вбудований - плагін xAI залишає власне формування Responses xAI у своєму - `wrapStreamFn`, зокрема переписування alias `/fast`, `tool_stream` за замовчуванням, - очищення непідтримуваних strict-tool і видалення payload reasoning, специфічного для xAI. + Інші вбудовані постачальники також тримають локальними обгортки, специфічні для транспорту, коли + цю поведінку неможливо чисто поділити між сімействами. Поточний приклад: вбудований + плагін xAI зберігає нативне формування Responses для xAI у власному + `wrapStreamFn`, включно з переписуванням псевдонімів `/fast`, `tool_stream` + за замовчуванням, очищенням непідтримуваних strict-tool і видаленням payload reasoning, + специфічним для xAI. `openclaw/plugin-sdk/provider-tools` наразі надає одне спільне - сімейство tool-schema плюс спільні helper-функції schema/compat: + сімейство схем інструментів, а також спільні помічники схем/сумісності: - `ProviderToolCompatFamily` документує поточний перелік спільних сімейств. - - `buildProviderToolCompatFamilyHooks("gemini")` підключає очищення schema - Gemini + діагностику для постачальників, яким потрібні Gemini-safe tool schemas. + - `buildProviderToolCompatFamilyHooks("gemini")` підключає очищення схем Gemini + + діагностику для постачальників, яким потрібні безпечні для Gemini схеми інструментів. - `normalizeGeminiToolSchemas(...)` і `inspectGeminiToolSchemas(...)` - — це базові публічні helper-функції schema Gemini. - - `resolveXaiModelCompatPatch()` повертає вбудований compat patch xAI: - `toolSchemaProfile: "xai"`, непідтримувані ключові слова schema, власну - підтримку `web_search` і декодування аргументів виклику інструментів з HTML-entity. - - `applyXaiModelCompat(model)` застосовує той самий compat patch xAI до - визначеної моделі, перш ніж вона потрапить до runner. + — це базові публічні помічники схем Gemini. + - `resolveXaiModelCompatPatch()` повертає вбудований compat patch для xAI: + `toolSchemaProfile: "xai"`, непідтримувані ключові слова схем, нативну + підтримку `web_search` і декодування аргументів викликів інструментів з HTML-entity. + - `applyXaiModelCompat(model)` застосовує той самий compat patch для xAI до + визначеної моделі до того, як вона потрапить до runner. - Реальний вбудований приклад: плагін xAI використовує `normalizeResolvedModel` плюс - `contributeResolvedModelCompat`, щоб зберегти ці метадані compat у власності - постачальника, а не жорстко кодувати правила xAI в core. + Реальний вбудований приклад: плагін xAI використовує `normalizeResolvedModel` разом із + `contributeResolvedModelCompat`, щоб метадані compat залишалися у власності постачальника, + а не були жорстко закодовані в core як правила xAI. - Такий самий шаблон на рівні кореня пакета також лежить в основі інших вбудованих постачальників: + Той самий шаблон кореня пакета також лежить в основі інших вбудованих постачальників: - - `@openclaw/openai-provider`: `api.ts` експортує builder-функції постачальника, - helper-функції для моделей за замовчуванням і builder-функції постачальника realtime - - `@openclaw/openrouter-provider`: `api.ts` експортує builder-функцію постачальника - плюс helper-функції для onboarding/config + - `@openclaw/openai-provider`: `api.ts` експортує генератори постачальника, + помічники моделей за замовчуванням і генератори realtime-постачальника + - `@openclaw/openrouter-provider`: `api.ts` експортує генератор постачальника + разом із помічниками онбордингу/конфігурації - - Для постачальників, яким потрібен обмін токенами перед кожним викликом inference: + + Для постачальників, яким потрібен обмін токенів перед кожним викликом інференсу: ```typescript prepareRuntimeAuth: async (ctx) => { @@ -407,8 +416,8 @@ x-i18n: }, ``` - - Для постачальників, яким потрібні користувацькі заголовки запиту або зміни тіла запиту: + + Для постачальників, яким потрібні власні заголовки запитів або зміни тіла запиту: ```typescript // wrapStreamFn returns a StreamFn derived from ctx.streamFn @@ -425,9 +434,9 @@ x-i18n: }, ``` - - Для постачальників, яким потрібні власні заголовки запиту/сесії або метадані на - універсальних HTTP- чи WebSocket-транспортах: + + Для постачальників, яким потрібні нативні заголовки запиту/сесії або метадані в + узагальнених HTTP або WebSocket транспортах: ```typescript resolveTransportTurnState: (ctx) => ({ @@ -462,84 +471,83 @@ x-i18n: - - OpenClaw викликає hooks у такому порядку. Більшість постачальників використовують лише 2-3: + + OpenClaw викликає хуки в такому порядку. Більшість постачальників використовують лише 2-3: | # | Hook | Коли використовувати | | --- | --- | --- | | 1 | `catalog` | Каталог моделей або значення `baseUrl` за замовчуванням | - | 2 | `applyConfigDefaults` | Глобальні значення за замовчуванням, що належать постачальнику, під час materialization config | - | 3 | `normalizeModelId` | Очищення aliases застарілих/preview model-id перед пошуком | - | 4 | `normalizeTransport` | Очищення `api` / `baseUrl` для сімейства постачальника перед загальним збиранням моделі | - | 5 | `normalizeConfig` | Нормалізація config `models.providers.` | - | 6 | `applyNativeStreamingUsageCompat` | Переписування compat для власного streaming-usage для постачальників config | - | 7 | `resolveConfigApiKey` | Визначення автентифікації за env-marker, що належить постачальнику | - | 8 | `resolveSyntheticAuth` | Синтетична автентифікація local/self-hosted або на основі config | - | 9 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет синтетичних placeholders збереженого профілю відносно env/config auth | - | 10 | `resolveDynamicModel` | Прийом довільних upstream model IDs | + | 2 | `applyConfigDefaults` | Глобальні значення за замовчуванням, що належать постачальнику, під час матеріалізації конфігурації | + | 3 | `normalizeModelId` | Очищення застарілих/preview-псевдонімів `model-id` перед пошуком | + | 4 | `normalizeTransport` | Очищення `api` / `baseUrl` для сімейства постачальника перед загальним складанням моделі | + | 5 | `normalizeConfig` | Нормалізація конфігурації `models.providers.` | + | 6 | `applyNativeStreamingUsageCompat` | Переписування сумісності native streaming-usage для конфігураційних постачальників | + | 7 | `resolveConfigApiKey` | Визначення автентифікації env-marker, що належить постачальнику | + | 8 | `resolveSyntheticAuth` | Синтетична автентифікація для local/self-hosted або конфігураційна автентифікація | + | 9 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет синтетичних placeholder збереженого профілю порівняно з env/config auth | + | 10 | `resolveDynamicModel` | Приймає довільні upstream-ідентифікатори моделей | | 11 | `prepareDynamicModel` | Асинхронне отримання метаданих перед визначенням | | 12 | `normalizeResolvedModel` | Переписування транспорту перед runner | - Примітки щодо runtime fallback: + Примітки щодо fallback у середовищі виконання: - - `normalizeConfig` спочатку перевіряє відповідного постачальника, потім інші - плагіни постачальників, здатні обробляти hooks, доки один із них справді не змінить config. - Якщо жоден hook постачальника не перепише підтримуваний запис config сімейства Google, - усе одно застосовується вбудований нормалізатор config Google. - - `resolveConfigApiKey` використовує hook постачальника, якщо він доступний. Вбудований + - `normalizeConfig` спочатку перевіряє відповідний постачальник, а потім інші + плагіни постачальників із підтримкою хуків, доки один із них справді не змінить конфігурацію. + Якщо жоден хук постачальника не переписує підтримуваний запис конфігурації сімейства Google, + усе одно застосовується вбудований нормалізатор конфігурації Google. + - `resolveConfigApiKey` використовує хук постачальника, якщо він доступний. Вбудований шлях `amazon-bedrock` також має тут вбудований resolver AWS env-marker, - хоча сама runtime auth Bedrock усе ще використовує стандартний - ланцюжок AWS SDK. - | 13 | `contributeResolvedModelCompat` | Прапори compat для моделей вендора за іншим сумісним транспортом | + хоча сама runtime-автентифікація Bedrock усе ще використовує ланцюжок за замовчуванням AWS SDK. + | 13 | `contributeResolvedModelCompat` | Прапорці compat для моделей постачальників за іншим сумісним транспортом | | 14 | `capabilities` | Застарілий статичний набір можливостей; лише для сумісності | - | 15 | `normalizeToolSchemas` | Очищення tool-schema, що належить постачальнику, перед реєстрацією | - | 16 | `inspectToolSchemas` | Діагностика tool-schema, що належить постачальнику | + | 15 | `normalizeToolSchemas` | Очищення схем інструментів, що належить постачальнику, перед реєстрацією | + | 16 | `inspectToolSchemas` | Діагностика схем інструментів, що належить постачальнику | | 17 | `resolveReasoningOutputMode` | Контракт tagged vs native reasoning-output | | 18 | `prepareExtraParams` | Параметри запиту за замовчуванням | - | 19 | `createStreamFn` | Повністю користувацький транспорт StreamFn | - | 20 | `wrapStreamFn` | Користувацькі обгортки заголовків/тіла на звичайному шляху stream | - | 21 | `resolveTransportTurnState` | Власні заголовки/метадані для кожного turn | - | 22 | `resolveWebSocketSessionPolicy` | Власні заголовки сесії WS / період охолодження | - | 23 | `formatApiKey` | Користувацька форма runtime token | - | 24 | `refreshOAuth` | Користувацьке оновлення OAuth | - | 25 | `buildAuthDoctorHint` | Підказка щодо виправлення автентифікації | - | 26 | `matchesContextOverflowError` | Визначення переповнення, що належить постачальнику | + | 19 | `createStreamFn` | Повністю власний транспорт StreamFn | + | 20 | `wrapStreamFn` | Власні обгортки заголовків/тіла у стандартному шляху stream | + | 21 | `resolveTransportTurnState` | Нативні заголовки/метадані для кожного turn | + | 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сесії WS/cool-down | + | 23 | `formatApiKey` | Власна форма runtime-токена | + | 24 | `refreshOAuth` | Власне оновлення OAuth | + | 25 | `buildAuthDoctorHint` | Підказка для виправлення автентифікації | + | 26 | `matchesContextOverflowError` | Виявлення overflow, що належить постачальнику | | 27 | `classifyFailoverReason` | Класифікація rate-limit/overload, що належить постачальнику | | 28 | `isCacheTtlEligible` | Керування TTL кешу prompt | - | 29 | `buildMissingAuthMessage` | Користувацька підказка про відсутню автентифікацію | - | 30 | `suppressBuiltInModel` | Приховати застарілі upstream rows | - | 31 | `augmentModelCatalog` | Синтетичні rows для forward-compat | - | 32 | `isBinaryThinking` | Бінарний thinking увімк./вимк. | + | 29 | `buildMissingAuthMessage` | Власна підказка про відсутню автентифікацію | + | 30 | `suppressBuiltInModel` | Приховати застарілі upstream-рядки | + | 31 | `augmentModelCatalog` | Синтетичні рядки для forward-compat | + | 32 | `isBinaryThinking` | Бінарний режим thinking увімк./вимк. | | 33 | `supportsXHighThinking` | Підтримка reasoning `xhigh` | | 34 | `resolveDefaultThinkingLevel` | Політика `/think` за замовчуванням | - | 35 | `isModernModelRef` | Відповідність live/smoke моделей | - | 36 | `prepareRuntimeAuth` | Обмін токенами перед inference | - | 37 | `resolveUsageAuth` | Користувацький розбір облікових даних usage | - | 38 | `fetchUsageSnapshot` | Користувацький endpoint usage | - | 39 | `createEmbeddingProvider` | Адаптер embedding, що належить постачальнику, для memory/search | - | 40 | `buildReplayPolicy` | Користувацька політика replay/compaction транскрипту | - | 41 | `sanitizeReplayHistory` | Специфічні для постачальника переписування replay після загального очищення | - | 42 | `validateReplayTurns` | Сувора валідація replay-turn перед вбудованим runner | - | 43 | `onModelSelected` | Колбек після вибору моделі (наприклад, telemetry) | + | 35 | `isModernModelRef` | Відповідність моделей live/smoke | + | 36 | `prepareRuntimeAuth` | Обмін токенів перед інференсом | + | 37 | `resolveUsageAuth` | Власний розбір облікових даних usage | + | 38 | `fetchUsageSnapshot` | Власна endpoint usage | + | 39 | `createEmbeddingProvider` | Адаптер embedding, що належить постачальнику, для пам’яті/пошуку | + | 40 | `buildReplayPolicy` | Власна політика replay/compaction для transcript | + | 41 | `sanitizeReplayHistory` | Переписування replay, специфічні для постачальника, після загального очищення | + | 42 | `validateReplayTurns` | Строга валідація replay-turn перед вбудованим runner | + | 43 | `onModelSelected` | Зворотний виклик після вибору моделі (наприклад, telemetry) | Примітка щодо налаштування prompt: - - `resolveSystemPromptContribution` дозволяє постачальнику додавати cache-aware - інструкції до system prompt для сімейства моделей. Віддавайте йому перевагу перед - `before_prompt_build`, якщо поведінка належить одному сімейству постачальника/моделей + - `resolveSystemPromptContribution` дає постачальнику змогу додавати + cache-aware інструкції system-prompt для сімейства моделей. Віддавайте йому перевагу замість + `before_prompt_build`, коли поведінка належить одному сімейству постачальника/моделі і має зберігати стабільний/динамічний поділ кешу. - Докладні описи та реальні приклади дивіться в - [Internals: Provider Runtime Hooks](/uk/plugins/architecture#provider-runtime-hooks). + Докладні описи та приклади з реального світу дивіться в + [Внутрішня будова: хуки runtime постачальника](/uk/plugins/architecture#provider-runtime-hooks). - Плагін постачальника може реєструвати speech, realtime transcription, realtime - voice, media understanding, image generation, video generation, web fetch - і web search поряд із текстовим inference: + Плагін постачальника може реєструвати мовлення, транскрипцію в realtime, realtime-голос, + розуміння медіа, генерацію зображень, генерацію відео, веб-отримання, + і вебпошук разом із текстовим інференсом: ```typescript register(api) { @@ -648,19 +656,19 @@ x-i18n: ``` OpenClaw класифікує це як плагін **hybrid-capability**. Це - рекомендований шаблон для корпоративних плагінів (один плагін на вендора). Див. - [Internals: Capability Ownership](/uk/plugins/architecture#capability-ownership-model). + рекомендований шаблон для корпоративних плагінів (один плагін на одного постачальника). + Див. [Внутрішня будова: володіння можливостями](/uk/plugins/architecture#capability-ownership-model). - Для генерації відео віддавайте перевагу наведеній вище структурі можливостей з урахуванням режимів: - `generate`, `imageToVideo` і `videoToVideo`. Пласкі агреговані поля, такі - як `maxInputImages`, `maxInputVideos` і `maxDurationSeconds`, недостатні, - щоб коректно оголошувати підтримку режимів трансформації або вимкнені режими. + Для генерації відео віддавайте перевагу наведеній вище структурі можливостей із урахуванням режимів: + `generate`, `imageToVideo` і `videoToVideo`. Плоских агрегованих полів, таких + як `maxInputImages`, `maxInputVideos` і `maxDurationSeconds`, недостатньо, + щоб коректно оголосити підтримку режимів трансформації або вимкнених режимів. Постачальники генерації музики мають дотримуватися того самого шаблону: `generate` для генерації лише за prompt і `edit` для генерації - на основі референсного зображення. Пласкі агреговані поля, такі як `maxInputImages`, - `supportsLyrics` і `supportsFormat`, недостатні, щоб оголосити підтримку edit; - очікуваним контрактом є явні блоки `generate` / `edit`. + на основі зображення-посилання. Плоских агрегованих полів, таких як `maxInputImages`, + `supportsLyrics` і `supportsFormat`, недостатньо, щоб оголосити підтримку + редагування; очікуваним контрактом є явні блоки `generate` / `edit`. @@ -708,36 +716,36 @@ clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -Не використовуйте тут застарілий alias публікації лише для Skills; пакети плагінів мають використовувати +Не використовуйте тут застарілий псевдонім публікації лише для Skills; пакети плагінів мають використовувати `clawhub package publish`. ## Структура файлів ``` /acme-ai/ -├── package.json # openclaw.providers metadata -├── openclaw.plugin.json # Manifest with provider auth metadata +├── package.json # Метадані openclaw.providers +├── openclaw.plugin.json # Маніфест із метаданими автентифікації постачальника ├── index.ts # definePluginEntry + registerProvider └── src/ - ├── provider.test.ts # Tests - └── usage.ts # Usage endpoint (optional) + ├── provider.test.ts # Тести + └── usage.ts # Endpoint usage (необов’язково) ``` -## Довідка щодо порядку catalog +## Довідка щодо порядку каталогу -`catalog.order` керує тим, коли ваш каталог об’єднується відносно вбудованих +`catalog.order` визначає, коли ваш каталог зливається відносно вбудованих постачальників: -| Order | Коли | Випадок використання | -| --------- | ------------- | --------------------------------------------- | -| `simple` | Перший прохід | Звичайні постачальники з API key | -| `profile` | Після simple | Постачальники, прив’язані до профілів auth | -| `paired` | Після profile | Синтез кількох пов’язаних записів | -| `late` | Останній прохід | Перевизначення наявних постачальників (перемагає при конфлікті) | +| Порядок | Коли | Випадок використання | +| --------- | ------------- | ----------------------------------------------- | +| `simple` | Перший прохід | Звичайні постачальники з API-ключем | +| `profile` | Після simple | Постачальники, що залежать від профілів автентифікації | +| `paired` | Після profile | Синтез кількох пов’язаних записів | +| `late` | Останній прохід | Перевизначення наявних постачальників (виграє при конфлікті) | ## Наступні кроки -- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — якщо ваш плагін також надає канал -- [SDK Runtime](/uk/plugins/sdk-runtime) — helper-функції `api.runtime` (TTS, search, subagent) -- [SDK Overview](/uk/plugins/sdk-overview) — повний довідник з імпорту subpath -- [Plugin Internals](/uk/plugins/architecture#provider-runtime-hooks) — деталі hooks і приклади вбудованих реалізацій +- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — якщо ваш плагін також надає канал +- [SDK Runtime](/uk/plugins/sdk-runtime) — помічники `api.runtime` (TTS, пошук, subagent) +- [Огляд SDK](/uk/plugins/sdk-overview) — повна довідка щодо імпорту subpath +- [Внутрішня будова плагінів](/uk/plugins/architecture#provider-runtime-hooks) — деталі хуків і приклади вбудованих плагінів diff --git a/docs/uk/plugins/sdk-runtime.md b/docs/uk/plugins/sdk-runtime.md index fa04c73fa..027b1346b 100644 --- a/docs/uk/plugins/sdk-runtime.md +++ b/docs/uk/plugins/sdk-runtime.md @@ -1,29 +1,29 @@ --- read_when: - - Вам потрібно викликати основні допоміжні засоби з плагіна (TTS, STT, генерація зображень, вебпошук, субагент) - - Ви хочете зрозуміти, що надає `api.runtime` - - Ви звертаєтеся до допоміжних засобів конфігурації, агента або медіа з коду плагіна + - Вам потрібно викликати допоміжні засоби ядра з плагіна (TTS, STT, генерація зображень, вебпошук, субагент) + - Ви хочете зрозуміти, що надає api.runtime + - Ви отримуєте доступ до допоміжних засобів конфігурації, агента або медіа з коду плагіна sidebarTitle: Runtime Helpers -summary: api.runtime -- вбудовані допоміжні засоби середовища виконання, доступні плагінам +summary: api.runtime -- впроваджені допоміжні засоби середовища виконання, доступні для плагінів title: Допоміжні засоби середовища виконання плагіна x-i18n: - generated_at: "2026-04-07T06:53:09Z" + generated_at: "2026-04-10T20:23:46Z" model: gpt-5.4 provider: openai - source_hash: acb9e56678e9ed08d0998dfafd7cd1982b592be5bc34d9e2d2c1f70274f8f248 + source_hash: fbf8a6ecd970300f784b8aca20eed40ba12c83107abd27385bfdc3347d2544be source_path: plugins/sdk-runtime.md workflow: 15 --- # Допоміжні засоби середовища виконання плагіна -Довідник щодо об’єкта `api.runtime`, який вбудовується в кожен плагін під час +Довідка щодо об’єкта `api.runtime`, який впроваджується в кожен плагін під час реєстрації. Використовуйте ці допоміжні засоби замість прямого імпорту внутрішніх компонентів хоста. - **Потрібен покроковий посібник?** Дивіться [Channel Plugins](/uk/plugins/sdk-channel-plugins) - або [Provider Plugins](/uk/plugins/sdk-provider-plugins) для покрокових інструкцій, + **Шукаєте покрокове пояснення?** Перегляньте [Плагіни каналів](/uk/plugins/sdk-channel-plugins) + або [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins), щоб знайти покрокові посібники, які показують ці допоміжні засоби в контексті. @@ -58,9 +58,9 @@ const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg); // Ensure workspace exists await api.runtime.agent.ensureAgentWorkspace(cfg); -// Run an embedded Pi agent +// Run an embedded agent turn const agentDir = api.runtime.agent.resolveAgentDir(cfg); -const result = await api.runtime.agent.runEmbeddedPiAgent({ +const result = await api.runtime.agent.runEmbeddedAgent({ sessionId: "my-plugin:task-1", runId: crypto.randomUUID(), sessionFile: path.join(agentDir, "sessions", "my-plugin-task-1.jsonl"), @@ -70,7 +70,14 @@ const result = await api.runtime.agent.runEmbeddedPiAgent({ }); ``` -**Допоміжні засоби сховища сесій** містяться в `api.runtime.agent.session`: +`runEmbeddedAgent(...)` — це нейтральний допоміжний засіб для запуску звичайного +ходу агента OpenClaw з коду плагіна. Він використовує той самий механізм +визначення провайдера/моделі та вибору harness агента, що й відповіді, +запущені каналом. + +`runEmbeddedPiAgent(...)` залишається псевдонімом для сумісності. + +**Допоміжні засоби сховища сесій** розміщені в `api.runtime.agent.session`: ```typescript const storePath = api.runtime.agent.session.resolveStorePath(cfg); @@ -81,7 +88,7 @@ const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId ### `api.runtime.agent.defaults` -Константи моделі та провайдера за замовчуванням: +Константи стандартної моделі та провайдера: ```typescript const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6" @@ -90,7 +97,7 @@ const provider = api.runtime.agent.defaults.provider; // e.g. "anthropic" ### `api.runtime.subagent` -Запуск і керування фоновими запусками субагентів. +Запуск і керування фоновими запусками субагента. ```typescript // Start a subagent run @@ -121,14 +128,14 @@ await api.runtime.subagent.deleteSession({ Перевизначення моделі (`provider`/`model`) потребує явної згоди оператора через `plugins.entries..subagent.allowModelOverride: true` у конфігурації. Ненадійні плагіни все одно можуть запускати субагентів, але запити на - перевизначення відхиляються. + перевизначення буде відхилено. ### `api.runtime.taskFlow` -Прив’яжіть середовище виконання Task Flow до наявного ключа сесії OpenClaw або -контексту довіреного інструмента, а потім створюйте й керуйте Task Flow без -передавання власника в кожному виклику. +Прив’язує середовище виконання Task Flow до наявного ключа сесії OpenClaw або +контексту довіреного інструмента, а потім дає змогу створювати й керувати Task Flow +без передавання власника в кожному виклику. ```typescript const taskFlow = api.runtime.taskFlow.fromToolContext(ctx); @@ -155,7 +162,7 @@ const waiting = taskFlow.setWaiting({ }); ``` -Використовуйте `bindSession({ sessionKey, requesterOrigin })`, якщо у вас уже є +Використовуйте `bindSession({ sessionKey, requesterOrigin })`, коли у вас уже є довірений ключ сесії OpenClaw із вашого власного шару прив’язки. Не виконуйте прив’язку на основі необробленого користувацького вводу. @@ -183,8 +190,8 @@ const voices = await api.runtime.tts.listVoices({ }); ``` -Використовує основну конфігурацію `messages.tts` і вибір провайдера. Повертає -PCM-аудіобуфер + частоту дискретизації. +Використовує основну конфігурацію `messages.tts` і механізм вибору провайдера. +Повертає буфер аудіо PCM + частоту дискретизації. ### `api.runtime.mediaUnderstanding` @@ -218,11 +225,11 @@ const result = await api.runtime.mediaUnderstanding.runFile({ }); ``` -Повертає `{ text: undefined }`, якщо жодного виводу не створено (наприклад, -вхідні дані пропущено). +Повертає `{ text: undefined }`, якщо вихідні дані не було створено +(наприклад, якщо вхідні дані було пропущено). - `api.runtime.stt.transcribeAudioFile(...)` залишається сумісним псевдонімом + `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом для сумісності для `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`. @@ -254,7 +261,7 @@ const result = await api.runtime.webSearch.search({ ### `api.runtime.media` -Низькорівневі медіаутиліти. +Низькорівневі мультимедійні утиліти. ```typescript const webMedia = await api.runtime.media.loadWebMedia(url); @@ -276,7 +283,7 @@ await api.runtime.config.writeConfigFile(cfg); ### `api.runtime.system` -Системні утиліти. +Утиліти системного рівня. ```typescript await api.runtime.system.enqueueSystemEvent(event); @@ -300,7 +307,7 @@ api.runtime.events.onSessionTranscriptUpdate((update) => { ### `api.runtime.logging` -Логування. +Журналювання. ```typescript const verbose = api.runtime.logging.shouldLogVerbose(); @@ -339,12 +346,11 @@ api.runtime.tools.registerMemoryCli(/* ... */); ### `api.runtime.channel` -Допоміжні засоби середовища виконання для каналу (доступні, коли завантажено -плагін каналу). +Допоміжні засоби середовища виконання, специфічні для каналу (доступні, коли +завантажено плагін каналу). -`api.runtime.channel.mentions` — це спільна поверхня політики згадок у вхідних -повідомленнях для вбудованих плагінів каналів, які використовують вбудоване -середовище виконання: +`api.runtime.channel.mentions` — це спільна поверхня політики вхідних згадок для +вбудованих плагінів каналів, які використовують впровадження середовища виконання: ```typescript const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, { @@ -379,7 +385,7 @@ const decision = api.runtime.channel.mentions.resolveInboundMentionDecision({ - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -`api.runtime.channel.mentions` навмисно не надає старі сумісні допоміжні засоби +`api.runtime.channel.mentions` навмисно не надає старі допоміжні засоби сумісності `resolveMentionGating*`. Надавайте перевагу нормалізованому шляху `{ facts, policy }`. @@ -421,14 +427,14 @@ export function tryGetRuntime() { | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | | `api.id` | `string` | Ідентифікатор плагіна | | `api.name` | `string` | Відображувана назва плагіна | -| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок середовища виконання в пам’яті, якщо доступний) | -| `api.pluginConfig` | `Record` | Конфігурація плагіна з `plugins.entries..config` | -| `api.logger` | `PluginLogger` | Логер з областю видимості (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування перед повним входом | -| `api.resolvePath(input)` | `(string) => string` | Визначити шлях відносно кореня плагіна | +| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок середовища виконання в пам’яті, коли доступний) | +| `api.pluginConfig` | `Record` | Конфігурація, специфічна для плагіна, з `plugins.entries..config` | +| `api.logger` | `PluginLogger` | Logger з областю видимості (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування перед повним запуском entry point | +| `api.resolvePath(input)` | `(string) => string` | Визначає шлях відносно кореня плагіна | ## Пов’язане -- [SDK Overview](/uk/plugins/sdk-overview) -- довідник щодо підшляхів -- [SDK Entry Points](/uk/plugins/sdk-entrypoints) -- параметри `definePluginEntry` -- [Plugin Internals](/uk/plugins/architecture) -- модель можливостей і реєстр +- [Огляд SDK](/uk/plugins/sdk-overview) -- довідка щодо підшляхів +- [Точки входу SDK](/uk/plugins/sdk-entrypoints) -- параметри `definePluginEntry` +- [Внутрішня структура плагіна](/uk/plugins/architecture) -- модель можливостей і реєстр