Створення плагінів провайдерів
Цей посібник пояснює, як створити плагін провайдера, який додає до OpenClaw провайдера моделей (LLM). Наприкінці у вас буде провайдер із каталогом моделей, автентифікацією за API-ключем і динамічним визначенням моделей.Якщо ви ще не створювали жодного плагіна OpenClaw, спочатку прочитайте
Getting Started про базову структуру пакунка
та налаштування маніфесту.
Покроковий посібник
Пакунок і маніфест
providerAuthEnvVars, щоб OpenClaw міг визначати
облікові дані без завантаження runtime вашого плагіна. modelSupport є необов’язковим
і дозволяє OpenClaw автоматично завантажувати ваш плагін провайдера за скороченими ідентифікаторами моделей
на кшталт 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 як свою модель.Для вбудованих провайдерів, які реєструють лише одного текстового провайдера з
автентифікацією за API-ключем і одним runtime на основі каталогу, надавайте перевагу
вужчому допоміжному засобу defineSingleProviderPluginEntry(...):models.providers.*, псевдоніми та
типову модель агента під час onboarding, використовуйте попередньо налаштовані допоміжні засоби з
openclaw/plugin-sdk/provider-onboard. Найвужчими допоміжними засобами є
createDefaultModelPresetAppliers(...),
createDefaultModelsPresetAppliers(...) і
createModelCatalogPresetAppliers(...).Коли нативна кінцева точка провайдера підтримує потокові блоки usage у
звичайному транспорті openai-completions, надавайте перевагу спільним допоміжним засобам каталогу в
openclaw/plugin-sdk/provider-catalog-shared замість жорсткого кодування перевірок provider-id. Функції
supportsNativeStreamingUsageCompat(...) і
applyProviderNativeStreamingUsageCompat(...) визначають підтримку за картою можливостей кінцевої точки,
тому нативні кінцеві точки на кшталт Moonshot/DashScope все одно підключаються, навіть коли плагін використовує власний provider id.Додайте динамічне визначення моделі
Якщо ваш провайдер приймає довільні ідентифікатори моделей (як проксі або маршрутизатор),
додайте Якщо для визначення потрібен мережевий виклик, використовуйте
resolveDynamicModel:prepareDynamicModel для асинхронного
попереднього прогріву — після його завершення resolveDynamicModel виконується знову.Додайте runtime-хуки (за потреби)
Більшості провайдерів потрібні лише Доступні на сьогодні сімейства replay:
Реальні вбудовані приклади:
Реальні вбудовані приклади:
catalog + resolveDynamicModel. Додавайте хуки
поступово, відповідно до потреб вашого провайдера.Спільні побудовники допоміжних засобів тепер охоплюють найпоширеніші сімейства replay/tool-compat,
тому плагінам зазвичай не потрібно вручну під’єднувати кожен хук окремо:| Family | Що воно підключає |
|---|---|
openai-compatible | Спільна політика replay у стилі OpenAI для OpenAI-сумісних транспортів, зокрема очищення tool-call-id, виправлення порядку assistant-first і загальну перевірку Gemini-turn там, де це потрібно транспорту |
anthropic-by-model | Політика replay з урахуванням Claude, що вибирається за modelId, тому транспорти повідомлень Anthropic отримують очищення thinking-block, специфічне для Claude, лише тоді, коли визначена модель справді є ідентифікатором Claude |
google-gemini | Нативна політика replay для Gemini плюс очищення bootstrap replay і тегований режим reasoning-output |
passthrough-gemini | Очищення thought-signature для Gemini-моделей, що працюють через OpenAI-сумісні проксі-транспорти; не вмикає нативну перевірку Gemini replay або переписування bootstrap |
hybrid-anthropic-openai | Гібридна політика для провайдерів, які поєднують поверхні моделей Anthropic-message і OpenAI-compatible в одному плагіні; необов’язкове відкидання thinking-block лише для Claude залишається обмеженим стороною Anthropic |
google:google-geminiopenrouter,kilocode,opencodeіopencode-go:passthrough-geminiamazon-bedrockіanthropic-vertex:anthropic-by-modelminimax:hybrid-anthropic-openaimoonshot,ollama,xaiіzai:openai-compatible
| Family | Що воно підключає |
|---|---|
google-thinking | Нормалізація payload thinking Gemini на спільному шляху stream |
kilocode-thinking | Обгортка Kilo reasoning на спільному шляху proxy 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 для маршрутів proxy, з централізованою обробкою пропусків для непідтримуваних моделей/auto |
tool-stream-default-on | Обгортка tool_stream, увімкнена типово, для провайдерів на кшталт Z.AI, яким потрібен потоковий режим інструментів, якщо його явно не вимкнено |
google: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 сімейств replay
разом зі спільними допоміжними засобами, з яких ці сімейства побудовані. Поширені публічні
експорти містять:ProviderReplayFamilybuildProviderReplayFamilyHooks(...)- спільні побудовники replay, як-от
buildOpenAICompatibleReplayPolicy(...),buildAnthropicReplayPolicyForModel(...),buildGoogleGeminiReplayPolicy(...)іbuildHybridAnthropicOrOpenAIReplayPolicy(...) - допоміжні засоби replay для Gemini, як-от
sanitizeGoogleGeminiReplayHistory(...)іresolveTaggedReasoningOutputMode() - допоміжні засоби для кінцевих точок/моделей, як-от
resolveProviderEndpoint(...),normalizeProviderId(...),normalizeGooglePreviewModelId(...)іnormalizeNativeXaiModelId(...)
openclaw/plugin-sdk/provider-stream надає і побудовник сімейств,
і публічні допоміжні засоби обгорток, які ці сімейства повторно використовують. Поширені публічні експорти
містять:ProviderStreamFamilybuildProviderStreamFamilyHooks(...)composeProviderStreamWrappers(...)- спільні обгортки OpenAI/Codex, як-от
createOpenAIAttributionHeadersWrapper(...),createOpenAIFastModeWrapper(...),createOpenAIServiceTierWrapper(...),createOpenAIResponsesContextManagementWrapper(...)іcreateCodexNativeWebSearchWrapper(...) - спільні обгортки proxy/провайдерів, як-от
createOpenRouterWrapper(...),createToolStreamWrapper(...)іcreateMinimaxFastModeWrapper(...)
@openclaw/anthropic-provider експортує
wrapAnthropicProviderStream, resolveAnthropicBetas,
resolveAnthropicFastMode, resolveAnthropicServiceTier і
низькорівневі побудовники обгорток Anthropic зі свого публічного шва api.ts /
contract-api.ts. Ці допоміжні засоби залишаються специфічними для Anthropic, оскільки
вони також кодують обробку бета-версій Claude OAuth і обмеження context1m.Інші вбудовані провайдери також зберігають транспортно-специфічні обгортки локально, коли
поведінка не ділиться чисто між сімействами. Поточний приклад: вбудований плагін xAI
зберігає власне формування native xAI Responses у своєму
wrapStreamFn, зокрема переписування псевдонімів /fast, типовий tool_stream,
очищення непідтримуваного strict-tool і видалення
payload reasoning, специфічного для xAI.openclaw/plugin-sdk/provider-tools наразі надає одне спільне
сімейство схем сумісності з інструментами плюс спільні допоміжні засоби схем/сумісності:ProviderToolCompatFamilyдокументує поточний перелік спільних сімейств.buildProviderToolCompatFamilyHooks("gemini")підключає очищення схем Gemini + діагностику для провайдерів, яким потрібні безпечні для Gemini схеми інструментів.normalizeGeminiToolSchemas(...)іinspectGeminiToolSchemas(...)є базовими публічними допоміжними засобами схем Gemini.resolveXaiModelCompatPatch()повертає вбудований патч сумісності xAI:toolSchemaProfile: "xai", непідтримувані ключові слова схеми, нативну підтримкуweb_searchі декодування аргументів tool-call із HTML-сутностей.applyXaiModelCompat(model)застосовує той самий патч сумісності xAI до визначеної моделі до того, як вона потрапить до runner.
normalizeResolvedModel плюс
contributeResolvedModelCompat, щоб метадані сумісності залишалися у власності
провайдера, а не правила xAI були жорстко закодовані в ядрі.Той самий шаблон кореня пакунка також лежить в основі інших вбудованих провайдерів:@openclaw/openai-provider:api.tsекспортує побудовники провайдерів, допоміжні засоби типової моделі та побудовники провайдерів realtime@openclaw/openrouter-provider:api.tsекспортує побудовник провайдера плюс допоміжні засоби onboarding/config
- Обмін токенів
- Власні заголовки
- Ідентичність нативного транспорту
- Usage і білінг
Для провайдерів, яким потрібен обмін токенів перед кожним викликом inference:
Усі доступні provider hooks
Усі доступні provider hooks
OpenClaw викликає хуки в такому порядку. Більшість провайдерів використовують лише 2-3:
Примітки щодо runtime fallback:
| # | Hook | Коли використовувати |
|---|---|---|
| 1 | catalog | Каталог моделей або типові значення base URL |
| 2 | applyConfigDefaults | Глобальні типові значення, що належать провайдеру, під час матеріалізації конфігурації |
| 3 | normalizeModelId | Очищення застарілих/preview псевдонімів model-id перед пошуком |
| 4 | normalizeTransport | Очищення api / baseUrl для сімейства провайдера перед загальним складанням моделі |
| 5 | normalizeConfig | Нормалізація конфігурації models.providers.<id> |
| 6 | applyNativeStreamingUsageCompat | Переписування сумісності native streaming-usage для конфігурованих провайдерів |
| 7 | resolveConfigApiKey | Визначення автентифікації за маркером env, що належить провайдеру |
| 8 | resolveSyntheticAuth | Синтетична автентифікація для локальних/self-hosted або конфігурованих варіантів |
| 9 | shouldDeferSyntheticProfileAuth | Розміщення синтетичних плейсхолдерів збереженого профілю нижче від env/config auth |
| 10 | resolveDynamicModel | Прийом довільних upstream ідентифікаторів моделей |
| 11 | prepareDynamicModel | Асинхронне отримання метаданих перед визначенням |
| 12 | normalizeResolvedModel | Переписування транспорту перед runner |
-
normalizeConfigспочатку перевіряє відповідний провайдер, а потім інші плагіни провайдерів із підтримкою хуків, доки якийсь із них справді не змінить конфігурацію. Якщо жоден provider hook не перепише підтримуваний запис конфігурації сімейства Google, усе одно буде застосовано вбудований нормалізатор конфігурації Google. -
resolveConfigApiKeyвикористовує provider hook, якщо його надано. Вбудований шляхamazon-bedrockтакож має тут вбудований AWS env-marker resolver, хоча сама runtime auth Bedrock усе ще використовує стандартний ланцюжок AWS SDK. | 13 |contributeResolvedModelCompat| Прапорці сумісності для моделей вендора за іншим сумісним транспортом | | 14 |capabilities| Застарілий статичний набір можливостей; лише для сумісності | | 15 |normalizeToolSchemas| Очищення схем інструментів, що належить провайдеру, перед реєстрацією | | 16 |inspectToolSchemas| Діагностика схем інструментів, що належить провайдеру | | 17 |resolveReasoningOutputMode| Контракт тегованого або нативного reasoning-output | | 18 |prepareExtraParams| Типові параметри запиту | | 19 |createStreamFn| Повністю власний транспорт StreamFn | | 20 |wrapStreamFn| Обгортки власних заголовків/тіла на звичайному шляху stream | | 21 |resolveTransportTurnState| Нативні заголовки/метадані для кожного turn | | 22 |resolveWebSocketSessionPolicy| Нативні заголовки сеансу WS/cool-down | | 23 |formatApiKey| Власна форма runtime-токена | | 24 |refreshOAuth| Власне оновлення OAuth | | 25 |buildAuthDoctorHint| Підказка для виправлення auth | | 26 |matchesContextOverflowError| Визначення переповнення, що належить провайдеру | | 27 |classifyFailoverReason| Класифікація rate-limit/overload, що належить провайдеру | | 28 |isCacheTtlEligible| Контроль TTL кешу prompt | | 29 |buildMissingAuthMessage| Власна підказка про відсутню auth | | 30 |suppressBuiltInModel| Приховування застарілих upstream-рядків | | 31 |augmentModelCatalog| Синтетичні рядки для сумісності вперед | | 32 |isBinaryThinking| Бінарне вмикання/вимикання thinking | | 33 |supportsXHighThinking| Підтримка reasoningxhigh| | 34 |resolveDefaultThinkingLevel| Типова політика/think| | 35 |isModernModelRef| Відповідність live/smoke моделей | | 36 |prepareRuntimeAuth| Обмін токенів перед inference | | 37 |resolveUsageAuth| Власний розбір облікових даних usage | | 38 |fetchUsageSnapshot| Власна кінцева точка usage | | 39 |createEmbeddingProvider| Адаптер embedding, що належить провайдеру, для memory/search | | 40 |buildReplayPolicy| Власна політика replay/ущільнення транскрипту | | 41 |sanitizeReplayHistory| Переписування replay, специфічні для провайдера, після загального очищення | | 42 |validateReplayTurns| Сувора перевірка replay-turn перед вбудованим runner | | 43 |onModelSelected| Зворотний виклик після вибору моделі (наприклад, телеметрія) | Примітка щодо налаштування prompt:resolveSystemPromptContributionдає змогу провайдеру додавати cache-aware інструкції для system prompt для сімейства моделей. Надавайте їй перевагу надbefore_prompt_build, коли така поведінка належить одному провайдеру/сімейству моделей і має зберігати стабільний/динамічний поділ кешу.
Додайте додаткові можливості (необов’язково)
Плагін провайдера може реєструвати speech, realtime transcription, realtime
voice, media understanding, image generation, video generation, web fetch
і web search разом із текстовим inference:OpenClaw класифікує це як плагін hybrid-capability. Це
рекомендований шаблон для корпоративних плагінів (один плагін на вендора). Див.
Internals: Capability Ownership.
Публікація в ClawHub
Плагіни провайдерів публікуються так само, як і будь-який інший зовнішній кодовий плагін:clawhub package publish.
Структура файлів
Довідник щодо порядку каталогу
catalog.order визначає, коли ваш каталог об’єднується відносно вбудованих
провайдерів:
| Порядок | Коли | Випадок використання |
|---|---|---|
simple | Перший прохід | Звичайні провайдери з API-ключем |
profile | Після simple | Провайдери, обмежені профілями auth |
paired | Після profile | Синтез кількох пов’язаних записів |
late | Останній прохід | Перевизначення наявних провайдерів (перемагає при колізії) |
Наступні кроки
- Channel Plugins — якщо ваш плагін також надає канал
- SDK Runtime — допоміжні засоби
api.runtime(TTS, search, subagent) - Огляд SDK — повний довідник імпортів subpath
- Внутрішня архітектура плагінів — подробиці про хуки та вбудовані приклади