Provider Adapters

Contents

Overview

flowchart LR
  subgraph Agent["Agent Engine"]
    Req["Chat Request"]
    Stream["Stream Consumer"]
  end
  subgraph Provider["ProviderPlugin"]
    Auth["Auth Resolution"]
    Model["Model Catalog"]
    Transport["Transport Normalization"]
    StreamFn["Stream Function"]
  end
  subgraph Vendor["Vendor API"]
    API["HTTP Endpoint"]
  end
  Req --> Auth
  Auth --> Model
  Model --> Transport
  Transport --> StreamFn
  StreamFn --> API
  API --> Stream

When the agent engine needs to send a chat request, it resolves the provider from the model ID, runs through the provider’s auth chain, normalizes the transport (base URL, API key headers), creates a streaming function, and pipes the response back to the conversation.

Decision Points

How It Works

The ProviderPlugin Interface

The ProviderPlugin type defines 25+ optional methods. Only id, label, and auth are required — everything else has sensible defaults:

type ProviderPlugin = {
  // Identity
  id: string;                    // Unique provider ID (e.g., "openai")
  label: string;                 // Display name (e.g., "OpenAI")
  docsPath?: string;             // Path to documentation
  envVars?: string[];            // Expected env vars (e.g., ["OPENAI_API_KEY"])

  // Authentication
  auth: ProviderAuthMethod[];    // Ordered list of auth strategies

  // Model Discovery
  catalog?: ProviderPluginCatalog;
  resolveDynamicModel?: (ctx) => ProviderRuntimeModel | null;
  augmentModelCatalog?: (ctx) => ModelCatalogEntry[];

  // Transport
  normalizeTransport?: (ctx) => { api?: string; baseUrl?: string } | null;
  normalizeResolvedModel?: (ctx) => ProviderRuntimeModel | null;
  normalizeConfig?: (ctx) => ModelProviderConfig | null;

  // Streaming
  createStreamFn?: (ctx) => StreamFn | null;
  wrapStreamFn?: (ctx) => StreamFn | null;

  // Capabilities
  capabilities?: Partial<ProviderCapabilities>;
  supportsXHighThinking?: (ctx) => boolean;
  resolveDefaultThinkingLevel?: (ctx) => ThinkingLevel | null;

  // Usage & Billing
  resolveUsageAuth?: (ctx) => Promise<ProviderResolvedUsageAuth>;
  fetchUsageSnapshot?: (ctx) => Promise<ProviderUsageSnapshot>;

  // Error Messages
  buildMissingAuthMessage?: (ctx) => string | null;
  buildUnknownModelHint?: (ctx) => string | null;
};

Authentication Chain

Each provider declares one or more ProviderAuthMethod objects. The auth resolver tries them in order, returning the first that succeeds (API key present, OAuth token valid, etc.):

// From extensions/openai/openai-provider.ts
auth: [
  createProviderApiKeyAuthMethod({
    providerId: "openai",
    methodId: "api-key",
    label: "OpenAI API key",
    hint: "Direct OpenAI API key",
    optionKey: "openaiApiKey",
    flagName: "--openai-api-key",
    envVar: "OPENAI_API_KEY",
    promptMessage: "Enter OpenAI API key",
    defaultModel: "gpt-5.4",
    expectedProviders: ["openai"],
    applyConfig: (cfg) => applyOpenAIConfig(cfg),
    wizard: {
      title: "OpenAI Setup",
      steps: [/* interactive setup steps */],
    },
  }),
],

Model Resolution Pipeline

When a user requests a model like openai/gpt-5.4, the resolution pipeline proceeds through these stages:

flowchart TD
  Input["User requests model: openai/gpt-5.4"]
  Catalog["Check static catalog"]
  Dynamic["resolveDynamicModel()"]
  Normalize["normalizeResolvedModel()"]
  Compat["contributeResolvedModelCompat()"]
  Transport["normalizeTransport()"]
  Ready["ProviderRuntimeModel ready"]

  Input --> Catalog
  Catalog -->|Found| Normalize
  Catalog -->|Not found| Dynamic
  Dynamic -->|Resolved| Normalize
  Dynamic -->|null| Error["Unknown model error"]
  Normalize --> Compat
  Compat --> Transport
  Transport --> Ready

Stream Processing

The streaming pipeline supports two extension points: createStreamFn (replace the entire stream) and wrapStreamFn (wrap the default stream with middleware):

// From extensions/openai/openai-provider.ts
wrapStreamFn: (ctx) => {
  return createOpenAIAttributionHeadersWrapper({
    innerStream: ctx.defaultStreamFn,
    modelId: ctx.model.id,
    providerFamily: "openai",
  });
},

Request Lifecycle

sequenceDiagram
  participant Agent as Agent Engine
  participant Resolver as Provider Resolver
  participant Auth as Auth Chain
  participant Provider as ProviderPlugin
  participant API as Vendor API

  Agent->>Resolver: resolveProvider("openai/gpt-5.4")
  Resolver->>Provider: resolveDynamicModel()
  Provider-->>Resolver: ProviderRuntimeModel
  Resolver->>Auth: prepareRuntimeAuth()
  Auth-->>Resolver: API key + headers
  Resolver->>Provider: normalizeTransport()
  Provider-->>Resolver: { baseUrl, api }
  Resolver->>Provider: wrapStreamFn()
  Provider-->>Resolver: Wrapped StreamFn
  Agent->>API: POST /v1/chat/completions (streaming)
  API-->>Agent: SSE token stream

The entire lifecycle from model selection to first token is typically under 100ms of local processing. Network latency to the vendor API dominates the total time-to-first-token.

Annotated Code Walkthrough

Walk through building a complete provider extension from scratch:

// extensions/my-provider/my-provider.ts
import { createProviderApiKeyAuthMethod } from "openclaw/plugin-sdk/core";
import type { ProviderPlugin } from "openclaw/plugin-sdk/core";

const PROVIDER_ID = "my-provider";

export function buildMyProvider(): ProviderPlugin {
  return {
    id: PROVIDER_ID,
    label: "My Provider",
    docsPath: "/providers/my-provider",
    envVars: ["MY_PROVIDER_API_KEY"],

    auth: [
      createProviderApiKeyAuthMethod({
        providerId: PROVIDER_ID,
        methodId: "api-key",
        label: "My Provider API key",
        envVar: "MY_PROVIDER_API_KEY",
        flagName: "--my-provider-api-key",
        defaultModel: "my-model-v1",
        expectedProviders: [PROVIDER_ID],
        applyConfig: (cfg) => ({
          ...cfg,
          baseUrl: "https://api.myprovider.com/v1",
        }),
      }),
    ],
  };
}

// Continue in my-provider.ts
export function buildMyProvider(): ProviderPlugin {
  return {
    // ... id, label, auth from Step 1 ...

    catalog: {
      models: [
        { id: "my-model-v1", label: "My Model v1", contextWindow: 128000 },
        { id: "my-model-v2", label: "My Model v2", contextWindow: 256000 },
      ],
    },

    resolveDynamicModel: (ctx) => {
      // Accept any model prefixed with "my-model-"
      if (ctx.modelId.startsWith("my-model-")) {
        return {
          id: ctx.modelId,
          label: ctx.modelId,
          provider: PROVIDER_ID,
        };
      }
      return null;
    },

    normalizeTransport: ({ provider, api, baseUrl }) => ({
      api: api ?? "openai",  // Use OpenAI-compatible API format
      baseUrl: baseUrl ?? "https://api.myprovider.com/v1",
    }),

    capabilities: { providerFamily: "openai" },
  };
}

// extensions/my-provider/index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { buildMyProvider } from "./my-provider.js";

export default definePluginEntry({
  id: "my-provider",
  name: "My Provider",
  description: "Custom LLM provider integration",
  register(api) {
    api.registerProvider(buildMyProvider());
  },
});

Edge Cases & Error Handling

Provider Capabilities Reference

Configuration

Related Topics

See also:

• Extensions overview — all extension categories and the full ecosystem
• Extension Contract — the shared registration interface all extensions use
• Channel Extensions — the parallel adapter pattern for messaging channels

Directory Map

extensions/
├── openai/
│   ├── index.ts                   ← Entry: registers provider, speech, image, media, CLI
│   ├── openai-provider.ts         ← ProviderPlugin: auth, catalog, transport, streaming
│   ├── speech-provider.ts         ← SpeechProviderPlugin: TTS via OpenAI
│   ├── image-generation-provider.ts ← ImageGenerationProviderPlugin: DALL-E
│   ├── media-understanding-provider.ts ← Media analysis (vision, audio)
│   └── cli-backend.ts             ← CLI interactive backend (Codex)
├── anthropic/
│   ├── index.ts                   ← Entry: registers Anthropic provider
│   └── anthropic-provider.ts      ← ProviderPlugin: Claude models, extended thinking
├── google/
│   ├── index.ts                   ← Entry: registers Google provider
│   └── google-provider.ts         ← ProviderPlugin: Gemini models, multimodal
├── ollama/
│   ├── index.ts                   ← Entry: registers Ollama provider
│   └── ollama-provider.ts         ← ProviderPlugin: local server, any GGUF model
├── groq/
│   ├── index.ts                   ← Entry: registers Groq provider
│   └── groq-provider.ts           ← ProviderPlugin: ultra-fast inference
└── (30+ more provider extensions...)