钩子接线
当 family builder 未覆盖该行为时,单独接入 provider 钩子。这是构建 provider 插件指南的一部分;对于共享 builder,请从Provider 钩子族开始。
模型路由策略¶
轻量级 provider-policy-api 工件通过 resolveModelRoutes 解析模型路由。其上下文和结果类型由 openclaw/plugin-sdk/provider-model-types 导出。
ProviderResolveModelRoutesContext.routeIntent 携带已准备好的、不含密钥的 consumer intent:可选的 runtimeId、可选的 authRequirement("subscription" 或 "api-key"),以及 source("explicit" 或 "inherited")。宿主会投射现有的 model/provider 策略和继承的 agent 默认值;插件不得重新加载配置或凭据来重建它。这一事实不会授予凭据访问权限,也不会改变哪些 runtime 可以执行某个路由。
带有 kind: "routes" 的 ProviderModelRouteResolution 可以设置 preferredAuthRequirement。Core 仅当两种认证类别都有符合条件的 profile 且选择为自动时,才应用该偏好。准备和可用性应用相同的优先级:必需的 consumer 或 provider profile 绑定会选择账户;已配置的 provider 认证会将自动选择限制到该计费路由;显式 auth 顺序会对剩余符合条件的 profile 排序。继承的 routeIntent 和 preferredAuthRequirement 仅在这些选择之后用于打破平局。环境凭据提供回退材料,而不会清除已配置的认证;仅当未配置 mode 时,才会推断其 mode。偏好不会创建凭据,也不会使不可用或处于 cooldown 阻塞状态的 profile 变为符合条件。单类别选择保持其现有行为。
候选顺序仍与凭据优先级相互独立,runtimePolicy.compatibleIds 继续描述执行兼容性。例如,OpenAI 使用遗留的官方 Completions 适配器,为受支持的模型保持两条路由可用,当两种类型都符合条件时优先使用 subscription 认证,并遵循显式 API 路由意图。这些是现有契约上的附加字段;它们不会新增 hook 或用户设置。
凭据查找取消¶
使用 openclaw/plugin-sdk/provider-auth-runtime 中 resolveApiKeyForProvider 的凭据消费者应传入其请求的可选 signal。它会结束调用方对排队准入、profile 锁或 OAuth settlement 的等待,而不是结束已认领的 refresh 的凭据写入。已开始的锁获取在清理前仍保持所有权。应保留非缺失的认证错误,而不是将每个失败都转换为缺失的 API key。
openclaw/plugin-sdk/extension-shared 中的 buildTimeoutAbortSignal 将调用方 signal 与操作超时组合在一起。当认证共享请求预算时,应在凭据准备之前启动它,并在 finally 中调用其 cleanup 以释放计时器。
钩子示例¶
对于需要在每次推理调用前进行 token 交换的 provider:
对于需要自定义请求头或 body 修改的 provider:
// wrapStreamFn returns a StreamFn derived from ctx.streamFn
wrapStreamFn: (ctx) => {
if (!ctx.streamFn) return undefined;
const inner = ctx.streamFn;
return (model, context, options) =>
inner(model, context, {
...options,
headers: {
...options?.headers,
"X-Acme-Version": "2",
},
});
},
现有 wrapper 仍可以传递已弃用的 maxRetries stream 选项,包括 0。内置 text transport 会忽略它:嵌入式 runner 拥有重试预算,SDK 内部重试保持禁用。新 wrapper 应省略该选项。此已发布的 source contract 将保留,直到未来的 Plugin SDK 主版本发布,并且已发布插件 reader sweep 确认移除安全为止;它不会改变 image-generation 或 native-runtime 重试策略。
对于需要在通用 HTTP 或 WebSocket transport 上使用原生 request/session 头或元数据的 provider:
resolveTransportTurnState: (ctx) => ({
headers: {
"x-request-id": ctx.turnId,
},
metadata: {
session_id: ctx.sessionId ?? "",
turn_id: ctx.turnId,
},
websocket: {
headers: {
"x-session-id": ctx.sessionId ?? "",
},
degradeCooldownMs: 60_000,
},
}),
旧的 resolveWebSocketSessionPolicy hook 仍受支持,但已弃用。将其字段移到 resolveTransportTurnState.websocket 下;迁移期间,新 hook 的字段优先。该 hook 仅带有 TypeScript @deprecated 注释:它没有 compatibility-registry 记录,因此没有已发布的移除日期。对于有移除日期的 surface,请参阅移除时间线。
对于暴露 usage/billing 数据的 provider:
resolveUsageAuth: async (ctx) => {
const auth = await ctx.resolveOAuthToken();
return auth ? { token: auth.token } : null;
},
fetchUsageSnapshot: async (ctx) => {
// fetchAcmeUsage is your plugin's own vendor API call, not an SDK export.
return await fetchAcmeUsage(ctx.token, ctx.timeoutMs, {
fetch: ctx.fetchFn,
signal: ctx.signal,
});
},
两个 usage hook 都会接收可选的 ctx.signal,用于取消采集。ctx.fetchFn 已经将其与请求取消组合在一起;自定义 transport 必须将 ctx.signal 转发到其 I/O。在 await 之后开始额外 auth 工作之前,应检查取消。预算耗尽时不会调用任一 hook,并会生成可见的 Timeout snapshot。Core 会保留已完成的 sibling,并通过清理跟踪未完成的工作,包括 auth 拥有的凭据 refresh。
resolveUsageAuth 有三种结果。当提供商具有用量/计费凭据时,返回
{ token, accountId?, subscriptionType?, rateLimitTier? }(可选字段会将已解析配置文件中的非机密套餐元数据带入
fetchUsageSnapshot)。仅当提供商已明确处理用量认证但没有可用的用量令牌,且 OpenClaw 必须跳过通用
API 密钥/OAuth 回退时,才返回
{ handled: true }。当提供商未处理该请求且 OpenClaw 应继续执行通用回退时,返回 null 或 undefined。
在 `contracts.usageProviders` 中声明提供商 ID。当该清单契约和**两个**钩子都存在时,OpenClaw 会自动将该提供商纳入用量收集,而无需加载无关的提供商插件。无需更新核心允许列表。
`fetchUsageSnapshot` 返回共享的提供商无关结构:
- `plan`:提供商报告的订阅或密钥标签
- `windows`:以使用百分比表示的可重置配额窗口
- `billing`:带类型的 `balance`、`spend` 或 `budget` 条目;`unit` 可以是 ISO 货币或提供商单位(例如 `credits`)
- `summary`:无法放入上述结构化字段的紧凑提供商特定上下文
保持货币语义精确。除非上游契约明确说明,否则提供商积分不是美元。仅实现
`fetchUsageSnapshot` 的插件仍可供显式/合成调用方使用,但不会被自动发现,因为 OpenClaw 无法解析其用量凭据。
仅当提供商注册的 createStreamFn 传输能够理解稳定/动态系统提示边界时,才在提供商注册上设置
supportsSystemPromptCacheBoundary: true。使用来自
openclaw/plugin-sdk/provider-transport-runtime 的 splitSystemPromptCacheBoundary 对稳定前缀单独设置检查点,并在发送任何负载之前消费标记。
当缓存被禁用时,使用 stripSystemPromptCacheBoundary。默认情况下,
OpenClaw 会在调用自定义传输之前移除标记。
对于累积 JSON 工具参数的自定义 createStreamFn 传输,请使用来自 openclaw/plugin-sdk/llm 的
createToolArgumentPreviewSchedule()。为每个工具调用创建一个调度,并在调用 parseStreamingJson 之前将累积原始字符串的长度传入该调度。返回的函数允许在几何增长检查点处刷新预览,因此在原始片段到达时,中间 arguments 快照可以保持不变。继续发出每个原始增量,并在传输的终端边界处验证完整参数,即使最后一次预览未刷新。
常见提供商钩子
OpenClaw 大致按此顺序为模型/提供商插件调用钩子。
大多数提供商只使用 2-3 个。这不是完整的 ProviderPlugin
契约——请参阅内部机制:提供商运行时钩子以获取完整且当前准确的钩子列表和回退说明。
OpenClaw 不再调用的仅用于兼容性的提供商字段(例如
ProviderPlugin.capabilities 和 suppressBuiltInModel)未在此列出。
保持 resolveSyntheticAuth 同步且有界。外部进程/网络登录检查应放在 prepareSyntheticAuth 中,该函数接收捕获的配置、环境和取消信号,并返回合成认证结果或无结果。OpenClaw 会在该准备代内保留已完成的可用性。只读工作进程会接收最终的 provider-ref 结果(包括不可用),从而在不重新运行外部检查的情况下保留别名优先级。已取消的准备必须在清理后拒绝,而不是报告缺少登录。
| 钩子 | 使用时机 |
|---|---|
catalog |
模型目录或基础 URL 默认值 |
applyConfigDefaults |
配置实例化期间由提供商拥有的全局默认值 |
normalizeModelId |
查找前对旧版/预览模型 ID 别名的清理 |
normalizeTransport |
通用模型组装前对提供商家族的 api / baseUrl 清理 |
normalizeConfig |
规范化 models.providers.<id> 配置 |
applyNativeStreamingUsageCompat |
针对配置提供商的原生流式用量兼容性重写 |
resolveConfigApiKey |
由提供商拥有的环境变量标记认证解析 |
resolveSyntheticAuth |
本地/自托管或基于配置的合成认证 |
prepareSyntheticAuth |
在同步可用性读取之前异步验证外部认证 |
resolveExternalAuthProfiles |
为 CLI/应用管理的凭据叠加由提供商拥有的外部认证配置文件 |
shouldDeferSyntheticProfileAuth |
将合成存储配置文件占位符置于环境变量/配置认证之后 |
resolveDynamicModel |
接受任意上游模型 ID |
prepareDynamicModel |
返回异步发现的模型,或在同步解析前预热可重用元数据 |
normalizeResolvedModel |
运行器之前的传输重写 |
normalizeToolSchemas |
注册前由提供商拥有的工具模式清理 |
| 钩子 | 使用时机 |
|---|---|
inspectToolSchemas |
Provider 拥有的工具模式诊断 |
resolveReasoningOutputMode |
带标签与原生推理输出契约 |
prepareExtraParams |
默认请求参数 |
createStreamFn |
完全自定义 StreamFn 传输 |
wrapStreamFn |
在常规流路径上自定义请求头/请求体包装器 |
reconcileLocalService |
健康检查后、每次请求前的低成本、幂等托管服务修复 |
resolveTransportTurnState |
原生每轮请求头/元数据以及 WebSocket 请求头/冷却 |
resolveWebSocketSessionPolicy |
已弃用的 WebSocket 兼容性钩子;请使用 resolveTransportTurnState |
formatApiKey |
自定义运行时令牌形状 |
loginOAuth |
基于回调的 OAuth 登录,用于会话 SDK 的 AuthStorage API |
refreshOAuth |
自定义 OAuth 刷新 |
buildAuthDoctorHint |
认证修复指导 |
matchesContextOverflowError |
Provider 拥有的溢出检测 |
classifyFailoverReason |
Provider 拥有的速率限制/过载分类 |
isCacheTtlEligible |
Prompt 缓存 TTL 门控 |
buildMissingAuthMessage |
自定义缺少认证提示 |
augmentModelCatalog |
合成前向兼容行(已弃用 - 建议使用 registerModelCatalogProvider) |
resolveThinkingProfile |
特定于模型的 /think 选项集 |
isBinaryThinking |
二元思考开/关兼容性(已弃用 - 建议使用 resolveThinkingProfile) |
supportsXHighThinking |
xhigh 推理支持兼容性(已弃用 - 建议使用 resolveThinkingProfile) |
resolveDefaultThinkingLevel |
默认 /think 策略兼容性(已弃用 - 建议使用 resolveThinkingProfile) |
isModernModelRef |
实时/冒烟模型匹配 |
prepareRuntimeAuth |
推理前的令牌交换 |
resolveUsageAuth |
自定义用量凭据解析 |
fetchUsageSnapshot |
自定义用量端点 |
createEmbeddingProvider |
Provider 拥有的用于记忆/搜索的嵌入适配器 |
buildReplayPolicy |
自定义转录重放/压缩策略 |
sanitizeReplayHistoryAsync |
在通用清理后,使用等待的转录元数据执行 Provider 特定的重放重写 |
sanitizeReplayHistory |
已弃用的第三方重放兼容性钩子;请迁移到 sanitizeReplayHistoryAsync |
validateReplayTurns |
在嵌入式运行器之前进行严格的重放轮次验证 |
onModelSelected |
选择后回调(例如遥测) |
reconcileLocalService 仅针对已配置的本地服务调用,
包括由重启后的 Gateway 复用的健康进程。请遵循其
中止信号,并在协调失败时拒绝;OpenClaw 会阻止
Provider 请求并释放请求租约。
运行时回退说明:
isCacheTtlEligible(ctx)接收provider、modelId、可选的modelApi,以及已解析的路由事实baseUrl和supportsPromptCacheKey。安装缓存 TTL 修剪和记录缓存访问时使用相同的有界上下文;它不包含完整模型、请求头或额外请求参数。OpenAI 在官方 Platform 和 Codex 端点上默认符合条件,遵循显式的supportsPromptCacheKey: false,并且自定义代理路由需要显式选择加入。这控制客户端空闲修剪,而非保证 Provider 缓存命中。- 错误分类使用已准备的 Provider 所有者或已加载的 Provider 钩子。
matchesContextOverflowError和classifyFailoverReason在处理错误时绝不会触发插件发现;Provider 准备负责加载这些钩子。 - 配置组装仅通过所属捆绑 Provider 的轻量级策略表面调用
normalizeConfig,而不加载 Provider 运行时或扫描其他 Provider。Google 自身的钩子通过该表面规范化google/google-vertex/google-antigravity配置项。 - 配置组装同样使用轻量级策略表面来处理
resolveConfigApiKey。Amazon Bedrock 在其 Provider 插件中保留 AWS 环境变量标记解析;当配置为auth: "aws-sdk"时,运行时认证本身仍使用 AWS SDK 默认链。 resolveThinkingProfile(ctx)接收所选的provider、modelId、可选目录路由事实api和baseUrl、可选合并的reasoning目录提示,以及可选合并的模型compat事实。仅使用compat来选择 Provider 的思考 UI/配置文件。- 当 Provider 具有首选的嵌入式摘要强度时,
normalizeResolvedModel(ctx)可以在返回的ProviderRuntimeModel上设置compactionThinkingDefault。这是已准备的运行时元数据,而不是操作员设置或目录字段。显式的agents.defaults.compaction.thinkingLevel优先;否则宿主使用此偏好,然后使用low。所选强度仍会被限制在实际压缩候选范围内。 resolveSystemPromptContribution允许 Provider 为某个模型系列注入缓存感知的系统提示指导。当行为属于某个 Provider/模型系列且应保留稳定/动态缓存拆分时,请优先使用它而不是遗留的插件级before_prompt_build钩子。
捆绑的 HTTP 适配器可以使用私有本地 openclaw/plugin-sdk/provider-http 入口点中的 createProviderHttpError 保留数值响应状态。已经绑定并脱敏其诊断信息的适配器可以构造 ProviderHttpError(message, { status })。在调整其消息时保留该错误实例,以便状态和重试元数据得以保留;搜索工具使用这些字段进行安全的身份验证和配额指导,而不会暴露响应主体。
捆绑的以及受信任的官方提供商策略可以使用私有 openclaw/plugin-sdk/provider-thinking-runtime 辅助函数中的 resolveEffortThinkingProfile(compat?.supportedReasoningEfforts)。它接受精确的 off、minimal、low、medium、high、xhigh 和 max 值,将 none 映射为 off,并在保留其余每个级别首次出现的同时前置 off。默认偏好顺序为 medium、high、low,然后是 off。缺失、null 或空元数据返回 undefined;不包含受支持值的非空列表返回仅包含 off 的配置文件。将模型特定覆盖和 API 回退保留在提供商策略中。
提供商流适配器可以调用 openclaw/plugin-sdk/llm 中的 resolveOpenAIRequestReasoning(model, level),通过共享传输所有者解析已声明的努力级别、原生标签映射、逻辑 Off 以及标量努力禁用。将其 effort 和 thinkingEnabled 结果转换为提供商的线路方言,而不是定义另一个努力级别阶梯。在回退到包装器上下文之前,先从每个流调用的选项中读取级别。
捆绑的以及受信任的官方插件还可以从其轻量级 provider-policy-api 工件中导出 resolveToolSearchMode(ctx)。上下文包含最终的 provider、modelId、api 以及可选的 baseUrl;其类型从 openclaw/plugin-sdk/provider-model-types 导出。返回 "tools" 以优先使用结构化 Tool Search,返回 false 以否决托管本地服务默认值,或返回 undefined 以将该决定留给宿主。宿主会将结果记录在已解析的运行时模型上,而不是写入配置。显式的 tools.toolSearch 设置具有优先权。此钩子改变的是模式暴露,而不是工具权限或可用性。
当提供商提供托管搜索时,可以从同一策略工件中导出 resolveNativeWebSearch(ctx)。其 ProviderNativeWebSearchPolicyContext(来自 openclaw/plugin-sdk/provider-model-types)包含 config、provider、可选的 modelId、api 和 baseUrl。仅当该路由将注入托管搜索时返回 true;将此策略与负载构造共享。保持该钩子为同步,并且不包含运行时激活或凭据检查。宿主独立应用工具权限,并在构建 Tool Search 和 Code Mode 目录之前移除托管的 web_search。显式的托管提供商选择必须保持权威。
resolveFastModeSupport(ctx) 可以从同一策略工件中导出并注册到提供商上。仅当确认某个 Fast 选项为无操作时返回 false,当存在适用的本地请求映射时返回 true,或在事实缺失时返回 undefined。ProviderFastModePolicyContext 携带所选模型、路由、身份验证模式、运行时、请求参数和传输策略;不包含凭据。将此策略与请求构造共享。宿主仅发布 supportsFastMode,保留未知行为并清除已保存的偏好。这描述的是本地适用性,而不是上游授权或履约,并且不会拒绝 /fast 命令。
resolveServiceTiers(ctx) 可以通过同一轻量级工件和提供商注册发布已知的模型/路由层级限制。它接收 ProviderFastModePolicyContext;当提供商没有要添加的限制时返回 undefined。API 密钥 OpenAI Responses 目录会将返回的列表与账户观察结果或其路由默认值求交集,并保留 "default" 作为 Standard 处理。false 的 Fast 能力与 ["default"] 一起使 Control UI 保持禁用的 Standard 控件,而不会将显式配置的层级与模型限制混淆。将此能力决定与提供商请求构建器共享;它本身不会更改配置或授予访问权限。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw