openclaw/docs/plugins/sdk-provider-plugins.md

title, sidebarTitle, summary, read_when

title	sidebarTitle	summary	read_when
Provider Plugin SDK	Provider Plugins	Contracts and helper subpaths for model-provider plugins, including auth, onboarding, catalogs, and usage	You are building a model provider plugin You need auth helpers for API keys or OAuth You need onboarding config patches or catalog helpers

Provider Plugin SDK

Provider plugins use definePluginEntry(...) and call api.registerProvider(...) with a ProviderPlugin definition.

Minimal provider entry

import { definePluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "example-provider",
  name: "Example Provider",
  description: "Example text-inference provider plugin",
  register(api: OpenClawPluginApi) {
    api.registerProvider({
      id: "example",
      label: "Example",
      auth: [],
    });
  },
});

Provider subpaths

Subpath	Use it for
plugin-sdk/provider-auth	API key, OAuth, auth-profile, and PKCE helpers
plugin-sdk/provider-onboard	Config patches after setup/auth
plugin-sdk/provider-models	Model-definition and catalog helpers
plugin-sdk/provider-setup	Shared local/self-hosted setup flows
plugin-sdk/self-hosted-provider-setup	OpenAI-compatible self-hosted providers
plugin-sdk/provider-usage	Usage snapshot fetch helpers

API key auth

createProviderApiKeyAuthMethod(...) is the standard helper for API-key providers:

import { createProviderApiKeyAuthMethod } from "openclaw/plugin-sdk/provider-auth";
import { applyProviderConfigWithDefaultModel } from "openclaw/plugin-sdk/provider-onboard";

const auth = [
  createProviderApiKeyAuthMethod({
    providerId: "example",
    methodId: "api-key",
    label: "Example API key",
    optionKey: "exampleApiKey",
    flagName: "--example-api-key",
    envVar: "EXAMPLE_API_KEY",
    promptMessage: "Enter Example API key",
    profileId: "example:default",
    defaultModel: "example/default",
    applyConfig: (cfg) =>
      applyProviderConfigWithDefaultModel(cfg, "example", {
        id: "default",
        name: "Default",
      }),
  }),
];

OAuth auth

buildOauthProviderAuthResult(...) builds the standard auth result payload for OAuth-style providers:

import { buildOauthProviderAuthResult } from "openclaw/plugin-sdk/provider-auth";

async function runOAuthLogin() {
  return buildOauthProviderAuthResult({
    providerId: "example-portal",
    defaultModel: "example-portal/default",
    access: "access-token",
    refresh: "refresh-token",
    email: "user@example.com",
    notes: ["Tokens auto-refresh when the provider supports refresh tokens."],
  });
}

Catalog and discovery hooks

Provider plugins usually implement either catalog or the legacy discovery alias. catalog is preferred.

api.registerProvider({
  id: "example",
  label: "Example",
  auth,
  catalog: {
    order: "simple",
    async run(ctx) {
      const apiKey = ctx.resolveProviderApiKey("example").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          api: "openai",
          baseUrl: "https://api.example.com/v1",
          apiKey,
          models: [
            {
              id: "default",
              name: "Default",
              input: ["text"],
            },
          ],
        },
      };
    },
  },
});

Onboarding config patches

plugin-sdk/provider-onboard keeps post-auth config writes consistent.

Common helpers:

• applyProviderConfigWithDefaultModel(...)
• applyProviderConfigWithDefaultModels(...)
• applyProviderConfigWithModelCatalog(...)
• applyAgentDefaultModelPrimary(...)
• ensureModelAllowlistEntry(...)

Self-hosted and local model setup

Use plugin-sdk/provider-setup or plugin-sdk/self-hosted-provider-setup when the provider is an OpenAI-style backend, Ollama, SGLang, or vLLM.

Examples from the shared setup surfaces:

• promptAndConfigureOllama(...)
• configureOllamaNonInteractive(...)
• promptAndConfigureOpenAICompatibleSelfHostedProvider(...)
• discoverOpenAICompatibleSelfHostedProvider(...)

These helpers keep setup behavior aligned with built-in provider flows.

Usage snapshots

If the provider owns quota or usage endpoints, use resolveUsageAuth(...) and fetchUsageSnapshot(...).

plugin-sdk/provider-usage includes shared fetch helpers such as:

• fetchClaudeUsage(...)
• fetchCodexUsage(...)
• fetchGeminiUsage(...)
• fetchMinimaxUsage(...)
• fetchZaiUsage(...)

Provider guidance

• Keep auth logic in provider-auth.
• Keep config mutation in provider-onboard.
• Keep catalog/model helpers in provider-models.
• Keep usage logic in provider-usage.
• Use catalog, not discovery, in new plugins.

Related

• Plugin SDK Overview
• Plugin Entry Points
• Plugin Setup
• Plugin Internals