Skip to main content

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.
Provider plugins add models to Velaclaw’s normal inference loop. If the model must run through a native agent daemon that owns threads, compaction, or tool events, pair the provider with an agent harness instead of putting daemon protocol details in core.

Walkthrough

1

Package and manifest

The manifest declares 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 id, label, auth, and catalog:
index.ts
That is a working provider. Users can now 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:
If your auth flow also needs to patch 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 resolveDynamicModel:
If resolving requires a network call, use prepareDynamicModel for async warm-up — resolveDynamicModel runs again after it completes.
4

Add runtime hooks (as needed)

Most providers only need 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:
Available replay families today:Real bundled examples:
  • google and google-gemini-cli: google-gemini
  • openrouter, kilocode, opencode, and opencode-go: passthrough-gemini
  • amazon-bedrock and anthropic-vertex: anthropic-by-model
  • minimax: hybrid-anthropic-openai
  • moonshot, ollama, xai, and zai: openai-compatible
Available stream families today:Real bundled examples:
  • google and google-gemini-cli: google-thinking
  • kilocode: kilocode-thinking
  • moonshot: moonshot-thinking
  • minimax and minimax-portal: minimax-fast-mode
  • openai and openai-codex: openai-responses-defaults
  • openrouter: openrouter-thinking
  • zai: 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:
  • ProviderReplayFamily
  • buildProviderReplayFamilyHooks(...)
  • shared replay builders such as buildOpenAICompatibleReplayPolicy(...), buildAnthropicReplayPolicyForModel(...), buildGoogleGeminiReplayPolicy(...), and buildHybridAnthropicOrOpenAIReplayPolicy(...)
  • Gemini replay helpers such as sanitizeGoogleGeminiReplayHistory(...) and resolveTaggedReasoningOutputMode()
  • endpoint/model helpers such as resolveProviderEndpoint(...), normalizeProviderId(...), normalizeGooglePreviewModelId(...), and normalizeNativeXaiModelId(...)
velaclaw/plugin-sdk/provider-stream exposes both the family builder and the public wrapper helpers those families reuse. Common public exports include:
  • ProviderStreamFamily
  • buildProviderStreamFamilyHooks(...)
  • composeProviderStreamWrappers(...)
  • shared OpenAI/Codex wrappers such as createOpenAIAttributionHeadersWrapper(...), createOpenAIFastModeWrapper(...), createOpenAIServiceTierWrapper(...), createOpenAIResponsesContextManagementWrapper(...), and createCodexNativeWebSearchWrapper(...)
  • shared proxy/provider wrappers such as createOpenRouterWrapper(...), createToolStreamWrapper(...), and createMinimaxFastModeWrapper(...)
Some stream helpers stay provider-local on purpose. Current bundled example: @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:
  • ProviderToolCompatFamily documents the shared family inventory today.
  • buildProviderToolCompatFamilyHooks("gemini") wires Gemini schema cleanup + diagnostics for providers that need Gemini-safe tool schemas.
  • normalizeGeminiToolSchemas(...) and inspectGeminiToolSchemas(...) are the underlying public Gemini schema helpers.
  • resolveXaiModelCompatPatch() returns the bundled xAI compat patch: toolSchemaProfile: "xai", unsupported schema keywords, native web_search support, and HTML-entity tool-call argument decoding.
  • applyXaiModelCompat(model) applies that same xAI compat patch to a resolved model before it reaches the runner.
Real bundled example: the xAI plugin uses 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.ts exports provider builders, default-model helpers, and realtime provider builders
  • @velaclaw/openrouter-provider: api.ts exports the provider builder plus onboarding/config helpers
For providers that need a token exchange before each inference call:
Velaclaw calls hooks in this order. Most providers only use 2-3:Runtime fallback notes:
  • normalizeConfig checks 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.
  • resolveConfigApiKey uses the provider hook when exposed. The bundled amazon-bedrock path 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 | xhigh reasoning support | | 34 | resolveDefaultThinkingLevel | Default /think policy | | 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:
    • resolveSystemPromptContribution lets a provider inject cache-aware system-prompt guidance for a model family. Prefer it over before_prompt_build when the behavior belongs to one provider/model family and should preserve the stable/dynamic cache split.
    For detailed descriptions and real-world examples, see Internals: Provider Runtime Hooks.
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.
6

Test

src/provider.test.ts

Publish to ClawHub

Provider plugins publish the same way as any other external code plugin:
Do not use the legacy skill-only publish alias here; plugin packages should use clawhub package publish.

File structure

Catalog order reference

catalog.order controls when your catalog merges relative to built-in providers:

Next steps