Criando plugins de provedor
Este guia mostra passo a passo como criar um plugin de provedor que adiciona um provedor de modelo (LLM) ao OpenClaw. Ao final, você terá um provedor com catálogo de modelos, autenticação por chave de API e resolução dinâmica de modelo.Se você ainda não criou nenhum plugin do OpenClaw antes, leia
Primeiros passos primeiro para entender a estrutura básica
do pacote e a configuração do manifesto.
Passo a passo
Pacote e manifesto
providerAuthEnvVars para que o OpenClaw possa detectar
credenciais sem carregar o runtime do seu plugin. Adicione providerAuthAliases
quando uma variante de provedor precisar reutilizar a autenticação de outro id de provedor. modelSupport
é opcional e permite que o OpenClaw carregue automaticamente seu plugin de provedor a partir de ids curtos
de modelo como acme-large antes de existirem hooks de runtime. Se você publicar o
provedor no ClawHub, esses campos openclaw.compat e openclaw.build
são obrigatórios no package.json.Registre o provedor
Um provedor mínimo precisa de Isso já é um provedor funcional. Os usuários agora podem executar
Se o seu fluxo de autenticação também precisar ajustar
id, label, auth e catalog:index.ts
openclaw onboard --acme-ai-api-key <key> e selecionar
acme-ai/acme-large como modelo.Se o provedor upstream usar tokens de controle diferentes dos do OpenClaw, adicione uma
pequena transformação de texto bidirecional em vez de substituir o caminho de stream:input reescreve o prompt final de sistema e o conteúdo de texto da mensagem antes do
transporte. output reescreve deltas de texto do assistente e o texto final antes que o
OpenClaw analise seus próprios marcadores de controle ou faça a entrega ao canal.Para provedores empacotados que registram apenas um provedor de texto com autenticação
por chave de API mais um único runtime baseado em catálogo, prefira o helper mais específico
defineSingleProviderPluginEntry(...):models.providers.*, aliases e
o modelo padrão do agente durante o onboarding, use os helpers predefinidos de
openclaw/plugin-sdk/provider-onboard. Os helpers mais específicos são
createDefaultModelPresetAppliers(...),
createDefaultModelsPresetAppliers(...) e
createModelCatalogPresetAppliers(...).Quando o endpoint nativo de um provedor oferece suporte a blocos de uso em streaming no
transporte normal openai-completions, prefira os helpers compartilhados de catálogo em
openclaw/plugin-sdk/provider-catalog-shared em vez de codificar verificações por id de provedor. supportsNativeStreamingUsageCompat(...) e
applyProviderNativeStreamingUsageCompat(...) detectam suporte a partir do mapa de capacidades do endpoint,
para que endpoints nativos no estilo Moonshot/DashScope também façam opt-in, mesmo quando um plugin estiver usando um id de provedor personalizado.Adicione resolução dinâmica de modelo
Se o seu provedor aceitar ids arbitrários de modelo (como um proxy ou roteador),
adicione Se a resolução exigir uma chamada de rede, use
resolveDynamicModel:prepareDynamicModel para o
aquecimento assíncrono — resolveDynamicModel é executado novamente após a conclusão.Adicione hooks de runtime (conforme necessário)
A maioria dos provedores só precisa de Famílias de replay disponíveis atualmente:
Exemplos empacotados reais:
Exemplos empacotados reais:
catalog + resolveDynamicModel. Adicione hooks
gradualmente, à medida que seu provedor precisar deles.Os builders de helper compartilhados agora cobrem as famílias mais comuns de replay/compatibilidade
com ferramentas, então os plugins normalmente não precisam conectar cada hook manualmente:| Família | O que ela conecta |
|---|---|
openai-compatible | Política compartilhada de replay no estilo OpenAI para transportes compatíveis com OpenAI, incluindo saneamento de tool-call-id, correções de ordenação assistant-first e validação genérica de turnos Gemini quando o transporte precisa disso |
anthropic-by-model | Política de replay compatível com Claude escolhida por modelId, para que transportes de mensagens da Anthropic recebam limpeza específica de blocos de raciocínio do Claude apenas quando o modelo resolvido for realmente um id Claude |
google-gemini | Política nativa de replay do Gemini mais saneamento de replay de bootstrap e modo de saída de raciocínio com tag |
passthrough-gemini | Saneamento de assinatura de pensamento do Gemini para modelos Gemini executados por transportes de proxy compatíveis com OpenAI; não habilita validação nativa de replay do Gemini nem regravações de bootstrap |
hybrid-anthropic-openai | Política híbrida para provedores que misturam superfícies de modelo de mensagens da Anthropic e compatíveis com OpenAI em um único plugin; a remoção opcional de blocos de raciocínio apenas do Claude continua restrita ao lado Anthropic |
googleegoogle-gemini-cli:google-geminiopenrouter,kilocode,opencodeeopencode-go:passthrough-geminiamazon-bedrockeanthropic-vertex:anthropic-by-modelminimax:hybrid-anthropic-openaimoonshot,ollama,xaiezai:openai-compatible
| Família | O que ela conecta |
|---|---|
google-thinking | Normalização de payload de raciocínio do Gemini no caminho de stream compartilhado |
kilocode-thinking | Wrapper de raciocínio do Kilo no caminho de stream de proxy compartilhado, com ids de raciocínio kilo/auto e de proxy sem suporte pulando o raciocínio injetado |
moonshot-thinking | Mapeamento de payload binário nativo de raciocínio do Moonshot a partir da configuração + nível de /think |
minimax-fast-mode | Regravação de modelo em modo rápido do MiniMax no caminho de stream compartilhado |
openai-responses-defaults | Wrappers nativos compartilhados de Responses do OpenAI/Codex: cabeçalhos de atribuição, /fast/serviceTier, verbosidade de texto, pesquisa web nativa do Codex, formatação de payload compatível com raciocínio e gerenciamento de contexto de Responses |
openrouter-thinking | Wrapper de raciocínio do OpenRouter para rotas de proxy, com pulos de modelos sem suporte/auto tratados centralmente |
tool-stream-default-on | Wrapper tool_stream ativado por padrão para provedores como Z.AI que querem streaming de ferramentas, a menos que seja desativado explicitamente |
googleegoogle-gemini-cli:google-thinkingkilocode:kilocode-thinkingmoonshot:moonshot-thinkingminimaxeminimax-portal:minimax-fast-modeopenaieopenai-codex:openai-responses-defaultsopenrouter:openrouter-thinkingzai:tool-stream-default-on
openclaw/plugin-sdk/provider-model-shared também exporta o enum da família
de replay, além dos helpers compartilhados a partir dos quais essas famílias são construídas. Exportações públicas comuns
incluem:ProviderReplayFamilybuildProviderReplayFamilyHooks(...)- builders compartilhados de replay, como
buildOpenAICompatibleReplayPolicy(...),buildAnthropicReplayPolicyForModel(...),buildGoogleGeminiReplayPolicy(...)ebuildHybridAnthropicOrOpenAIReplayPolicy(...) - Helpers de replay do Gemini, como
sanitizeGoogleGeminiReplayHistory(...)eresolveTaggedReasoningOutputMode() - Helpers de endpoint/modelo, como
resolveProviderEndpoint(...),normalizeProviderId(...),normalizeGooglePreviewModelId(...)enormalizeNativeXaiModelId(...)
openclaw/plugin-sdk/provider-stream expõe tanto o builder de família quanto
os helpers públicos de wrapper que essas famílias reutilizam. Exportações públicas comuns
incluem:ProviderStreamFamilybuildProviderStreamFamilyHooks(...)composeProviderStreamWrappers(...)- wrappers compartilhados do OpenAI/Codex, como
createOpenAIAttributionHeadersWrapper(...),createOpenAIFastModeWrapper(...),createOpenAIServiceTierWrapper(...),createOpenAIResponsesContextManagementWrapper(...)ecreateCodexNativeWebSearchWrapper(...) - wrappers compartilhados de proxy/provedor, como
createOpenRouterWrapper(...),createToolStreamWrapper(...)ecreateMinimaxFastModeWrapper(...)
@openclaw/anthropic-provider exporta
wrapAnthropicProviderStream, resolveAnthropicBetas,
resolveAnthropicFastMode, resolveAnthropicServiceTier e os
builders de wrapper Anthropic de nível mais baixo por meio de seu seam público api.ts /
contract-api.ts. Esses helpers continuam específicos da Anthropic porque
também codificam o tratamento beta do Claude OAuth e o gating de context1m.Outros provedores empacotados também mantêm wrappers específicos de transporte localmente quando
o comportamento não é compartilhado de forma limpa entre famílias. Exemplo atual: o
plugin xAI empacotado mantém a formatação nativa de Responses do xAI em seu próprio
wrapStreamFn, incluindo regravações de alias /fast, tool_stream padrão,
limpeza de strict-tool sem suporte e remoção de payload de raciocínio
específica do xAI.openclaw/plugin-sdk/provider-tools atualmente expõe uma família compartilhada
de schema de ferramentas, além de helpers compartilhados de schema/compatibilidade:ProviderToolCompatFamilydocumenta hoje o inventário de famílias compartilhadas.buildProviderToolCompatFamilyHooks("gemini")conecta a limpeza de schema do Gemini- diagnósticos para provedores que precisam de schemas de ferramentas seguros para Gemini.
normalizeGeminiToolSchemas(...)einspectGeminiToolSchemas(...)são os helpers públicos subjacentes de schema do Gemini.resolveXaiModelCompatPatch()retorna o patch de compatibilidade empacotado do xAI:toolSchemaProfile: "xai", palavras-chave de schema sem suporte, suporte nativo aweb_searche decodificação de argumentos de chamada de ferramenta com entidades HTML.applyXaiModelCompat(model)aplica esse mesmo patch de compatibilidade do xAI a um modelo resolvido antes de ele chegar ao runner.
normalizeResolvedModel mais
contributeResolvedModelCompat para manter esses metadados de compatibilidade sob responsabilidade do
provedor em vez de codificar regras de xAI no core.O mesmo padrão de raiz de pacote também dá suporte a outros provedores empacotados:@openclaw/openai-provider:api.tsexporta builders de provedor, helpers de modelo padrão e builders de provedor realtime@openclaw/openrouter-provider:api.tsexporta o builder de provedor além de helpers de onboarding/configuração
- Troca de token
- Cabeçalhos personalizados
- Identidade nativa de transporte
- Uso e cobrança
Para provedores que precisam de uma troca de token antes de cada chamada de inferência:
Todos os hooks de provedor disponíveis
Todos os hooks de provedor disponíveis
O OpenClaw chama os hooks nesta ordem. A maioria dos provedores usa apenas 2 ou 3:
Observações sobre fallback de runtime:
| # | Hook | Quando usar |
|---|---|---|
| 1 | catalog | Catálogo de modelos ou padrões de base URL |
| 2 | applyConfigDefaults | Padrões globais de propriedade do provedor durante a materialização da configuração |
| 3 | normalizeModelId | Limpeza de aliases legados/prévia de ids de modelo antes da busca |
| 4 | normalizeTransport | Limpeza de api / baseUrl da família do provedor antes da montagem genérica do modelo |
| 5 | normalizeConfig | Normalizar a configuração models.providers.<id> |
| 6 | applyNativeStreamingUsageCompat | Regravações de compatibilidade de uso em streaming nativo para provedores de configuração |
| 7 | resolveConfigApiKey | Resolução de autenticação por marcador de env de propriedade do provedor |
| 8 | resolveSyntheticAuth | Autenticação sintética local/self-hosted ou baseada em configuração |
| 9 | shouldDeferSyntheticProfileAuth | Rebaixar placeholders sintéticos de perfil armazenado em favor de autenticação por env/configuração |
| 10 | resolveDynamicModel | Aceitar ids arbitrários de modelos upstream |
| 11 | prepareDynamicModel | Busca assíncrona de metadados antes da resolução |
| 12 | normalizeResolvedModel | Regravações de transporte antes do runner |
-
normalizeConfigverifica primeiro o provedor correspondente e depois outros plugins de provedor com suporte a hooks até que um realmente altere a configuração. Se nenhum hook de provedor regravar uma entrada de configuração compatível com a família Google, o normalizador de configuração Google empacotado ainda será aplicado. -
resolveConfigApiKeyusa o hook do provedor quando exposto. O caminho empacotado deamazon-bedrocktambém tem aqui um resolvedor interno de marcador de env da AWS, mesmo que a autenticação de runtime do Bedrock ainda use a cadeia padrão do AWS SDK. | 13 |contributeResolvedModelCompat| Flags de compatibilidade para modelos de fornecedor por trás de outro transporte compatível | | 14 |capabilities| Bag estática legada de capacidades; somente compatibilidade | | 15 |normalizeToolSchemas| Limpeza de schema de ferramentas de propriedade do provedor antes do registro | | 16 |inspectToolSchemas| Diagnósticos de schema de ferramentas de propriedade do provedor | | 17 |resolveReasoningOutputMode| Contrato de saída de raciocínio com tag vs nativo | | 18 |prepareExtraParams| Parâmetros padrão de requisição | | 19 |createStreamFn| Transporte StreamFn totalmente personalizado | | 20 |wrapStreamFn| Wrappers de cabeçalho/body personalizados no caminho normal de stream | | 21 |resolveTransportTurnState| Cabeçalhos/metadados nativos por turno | | 22 |resolveWebSocketSessionPolicy| Cabeçalhos de sessão WS nativos / resfriamento | | 23 |formatApiKey| Formato personalizado de token de runtime | | 24 |refreshOAuth| Renovação personalizada de OAuth | | 25 |buildAuthDoctorHint| Orientação de reparo de autenticação | | 26 |matchesContextOverflowError| Detecção de overflow de contexto de propriedade do provedor | | 27 |classifyFailoverReason| Classificação de limite de taxa/sobrecarga de propriedade do provedor | | 28 |isCacheTtlEligible| Gating de TTL de cache de prompt | | 29 |buildMissingAuthMessage| Dica personalizada de autenticação ausente | | 30 |suppressBuiltInModel| Ocultar linhas upstream desatualizadas | | 31 |augmentModelCatalog| Linhas sintéticas de compatibilidade futura | | 32 |isBinaryThinking| Raciocínio binário ligado/desligado | | 33 |supportsXHighThinking| Suporte a raciocínioxhigh| | 34 |resolveDefaultThinkingLevel| Política padrão de/think| | 35 |isModernModelRef| Correspondência de modelo para live/smoke | | 36 |prepareRuntimeAuth| Troca de token antes da inferência | | 37 |resolveUsageAuth| Parsing personalizado de credencial de uso | | 38 |fetchUsageSnapshot| Endpoint personalizado de uso | | 39 |createEmbeddingProvider| Adaptador de embeddings de propriedade do provedor para memória/busca | | 40 |buildReplayPolicy| Política personalizada de replay/compactação da transcrição | | 41 |sanitizeReplayHistory| Regravações específicas do provedor no replay após a limpeza genérica | | 42 |validateReplayTurns| Validação estrita de turnos de replay antes do runner incorporado | | 43 |onModelSelected| Callback pós-seleção (por exemplo, telemetria) | Observação sobre ajuste de prompt:resolveSystemPromptContributionpermite que um provedor injete orientação de prompt de sistema com reconhecimento de cache para uma família de modelos. Prefira-o em vez debefore_prompt_buildquando o comportamento pertencer a uma família de provedor/modelo e precisar preservar a divisão estável/dinâmica do cache.
Adicionar capacidades extras (opcional)
Um plugin de provedor pode registrar fala, transcrição em tempo real, voz em tempo real,
compreensão de mídia, geração de imagem, geração de vídeo, web fetch
e web search juntamente com a inferência de texto:O OpenClaw classifica isso como um plugin de capacidade híbrida. Esse é o
padrão recomendado para plugins de empresa (um plugin por fornecedor). Consulte
Internals: Capability Ownership.Para geração de vídeo, prefira o formato de capacidades com reconhecimento de modo mostrado acima:
generate, imageToVideo e videoToVideo. Campos agregados planos como
maxInputImages, maxInputVideos e maxDurationSeconds não
são suficientes para anunciar suporte a modo de transformação ou modos desabilitados com clareza.Provedores de geração de música devem seguir o mesmo padrão:
generate para geração somente por prompt e edit para geração baseada em imagem de referência.
Campos agregados planos como maxInputImages,
supportsLyrics e supportsFormat não são suficientes para anunciar suporte a edição;
blocos explícitos generate / edit são o contrato esperado.Publicar no ClawHub
Plugins de provedor são publicados da mesma forma que qualquer outro plugin de código externo:clawhub package publish.
Estrutura de arquivos
Referência da ordem do catálogo
catalog.order controla quando o seu catálogo é mesclado em relação aos
provedores integrados:
| Ordem | Quando | Caso de uso |
|---|---|---|
simple | Primeira passada | Provedores simples com chave de API |
profile | Após simple | Provedores condicionados a perfis de autenticação |
paired | Após profile | Sintetizar várias entradas relacionadas |
late | Última passada | Substituir provedores existentes (vence em colisão) |
Próximos passos
- Plugins de canal — se o seu plugin também fornecer um canal
- Runtime do SDK — helpers de
api.runtime(TTS, busca, subagente) - Visão geral do SDK — referência completa de importação por subpath
- Internals de plugins — detalhes de hooks e exemplos empacotados