Building Provider Plugins
This guide walks through building a provider plugin that adds a model provider (LLM) to Velaclaw. By the end you will have a provider with a model catalog, API key auth, and dynamic model resolution.If you have not built any Velaclaw plugin before, read
Getting Started first for the basic package
structure and manifest setup.
Walkthrough
1
Package and manifest
providerAuthEnvVars so Velaclaw can detect
credentials without loading your plugin runtime. Add providerAuthAliases
when a provider variant should reuse another provider id’s auth. modelSupport
is optional and lets Velaclaw auto-load your provider plugin from shorthand
model ids like acme-large before runtime hooks exist. If you publish the
provider on ClawHub, those velaclaw.compat and velaclaw.build fields
are required in package.json.2
Register the provider
A minimal provider needs an That is a working provider. Users can now
If your auth flow also needs to patch
id, label, auth, and catalog:index.ts
velaclaw onboard --acme-ai-api-key <key> and select
acme-ai/acme-large as their model.If the upstream provider uses different control tokens than Velaclaw, add a
small bidirectional text transform instead of replacing the stream path:input rewrites the final system prompt and text message content before
transport. output rewrites assistant text deltas and final text before
Velaclaw parses its own control markers or channel delivery.For bundled providers that only register one text provider with API-key
auth plus a single catalog-backed runtime, prefer the narrower
defineSingleProviderPluginEntry(...) helper:models.providers.*, aliases, and
the agent default model during onboarding, use the preset helpers from
velaclaw/plugin-sdk/provider-onboard. The narrowest helpers are
createDefaultModelPresetAppliers(...),
createDefaultModelsPresetAppliers(...), and
createModelCatalogPresetAppliers(...).When a provider’s native endpoint supports streamed usage blocks on the
normal openai-completions transport, prefer the shared catalog helpers in
velaclaw/plugin-sdk/provider-catalog-shared instead of hardcoding
provider-id checks. supportsNativeStreamingUsageCompat(...) and
applyProviderNativeStreamingUsageCompat(...) detect support from the
endpoint capability map, so native Moonshot/DashScope-style endpoints still
opt in even when a plugin is using a custom provider id.3
Add dynamic model resolution
If your provider accepts arbitrary model IDs (like a proxy or router),
add If resolving requires a network call, use
resolveDynamicModel:prepareDynamicModel for async
warm-up — resolveDynamicModel runs again after it completes.4
Add runtime hooks (as needed)
Most providers only need Available replay families today:
catalog + resolveDynamicModel. Add hooks
incrementally as your provider requires them.Shared helper builders now cover the most common replay/tool-compat
families, so plugins usually do not need to hand-wire each hook one by one:Real bundled examples:
googleandgoogle-gemini-cli:google-geminiopenrouter,kilocode,opencode, andopencode-go:passthrough-geminiamazon-bedrockandanthropic-vertex:anthropic-by-modelminimax:hybrid-anthropic-openaimoonshot,ollama,xai, andzai:openai-compatible
Real bundled examples:
googleandgoogle-gemini-cli:google-thinkingkilocode:kilocode-thinkingmoonshot:moonshot-thinkingminimaxandminimax-portal:minimax-fast-modeopenaiandopenai-codex:openai-responses-defaultsopenrouter:openrouter-thinkingzai:tool-stream-default-on
velaclaw/plugin-sdk/provider-model-shared also exports the replay-family
enum plus the shared helpers those families are built from. Common public
exports include:ProviderReplayFamilybuildProviderReplayFamilyHooks(...)- shared replay builders such as
buildOpenAICompatibleReplayPolicy(...),buildAnthropicReplayPolicyForModel(...),buildGoogleGeminiReplayPolicy(...), andbuildHybridAnthropicOrOpenAIReplayPolicy(...) - Gemini replay helpers such as
sanitizeGoogleGeminiReplayHistory(...)andresolveTaggedReasoningOutputMode() - endpoint/model helpers such as
resolveProviderEndpoint(...),normalizeProviderId(...),normalizeGooglePreviewModelId(...), andnormalizeNativeXaiModelId(...)
velaclaw/plugin-sdk/provider-stream exposes both the family builder and
the public wrapper helpers those families reuse. Common public exports
include:ProviderStreamFamilybuildProviderStreamFamilyHooks(...)composeProviderStreamWrappers(...)- shared OpenAI/Codex wrappers such as
createOpenAIAttributionHeadersWrapper(...),createOpenAIFastModeWrapper(...),createOpenAIServiceTierWrapper(...),createOpenAIResponsesContextManagementWrapper(...), andcreateCodexNativeWebSearchWrapper(...) - shared proxy/provider wrappers such as
createOpenRouterWrapper(...),createToolStreamWrapper(...), andcreateMinimaxFastModeWrapper(...)
@velaclaw/anthropic-provider exports
wrapAnthropicProviderStream, resolveAnthropicBetas,
resolveAnthropicFastMode, resolveAnthropicServiceTier, and the
lower-level Anthropic wrapper builders from its public api.ts /
contract-api.ts seam. Those helpers remain Anthropic-specific because
they also encode Claude OAuth beta handling and context1m gating.Other bundled providers also keep transport-specific wrappers local when
the behavior is not shared cleanly across families. Current example: the
bundled xAI plugin keeps native xAI Responses shaping in its own
wrapStreamFn, including /fast alias rewrites, default tool_stream,
unsupported strict-tool cleanup, and xAI-specific reasoning-payload
removal.velaclaw/plugin-sdk/provider-tools currently exposes one shared
tool-schema family plus shared schema/compat helpers:ProviderToolCompatFamilydocuments the shared family inventory today.buildProviderToolCompatFamilyHooks("gemini")wires Gemini schema cleanup + diagnostics for providers that need Gemini-safe tool schemas.normalizeGeminiToolSchemas(...)andinspectGeminiToolSchemas(...)are the underlying public Gemini schema helpers.resolveXaiModelCompatPatch()returns the bundled xAI compat patch:toolSchemaProfile: "xai", unsupported schema keywords, nativeweb_searchsupport, and HTML-entity tool-call argument decoding.applyXaiModelCompat(model)applies that same xAI compat patch to a resolved model before it reaches the runner.
normalizeResolvedModel plus
contributeResolvedModelCompat to keep that compat metadata owned by the
provider instead of hardcoding xAI rules in core.The same package-root pattern also backs other bundled providers:@velaclaw/openai-provider:api.tsexports provider builders, default-model helpers, and realtime provider builders@velaclaw/openrouter-provider:api.tsexports the provider builder plus onboarding/config helpers
- Token exchange
- Custom headers
- Native transport identity
- Usage and billing
For providers that need a token exchange before each inference call:
All available provider hooks
All available provider hooks
Velaclaw calls hooks in this order. Most providers only use 2-3:
Runtime fallback notes:
-
normalizeConfigchecks the matched provider first, then other hook-capable provider plugins until one actually changes the config. If no provider hook rewrites a supported Google-family config entry, the bundled Google config normalizer still applies. -
resolveConfigApiKeyuses the provider hook when exposed. The bundledamazon-bedrockpath also has a built-in AWS env-marker resolver here, even though Bedrock runtime auth itself still uses the AWS SDK default chain. | 13 |contributeResolvedModelCompat| Compat flags for vendor models behind another compatible transport | | 14 |capabilities| Legacy static capability bag; compatibility only | | 15 |normalizeToolSchemas| Provider-owned tool-schema cleanup before registration | | 16 |inspectToolSchemas| Provider-owned tool-schema diagnostics | | 17 |resolveReasoningOutputMode| Tagged vs native reasoning-output contract | | 18 |prepareExtraParams| Default request params | | 19 |createStreamFn| Fully custom StreamFn transport | | 20 |wrapStreamFn| Custom headers/body wrappers on the normal stream path | | 21 |resolveTransportTurnState| Native per-turn headers/metadata | | 22 |resolveWebSocketSessionPolicy| Native WS session headers/cool-down | | 23 |formatApiKey| Custom runtime token shape | | 24 |refreshOAuth| Custom OAuth refresh | | 25 |buildAuthDoctorHint| Auth repair guidance | | 26 |matchesContextOverflowError| Provider-owned overflow detection | | 27 |classifyFailoverReason| Provider-owned rate-limit/overload classification | | 28 |isCacheTtlEligible| Prompt cache TTL gating | | 29 |buildMissingAuthMessage| Custom missing-auth hint | | 30 |suppressBuiltInModel| Hide stale upstream rows | | 31 |augmentModelCatalog| Synthetic forward-compat rows | | 32 |isBinaryThinking| Binary thinking on/off | | 33 |supportsXHighThinking|xhighreasoning support | | 34 |resolveDefaultThinkingLevel| Default/thinkpolicy | | 35 |isModernModelRef| Live/smoke model matching | | 36 |prepareRuntimeAuth| Token exchange before inference | | 37 |resolveUsageAuth| Custom usage credential parsing | | 38 |fetchUsageSnapshot| Custom usage endpoint | | 39 |createEmbeddingProvider| Provider-owned embedding adapter for memory/search | | 40 |buildReplayPolicy| Custom transcript replay/compaction policy | | 41 |sanitizeReplayHistory| Provider-specific replay rewrites after generic cleanup | | 42 |validateReplayTurns| Strict replay-turn validation before the embedded runner | | 43 |onModelSelected| Post-selection callback (e.g. telemetry) | Prompt tuning note:resolveSystemPromptContributionlets a provider inject cache-aware system-prompt guidance for a model family. Prefer it overbefore_prompt_buildwhen the behavior belongs to one provider/model family and should preserve the stable/dynamic cache split.
5
Add extra capabilities (optional)
A provider plugin can register speech, realtime transcription, realtime
voice, media understanding, image generation, video generation, web fetch,
and web search alongside text inference:Velaclaw classifies this as a hybrid-capability plugin. This is the
recommended pattern for company plugins (one plugin per vendor). See
Internals: Capability Ownership.For video generation, prefer the mode-aware capability shape shown above:
generate, imageToVideo, and videoToVideo. Flat aggregate fields such
as maxInputImages, maxInputVideos, and maxDurationSeconds are not
enough to advertise transform-mode support or disabled modes cleanly.Music-generation providers should follow the same pattern:
generate for prompt-only generation and edit for reference-image-based
generation. Flat aggregate fields such as maxInputImages,
supportsLyrics, and supportsFormat are not enough to advertise edit
support; explicit generate / edit blocks are the expected contract.Publish to ClawHub
Provider plugins publish the same way as any other external code plugin:clawhub package publish.
File structure
Catalog order reference
catalog.order controls when your catalog merges relative to built-in
providers:
Next steps
- Channel Plugins — if your plugin also provides a channel
- SDK Runtime —
api.runtimehelpers (TTS, search, subagent) - SDK Overview — full subpath import reference
- Plugin Internals — hook details and bundled examples