跳转至

模型目录

提供商插件的目录参考:共享实时模型发现、目录辅助函数、价格规范化,以及更窄的单提供商入口点。 属于构建提供商插件指南的一部分。

对于轻量级的模型引用规范化,请使用 openclaw/plugin-sdk/model-ref-parse。其 normalizeGooglePreviewModelId 和 normalizeAntigravityPreviewModelId 导出共享目录的别名规则,而不会加载提供商重放或传输辅助函数。 使用 splitTrailingAuthProfile 分离尾部的认证配置,同时保留 模型版本和本地量化后缀。

实时模型发现

如果你的提供商暴露了 OpenAI 兼容的 /models API,请将 单提供商辅助函数纳入共享发现:

catalog: {
  buildProvider: () => ({
    api: "openai-completions",
    baseUrl: "https://api.acme-ai.com/v1",
    models: [...STATIC_MODELS],
  }),
  buildStaticProvider: () => ({
    api: "openai-completions",
    baseUrl: "https://api.acme-ai.com/v1",
    models: [...STATIC_MODELS],
  }),
  liveModelDiscovery: true,
},

liveModelDiscovery: true 是公开的 Plugin SDK 契约,具有以下 行为:

方面 契约
凭据 发现使用目录中已解析的提供商凭据,当认证提供 discoveryApiKey 时优先使用它。密钥引用标记永远不会作为令牌发送。默认请求使用 Authorization: Bearer <token>;对于其他供应商认证方案,请使用 buildRequestHeaders。
端点 默认 URL 是相对于有效提供商 baseUrl 的 models,当启用 allowExplicitBaseUrl 时包括操作员覆盖。对于其他相对路径,请使用 endpointPath。仅对于固定的供应商 URL 使用 endpointUrl: { url, requireBaseUrl };除非有效基础 URL 仍等于 requireBaseUrl,否则跳过发现,因此自定义代理凭据不会被发送到供应商。
网络限制 获取使用 OpenClaw 的 SSRF 防护、跨分页的一个 5 秒超时预算、每页 4 MiB 响应限制以及 50 页限制。跨源分页链接会被拒绝;跨源重定向后会移除凭据。
缓存 成功的非空目录会按提供商、端点和已解析凭据缓存 60 秒。空结果或不可用结果不会被缓存。
过滤 列表决定哪些模型存在。精确的实时 ID 保留其受信任的静态元数据;其他列出的聊天 ID 都会变成保守的文本/聊天行,因此新模型无需 OpenClaw 发布即可出现。已禁用、已归档、已弃用、已过 shutdown_date、明确非聊天、嵌入、重排序、审核、语音、转录、实时、音频、图像、视频以及旧版补全行均被排除,包括静态 ID。仅使用 readRows 从非标准响应信封中选择行;提供商特定的模型语义仍应放在自定义目录中。
准入 可选。当你的请求构造依赖于模型版本时,设置 acceptUnknownModel: ({ id, record }) => boolean,以便发现不会发布你尚无法构建有效请求的模型。它仅对你的静态目录尚未发布的 ID 调用;已知 ID 会绕过它并保留其已发布的元数据。返回 false 以丢弃该行。省略它的提供商保持先前行为不变。优先将供应商宣传的能力与你自己的契约检查进行比较,而不是使用手工维护的模型列表,并且当该行没有能力数据时采取失败关闭策略。
领域 契约
故障 实时发现是建议性的。认证、网络、超时、分页、解析、空目录和过滤失败会返回由提供商拥有的静态种子,而不是移除该提供商。

相对目录缓存 TTL 从成功加载完成时开始。缓存命中保留该截止时间,显式的绝对提供商截止时间保持不变。 待处理加载保留其初始过期时间,以便停滞的工作可以被替换。 通过已准备的目录所有者进行的显式刷新仅绕过该请求获取的键所对应的已完成响应缓存条目。同一获取内的重复读取共享刷新后的值;并发调用者共享待处理工作。普通获取保持其现有缓存生命周期。

捆绑提供商在其目录选项中设置 discoveryMode: "strict"。 该代码选项使成功的空结果保持为空,并通过 ProviderCatalogResult.outcomes 报告失败的获取,而不是将种子模型作为成功刷新返回。HTTP 401/403 会产生目录范围的 auth-rejected 结果;其他获取失败会产生 unavailable。静态目录或跳过的发现均不会产生实时结果。当某个配置提供了其凭据时,每个结果都会携带为实际请求选择的配置。家族提供商独立报告每个同级项。显式的 ready 结果可以包含 modelOrder: string[],以在选择器中对其已发现的模型进行排序。这不会添加模型或授予访问权限;缺失的模型会被忽略,没有 modelOrder 的结果保留清单顺序。提供商范围的刷新会保留在所选提供商的已注册别名下报告的显式结果;无关的同级结果仍被排除。在正的缓存生命周期下,经过验证的空结果使用与非空结果相同的成功观察生命周期。过期后,普通目录读取返回保留的行,同时现有清单所有者在后台刷新提供商。ttlMs: 0 仍然禁用响应缓存,并且不为该续期路径记录过期时间。

成功的已认证结果可能包含私有的 modelServiceTiers 观察值:绑定到该结果 profileId 的 { modelId, runtimeId, api, baseUrl, serviceTiers } 行。仅提供账户成功响应中明确宣传的层级 ID;切勿从静态种子或原生回退目录中复制它们。主机在将 serviceTiers 投影到公共模型选择之前,会匹配所选配置、模型、路由和运行时。账户层级映射永远不会出现在公共 providerOutcomes 中。缺失、失败、过期或不匹配的观察值会使支持状态未知。此元数据不会授权执行或保证上游履行。

来自账户范围订阅列表的 ready 结果可能包含私有的 listedModelIds: string[] 来源信息:响应返回的每个模型 ID,包括隐藏行。它永远不会出现在公共 providerOutcomes 中。当存在时,如果 ID 缺失,选择器会将模型的订阅路由视为该账户无权使用,除非另一个可用的凭据类别提供该模型。空数组是权威的。该列表仅适用于创建它的凭据:结果的 profileId,或在省略时的非配置认证。另一个账户的列表会使授权状态未知。当列表失败或未描述账户授权时,省略该字段。

公共元数据请求在发现选项中声明 authentication: "none"。已准备的请求随后没有凭据或配置身份;其缓存键独立于配置的推理凭据。返回的提供商配置仍保留其推理凭据。

省略 discoveryMode 的外部调用保留上述建议性契约。公共 Chutes、Hugging Face、KiloCode 和 Vercel AI Gateway 发现函数和构建器也保留该默认值。它们的捆绑目录钩子显式传递 { discoveryMode: "strict" };Hugging Face 发现接受在其现有超时参数之后传递此选项对象。Chutes 公共默认在 HTTP 401 后保留其匿名重试;严格调用在没有所选凭据的情况下从不重试。严格路径和建议性路径共享相同的受保护传输和缓存,但具有不同的缓存身份。建议性调用仍然仅保留非空结果。自定义实时构建器可以在其目录钩子中使用 runLiveProviderCatalog 来报告成功获取并将获取错误转换为结果。仅返回提供商配置不会建立实时发现结果。出于兼容性考虑,由没有结果的旧版目录钩子返回的非空行会在相同凭据下在提供商范围故障中存活。这不会建立成功的发现来源,也不会保留无关的配置行和补充行。空的旧版目录和特定配置失败不使用该回退;成功替换会清除之前的行来源。将元数据源回退与账户发现分开;不要匿名重试被拒绝的账户请求,也不要在严格构建器内用种子行替代。

自定义目录钩子可能会从 ctx.resolveProviderApiKey() 接收可选的 mode 元数据:api_key、oauth 或 token。当存在时,它描述该查找所选用的凭据。在选择供应商身份验证方案时使用它;单独的 resolveProviderAuth() 调用可能会选择另一个配置文件。省略的 mode 元数据不会改变现有回调行为。

ctx.resolveProviderAuth() 可能在 OAuth 准备耗尽候选项时设置 preparationFailed: true。不要将该标志视为配置缺失,也不要重新启动对相同配置文件的解析。钩子仍可选择其他凭据来源。其返回的供应商配置或显式结果仍具有权威性;否则,目录所有者将报告已消费的准备工作失败,并附上尝试过的配置文件标识。

对于非 Bearer 或非标准的列表端点,请传递选项而不是 true:

liveModelDiscovery: {
  endpointPath: "model-catalog",
  buildRequestHeaders: ({ apiKey, discoveryApiKey }) => ({
    "vendor-version": "2026-01-01",
    "x-api-key": discoveryApiKey ?? apiKey ?? "",
  }),
  readRows: (body) =>
    body && typeof body === "object" &&
    Array.isArray((body as { models?: unknown }).models)
      ? (body as { models: unknown[] }).models
      : [],
},

不要将 endpointUrl 用作无条件的备用主机。其 requireBaseUrl 检查是凭据隔离边界,适用于模型列表主机与推理主机不同的供应商。

如果供应商需要自定义模型语义,而不是保守的 OpenAI 兼容投影,请仅在插件中保留该投影。将其作为 projectRows 传递;共享运行时仍负责受保护的获取、供应商身份验证头、缓存准入和静态回退。

当插件自行构建供应商配置时,使用 buildLiveModelProviderConfig。如果没有 projectRows,列表将决定哪些模型存在:每个列出的聊天模型都会发布,静态 models 行仅丰富匹配的 ID,非聊天行按照与 liveModelDiscovery 相同的规则过滤。要限制列表,请传递 readModelId(row),并对供应商不支持的行返回 undefined;返回的字符串也会成为模型 ID。当实时 API 发布更丰富的模型元数据时,传递 projectRows:

```typescript index.ts import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { buildLiveModelProviderConfig, type LiveModelCatalogFetchGuard, } from "openclaw/plugin-sdk/provider-catalog-live-runtime";

const STATIC_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, }, ] as const;

async function buildAcmeLiveProvider(params: { apiKey: string; discoveryApiKey?: string; fetchGuard?: LiveModelCatalogFetchGuard; }) { return await buildLiveModelProviderConfig({ providerId: "acme-ai", endpoint: "https://api.acme-ai.com/v1/models", providerConfig: { baseUrl: "https://api.acme-ai.com/v1", api: "openai-completions", }, models: STATIC_MODELS, apiKey: params.apiKey, discoveryApiKey: params.discoveryApiKey, fetchGuard: params.fetchGuard, ttlMs: 60_000, auditContext: "acme-ai-model-discovery", projectRows: (rows, fallback) => rows.flatMap((row) => { const model = projectAcmeModel(row, fallback); return model ? [model] : []; }), }); }

export default definePluginEntry({ id: "acme-ai", name: "Acme AI", register(api) { api.registerProvider({ id: "acme-ai", label: "Acme AI", catalog: { order: "simple", run: async (ctx) => { const auth = ctx.resolveProviderAuth("acme-ai"); const apiKey = auth.apiKey ?? ctx.resolveProviderApiKey("acme-ai").apiKey; if (!apiKey) return null; return { provider: await buildAcmeLiveProvider({ apiKey, discoveryApiKey: auth.discoveryApiKey, }), }; }, }, staticCatalog: { order: "simple", run: async () => ({ provider: { baseUrl: "https://api.acme-ai.com/v1", api: "openai-completions", models: [...STATIC_MODELS], }, }), }, }); }, });

`run` 应保持身份验证门控,并在没有可用凭据时返回 `null`。保留离线 `staticRun` 或静态回退,以便设置、文档、测试和选择器界面不依赖于实时网络访问。使用适合模型列表新鲜度的 TTL,避免请求时文件系统轮询,并且仅当上游响应不是 OpenAI 兼容的 `{ data: [{ id, object }] }` 形状时,才传递供应商特定的 `readRows`。当行在其他位置携带其 ID,或供应商必须拒绝某些列出的行时,传递 `readModelId`。

在模型运行时准备期间,`staticCatalog.run` 和 `prepareSyntheticAuth` 会接收一个可选的 `signal`。关闭以及插件/配置替换会中止它。当它中止时,停止等待中的获取,并在钩子完成前完成资源清理。OpenClaw 会丢弃已取消的结果,并在替换项能够获取相同的代理资源之前等待清理完成。

对于独立的权威元数据源,相同的 `provider-catalog-live-runtime` 子路径暴露了 `ProviderCatalogSnapshot`:每个条目将一个运行时模型与其生命周期状态配对。`projectUpstreamProviderCatalogSnapshot` 从可信种子和已接受的上游行重建该快照,并丢弃已撤回的仅上游模型。`projectProviderCatalogSnapshotRows` 将通告的 ID 与活动快照条目求交集,并按端点顺序去重;`listProviderCatalogSnapshotEntries` 为目录消费者投影相同的生命周期事实。将种子生命周期策略和特定于模型的装饰保留在所属插件中。在刷新元数据后派生静态回退资格,以便首次失败或完全过滤的发现使用当前状态。公共元数据永远不会建立账户权限或扩大发现的凭据范围。



The private `createUpstreamProviderCatalog` helper keeps this snapshot lifecycle in one prepared owner. Supply the trusted seed, provider routes, metadata and model-list endpoints, discovery and starter-model audit labels, static-entry eligibility, and any model decoration. An optional `upstreamSeed` controls which seed lifecycle facts survive an upstream refresh, and an optional `projectRows` replaces the default selection of listed rows (`projectProviderCatalogSnapshotRows`) when the plugin admits listed IDs the metadata does not describe. Model-list requests carry the provider's attribution headers from the same owner inference uses.
The owner exposes `getSnapshot`, `refreshMetadata`, `buildStaticProvider`, and `buildLiveProvider`; credentials belong to each build call. Live builds refresh metadata before deriving static eligibility and projecting advertised IDs.
Metadata acquisition failure retains the previous snapshot; model-list failures and empty results remain strict. `refreshMetadata` returns `undefined` when the feed lacks the provider, so explicit model preparation cannot mistake retained metadata for a successful refresh. Plugin policy still owns which models may resolve directly from the seed or current snapshot.

`resolveStarterModel` checks the preferred provider/model reference against a fresh account model-list response. It returns that reference only when its exact model ID is advertised, without refreshing or extending the metadata snapshot.

Upstream reasoning metadata preserves omitted controls as unspecified and an empty options or effort list as no effort control. A native `null` effort maps to `none`; provider-native effort names retain their casing. These facts remain separate from whether a model performs reasoning internally.

Official plugins use the private, pure `openclaw/plugin-sdk/model-catalog-pricing` runtime subpath. It exposes `normalizeModelPricingCatalog(rows, normalizePricing, options?)` for provider-owned pricing feeds. It returns a map of complete costs: absent prices are omitted, while malformed declared prices, invalid or duplicate model IDs, and a feed with no usable prices return `undefined`. Supply the provider's unit conversion. Options can select `readModelId(model)` (default `model.id`), `readPricing(model)` (default `model.pricing`), and `isSupportedPricing(rawPricing)` (default `true`). Declared prices are normalized and validated before unsupported schedules are omitted; duplicate IDs are rejected even on unpriced or unsupported rows. Non-token domains can return `undefined` from `readPricing`. No auth, discovery, or runtime loader is imported.

DeepInfra's `pricing-api.ts` uses these selectors for its native array and `model_name` identities. Release plugins using the options contract (including DeepInfra and Venice) with a matching host, and coordinate their plugin API and minimum-host floors at release time. The private subpath is not an independently versioned third-party compatibility API.

This subpath also exposes `normalizeOpenRouterModelPricing(pricing)` for native OpenRouter pricing objects. It converts per-token rates and static prompt-length overrides into a complete per-million cost schedule, without network access or prices from another source. Overrides apply strictly above `min_prompt_tokens`, counting uncached input, cache reads, and cache writes. Matching entries apply in source order: later entries win per price key, including at equal thresholds; omitted keys inherit the native base or an earlier matching entry. Cache rates absent from the base default to zero. Invalid effective token rates return `undefined`. Entries with time-based or unknown conditions are skipped; other known charge dimensions are ignored.

## 选择目录增强钩子 {#selecting-catalog-augmentation-hooks}

`augmentModelCatalogWithProviderPlugins` 从 `openclaw/plugin-sdk/provider-catalog-runtime` 导出。其可选的顶层 `providerIds` 选择要运行哪些已注册的 `augmentModelCatalog` 钩子:

- 省略 `providerIds` 以保留无范围行为。
- 传入 `[]` 以不运行任何增强钩子。
- 传入提供商 ID 或已注册别名以选择匹配的钩子。匹配会规范化 ID 和别名,包括提供商家族使用的钩子别名。

该选择器**不会**过滤所选钩子返回的行。一个家族钩子可能为多个提供商返回行;调用方负责任何行过滤。该辅助函数返回补充行,而不是输入 `context.entries`。

已发布的 v2026.9.4 导出没有 `providerIds` 选择器,并且可能在运行时忽略该选项。依赖范围化钩子选择的插件必须在 `openclaw.compat.pluginApi` 中要求包含该选择器的宿主版本。省略该选项会在较旧和较新的宿主上保留现有行为。

该顶层选择器独立于 `catalog.run` 回调上下文。当 `ctx.providerIds` 存在时,它包含为该目录所有者选择的规范化提供商标识。当钩子不服务于其中任何一个时,在解析凭据或发起网络请求之前返回 `null`;OpenClaw 还会将返回的标识过滤到该范围。缺失的范围表示调用方请求了完整目录。

如果上游提供商使用的控制 token 与 OpenClaw 不同,请添加一个小型双向文本转换,而不是替换流路径:

```typescript
api.registerTextTransforms({
  input: [
    { from: /red basket/g, to: "blue basket" },
    { from: /paper ticket/g, to: "digital ticket" },
    { from: /left shelf/g, to: "right shelf" },
  ],
  output: [
    { from: /blue basket/g, to: "red basket" },
    { from: /digital ticket/g, to: "paper ticket" },
    { from: /right shelf/g, to: "left shelf" },
  ],
});

input 在传输前重写最终系统提示和文本消息内容。output 在 OpenClaw 解析其自身控制标记或通道投递之前重写助手文本增量和最终文本。

对于仅注册一个使用 API 密钥认证加单一目录支持运行时的文本提供商的捆绑提供商,请优先使用更窄的 defineSingleProviderPluginEntry(...) 辅助函数:

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",
    docsPath: "/providers/acme-ai",
    auth: [
      {
        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: {
      buildProvider: () => ({
        api: "openai-completions",
        baseUrl: "https://api.acme-ai.com/v1",
        models: [{ id: "acme-large", name: "Acme Large" }],
      }),
      buildStaticProvider: () => ({
        api: "openai-completions",
        baseUrl: "https://api.acme-ai.com/v1",
        models: [{ id: "acme-large", name: "Acme Large" }],
      }),
    },
  },
});

buildProvider 是当 OpenClaw 能够解析真实 provider 认证时使用的实时目录路径。它可以执行 provider 特定的发现。仅在离线行中,且这些行在配置认证之前可以安全显示时,才使用 buildStaticProvider;它不得要求凭据或发起网络请求。OpenClaw 的 models list --all 显示当前仅对捆绑的 provider 插件执行静态目录,并且使用空配置、空环境变量,以及没有 agent/workspace 路径。

如果你的认证流程在引导设置期间还需要修补 models.providers.*、别名以及 agent 默认模型,请使用来自 openclaw/plugin-sdk/provider-onboard 的预设辅助函数。对于已注册的仅连接设置,请使用带有惰性 catalogModels supplier 的 createProviderConnectionPresetAppliers(...)。普通设置会写入连接事实、别名以及缺失的主模型,而不会将内置目录复制到已保存的配置中。显式的 models.mode: "replace" 会评估 supplier,并将生成的行合并到已编写行的后面。每个设置结果都拥有其生成的模型数据。

当 replace 模式必须保留现有的必需默认规则时,请使用 createDefaultModelsConnectionPresetAppliers(...):仅当已配置的 provider 缺少所选的 defaultModelId 时,才添加所提供的 defaultModels。applyProviderConnectionConfig(...) 为每次调用都会解析其端点或主模型的认证流程提供目录变体。这些辅助函数会保留已编写的行、现有别名和回退。认证流程仍然负责任何显式默认选择。

现有的公开 createDefaultModelPresetAppliers(...)、createDefaultModelsPresetAppliers(...) 和 createModelCatalogPresetAppliers(...) 在普通模式下保留其目录播种行为。后两者还接受惰性模型 supplier。具有已发布配置辅助函数的 provider 可以在其现有辅助函数和新的已注册设置辅助函数之间共享一个预设描述符;迁移注册时,不要悄悄更改已发布辅助函数的契约。

独立发布的插件必须在 openclaw.compat.pluginApi 中要求包含这些辅助函数的 host 版本。核心发布版本同步工具会随配对发布更新该范围;这些导入在缺少这些辅助函数的旧 host 上无法工作。

当 provider 的原生端点在正常的 openai-completions 传输上支持流式 usage 块时,请优先使用 openclaw/plugin-sdk/provider-catalog-shared 中的共享目录辅助函数,而不是硬编码 provider-id 检查。supportsNativeStreamingUsageCompat(...) 和 applyProviderNativeStreamingUsageCompat(...) 会从端点能力映射中检测支持情况,因此即使插件正在使用自定义 provider id,原生 Moonshot/DashScope 风格的端点仍然可以启用。

上面的实时发现示例覆盖了 /models 风格的 provider API。请将这种发现保留在 catalog.run 内,并以可用的认证作为门控,同时保持 staticRun 无网络,用于离线目录生成。

运行时模型准备也会在已配置的模型引用需要其行时运行 staticRun,然后将 ctx.providerIds 设置为所选的 provider id。仅在这种情况下,hook 才可以等待其同步 hook 读取的 provider 拥有的缓存,例如用于思考级别的模型能力。目录生成、models list --all 和 doctor 验证会保持 ctx.providerIds 未设置;请保持这些运行无网络。

共享凭据的官方 provider 插件可以使用私有运行时 openclaw/plugin-sdk/provider-catalog-shared 子路径中的 resolveFirstProviderCatalogAuth(ctx.resolveProviderApiKey, providerIds)。请在调用方的有序 ID 中保持 provider 优先级。该辅助函数会在第一个带有 apiKey 或 discoveryApiKey 的结果处停止,并返回该完整结果,同时保留其 profile 和认证模式。未解析的 SecretRef 标记优先于另一个 provider 的实时密钥;字段绝不会跨账户混合。当没有任何 provider 具有认证时,它返回 undefined,并传播查找失败。使用此 host 导出的官方插件发布必须在 compat.pluginApi 中要求提供它的 host 版本。

来自私有本地 openclaw/plugin-sdk/provider-model-metadata 接口的 findNormalizedProviderKey(entries, providerId) 返回第一个其修剪后的小写拼写与 provider ID 匹配的已配置密钥。偏好精确已编写密钥的调用方必须先检查该密钥。

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