提供程序运行时挂钩和目录

三个提供程序层、完整的钩子顺序表、工作的提供程序示例、捆绑的钩子形状以及提供程序目录如何合并。 插件架构内部指南的一部分。

提供方运行时钩子

提供方插件有三层：

• Manifest 元数据，用于运行时前的低成本查找： setup.providers[].envVars、providerAuthAliases、providerAuthChoices 和 channelConfigs。
• 配置时钩子：catalog 以及 applyConfigDefaults。
• 运行时钩子：40 多个可选钩子，涵盖身份验证、模型解析、 流包装、思考级别、重放策略和用量端点。请参阅 钩子顺序和用法。

OpenClaw 仍然负责通用的代理循环、故障切换、转录处理和工具策略。 这些钩子是面向提供方特定行为的扩展接口，而不需要完全自定义的推理传输。

挂钩查找首先使用准备好的生成或匹配的加载注册表。如果未命中，provider/model-scoped 发现会重用加载程序的注册表缓存；显式运行时发现失效会清除该查找，而不是让另一个提供者缓存保留旧的挂钩。尝试准备的提供程序句柄保留其选择的插件，而每个挂钩接收当前的调用上下文。

Synthetic-auth 查找包括来自声明的提供者或 CLI 后端所有者的仅身份验证发现条目。静态模型目录行不会替换这些身份验证实现。如果所有者未提供合成验证挂钩，则查找不会返回合成结果，而不会加载不相关的发现条目。对于没有声明所有者的别名，轻量级条目后备仍然可用。外部身份验证捕获仍然在只读工作人员工作之前准备新的结果。

当提供程序具有基于环境的凭据时，使用清单 setup.providers[].envVars 通用 auth/status/model-picker 路径应该在不加载插件运行时的情况下看到。当一个提供商 ID 应重用另一提供商 ID 的环境变量、身份验证配置文件、配置支持的身份验证和 API-key 入门选择时，请使用清单 providerAuthAliases。当 onboarding/auth-choice CLI 表面应该知道提供程序的选择 id、组标签和简单的单标志身份验证连接而不加载提供程序运行时时，请使用清单 providerAuthChoices。保留提供程序运行时 envVars 以用于面向操作员的提示，例如加入标签或 OAuth 客户端 id/client-secret 设置变量。

通过所属的 channelConfigs.<id>.schema 和设置描述符，描述由环境变量驱动的频道设置和身份验证。

钩子顺序与使用

对于 model/provider 插件，OpenClaw 按此粗略顺序调用挂钩。 “何时使用”栏是快速决策指南。 OpenClaw 不再调用的仅兼容提供程序字段（例如 ProviderPlugin.capabilities 和 suppressBuiltInModel）故意不在此处列出。

reconcileLocalService 仅针对配置的本地服务运行，包括从当前网关进程外部重用的健康进程。保持成本低廉、重复安全且具有中止意识。拒绝会阻止提供者请求并释放其租约，而不会将健康进程分类为启动失败。

规范化调度是特定于钩子的：

• Model 引用在 normalizeModelId 调度之前应用清单声明的模型 ID 规范化一次。匹配的提供商钩子可以细化准备好的模型ID；空结果使其保持不变。 OpenClaw 不会尝试其他提供商的规范化挂钩或随后重新应用清单规则。引用解析会读取选定的运行时注册表，而无需激活插件。可执行规范化需要一个准备好的运行时所有者；无需仅使用静态清单策略即可读取。直接注册的提供商拥有其 ID；兼容性别名仅在不存在文字提供程序时匹配，保留仅别名路由和显式 API-owner 资格。
• normalizeTransport 首先尝试匹配的提供商。仅当这不会更改 api 或 baseUrl 并且提供程序没有 models.providers.<id> 条目时，它才会尝试其他传输挂钩，并在第一次更改时停止。
• Config 程序集通过拥有的捆绑提供程序的轻量级策略表面调用 normalizeConfig 和 resolveConfigApiKey。它永远不会加载提供程序运行时，扫描其他提供程序的挂钩，或者在拥有的挂钩未返回任何更改后失败。

Google-family 配置清理由 Google 插件自己的 normalizeConfig 挂钩实现，与其轻量级策略表面共享。它不是一个单独的核心兼容性支持。

如果提供者需要完全自定义的线协议或自定义请求执行器，那就是另一类扩展。这些钩子面向仍然运行在 OpenClaw 正常推理循环上的提供者行为。

resolveUsageAuth 决定 OpenClaw 是否应调用 fetchUsageSnapshot 或回退到 usage/status 表面的通用凭证解析。当提供者具有使用凭证时返回 { token, accountId?, subscriptionType?, rateLimitTier? }（可选计划元数据流入 fetchUsageSnapshot），当提供者拥有的使用身份验证已处理请求并且必须抑制通用 API-key/OAuth 回退时返回 { handled: true }，并返回 null 或undefined 当提供商未处理使用身份验证时。

在清单 providerUsageAuthEnvVars 中声明组织或计费凭据。这样通用发现和秘密清理界面就能识别它们，而不会把它们当作推理认证候选项。

提供商示例

example-proxy、exchangeToken 和 fetchExampleProxyUsage 是您自己的提供商 id 和供应商 API 调用的占位符，而不是导出的 OpenClaw 帮助程序。

api.registerProvider({  id: "example-proxy",  label: "Example Proxy",  auth: [],  catalog: {    order: "simple",    run: async (ctx) => {      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;      if (!apiKey) {        return null;      }      return {        provider: {          baseUrl: "https://proxy.example.com/v1",          apiKey,          api: "openai-completions",          models: [{ id: "auto", name: "Auto" }],        },      };    },  },  resolveDynamicModel: (ctx) => ({    id: ctx.modelId,    name: ctx.modelId,    provider: "example-proxy",    api: "openai-completions",    baseUrl: "https://proxy.example.com/v1",    reasoning: false,    input: ["text"],    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },    contextWindow: 128000,    maxTokens: 8192,  }),  prepareRuntimeAuth: async (ctx) => {    const exchanged = await exchangeToken(ctx.apiKey);    return {      apiKey: exchanged.token,      baseUrl: exchanged.baseUrl,      expiresAt: exchanged.expiresAt,    };  },  resolveUsageAuth: async (ctx) => {    const auth = await ctx.resolveOAuthToken();    return auth ? { token: auth.token } : null;  },  fetchUsageSnapshot: async (ctx) => {    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);  },});

内置示例

捆绑的提供者插件会结合上面的钩子，以适配每个供应商的目录、认证、thinking、回放和使用量需求。权威的钩子集合位于各插件在 extensions/ 下的实现中；本页展示的是形态，而不是逐项复刻列表。

提供商目录

provider 插件可以通过 registerProvider({ catalog: { run(...) { ... } } }) 为推理定义模型目录。

catalog.run(...) 返回与 OpenClaw 写入 models.providers 的相同结构：

• { provider } 表示单个 provider 条目
• { providers } 表示多个 provider 条目

当插件拥有 provider 特定的模型 id、base URL 默认值，或受认证门控的模型元数据时，使用 catalog。

catalog.order 控制插件的目录与 OpenClaw 内置隐式 provider 的合并顺序：

• simple：普通 API-key 或环境驱动的提供程序
• profile：在存在认证 profile 时出现的 provider
• paired：合成多个相关 provider 条目的 provider
• late：最后一轮，在其他隐式 provider 之后

后面的 provider 在键冲突时获胜，因此插件可以有意用相同的 provider id 覆盖内置 provider 条目。

插件还可以通过 api.registerModelCatalogProvider({ provider, kinds, staticCatalog, liveCatalog }) 发布只读模型行。这是 list/help/picker 曲面的前向路径，支持 text、voice、image_generation、video_generation 和 music_generation 行。提供商插件仍然拥有实时端点调用、令牌交换和供应商响应映射； core 拥有通用的行形状、源标签和媒体工具帮助格式化。媒体生成提供程序注册会自动从 defaultModel、models 和 capabilities 合成静态目录行。

兼容性：

• discovery 是 catalog 的旧别名。 OpenClaw 删除了 2026.4.26 中的别名及其弃用警告
• 将discovery重命名为catalog。仍然注册 discovery 的提供程序插件不发布任何目录行
• augmentModelCatalog 已弃用；捆绑提供商应通过 registerModelCatalogProvider 发布补充行。其移除时间为 2026-10-01