OpenClaw 开发系列:第3篇-Provider 插件 — 接入 AI 模型与服务

my-provider/my-model-large       # 使用你注册的 Provider 和模型openai/gpt-4o                    # 使用 OpenAI 官方插件的 GPT-4oanthropic/claude-sonnet-4-20250514 # 使用 Anthropic 官方插件的 Claude

{  "agents": {    "defaults": {      "model": "my-provider/my-model-large"    }  }}

{  "id": "my-provider",  "providerAuthChoices": [    {      "provider": "my-provider",      "method": "api-key",      "choiceId": "my-provider-api-key",      "choiceLabel": "My Provider API Key",      "optionKey": "myProviderApiKey",      "cliFlag": "--my-provider-api-key"    }  ],  "uiHints": {    "myProviderApiKey": {      "label": "API Key",      "placeholder": "mpk-...",      "sensitive": true    }  }}

{  "plugins": {    "entries": {      "my-provider": {        "config": {          "apiKey": "your-api-key-here"        }      }    }  }}

{  "contracts": {    "providers": ["my-provider"]  }}

api.registerCliBackend({  id: "my-cli-backend",          // 后端 ID，用于模型引用（如 my-cli-backend/fast）  name: "My CLI Backend",        // 显示名称  command: "my-cli",             // CLI 可执行文件名（必须在系统 PATH 中可用）  args: ["--model", "$MODEL"],   // 参数模板，$MODEL 占位符会在运行时被替换为实际模型名  modelMapping: {                // 将 OpenClaw 的模型 ID 映射为 CLI 工具接受的模型参数    "my-cli/fast": "fast",       // 用户引用 my-cli/fast 时，传给 CLI 的参数是 fast    "my-cli/quality": "quality",  },  normalizeConfig(config) {    // 可选的配置规范化函数    // 用于兼容旧版本的配置格式，避免用户升级时需要手动改配置    if (config.legacyFlag) {      config.newFlag = config.legacyFlag;      delete config.legacyFlag;    }    return config;  },});

claude-cli/opuscodex-cli/gpt-4my-cli/quality

api.registerSpeechProvider({  id: "my-speech",  name: "My Speech Provider",  // 文本转语音（TTS）：将 Agent 的文字回复转为语音输出  async synthesize(text, options) {    // text: 要转换的文本    // options: 语速、音色等可选参数    // 返回：音频流（Buffer）或音频文件的 URL  },  // 语音转文本（STT）：将用户的语音输入转为文字  async transcribe(audioBuffer, options) {    // audioBuffer: 音频数据    // options: 语言、采样率等可选参数    // 返回：识别出的文本字符串  },});

api.registerMediaUnderstandingProvider({  id: "my-media-understanding",  name: "My Media Understanding",  async understand(mediaInput) {    // mediaInput 可以是图片、音频或视频    // mediaInput.type 指示媒体类型："image" | "audio" | "video"    // mediaInput.url 或 mediaInput.buffer 提供媒体数据    // 返回：文本描述字符串  },});

api.registerImageGenerationProvider({  id: "my-image-gen",  name: "My Image Generator",  async generate(params) {    // params 包含 prompt（生成提示词）、size（图片尺寸）、style（风格）等    // 返回：生成的图像 URL 或 base64 编码的图像数据  },});

api.registerWebSearchProvider({  id: "my-search",  name: "My Web Search",  async search(query, options) {    // query: 搜索关键词    // options: 可选参数（如 limit、language 等）    // 返回：搜索结果数组，每条结果包含 title、url、snippet    return [      { title: "...", url: "...", snippet: "..." },      // ...    ];  },});

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";export default definePluginEntry({  id: "unified-ai",  name: "Unified AI Provider",  version: "1.0.0",  register(api) {    const apiKey = (api.pluginConfig as { apiKey?: string })?.apiKey;    // 注册 LLM Provider    api.registerProvider({      id: "unified-ai",      name: "Unified AI",      models: [        {          id: "ua-pro",          name: "Unified AI Pro",          contextWindow: 200000,          supportsVision: true,          supportsStreaming: true,          supportsToolUse: true,        },      ],      async createCompletion(params) {        // 实现 LLM 调用逻辑      },    });    // 注册图像生成    api.registerImageGenerationProvider({      id: "unified-ai",      name: "Unified AI Image",      async generate(params) {        // 实现图像生成逻辑      },    });    // 注册网络搜索    api.registerWebSearchProvider({      id: "unified-ai",      name: "Unified AI Search",      async search(query, options) {        // 实现搜索逻辑      },    });    // 在清单中声明所有能力    // contracts 字段在 openclaw.plugin.json 中声明  },});

{  "id": "unified-ai",  "providerAuthChoices": [    {      "provider": "unified-ai",      "method": "api-key",      "choiceId": "unified-ai-key",      "choiceLabel": "Unified AI API Key",      "optionKey": "apiKey",      "cliFlag": "--unified-api-key"    }  ],  "contracts": {    "providers": ["unified-ai"],    "imageGenerationProviders": ["unified-ai"],    "webSearchProviders": ["unified-ai"]  }}

api.registerCliBackend({  id: "my-backend",  normalizeConfig(config) {    // 旧版使用 modelSize 字符串，新版使用 model 枚举    if (typeof config.modelSize === "string") {      const mapping: Record<string, string> = {        fast: "ua-small",        quality: "ua-pro",      };      config.model = mapping[config.modelSize] ?? config.modelSize;      delete config.modelSize;    }    return config;  },});