提供商钩子和目录
三个提供商层级、完整的钩子顺序表、一个完整的提供商示例、 内置的钩子形状,以及提供商目录如何合并。属于插件 架构内部机制指南的一部分。
提供商运行时钩子¶
提供商插件具有三个层级:
- Manifest 元数据,用于低成本的运行时前查找:
setup.providers[].envVars、providerAuthAliases、providerAuthChoices和channelConfigs。 - 配置时钩子:
catalog以及applyConfigDefaults。 - 运行时钩子:40 多个可选钩子,覆盖认证、模型解析、 流包装、思考级别、重放策略和使用量端点。参见 钩子顺序与使用。
OpenClaw 仍然负责通用代理循环、故障转移、转录处理以及 工具策略。这些钩子是提供商特定行为的扩展面,无需完整的自定义推理传输。
钩子查找首先使用已准备的生成或匹配的已加载注册表。 未命中时,提供商/模型范围的发现会复用加载器的注册表缓存; 显式的运行时发现失效会清除该查找,而不是让另一个提供商缓存保留旧钩子。尝试准备的提供商句柄 会保留其选定的插件,同时每个钩子接收当前调用上下文。
合成认证查找包括来自已声明提供商或 CLI 后端所有者的仅认证发现条目。静态模型目录行不会替换这些 认证实现。如果所有者未提供合成认证钩子,查找 将不返回合成结果,而不会加载无关的发现条目。对于没有声明所有者的别名,仍保留轻量级条目回退。 外部认证捕获在只读 worker 工作之前仍会准备新的结果。
当提供商具有基于环境变量的凭据,且通用认证/状态/模型选择器路径应在不加载插件运行时的情况下看到这些凭据时,使用 Manifest 的 setup.providers[].envVars。当一个提供商 id 应复用另一个提供商 id 的环境变量、认证配置、基于配置的认证以及 API 密钥入门选择时,使用 Manifest 的 providerAuthAliases。当入门/认证选择 CLI 界面应了解提供商的选择 id、分组标签以及简单的单标志认证接线,而无需加载提供商运行时时,使用 Manifest 的 providerAuthChoices。将提供商运行时的 envVars 保留给面向操作者的提示,例如入门标签或 OAuth client-id/client-secret 设置变量。
通过所属的 channelConfigs.<id>.schema 和设置描述符描述由环境变量驱动的通道设置与认证。
钩子顺序与使用¶
对于模型/提供商插件,OpenClaw 按以下大致顺序调用钩子。
“何时使用”列是快速决策指南。
OpenClaw 不再调用的仅兼容性提供商字段,例如
ProviderPlugin.capabilities 和 suppressBuiltInModel,有意未在此列出。
| 钩子 | 作用 | 何时使用 |
|---|---|---|
catalog |
在 models.json 生成期间将提供商配置发布到 models.providers |
提供商拥有目录或基础 URL 默认值 |
applyConfigDefaults |
在配置物化期间应用提供商拥有的全局配置默认值 | 默认值取决于认证模式、环境变量或提供商模型族语义 |
| (内置模型查找) | OpenClaw 首先尝试常规注册表/目录路径 | (不是插件钩子) |
normalizeModelId |
在查找前规范化旧版或预览模型 id 别名 | 提供商负责在规范模型解析前进行别名清理 |
normalizeTransport |
在通用模型组装前规范化提供商家族的 api / baseUrl |
提供商负责同一传输家族中自定义提供商 id 的传输清理 |
normalizeConfig |
在运行时/提供商解析前规范化 models.providers.<id> |
提供商需要应归属于所属插件的配置清理 |
applyNativeStreamingUsageCompat |
对配置提供商应用原生流式使用量兼容性重写 | 提供商需要由端点驱动的原生流式使用量元数据修复 |
resolveConfigApiKey |
在运行时认证加载前为配置提供商解析环境变量标记认证 | 提供商公开其自己的环境变量标记 API 密钥解析钩子 |
resolveSyntheticAuth |
在不持久化明文的情况下呈现本地/自托管或基于配置的认证 | 提供商可以使用合成/本地凭据标记运行 |
| 钩子 | 作用 | 使用时机 |
|---|---|---|
resolveExternalAuthProfiles |
覆盖提供方拥有的外部身份验证配置文件;默认 persistence 为 runtime-only,用于 CLI/应用拥有的凭据 |
提供方复用外部身份验证凭据,而不持久化复制的刷新令牌;在清单中声明 contracts.externalAuthProviders |
shouldDeferSyntheticProfileAuth |
降低已存储的合成配置文件占位符的优先级,使其位于基于环境变量/配置的身份验证之后 | 提供方存储不应获得优先级的合成占位配置文件 |
resolveDynamicModel |
为尚未存在于本地注册表中的提供方拥有的模型 ID 提供同步回退 | 提供方接受任意上游模型 ID |
prepareDynamicModel |
返回异步准备好的模型,或在重试 resolveDynamicModel 之前预热可复用元数据 |
提供方在解析未知 ID 之前需要网络元数据 |
normalizeResolvedModel |
在嵌入式运行器使用已解析模型之前的最终重写 | 提供方需要传输层重写,但仍使用核心传输 |
normalizeToolSchemas |
在嵌入式运行器看到工具架构之前对其进行规范化 | 提供方需要传输族架构清理 |
inspectToolSchemas |
在规范化后呈现提供方拥有的架构诊断 | 提供方希望获得关键字警告,而不必让核心学习提供方特定规则 |
resolveReasoningOutputMode |
选择原生与带标记的推理输出契约 | 提供方需要带标记的推理/最终输出,而不是原生字段 |
prepareExtraParams |
在通用流选项包装器之前进行请求参数规范化 | 提供方需要默认请求参数或按提供方清理参数 |
createStreamFn |
使用自定义传输完全替换正常流路径 | 提供方需要自定义线路协议,而不仅仅是包装器 |
wrapStreamFn |
在应用通用包装器之后的流包装器 | 提供方需要请求头/正文/模型兼容包装器,而不需要自定义传输 |
reconcileLocalService |
在本地服务健康检查之后、每次请求之前协调提供方拥有的状态 | 受管本地路由器必须重新加载持久提供方状态,而无需将提供方策略移入核心 |
resolveTransportTurnState |
附加原生的每轮请求头、元数据或 WebSocket 策略 | 提供方希望通用传输发送提供方原生的轮次身份,或调整 WebSocket 请求头和回退冷却时间 |
resolveWebSocketSessionPolicy |
已弃用的 WebSocket 策略兼容钩子 | 现有插件将 WebSocket 字段迁移到 resolveTransportTurnState |
formatApiKey |
身份验证配置文件格式化器:已存储配置文件成为运行时 apiKey 字符串 |
提供方存储额外身份验证元数据,并需要自定义运行时令牌格式 |
refreshOAuth |
用于自定义刷新端点或刷新失败策略的 OAuth 刷新覆盖 | 提供方不适合共享的 OpenClaw 刷新器 |
buildAuthDoctorHint |
OAuth 刷新失败时附加的修复提示 | 提供方在刷新失败后需要提供方拥有的身份验证修复指导 |
matchesContextOverflowError |
提供方拥有的上下文窗口溢出匹配器 | 提供方存在通用启发式方法会遗漏的原始溢出错误 |
classifyFailoverReason |
提供方拥有的故障转移原因分类 | 提供方可以将原始 API/传输错误映射为速率限制/过载等 |
| 钩子 | 作用 | 使用时机 |
|---|---|---|
isCacheTtlEligible |
代理/回传提供商的 Prompt 缓存策略 | 提供商需要代理特定的缓存 TTL 门控 |
buildMissingAuthMessage |
替代通用的缺失认证恢复消息 | 提供商需要提供商特定的缺失认证恢复提示 |
augmentModelCatalog |
发现后追加的合成/最终目录行(已弃用,见下文) | 提供商需要在 models list 和选择器中拥有合成前向兼容行 |
resolveThinkingProfile |
模型特定的 /think 级别集、显示标签和默认值 |
提供商为选定模型暴露自定义思考阶梯或二元标签 |
isBinaryThinking |
开/关推理切换兼容性钩子 | 提供商仅暴露二元思考开/关 |
supportsXHighThinking |
xhigh 推理支持兼容性钩子 |
提供商希望仅在部分模型上启用 xhigh |
resolveDefaultThinkingLevel |
默认 /think 级别兼容性钩子 |
提供商拥有某个模型族的默认 /think 策略 |
isModernModelRef |
用于实时配置文件筛选和冒烟选择的现代模型匹配器 | 提供商拥有实时/冒烟首选模型匹配 |
prepareRuntimeAuth |
在推理前将已配置的凭据交换为实际的运行时 Token/密钥 | 提供商需要 Token 交换或短生命周期请求凭据 |
resolveUsageAuth |
为 /usage 及相关状态界面解析用量/计费凭据 |
提供商需要自定义用量/配额 Token 解析或不同的用量凭据 |
fetchUsageSnapshot |
在认证解析后获取并规范化提供商特定的用量/配额快照 | 提供商需要提供商特定的用量端点或负载解析器 |
createEmbeddingProvider |
为记忆/搜索构建提供商拥有的嵌入适配器 | 记忆嵌入行为属于提供商插件 |
buildReplayPolicy |
返回控制提供商转录处理的回放策略 | 提供商需要自定义转录策略(例如,思考块剥离) |
sanitizeReplayHistoryAsync |
在通用转录清理后重写回放历史,并等待转录元数据 | 提供商需要超出共享压缩助手的提供商特定回放重写 |
sanitizeReplayHistory |
已弃用的第三方兼容性钩子 | 现有插件迁移到等待钩子及其 V2 会话状态契约 |
validateReplayTurns |
在嵌入式运行器之前进行最终回放轮次验证或重塑 | 提供商传输需要在通用清理后进行更严格的轮次验证 |
onModelSelected |
运行提供商拥有的选择后副作用 | 当模型变为活动时,提供商需要遥测或提供商拥有的状态 |
reconcileLocalService 仅针对已配置的本地服务运行,包括从当前 Gateway 进程外部复用的健康进程。请保持其低成本、幂等且可感知中止。拒绝会阻止提供商请求并释放其租约,而不会将该健康进程归类为启动失败。
规范化分发是钩子特定的:
- 模型引用在
normalizeModelId分发之前,仅应用一次清单声明的模型 ID 规范化。匹配的提供商钩子可以细化该准备好的模型 ID;空结果会保持其不变。OpenClaw 不会尝试其他提供商的规范化钩子,也不会在之后重新应用清单规则。引用解析读取选定的运行时注册表,而不会激活插件。可执行规范化需要一个准备好的运行时所有者;没有它的读取仅使用静态清单策略。直接注册的提供商拥有其 ID;兼容性别名仅在不存在字面提供商时匹配,从而保留仅别名路由和显式 API 所有者资格。 normalizeTransport首先尝试匹配的提供商。只有当它未更改api或baseUrl,并且该提供商没有models.providers.<id>条目时,才会尝试其他传输钩子,并在首次更改时停止。- 配置组装通过所属捆绑提供商的轻量级策略接口调用
normalizeConfig和resolveConfigApiKey。它从不加载提供商运行时、扫描其他提供商的钩子,或在所属钩子返回无更改后继续回退。
Google 系列配置清理由 Google 插件自身的
normalizeConfig 钩子实现,该钩子与其轻量级策略表面共享。它不是独立的
核心兼容性兜底机制。
如果提供商需要完全自定义的线路协议或自定义请求执行器, 则属于另一类扩展。这些钩子用于仍然运行在 OpenClaw 正常推理循环上的提供商行为。
resolveUsageAuth 决定 OpenClaw 应调用 fetchUsageSnapshot,还是
回退到通用凭据解析以处理用量/状态界面。当提供商拥有用量凭据时,返回
{ token, accountId?, subscriptionType?, rateLimitTier? }(可选的套餐元数据会流入
fetchUsageSnapshot);当提供商自有的用量认证已处理请求且必须抑制通用 API 密钥/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);
},
});
内置示例¶
捆绑的提供商插件会组合上述钩子,以满足各供应商在目录、认证、思考、重放和用量方面的需求。权威钩子集合位于每个插件的 extensions/ 下;本页用于说明结构,而不是照搬列表。
直通目录提供商
OpenRouter、Kilocode、Z.AI 和 xAI 注册 catalog,并配合
resolveDynamicModel / prepareDynamicModel,以便在 OpenClaw 静态目录之前呈现上游模型 ID。
OAuth 与用量端点提供商
GitHub Copilot、Gemini CLI、ChatGPT Codex、MiniMax、Xiaomi 和 z.ai 将
prepareRuntimeAuth 或 formatApiKey 与 resolveUsageAuth +
fetchUsageSnapshot 配对,以自主处理令牌交换和 /usage 集成。
重放与转录清理家族
共享命名家族(google-gemini、passthrough-gemini、
anthropic-by-model、hybrid-anthropic-openai)让提供商可以通过
buildReplayPolicy 选择加入转录策略,而无需每个插件重新实现清理。
仅目录提供商
byteplus、cloudflare-ai-gateway、huggingface、kimi-coding、nvidia、
qianfan、synthetic、together、venice、vercel-ai-gateway 和
volcengine 仅注册 catalog,并复用共享推理循环。
Anthropic 专用流辅助函数
Beta 请求头、/fast / serviceTier 和 context1m 位于 Anthropic 插件公开的
api.ts / contract-api.ts 接缝中(wrapAnthropicProviderStream、resolveAnthropicBetas、
resolveAnthropicFastMode、resolveAnthropicServiceTier),而不是在通用 SDK 中。
提供商目录¶
提供商插件可以使用
registerProvider({ catalog: { run(...) { ... } } }) 为推理定义模型目录。
catalog.run(...) 返回 OpenClaw 写入
models.providers 的相同结构:
{ provider }表示一个提供商条目{ providers }表示多个提供商条目
当插件拥有提供商特定的模型 ID、基础 URL 默认值或受认证保护的模型元数据时,使用 catalog。
catalog.order 控制插件目录相对于 OpenClaw 内置隐式提供商的合并时机:
simple:普通 API 密钥或环境变量驱动的提供商profile:当存在认证配置时出现的提供商paired:合成多个相关提供商条目的提供商late:最后一轮,在其他隐式提供商之后
在键冲突时,较晚的提供商获胜,因此插件可以有意覆盖具有相同提供商 ID 的内置提供商条目。
插件还可以通过
api.registerModelCatalogProvider({ provider, kinds, staticCatalog, liveCatalog
}) 发布只读模型行。这是列表/帮助/选择器界面的后续路径,支持
text、voice、image_generation、video_generation 和 music_generation
行。提供商插件仍负责实时端点调用、令牌交换和供应商响应映射;核心负责通用行结构、来源标签和媒体工具帮助格式。媒体生成提供商注册会根据 defaultModel、models 和 capabilities 自动合成静态目录行。
兼容性:
discovery曾是catalog的旧版别名。OpenClaw 在 2026.4.26 中移除了该别名及其弃用警告- 将
discovery重命名为catalog。仍注册discovery的提供商插件不会发布任何目录行 augmentModelCatalog已弃用;捆绑提供商应通过registerModelCatalogProvider发布补充行。其移除门槛为 2026-10-01
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw