Plugin SDK Provider 插件构建

概述

Provider 插件为 OpenClaw 添加模型提供商（LLM）。一个最小的文本 Provider 需要 id、label、auth 和 catalog。Provider 插件还可以注册语音、实时转录、实时语音、媒体理解、图像/视频/音乐生成、Web 抓取和 Web 搜索能力（混合能力插件）。

核心 API

注册 Provider

api.registerProvider({
  id: "acme-ai",
  label: "Acme AI",
  docsPath: "/providers/acme-ai",
  envVars: ["ACME_AI_API_KEY"],
  auth: [createProviderApiKeyAuthMethod({ ... })],
  catalog: {
    order: "simple",  // simple | profile | paired | late
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("acme-ai").apiKey;
      if (!apiKey) return null;
      return {
        provider: {
          baseUrl: "https://api.acme-ai.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "acme-large", name: "Acme Large", reasoning: true, ... }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({ id: ctx.modelId, provider: "acme-ai", ... }),
});

完整 Provider 钩子（按调用顺序）

#	钩子	用途
1	`catalog`	模型目录或基础 URL 默认值
10	`resolveDynamicModel`	接受任意上游模型 ID
11	`prepareDynamicModel`	解析前的异步元数据获取
18	`createStreamFn`	完全自定义 StreamFn 传输
19	`wrapStreamFn`	自定义请求头/正文包装器
25	`matchesContextOverflowError`	Provider 拥有的溢出检测
26	`classifyFailoverReason`	Provider 拥有的速率限制/过载分类
30	`resolveThinkingProfile`	模型特定的 `/think` 选项集
35	`prepareRuntimeAuth`	推理前的令牌交换
38	`createEmbeddingProvider`	Provider 拥有的嵌入适配器
39	`buildReplayPolicy`	自定义转录重放/压缩策略

共享家族构建器

import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared";
import { buildProviderStreamFamilyHooks } from "openclaw/plugin-sdk/provider-stream";
import { buildProviderToolCompatFamilyHooks } from "openclaw/plugin-sdk/provider-tools";
 
const GOOGLE_FAMILY_HOOKS = {
  ...buildProviderReplayFamilyHooks({ family: "google-gemini" }),
  ...buildProviderStreamFamilyHooks("google-thinking"),
  ...buildProviderToolCompatFamilyHooks("gemini"),
};

可用 Replay 家族： openai-compatible、anthropic-by-model、google-gemini、passthrough-gemini、hybrid-anthropic-openai

额外能力注册

api.registerSpeechProvider({ id, label, isConfigured, synthesize });
api.registerRealtimeTranscriptionProvider({ id, label, isConfigured, createSession });
api.registerRealtimeVoiceProvider({ id, label, capabilities, isConfigured, createBridge });
api.registerMediaUnderstandingProvider({ id, capabilities, describeImage, transcribeAudio });
api.registerImageGenerationProvider({ id, label, generate });
api.registerVideoGenerationProvider({ id, label, capabilities, generateVideo });
api.registerWebFetchProvider({ id, label, createTool });
api.registerWebSearchProvider({ id, label, search });

使用示例

// 单 Provider 简化入口
import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry";
 
export default defineSingleProviderPluginEntry({
  id: "acme-ai",
  name: "Acme AI",
  description: "Acme AI model provider",
  provider: {
    label: "Acme AI",
    auth: [{ methodId: "api-key", envVar: "ACME_AI_API_KEY", ... }],
    catalog: {
      buildProvider: () => ({ api: "openai-completions", baseUrl: "...", models: [...] }),
      buildStaticProvider: () => ({ api: "openai-completions", baseUrl: "...", models: [...] }),
    },
  },
});

Wiki AI

目录