Provider hook wiring

Wire individual provider hooks when a family builder does not cover the behavior. Part of the Building provider plugins guide; start with Provider hook families for the shared builders.

Hook examples

Token exchange
Custom headers
Native transport identity
Usage and billing

For providers that need a token exchange before each inference call:

prepareRuntimeAuth: async (ctx) => {
  const exchanged = await exchangeToken(ctx.apiKey);
  return {
    apiKey: exchanged.token,
    baseUrl: exchanged.baseUrl,
    expiresAt: exchanged.expiresAt,
  };
},

For providers that need custom request headers or body modifications:

// wrapStreamFn returns a StreamFn derived from ctx.streamFn
wrapStreamFn: (ctx) => {
  if (!ctx.streamFn) return undefined;
  const inner = ctx.streamFn;
  return (model, context, options) =>
    inner(model, context, {
      ...options,
      headers: {
        ...options?.headers,
        "X-Acme-Version": "2",
      },
    });
},

Existing wrappers may still pass the deprecated maxRetries stream option, including 0. Built-in text transports ignore it: the embedded runner owns retry budgeting, and SDK-internal retries stay disabled. New wrappers should omit the option. This shipped source contract is retained until a future Plugin SDK major release and a published-plugin reader sweep confirm removal is safe; it does not change image-generation or native-runtime retry policy.

For providers that need native request/session headers or metadata on generic HTTP or WebSocket transports:

resolveTransportTurnState: (ctx) => ({
  headers: {
    "x-request-id": ctx.turnId,
  },
  metadata: {
    session_id: ctx.sessionId ?? "",
    turn_id: ctx.turnId,
  },
  websocket: {
    headers: {
      "x-session-id": ctx.sessionId ?? "",
    },
    degradeCooldownMs: 60_000,
  },
}),

The older resolveWebSocketSessionPolicy hook remains supported but is deprecated. Move its fields under resolveTransportTurnState.websocket; fields from the new hook take precedence during migration.

For providers that expose usage/billing data:

resolveUsageAuth: async (ctx) => {
  const auth = await ctx.resolveOAuthToken();
  return auth ? { token: auth.token } : null;
},
fetchUsageSnapshot: async (ctx) => {
  return await fetchAcmeUsage(ctx.token, ctx.timeoutMs);
},

resolveUsageAuth has three outcomes. Return { token, accountId?, subscriptionType?, rateLimitTier? } when the provider has a usage/billing credential (the optional fields carry non-secret plan metadata from the resolved profile into fetchUsageSnapshot). Return { handled: true } only when the provider has definitively handled usage auth but has no usable usage token, and OpenClaw must skip generic API-key/OAuth fallback. Return null or undefined when the provider did not handle the request and OpenClaw should continue with generic fallback.Declare the provider id in contracts.usageProviders. When that manifest contract and both hooks are present, OpenClaw automatically includes the provider in usage collection without loading unrelated provider plugins. No core allowlist update is required. fetchUsageSnapshot returns the shared provider-neutral shape:

plan: provider-reported subscription or key label
windows: resettable quota windows as used percentages
billing: typed balance, spend, or budget entries; unit can be an ISO currency or a provider unit such as credits
summary: compact provider-specific context that does not fit those structured fields

Keep currency semantics exact. A provider credit is not USD unless the upstream contract says so. A plugin that implements only fetchUsageSnapshot remains available for explicit/synthetic callers but is not auto-discovered, because OpenClaw cannot resolve its usage credential.

Set supportsSystemPromptCacheBoundary: true on a provider registration only when its createStreamFn transport understands the stable/dynamic system-prompt boundary. Use splitSystemPromptCacheBoundary from openclaw/plugin-sdk/provider-transport-runtime to checkpoint the stable prefix separately, and consume the marker before sending any payload. Use stripSystemPromptCacheBoundary when caching is disabled. By default, OpenClaw strips the marker before invoking a custom transport. For custom createStreamFn transports that accumulate JSON tool arguments, use createToolArgumentPreviewSchedule() from openclaw/plugin-sdk/llm. Create one schedule per tool call and pass the accumulated raw string’s length to it before calling parseStreamingJson. The returned function admits preview refreshes at geometric growth checkpoints, so intermediate arguments snapshots can remain unchanged while raw fragments arrive. Keep emitting every raw delta and validate the complete arguments at the transport’s terminal boundary, even when the last preview was not refreshed.

Common provider hooks

OpenClaw calls hooks in roughly this order for model/provider plugins. Most providers only use 2-3. This is not the full ProviderPlugin contract - see Internals: Provider Runtime Hooks for the complete, currently-accurate hook list and fallback notes. Compatibility-only provider fields that OpenClaw no longer calls, such as ProviderPlugin.capabilities and suppressBuiltInModel, are not listed here.Keep resolveSyntheticAuth synchronous and bounded. External process/network login checks belong in prepareSyntheticAuth, which receives the captured config, environment, and cancellation signal and returns a synthetic auth result or no result. OpenClaw retains completed availability within that preparation generation. Read-only workers receive the final provider-ref outcome (including unavailable), preserving alias precedence without rerunning external checks. Cancelled preparation must reject after cleanup, not report a missing login.

Hook	When to use
`catalog`	Model catalog or base URL defaults
`applyConfigDefaults`	Provider-owned global defaults during config materialization
`normalizeModelId`	Legacy/preview model-id alias cleanup before lookup
`normalizeTransport`	Provider-family `api` / `baseUrl` cleanup before generic model assembly
`normalizeConfig`	Normalize `models.providers.<id>` config
`applyNativeStreamingUsageCompat`	Native streaming-usage compat rewrites for config providers
`resolveConfigApiKey`	Provider-owned env-marker auth resolution
`resolveSyntheticAuth`	Local/self-hosted or config-backed synthetic auth
`prepareSyntheticAuth`	Asynchronously verify external auth before synchronous availability reads
`resolveExternalAuthProfiles`	Overlay provider-owned external auth profiles for CLI/app-managed credentials
`shouldDeferSyntheticProfileAuth`	Lower synthetic stored-profile placeholders behind env/config auth
`resolveDynamicModel`	Accept arbitrary upstream model IDs
`prepareDynamicModel`	Return an asynchronously discovered model, or warm reusable metadata before sync resolution
`normalizeResolvedModel`	Transport rewrites before the runner
`normalizeToolSchemas`	Provider-owned tool-schema cleanup before registration
`inspectToolSchemas`	Provider-owned tool-schema diagnostics
`resolveReasoningOutputMode`	Tagged vs native reasoning-output contract
`prepareExtraParams`	Default request params
`createStreamFn`	Fully custom StreamFn transport
`wrapStreamFn`	Custom headers/body wrappers on the normal stream path
`reconcileLocalService`	Cheap, idempotent managed-service repair after health and before every request
`resolveTransportTurnState`	Native per-turn headers/metadata and WebSocket headers/cool-down
`resolveWebSocketSessionPolicy`	Deprecated WebSocket compatibility hook; use `resolveTransportTurnState`
`formatApiKey`	Custom runtime token shape
`loginOAuth`	Callback-based OAuth login for the session SDK `AuthStorage` API
`refreshOAuth`	Custom OAuth refresh
`buildAuthDoctorHint`	Auth repair guidance
`matchesContextOverflowError`	Provider-owned overflow detection
`classifyFailoverReason`	Provider-owned rate-limit/overload classification
`isCacheTtlEligible`	Prompt cache TTL gating
`buildMissingAuthMessage`	Custom missing-auth hint
`augmentModelCatalog`	Synthetic forward-compat rows (deprecated - prefer `registerModelCatalogProvider`)
`resolveThinkingProfile`	Model-specific `/think` option set
`isBinaryThinking`	Binary thinking on/off compatibility (deprecated - prefer `resolveThinkingProfile`)
`supportsXHighThinking`	`xhigh` reasoning support compatibility (deprecated - prefer `resolveThinkingProfile`)
`resolveDefaultThinkingLevel`	Default `/think` policy compatibility (deprecated - prefer `resolveThinkingProfile`)
`isModernModelRef`	Live/smoke model matching
`prepareRuntimeAuth`	Token exchange before inference
`resolveUsageAuth`	Custom usage credential parsing
`fetchUsageSnapshot`	Custom usage endpoint
`createEmbeddingProvider`	Provider-owned embedding adapter for memory/search
`buildReplayPolicy`	Custom transcript replay/compaction policy
`sanitizeReplayHistory`	Provider-specific replay rewrites after generic cleanup
`validateReplayTurns`	Strict replay-turn validation before the embedded runner
`onModelSelected`	Post-selection callback (e.g. telemetry)

reconcileLocalService is called only for a configured local service, including a healthy process reused by a restarted Gateway. Honor its abort signal and reject when reconciliation fails; OpenClaw blocks the provider request and releases the request lease.Runtime fallback notes:

Error classification uses the prepared provider owner or already loaded provider hooks. matchesContextOverflowError and classifyFailoverReason never trigger plugin discovery while handling an error; provider preparation owns loading those hooks.
normalizeConfig resolves one owning plugin per provider id (bundled providers first, then the matched runtime plugin) and calls only that hook - there is no scan across other providers. Google’s own normalizeConfig hook is what normalizes google / google-vertex / google-antigravity config entries; it is not a separate core fallback.
resolveConfigApiKey uses the provider hook when exposed. Amazon Bedrock keeps AWS env-marker resolution in its provider plugin; runtime auth itself still uses the AWS SDK default chain when configured with auth: "aws-sdk".
resolveThinkingProfile(ctx) receives the selected provider, modelId, optional merged reasoning catalog hint, and optional merged model compat facts. Use compat only to select the provider’s thinking UI/profile.
normalizeResolvedModel(ctx) can set compactionThinkingDefault on the returned ProviderRuntimeModel when the provider has a preferred embedded-summary effort. This is prepared runtime metadata, not an operator setting or catalog field. Explicit agents.defaults.compaction.thinkingLevel takes precedence; otherwise the host uses this preference and then low. The chosen effort is still clamped to the actual compaction candidate.
resolveSystemPromptContribution lets a provider inject cache-aware system-prompt guidance for a model family. Prefer it over the legacy plugin-wide before_prompt_build hook when the behavior belongs to one provider/model family and should preserve the stable/dynamic cache split.

Bundled and trusted official provider policies can use resolveEffortThinkingProfile(compat?.supportedReasoningEfforts) from the private openclaw/plugin-sdk/provider-thinking-runtime helper. It accepts exact off, minimal, low, medium, high, xhigh, and max values, maps none to off, and prepends off while preserving the first occurrence of each remaining level. The default preference is medium, high, low, then off. Missing, null, or empty metadata returns undefined; a nonempty list without supported values returns an off-only profile. Keep model-specific overrides and API fallbacks in the provider policy.Bundled and trusted official plugins can also export resolveToolSearchMode(ctx) from their lightweight provider-policy-api artifact. The context contains the final provider, modelId, api, and optional baseUrl; its type is exported from openclaw/plugin-sdk/provider-model-types. Return "tools" to prefer structured Tool Search, false to veto the managed-local-service default, or undefined to leave that decision to the host. The host records the result on the resolved runtime model rather than writing configuration. Explicit tools.toolSearch settings take precedence. This hook changes schema exposure, not tool permissions or availability.resolveFastModeSupport(ctx) can be exported from the same policy artifact and registered on the provider. Return false only for a confirmed no-op Fast choice, true for an applicable local request mapping, or undefined when facts are missing. ProviderFastModePolicyContext carries the selected model, route, auth mode, runtime, request parameters and transport policy; credentials are not included. Share the policy with request construction. The host publishes only supportsFastMode, preserving unknown behavior and clearing saved preferences. This describes local applicability, not upstream entitlement or fulfillment, and does not reject /fast commands.

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Provider hook wiring

Hook examples

​Hook examples

Hook examples