跳转至

提供商插件

构建一个提供程序插件,以向 OpenClaw 添加一个模型提供程序(LLM):包括模型目录、API 密钥认证和动态模型解析。

Acme AI 是本指南及其子页面中使用的虚构供应商。示例中名为 fetchAcme* 的辅助函数是你自己的供应商 API 调用的占位符,而不是导出的 OpenClaw 函数。

Info

OpenClaw 插件新手?请先阅读入门指南,了解包结构和清单配置。

Tip

提供程序插件会将模型添加到 OpenClaw 的正常推理循环中。如果模型必须通过一个拥有线程、压缩或工具事件的原生 agent 守护进程运行,请将提供程序与 agent 框架 配对,而不是将守护进程协议细节放在核心中。

在登录期间导入现有凭据

认证方法可以声明 credentialImport,其中包含 migrationProviderId、精确的 itemId 以及 credentialKind(api_key、oauth 或 token)。models auth login 会在开始交互式登录之前,向该迁移所有者请求一个仅用于认证的迁移方案。--force、--profile-id 和 --set-default 会跳过导入。--set-default 通过正常登录流程使用该认证方法推荐的模型。

迁移插件在 contracts.migrationProviders 中声明其 ID,并可以从顶层 migration-provider-api.ts 公共产物中导出 buildMigrationProvider()。请保持该入口轻量。内置插件和已启用的已安装插件可以提供它,而无需替换正在运行的插件注册表。被明确禁用或拒绝的迁移所有者不能执行其产物。现有的内置迁移兼容性规则仍然适用。

登录调用方只选择已声明的认证项。其详细信息必须包含匹配的 provider 和 credentialKind。迁移结果还会提供已保存的 profileId。所有者必须尊重取消操作,在持久化之前重新读取所选来源,并拒绝已更改的凭据。登录会传递 configPatchMode: "none",因此导入会保留模型默认设置和限制。存储不可用或匹配的 OAuth 配置不可用时,将继续进行交互式登录。仅匹配账户身份并不会使过期凭据可用。所选导入失败会停止操作,而不是静默启动另一种登录。

回环 OAuth 回调

内置提供程序使用来自 openclaw/plugin-sdk/provider-auth-runtime 的 startProviderOAuthLoopbackCallbackServer,在打开浏览器之前绑定其回调。waitForCallback() 会返回一个 OAuth 错误,或一个经过验证的 code/state 对,其中包含用于提供程序特定字段的 parameters: URLSearchParams。重复的参数仍可供提供程序验证。

默认响应会确认回调并关闭监听器。设置 deferResponse: true,可在调用 complete({ status, body, contentType }) 之前完成令牌交换和身份检查。中止、可选的 timeoutMs 以及浏览器断开连接仍会关闭延迟响应;迟到的 complete() 是空操作。始终在 finally 中调用 close()。调用方的信号和权限检查负责令牌请求和持久化;监听器截止时间不会取消这些工作。

默认情况下,监听器会绑定为重定向主机名解析出的所有回环地址。bindHostname 会添加一个回环主机。改用 bindOnlyHostname 可保留提供程序确切的 Node 绑定主机(localhost、127.0.0.1 或 ::1)。

在登录后处理模型访问

来自 openclaw/plugin-sdk/provider-auth-login-flow-runtime 的 runModelsAuthLoginFlow 的现有使用者必须在凭据保存后处理一个选择。当有效限制可能会隐藏提供程序的模型时,现有的 prompter.select 会收到以下选项:

值 标签 效果
all Show all <Provider> models 将该提供程序的通配符添加到现有策略所有者中。
keep Keep current restrictions 保持限制不变。

渲染提供的消息和选项,并返回所选选项的值。不要假设每次 select 调用都会选择提供程序或认证方法。两种选择都不会激活新的默认模型。当不存在限制或限制已允许整个提供程序时,不会请求选择。

取消或拒绝此保存后的选择不会撤销已保存的凭据。该流程会抛出 ProviderAuthConfigApplyError,它继承自 ProviderCredentialsSavedError;应报告凭据已保存,而不是将其视为凭据交换失败。在选择时取消会保持限制不变。后续应用失败可能导致策略已保存但未在运行中的 Gateway 中激活。请将凭据持久化和模型可见性结果区分开来。

将选择推迟到后续回复

对于聊天按钮,请传递同步的 onModelAccessRequested 回调。它会接收一个 PreparedProviderModelAccess 请求,并替换保存后的 select 调用;它不会应用该选择。请在登录完成之前保留已准备好的请求。使用 createProviderLoginFlowRegistry 和 reserveProviderLoginFlow 仅预留凭据交换。

登录完成后,使用 flows、flowKey、prepared 和 terminalMessage 调用 offerProviderLoginModelAccess。传递其结构化回复。始终在 finally 中使用 releaseProviderLoginFlow({ flows, flowKey, record }) 释放登录。待处理的模型访问问题具有自己的生命周期,并在该释放之后仍可回答;它不会阻塞另一个登录。

将后续命令与 flows、flowKey、agentId、command、runtime、readConfig 和 assertCurrent 一起传递给 answerProviderLoginModelAccess;signal 是可选的。readConfig 必须返回宿主当前的配置。所有者会验证答案,应用选择,并消费该问题。过期或冲突的选择会收到基于当前限制的新问题。使用 cancelProviderLoginFlow({ flows, flowKey }) 取消任一待处理阶段。不要从按钮文本重建通配符写入,也不要为新的登录重用已准备好的请求。

保持托管写入已授权

托管调用方提供 signal 和 assertCurrent,以在副作用之前以及等待的工作之后检查当前登录、发送方权限以及所选 provider/method。仅中止信号或匹配的登录标识符本身并不构成当前授权。beforePersistentEffect 仍然是凭据持久化准备回调。浏览器授权在凭据阶段后结束;后续的模型选择使用当前对话或向导权限。

对于延迟选择,将应答命令的当前权限检查作为 answerProviderLoginModelAccess.assertCurrent 传入。如果提供了其 config 参数,请使用它:它是策略写入方的当前配置。否则读取宿主机的当前配置。原始登录回调不会授权后续命令。让共享所有者报告可见性结果:已保存的策略并不能证明正在运行的 Gateway 已应用该策略。

演练

1. 打包和清单

### 步骤 1:打包和清单 {#step-1-package-and-manifest}
{
  "name": "@myorg/openclaw-acme-ai",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "providers": ["acme-ai"],
    "compat": {
      "pluginApi": ">=2026.3.24-beta.2",
      "minGatewayVersion": "2026.3.24-beta.2"
    },
    "build": {
      "openclawVersion": "2026.3.24-beta.2",
      "pluginSdkVersion": "2026.3.24-beta.2"
    }
  }
}
{
  "id": "acme-ai",
  "name": "Acme AI",
  "description": "Acme AI model provider",
  "providers": ["acme-ai"],
  "modelSupport": {
    "modelPrefixes": ["acme-"]
  },
  "setup": {
    "providers": [
      {
        "id": "acme-ai",
        "envVars": ["ACME_AI_API_KEY"]
      }
    ]
  },
  "providerAuthAliases": {
    "acme-ai-coding": "acme-ai"
  },
  "providerAuthChoices": [
    {
      "provider": "acme-ai",
      "method": "api-key",
      "choiceId": "acme-ai-api-key",
      "choiceLabel": "Acme AI API key",
      "groupId": "acme-ai",
      "groupLabel": "Acme AI",
      "cliFlag": "--acme-ai-api-key",
      "cliOption": "--acme-ai-api-key <key>",
      "cliDescription": "Acme AI API key"
    }
  ],
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

setup.providers[].envVars 让 OpenClaw 无需加载你的插件运行时即可检测凭据。当某个 provider 变体需要复用另一个 provider id 的认证时,添加 providerAuthAliases。modelSupport 是可选的,它让 OpenClaw 在运行时钩子存在之前,从类似 acme-large 的简写模型 id 自动加载你的 provider 插件。package.json 中的 openclaw.compat 和 openclaw.build 是 ClawHub 发布所必需的(openclaw.compat.pluginApi 和 openclaw.build.openclawVersion 是两个必需字段。省略 minGatewayVersion 时,它会回退到 openclaw.install.minHostVersion)。

示例清单中的版本字符串是占位符。请将其固定为你的插件构建和测试所针对的 OpenClaw 版本。

2. 注册 provider

最小文本 provider 需要一个 id、label、auth 和 catalog。catalog 是 provider 拥有的运行时/配置钩子。它可以调用实时供应商 API,并返回 models.providers 条目。

```typescript index.ts import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { createProviderApiKeyAuthMethod } from "openclaw/plugin-sdk/provider-auth";

export default definePluginEntry({ id: "acme-ai", name: "Acme AI", description: "Acme AI model provider", register(api) { api.registerProvider({ id: "acme-ai", label: "Acme AI", docsPath: "/providers/acme-ai", envVars: ["ACME_AI_API_KEY"],

  auth: [
    createProviderApiKeyAuthMethod({
      providerId: "acme-ai",
      methodId: "api-key",
      label: "Acme AI API key",
      hint: "API key from your Acme AI dashboard",
      optionKey: "acmeAiApiKey",
      flagName: "--acme-ai-api-key",
      envVar: "ACME_AI_API_KEY",
      promptMessage: "Enter your Acme AI API key",
      defaultModel: "acme-ai/acme-large",
    }),
  ],

  catalog: {
    order: "simple",
    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,
              input: ["text", "image"],
              cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
              contextWindow: 200000,
              maxTokens: 32768,
            },
            {
              id: "acme-small",
              name: "Acme Small",
              reasoning: false,
              input: ["text"],
              cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
              contextWindow: 128000,
              maxTokens: 8192,
            },
          ],
        },
      };
    },
  },
});

api.registerModelCatalogProvider({
  provider: "acme-ai",
  kinds: ["text"],
  liveCatalog: async (ctx) => {
    const apiKey = ctx.resolveProviderApiKey("acme-ai").apiKey;
    if (!apiKey) return null;
    return [
      {
        kind: "text",
        provider: "acme-ai",
        model: "acme-large",
        label: "Acme Large",
        source: "live",
      },
    ];
  },
});

}, }); `registerModelCatalogProvider` 是用于列表/帮助/选择器 UI 的较新控制平面目录接口,覆盖 `text`、`voice`、`image_generation`、`video_generation` 和 `music_generation` 行。请将供应商端点调用和响应映射保留在插件中。OpenClaw 负责共享行结构、来源标签和帮助渲染。 这是一个可用的提供商。用户现在可以运行 `openclaw onboard --acme-ai-api-key <key>`,并选择 `acme-ai/acme-large` 作为其模型。 对于从已加载的认证存储中查找和选择 provider 密钥,请从 `openclaw/plugin-sdk/provider-auth` 导入 `findNormalizedProviderValue` 和 `resolveAuthProfileOrder`。这可避免 provider 入口仅为选择凭据而加载完整的 agent 运行时。已弃用的 `agent-runtime` 导出仍可用于兼容性。在新代码中请使用更窄的 `provider-auth` 路径。有关管理本页及其子页面中列出的已弃用接口的日期和门槛,请参阅[移除 时间线](/plugins/sdk-migration/removal-timeline)。 内置的自定义 API 密钥方法可以在供应商提示或验证需要在认证步骤之间保留时,使用来自 `openclaw/plugin-sdk/provider-auth-api-key` 的 `captureProviderApiKey` 和 `persistProviderApiKey`。 `captureProviderApiKey(ctx, options)` 接受现有的 token/provider、环境和提示选项。它会返回用于验证的已解析 `apiKey`,同时保留原始存储 `input` 和 `mode`,而不会保存凭据。请基于 `input` 和 `mode` 构建返回的 profiles,使 SecretRefs 保持为引用。该辅助函数会保留上下文中的暂存工作区和 secret-storage 提示偏好。 `persistProviderApiKey(ctx, profileId, { provider, resolved, metadata })` 接受一个已解析的非交互式密钥。它不会更改来自 profile 的凭据,如果凭据转换失败则返回 `false`,并传播持久化错误。请在此调用之前保留供应商检查;之后通过其现有所有者应用 auth-profile 配置和模型默认值。这两个辅助函数都不会选择端点或模型。 交互式认证方法可以使用 `ctx.existingProfiles` 与主机授权的 `{ profileId, credential }` 候选项重新连接。CLI 登录和引导会为所选 provider 提供已存储的 profiles;`--profile-id` 会将 CLI 登录限定到该 profile。个人账户流程只提供当前用户所选的私有账户。 列表缺失或为空表示没有可复用的账户。 Provider 方法会选择兼容的候选项,并提供复用或新账户;它们不得加载共享凭据来填充列表。 一个会签发静态 token 或 API 密钥的自定义交互式认证方法,可以在其返回的 profile 上请求受保护的持久化:typescript return { profiles: [ { profileId: "acme-ai:device", credential: { type: "token", provider: "acme-ai", token }, secretStorage: { kind: "store", namePrefix: "ACME_AI_TOKEN", }, }, ], }; ```

OpenClaw 仅在暂存验证运行期间保留内联值。在最终持久化边界,它会将值写入受保护的本地存储,并在 auth profile 中保存 tokenRef 或 keyRef。namePrefix 必须是大写的环境变量风格名称。OpenClaw 会添加一个从 provider 和最终 profile id 派生的稳定后缀,以便多个 profiles 保持独立。 请仅将其用于 provider 签发的静态凭据,不要用于轮换的 OAuth 凭据或已作为 SecretRefs 提供的值。

有关实时 /models 发现、目录辅助函数、价格归一化以及更窄的单 provider 入口点,请参阅提供商模型 目录。

3. 添加动态模型解析

如果你的 provider 接受任意模型 ID(例如代理或路由器),请添加 resolveDynamicModel:

api.registerProvider({
  // ... id, label, auth, catalog from above

  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "acme-ai",
    api: "openai-completions",
    baseUrl: "https://api.acme-ai.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
});

如果解析需要网络调用,请直接从 prepareDynamicModel 返回请求的模型。OpenClaw 会应用与同步动态解析相同的已配置覆盖和归一化。返回空值的现有 hooks 仍会在准备后重试 resolveDynamicModel。

4. 添加运行时钩子(按需)

大多数 provider 只需要 catalog + resolveDynamicModel。请根据你的 provider 需求逐步添加钩子。

请从提供商钩子族中的共享族构建器开始,然后使用提供商钩子接线连接单个钩子。

5. 添加额外功能(可选)

步骤 5:添加额外功能

provider 插件可以注册 embeddings、语音、实时转录、实时语音、媒体理解、图像生成、视频生成、网页抓取和网页搜索,与文本推理并列。OpenClaw 将其归类为 混合功能 插件——这是公司插件的推荐模式(每个供应商一个插件)。请参阅 内部机制:功能所有权。

请从提供商语音功能注册音频功能。请从提供商媒体与搜索注册 embeddings、生成、抓取和搜索。

6. 测试

步骤 6:测试

```typescript src/provider.test.ts import { describe, it, expect } from "vitest"; // Export your provider config object from index.ts or a dedicated file import { acmeProvider } from "./provider.js";

describe("acme-ai provider", () => { it("resolves dynamic models", () => { const model = acmeProvider.resolveDynamicModel!({ modelId: "acme-beta-v3", } as any); expect(model.id).toBe("acme-beta-v3"); expect(model.provider).toBe("acme-ai"); });

it("returns catalog when key is available", async () => { const result = await acmeProvider.catalog!.run({ resolveProviderApiKey: () => ({ apiKey: "test-key" }), } as any); expect(result?.provider?.models).toHaveLength(2); });

it("returns null catalog when no key", async () => { const result = await acmeProvider.catalog!.run({ resolveProviderApiKey: () => ({ apiKey: undefined }), } as any); expect(result).toBeNull(); }); });

## 发布到 ClawHub {#publish-to-clawhub}

提供商插件的发布方式与其他任何外部代码插件相同:

```bash
clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin

clawhub skill publish <path> 是用于发布技能文件夹的不同命令,而不是插件包——请勿在此处使用它。

文件结构

<bundled-plugin-root>/acme-ai/
├── package.json              # openclaw.providers metadata
├── openclaw.plugin.json      # Manifest with provider auth metadata
├── index.ts                  # definePluginEntry + registerProvider
└── src/
    ├── provider.test.ts      # Tests
    └── usage.ts              # Usage endpoint (optional)

目录顺序参考

catalog.order 控制你的目录相对于内置提供商何时合并:

顺序 时机 使用场景
simple 第一轮 普通 API 密钥提供商
profile 在 simple 之后 基于身份验证配置文件控制的提供商
paired 在 profile 之后 综合多个相关条目
late 最后一轮 覆盖现有提供商(冲突时胜出)

在每个阶段内,OpenClaw 会并发运行最多四个目录钩子。它会等待该阶段稳定,然后按提供商标签顺序合并模型行和提供商结果。钩子保留各自的发现截止时间;完成顺序不会改变目录优先级。

后续步骤

各章节迁移位置

单页版本的每个章节现在都位于此页面或以下五个子页面之一。单页版本中的锚点仍会在此处解析。

提供商模型目录

提供商模型目录 — 实时模型发现、目录辅助函数、价格规范化以及单提供商入口辅助函数。

提供商钩子族

提供商钩子族 — 共享的 replay、stream 和 tool-compat 族构建器,以及其背后的 SDK 接缝。

提供商钩子接线

提供商钩子接线 — 针对身份验证交换、请求头、传输身份、用量以及钩子顺序表的逐钩子接线。

提供商语音功能

提供商语音功能 — 语音、实时转录、实时语音和媒体理解功能。

提供商媒体与搜索 — 嵌入、图像和视频生成、网页抓取以及网页搜索功能。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw