chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
c0c7ed2f19
commit
d1b5802b86
@ -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 <provider/model>`.
|
||||
- Резервні правила під час виконання, 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.<id>` перед тим,
|
||||
як runtime її використає; OpenClaw спершу перевіряє відповідного постачальника, потім інші
|
||||
- `normalizeConfig`: постачальник нормалізує конфігурацію `models.providers.<id>` перед
|
||||
використанням у середовищі виконання; 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:
|
||||
- `<PROVIDER>_API_KEYS` (список через кому або крапку з комою)
|
||||
- `<PROVIDER>_API_KEY` (основний ключ)
|
||||
- `<PROVIDER>_API_KEY_*` (нумерований список, наприклад `<PROVIDER>_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/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- Warm-up OpenAI Responses WebSocket за замовчуванням увімкнено через `params.openaiWsWarmup` (`true`/`false`)
|
||||
- Типовий транспорт — `auto` (спочатку WebSocket, запасний варіант SSE)
|
||||
- Перевизначення для окремої моделі через `agents.defaults.models["openai/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- Warm-up OpenAI Responses WebSocket типово ввімкнений через `params.openaiWsWarmup` (`true`/`false`)
|
||||
- Пріоритетну обробку OpenAI можна ввімкнути через `agents.defaults.models["openai/<model>"].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/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- Типовий транспорт — `auto` (спочатку WebSocket, запасний варіант SSE)
|
||||
- Перевизначення для окремої моделі через `agents.defaults.models["openai-codex/<model>"].params.transport` (`"sse"`, `"websocket"` або `"auto"`)
|
||||
- `params.serviceTier` також пересилається в нативних запитах Codex Responses (`chatgpt.com/backend-api`)
|
||||
- Приховані заголовки атрибуції OpenClaw (`originator`, `version`,
|
||||
`User-Agent`) додаються лише до нативного трафіку Codex на
|
||||
`chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних проксі
|
||||
- Використовує той самий перемикач `/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/<model>"].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/<model>"].params.tool_stream` як `false`, щоб
|
||||
вимкнути його
|
||||
- `tool_stream` типово ввімкнено; установіть
|
||||
`agents.defaults.models["xai/<model>"].params.tool_stream` у `false`, щоб
|
||||
його вимкнути
|
||||
- Mistral: `mistral` (`MISTRAL_API_KEY`)
|
||||
- Приклад моделі: `mistral/mistral-large-latest`
|
||||
- CLI: `openclaw onboard --auth-choice mistral-api-key`
|
||||
- Groq: `groq` (`GROQ_API_KEY`)
|
||||
- Cerebras: `cerebras` (`CEREBRAS_API_KEY`)
|
||||
- Моделі GLM на Cerebras використовують ідентифікатори `zai-glm-4.7` і `zai-glm-4.6`.
|
||||
- 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.<id>` лише тоді, коли хочете перевизначити
|
||||
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) — посібники з налаштування для окремих постачальників
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
192
docs/uk/plugins/sdk-agent-harness.md
Normal file
192
docs/uk/plugins/sdk-agent-harness.md
Normal file
@ -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>` примусово вибирає зареєстрований каркас із цим 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)
|
||||
@ -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. Ця сторінка є
|
||||
довідником для **того, що імпортувати** і **що можна реєструвати**.
|
||||
|
||||
<Tip>
|
||||
**Шукаєте покроковий посібник?**
|
||||
**Шукаєте практичний посібник?**
|
||||
- Перший плагін? Почніть із [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)
|
||||
</Tip>
|
||||
|
||||
## Правило імпорту
|
||||
## Угода щодо імпорту
|
||||
|
||||
Завжди імпортуйте з конкретного підшляху:
|
||||
|
||||
@ -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` |
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Підшляхи каналів">
|
||||
@ -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`, і типи цілей секретів |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи провайдерів">
|
||||
@ -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 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи автентифікації та безпеки">
|
||||
<Accordion title="Підшляхи auth і безпеки">
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `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 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи runtime і сховища">
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `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` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи можливостей і тестування">
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `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` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підшляхи пам’яті">
|
||||
| Підшлях | Ключові експорти |
|
||||
| --- | --- |
|
||||
| `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 |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Зарезервовані підшляхи допоміжних засобів вбудованих плагінів">
|
||||
| Сімейство | Поточні підшляхи | Призначення |
|
||||
<Accordion title="Зарезервовані підшляхи допоміжних засобів для вбудованих плагінів">
|
||||
| Сімейство | Поточні підшляхи | Призначене використання |
|
||||
| --- | --- | --- |
|
||||
| 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` |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 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.<id>`.
|
||||
- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.<id>` поверх
|
||||
типового значення плагіна перед запуском CLI.
|
||||
- Використовуйте `normalizeConfig`, коли бекенду потрібні переписування сумісності після злиття
|
||||
(наприклад, для нормалізації старих форм прапорців).
|
||||
- `id` бекенда стає префіксом провайдера в model ref, наприклад `codex-cli/gpt-5`.
|
||||
- `config` бекенда використовує ту саму форму, що й `agents.defaults.cliBackends.<id>`.
|
||||
- Конфігурація користувача все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.<id>` поверх
|
||||
значення плагіна за замовчуванням перед запуском 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<string, unknown>` | Конфігурація, специфічна для плагіна, з `plugins.entries.<id>.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<string, unknown>` | Конфігурація, специфічна для плагіна, з `plugins.entries.<id>.config` |
|
||||
| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) |
|
||||
| `api.logger` | `PluginLogger` | Logger з обмеженою областю (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування до повного entry |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Визначити шлях відносно кореня плагіна |
|
||||
|
||||
## Внутрішнє правило модулів
|
||||
## Угода щодо внутрішніх модулів
|
||||
|
||||
Усередині вашого плагіна використовуйте локальні barrel-файли для внутрішніх імпортів:
|
||||
|
||||
@ -471,49 +470,45 @@ my-plugin/
|
||||
api.ts # Публічні експорти для зовнішніх споживачів
|
||||
runtime-api.ts # Експорти runtime лише для внутрішнього використання
|
||||
index.ts # Точка входу плагіна
|
||||
setup-entry.ts # Полегшений вхід лише для налаштування (необов’язково)
|
||||
setup-entry.ts # Полегшений entry лише для налаштування (необов’язково)
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/<your-plugin>`
|
||||
у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або
|
||||
з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або
|
||||
`./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт.
|
||||
</Warning>
|
||||
|
||||
Публічні поверхні вбудованих плагінів, що завантажуються через 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` експортує побудовник провайдера, а також
|
||||
допоміжні засоби онбордингу/конфігурації
|
||||
|
||||
<Warning>
|
||||
Production-код розширень також має уникати імпортів
|
||||
`openclaw/plugin-sdk/<other-plugin>`. Якщо допоміжний засіб справді є спільним,
|
||||
перенесіть його до нейтрального підшляху SDK, такого як
|
||||
`openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої
|
||||
поверхні, орієнтованої на можливості, замість зв’язування двох плагінів між собою.
|
||||
Production-код розширень також має уникати імпортів `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Якщо допоміжний засіб справді є спільним, винесіть його в нейтральний підшлях SDK,
|
||||
такий як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншу
|
||||
поверхню, орієнтовану на можливість, замість жорсткого зв’язування двох плагінів.
|
||||
</Warning>
|
||||
|
||||
## Пов’язане
|
||||
## Пов’язані матеріали
|
||||
|
||||
- [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) — детальна архітектура і модель можливостей
|
||||
|
||||
@ -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-ключ і динамічним визначенням моделей.
|
||||
|
||||
<Info>
|
||||
Якщо ви раніше не створювали жодного плагіна OpenClaw, спочатку прочитайте
|
||||
[Getting Started](/uk/plugins/building-plugins), щоб ознайомитися з базовою
|
||||
Якщо ви ще не створювали жодного плагіна OpenClaw, спочатку прочитайте
|
||||
[Початок роботи](/uk/plugins/building-plugins), щоб ознайомитися з базовою
|
||||
структурою пакета та налаштуванням маніфесту.
|
||||
</Info>
|
||||
|
||||
<Tip>
|
||||
Плагіни постачальників додають моделі до стандартного циклу інференсу OpenClaw. Якщо модель
|
||||
має працювати через нативний демон агента, який керує потоками, компакцією або подіями
|
||||
інструментів, поєднайте постачальника з [agent harness](/uk/plugins/sdk-agent-harness)
|
||||
замість того, щоб виносити деталі протоколу демона в core.
|
||||
</Tip>
|
||||
|
||||
## Покроковий приклад
|
||||
|
||||
<Steps>
|
||||
@ -90,12 +97,12 @@ x-i18n:
|
||||
</CodeGroup>
|
||||
|
||||
Маніфест оголошує `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` є обов’язковими.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -175,9 +182,9 @@ x-i18n:
|
||||
`openclaw onboard --acme-ai-api-key <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 теж можуть увімкнути цю можливість,
|
||||
навіть якщо плагін використовує власний ідентифікатор постачальника.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте динамічне визначення моделей">
|
||||
Якщо ваш постачальник приймає довільні ідентифікатори моделей (як проксі чи маршрутизатор),
|
||||
Якщо ваш постачальник приймає довільні ідентифікатори моделей (як проксі або маршрутизатор),
|
||||
додайте `resolveDynamicModel`:
|
||||
|
||||
```typescript
|
||||
@ -252,16 +260,16 @@ x-i18n:
|
||||
```
|
||||
|
||||
Якщо для визначення потрібен мережевий виклик, використовуйте `prepareDynamicModel` для асинхронного
|
||||
прогріву — після завершення `resolveDynamicModel` буде запущено знову.
|
||||
прогріву — після його завершення `resolveDynamicModel` виконається знову.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте runtime hooks (за потреби)">
|
||||
Більшості постачальників потрібні лише `catalog` + `resolveDynamicModel`. Додавайте hooks
|
||||
поступово, коли вони стають потрібними вашому постачальнику.
|
||||
<Step title="Додайте хуки середовища виконання (за потреби)">
|
||||
Більшості постачальників потрібні лише `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` експортує генератор постачальника
|
||||
разом із помічниками онбордингу/конфігурації
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Обмін токенами">
|
||||
Для постачальників, яким потрібен обмін токенами перед кожним викликом inference:
|
||||
<Tab title="Обмін токенів">
|
||||
Для постачальників, яким потрібен обмін токенів перед кожним викликом інференсу:
|
||||
|
||||
```typescript
|
||||
prepareRuntimeAuth: async (ctx) => {
|
||||
@ -407,8 +416,8 @@ x-i18n:
|
||||
},
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Користувацькі заголовки">
|
||||
Для постачальників, яким потрібні користувацькі заголовки запиту або зміни тіла запиту:
|
||||
<Tab title="Власні заголовки">
|
||||
Для постачальників, яким потрібні власні заголовки запитів або зміни тіла запиту:
|
||||
|
||||
```typescript
|
||||
// wrapStreamFn returns a StreamFn derived from ctx.streamFn
|
||||
@ -425,9 +434,9 @@ x-i18n:
|
||||
},
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Власна ідентичність транспорту">
|
||||
Для постачальників, яким потрібні власні заголовки запиту/сесії або метадані на
|
||||
універсальних HTTP- чи WebSocket-транспортах:
|
||||
<Tab title="Ідентичність нативного транспорту">
|
||||
Для постачальників, яким потрібні нативні заголовки запиту/сесії або метадані в
|
||||
узагальнених HTTP або WebSocket транспортах:
|
||||
|
||||
```typescript
|
||||
resolveTransportTurnState: (ctx) => ({
|
||||
@ -462,84 +471,83 @@ x-i18n:
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
<Accordion title="Усі доступні hooks постачальника">
|
||||
OpenClaw викликає hooks у такому порядку. Більшість постачальників використовують лише 2-3:
|
||||
<Accordion title="Усі доступні хуки постачальника">
|
||||
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.<id>` |
|
||||
| 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.<id>` |
|
||||
| 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).
|
||||
</Accordion>
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте додаткові можливості (необов’язково)">
|
||||
<a id="step-5-add-extra-capabilities"></a>
|
||||
Плагін постачальника може реєструвати 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`.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -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`.
|
||||
|
||||
## Структура файлів
|
||||
|
||||
```
|
||||
<bundled-plugin-root>/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) — деталі хуків і приклади вбудованих плагінів
|
||||
|
||||
@ -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`, який впроваджується в кожен плагін під час
|
||||
реєстрації. Використовуйте ці допоміжні засоби замість прямого імпорту внутрішніх
|
||||
компонентів хоста.
|
||||
|
||||
<Tip>
|
||||
**Потрібен покроковий посібник?** Дивіться [Channel Plugins](/uk/plugins/sdk-channel-plugins)
|
||||
або [Provider Plugins](/uk/plugins/sdk-provider-plugins) для покрокових інструкцій,
|
||||
**Шукаєте покрокове пояснення?** Перегляньте [Плагіни каналів](/uk/plugins/sdk-channel-plugins)
|
||||
або [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins), щоб знайти покрокові посібники,
|
||||
які показують ці допоміжні засоби в контексті.
|
||||
</Tip>
|
||||
|
||||
@ -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.<id>.subagent.allowModelOverride: true` у конфігурації.
|
||||
Ненадійні плагіни все одно можуть запускати субагентів, але запити на
|
||||
перевизначення відхиляються.
|
||||
перевизначення буде відхилено.
|
||||
</Warning>
|
||||
|
||||
### `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 }`, якщо вихідні дані не було створено
|
||||
(наприклад, якщо вхідні дані було пропущено).
|
||||
|
||||
<Info>
|
||||
`api.runtime.stt.transcribeAudioFile(...)` залишається сумісним псевдонімом
|
||||
`api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом для сумісності
|
||||
для `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`.
|
||||
</Info>
|
||||
|
||||
@ -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<string, unknown>` | Конфігурація плагіна з `plugins.entries.<id>.config` |
|
||||
| `api.logger` | `PluginLogger` | Логер з областю видимості (`debug`, `info`, `warn`, `error`) |
|
||||
| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування перед повним входом |
|
||||
| `api.resolvePath(input)` | `(string) => string` | Визначити шлях відносно кореня плагіна |
|
||||
| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок середовища виконання в пам’яті, коли доступний) |
|
||||
| `api.pluginConfig` | `Record<string, unknown>` | Конфігурація, специфічна для плагіна, з `plugins.entries.<id>.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) -- модель можливостей і реєстр
|
||||
|
||||
Loading…
Reference in New Issue
Block a user