Створення плагінів постачальників
Цей посібник покроково пояснює створення плагіна постачальника, який додає постачальника моделей (LLM) до OpenClaw. Наприкінці у вас буде постачальник із каталогом моделей, автентифікацією за API-ключем і динамічним визначенням моделі.Якщо ви раніше не створювали жодного плагіна OpenClaw, спочатку прочитайте
Початок роботи, щоб ознайомитися з базовою
структурою пакета та налаштуванням маніфесту.
Покроковий приклад
Пакет і маніфест
providerAuthEnvVars, щоб OpenClaw міг виявляти
облікові дані без завантаження runtime вашого плагіна. Додавайте providerAuthAliases,
коли варіант постачальника має повторно використовувати автентифікацію іншого id постачальника. modelSupport
є необов’язковим і дозволяє OpenClaw автоматично завантажувати ваш плагін постачальника зі скорочених
id моделей, таких як acme-large, ще до появи runtime-хуків. Якщо ви публікуєте
постачальника на ClawHub, поля openclaw.compat і openclaw.build
є обов’язковими в package.json.Зареєструйте постачальника
Мінімальному постачальнику потрібні Це вже робочий постачальник. Тепер користувачі можуть виконати
Якщо вашому потоку автентифікації також потрібно змінювати
id, label, auth і catalog:index.ts
openclaw onboard --acme-ai-api-key <key> і вибрати
acme-ai/acme-large як свою модель.Якщо постачальник вище за потоком використовує інші керівні токени, ніж OpenClaw, додайте
невелике двостороннє текстове перетворення замість заміни шляху потоку:input переписує фінальний системний промпт і текстовий вміст повідомлення перед
транспортуванням. output переписує текстові дельти відповіді асистента та фінальний текст до того, як
OpenClaw розбере власні керівні маркери або виконає доставку каналом.Для вбудованих постачальників, які реєструють лише одного текстового постачальника з
автентифікацією за API-ключем і одним runtime, що працює через каталог, краще використовувати вужчий
помічник defineSingleProviderPluginEntry(...):models.providers.*, псевдоніми та
стандартну модель агента під час онбордингу, використовуйте preset-хелпери з
openclaw/plugin-sdk/provider-onboard. Найвужчі хелпери:
createDefaultModelPresetAppliers(...),
createDefaultModelsPresetAppliers(...) і
createModelCatalogPresetAppliers(...).Коли нативний endpoint постачальника підтримує потокові блоки використання в межах
звичайного транспорту openai-completions, віддавайте перевагу спільним хелперам каталогу з
openclaw/plugin-sdk/provider-catalog-shared замість жорстко закодованих перевірок id постачальника.
supportsNativeStreamingUsageCompat(...) і
applyProviderNativeStreamingUsageCompat(...) визначають підтримку за мапою можливостей endpoint, тому
нативні endpoint-и у стилі Moonshot/DashScope також зможуть увімкнути цю функцію, навіть якщо плагін
використовує власний id постачальника.Додайте динамічне визначення моделі
Якщо ваш постачальник приймає довільні id моделей (наприклад, проксі або маршрутизатор),
додайте Якщо для визначення потрібен мережевий виклик, використовуйте
resolveDynamicModel:prepareDynamicModel для асинхронного
прогріву — після його завершення resolveDynamicModel запускається знову.Додайте runtime-хуки (за потреби)
Більшості постачальників потрібні лише Доступні сьогодні сімейства повторного відтворення:
Реальні вбудовані приклади:
Реальні вбудовані приклади:
catalog + resolveDynamicModel. Додавайте хуки
поступово, у міру того як цього вимагатиме ваш постачальник.Спільні builder-хелпери тепер покривають найпоширеніші сімейства повторного відтворення та
сумісності інструментів, тому плагінам зазвичай не потрібно вручну підключати кожен хук окремо:| Сімейство | Що воно підключає |
|---|---|
openai-compatible | Спільну політику повторного відтворення у стилі OpenAI для OpenAI-сумісних транспортів, зокрема санітизацію id викликів інструментів, виправлення порядку “assistant-first” і загальну валідацію ходів Gemini там, де цього потребує транспорт |
anthropic-by-model | Політику повторного відтворення з урахуванням Claude, яка вибирається за modelId, щоб транспорти повідомлень Anthropic отримували специфічне очищення thinking-блоків Claude лише тоді, коли визначена модель справді має id Claude |
google-gemini | Нативну політику повторного відтворення Gemini, а також санітизацію bootstrap replay і режим тегованого виводу міркувань |
passthrough-gemini | Санітизацію сигнатури думок Gemini для моделей Gemini, що працюють через OpenAI-сумісні проксі-транспорти; не вмикає нативну валідацію повторного відтворення Gemini або переписування bootstrap |
hybrid-anthropic-openai | Гібридну політику для постачальників, які поєднують поверхні моделей Anthropic-message та OpenAI-compatible в одному плагіні; необов’язкове відкидання thinking-блоків лише для Claude залишається обмеженим стороною Anthropic |
googleіgoogle-gemini-cli:google-geminiopenrouter,kilocode,opencodeіopencode-go:passthrough-geminiamazon-bedrockіanthropic-vertex:anthropic-by-modelminimax:hybrid-anthropic-openaimoonshot,ollama,xaiіzai:openai-compatible
| Сімейство | Що воно підключає |
|---|---|
google-thinking | Нормалізацію thinking payload Gemini на спільному шляху потоку |
kilocode-thinking | Обгортку міркувань Kilo на спільному шляху проксі-потоку, де kilo/auto і непідтримувані id міркувань проксі пропускають ін’єктований thinking |
moonshot-thinking | Мапінг binary native-thinking payload Moonshot із config + рівня /think |
minimax-fast-mode | Переписування моделі MiniMax fast-mode на спільному шляху потоку |
openai-responses-defaults | Спільні нативні обгортки OpenAI/Codex Responses: заголовки attribution, /fast/serviceTier, деталізація тексту, нативний вебпошук Codex, формування payload для сумісності з reasoning і керування контекстом Responses |
openrouter-thinking | Обгортку міркувань OpenRouter для проксі-маршрутів, із централізованою обробкою пропусків для непідтримуваних моделей/auto |
tool-stream-default-on | Стандартно ввімкнену обгортку tool_stream для постачальників на кшталт Z.AI, яким потрібен потоковий режим інструментів, якщо його явно не вимкнено |
googleіgoogle-gemini-cli:google-thinkingkilocode:kilocode-thinkingmoonshot:moonshot-thinkingminimaxіminimax-portal:minimax-fast-modeopenaiіopenai-codex:openai-responses-defaultsopenrouter:openrouter-thinkingzai:tool-stream-default-on
openclaw/plugin-sdk/provider-model-shared також експортує enum сімейств
повторного відтворення, а також спільні хелпери, з яких ці сімейства будуються. Поширені публічні
експорти включають:ProviderReplayFamilybuildProviderReplayFamilyHooks(...)- спільні builder-и повторного відтворення, такі як
buildOpenAICompatibleReplayPolicy(...),buildAnthropicReplayPolicyForModel(...),buildGoogleGeminiReplayPolicy(...)іbuildHybridAnthropicOrOpenAIReplayPolicy(...) - хелпери повторного відтворення Gemini, такі як
sanitizeGoogleGeminiReplayHistory(...)іresolveTaggedReasoningOutputMode() - хелпери endpoint-ів/моделей, такі як
resolveProviderEndpoint(...),normalizeProviderId(...),normalizeGooglePreviewModelId(...)іnormalizeNativeXaiModelId(...)
openclaw/plugin-sdk/provider-stream надає як builder сімейств, так і
публічні хелпери-обгортки, які ці сімейства повторно використовують. Поширені публічні експорти
включають:ProviderStreamFamilybuildProviderStreamFamilyHooks(...)composeProviderStreamWrappers(...)- спільні обгортки OpenAI/Codex, такі як
createOpenAIAttributionHeadersWrapper(...),createOpenAIFastModeWrapper(...),createOpenAIServiceTierWrapper(...),createOpenAIResponsesContextManagementWrapper(...)іcreateCodexNativeWebSearchWrapper(...) - спільні обгортки проксі/постачальників, такі як
createOpenRouterWrapper(...),createToolStreamWrapper(...)іcreateMinimaxFastModeWrapper(...)
@openclaw/anthropic-provider експортує
wrapAnthropicProviderStream, resolveAnthropicBetas,
resolveAnthropicFastMode, resolveAnthropicServiceTier і
низькорівневі builder-и обгорток Anthropic через свій публічний seam api.ts /
contract-api.ts. Ці хелпери залишаються специфічними для Anthropic, оскільки
також кодують обробку Claude OAuth beta і gating для context1m.Інші вбудовані постачальники також зберігають локальні обгортки, специфічні для транспорту, коли
цю поведінку не можна чисто повторно використати між сімействами. Поточний приклад: вбудований
плагін xAI зберігає нативне формування xAI Responses у власному
wrapStreamFn, включно з переписуванням псевдонімів /fast, стандартним tool_stream,
очищенням непідтримуваних strict-tool і видаленням payload міркувань,
специфічним для xAI.openclaw/plugin-sdk/provider-tools наразі надає одне спільне
сімейство схем інструментів, а також спільні хелпери схем/сумісності:ProviderToolCompatFamilyдокументує наявний сьогодні набір спільних сімейств.buildProviderToolCompatFamilyHooks("gemini")підключає очищення схем Gemini- діагностику для постачальників, яким потрібні безпечні для Gemini схеми інструментів.
normalizeGeminiToolSchemas(...)іinspectGeminiToolSchemas(...)— це базові публічні хелпери схем Gemini.resolveXaiModelCompatPatch()повертає вбудований patch сумісності xAI:toolSchemaProfile: "xai", непідтримувані ключові слова схеми, нативну підтримкуweb_searchі декодування аргументів виклику інструментів з HTML-сутностей.applyXaiModelCompat(model)застосовує той самий patch сумісності xAI до визначеної моделі перед тим, як вона потрапить до runner-а.
normalizeResolvedModel плюс
contributeResolvedModelCompat, щоб залишити ці метадані сумісності у власності
постачальника, замість жорсткого кодування правил xAI в core.Той самий шаблон на рівні кореня пакета також лежить в основі інших вбудованих постачальників:@openclaw/openai-provider:api.tsекспортує builder-и постачальника, хелпери стандартної моделі та builder-и постачальників realtime@openclaw/openrouter-provider:api.tsекспортує builder постачальника, а також хелпери онбордингу/config
- Обмін токенів
- Користувацькі заголовки
- Ідентичність нативного транспорту
- Використання та білінг
Для постачальників, яким потрібен обмін токенів перед кожним викликом інференсу:
Усі доступні хуки постачальника
Усі доступні хуки постачальника
OpenClaw викликає хуки в такому порядку. Більшість постачальників використовують лише 2–3:
Нотатки щодо runtime fallback:
| # | Хук | Коли використовувати |
|---|---|---|
| 1 | catalog | Каталог моделей або стандартні значення baseUrl |
| 2 | applyConfigDefaults | Глобальні стандартні значення, що належать постачальнику, під час materialization config |
| 3 | normalizeModelId | Очищення псевдонімів застарілих/preview id моделей перед пошуком |
| 4 | normalizeTransport | Очищення api / baseUrl сімейства постачальника перед загальним складанням моделі |
| 5 | normalizeConfig | Нормалізація config models.providers.<id> |
| 6 | applyNativeStreamingUsageCompat | Переписування сумісності нативного потокового usage для config-постачальників |
| 7 | resolveConfigApiKey | Визначення автентифікації env-marker, що належить постачальнику |
| 8 | resolveSyntheticAuth | Синтетична автентифікація для local/self-hosted або така, що спирається на config |
| 9 | shouldDeferSyntheticProfileAuth | Зниження пріоритету синтетичних placeholder-ів збереженого профілю порівняно з env/config auth |
| 10 | resolveDynamicModel | Прийом довільних id моделей upstream |
| 11 | prepareDynamicModel | Асинхронне отримання метаданих перед визначенням |
| 12 | normalizeResolvedModel | Переписування транспорту перед runner-ом |
-
normalizeConfigспочатку перевіряє відповідного постачальника, а потім інші плагіни постачальників із підтримкою хуків, доки один із них справді не змінить config. Якщо жоден хук постачальника не переписує підтримуваний запис config сімейства Google, усе одно застосовується вбудований нормалізатор config Google. -
resolveConfigApiKeyвикористовує хук постачальника, якщо він доступний. Вбудований шляхamazon-bedrockтакож має тут вбудований resolver AWS env-marker, хоча сама runtime-автентифікація Bedrock і далі використовує стандартний ланцюжок AWS SDK. | 13 |contributeResolvedModelCompat| Прапори сумісності для моделей постачальника за іншим сумісним транспортом | | 14 |capabilities| Застарілий статичний набір можливостей; лише для сумісності | | 15 |normalizeToolSchemas| Очищення схем інструментів, що належить постачальнику, перед реєстрацією | | 16 |inspectToolSchemas| Діагностика схем інструментів, що належить постачальнику | | 17 |resolveReasoningOutputMode| Контракт тегованого чи нативного виводу reasoning | | 18 |prepareExtraParams| Стандартні параметри запиту | | 19 |createStreamFn| Повністю користувацький транспорт StreamFn | | 20 |wrapStreamFn| Користувацькі обгортки заголовків/тіла на звичайному шляху потоку | | 21 |resolveTransportTurnState| Нативні заголовки/метадані для кожного ходу | | 22 |resolveWebSocketSessionPolicy| Нативні заголовки сесії WS / cooldown | | 23 |formatApiKey| Користувацька форма runtime-токена | | 24 |refreshOAuth| Користувацьке оновлення OAuth | | 25 |buildAuthDoctorHint| Рекомендації щодо виправлення автентифікації | | 26 |matchesContextOverflowError| Виявлення переповнення, що належить постачальнику | | 27 |classifyFailoverReason| Класифікація rate-limit/overload, що належить постачальнику | | 28 |isCacheTtlEligible| Керування TTL кешу промптів | | 29 |buildMissingAuthMessage| Користувацька підказка про відсутню автентифікацію | | 30 |suppressBuiltInModel| Приховування застарілих рядків upstream | | 31 |augmentModelCatalog| Синтетичні рядки для forward-compat | | 32 |isBinaryThinking| Увімкнення/вимкнення binary thinking | | 33 |supportsXHighThinking| Підтримка reasoningxhigh| | 34 |resolveDefaultThinkingLevel| Стандартна політика/think| | 35 |isModernModelRef| Відповідність моделей live/smoke | | 36 |prepareRuntimeAuth| Обмін токенів перед інференсом | | 37 |resolveUsageAuth| Користувацький розбір облікових даних usage | | 38 |fetchUsageSnapshot| Користувацький endpoint usage | | 39 |createEmbeddingProvider| Адаптер embedding, що належить постачальнику, для пам’яті/пошуку | | 40 |buildReplayPolicy| Користувацька політика повторного відтворення/ущільнення транскрипту | | 41 |sanitizeReplayHistory| Специфічні для постачальника переписування історії повторного відтворення після загального очищення | | 42 |validateReplayTurns| Строга валідація ходів повторного відтворення перед вбудованим runner-ом | | 43 |onModelSelected| Зворотний виклик після вибору моделі (наприклад, telemetry) | Нотатка щодо налаштування промптів:resolveSystemPromptContributionдає змогу постачальнику ін’єктувати cache-aware інструкції системного промпту для сімейства моделей. Віддавайте йому перевагу передbefore_prompt_build, коли поведінка належить одному сімейству постачальника/моделі і має зберігати стабільний/динамічний поділ кешу.
Додайте додаткові можливості (необов’язково)
Плагін постачальника може реєструвати speech, realtime transcription, realtime
voice, media understanding, image generation, video generation, web fetch
і web search поряд із текстовим інференсом:OpenClaw класифікує це як плагін hybrid-capability. Це
рекомендований шаблон для корпоративних плагінів (один плагін на одного постачальника). Див.
Внутрішні механізми: Володіння можливостями.Для генерації відео віддавайте перевагу показаній вище структурі можливостей з урахуванням режимів:
generate, imageToVideo і videoToVideo. Плоских агрегованих полів на кшталт
maxInputImages, maxInputVideos і maxDurationSeconds недостатньо,
щоб коректно оголосити підтримку режиму трансформації або вимкнених режимів.Постачальники генерації музики мають дотримуватися того самого шаблону:
generate для генерації лише за промптом і edit для генерації
на основі референсного зображення. Плоских агрегованих полів на кшталт maxInputImages,
supportsLyrics і supportsFormat недостатньо для оголошення підтримки
редагування; очікуваним контрактом є явні блоки generate / edit.Публікація в ClawHub
Плагіни постачальників публікуються так само, як і будь-які інші зовнішні плагіни коду:clawhub package publish.
Структура файлів
Довідка щодо порядку каталогу
catalog.order визначає, коли ваш каталог зливається відносно вбудованих
постачальників:
| Порядок | Коли | Варіант використання |
|---|---|---|
simple | Перший прохід | Звичайні постачальники з API-ключем |
profile | Після simple | Постачальники, що залежать від профілів автентифікації |
paired | Після profile | Синтез кількох пов’язаних записів |
late | Останній прохід | Перевизначення наявних постачальників (перемагає при колізії) |
Наступні кроки
- Плагіни каналів — якщо ваш плагін також надає канал
- SDK Runtime — хелпери
api.runtime(TTS, пошук, субагент) - Огляд SDK — повний довідник щодо імпорту subpath
- Внутрішні механізми плагінів — деталі хуків і приклади вбудованих рішень