Skip to main content

​
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

SubpathUse it for
plugin-sdk/provider-authAPI key, OAuth, auth-profile, and PKCE helpers
plugin-sdk/provider-onboardConfig patches after setup/auth
plugin-sdk/provider-modelsModel-definition and catalog helpers
plugin-sdk/provider-setupShared local/self-hosted setup flows
plugin-sdk/self-hosted-provider-setupOpenAI-compatible self-hosted providers
plugin-sdk/provider-usageUsage 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.