LLM/moltbot
1
0
Fork 0
mirror of https://github.com/moltbot/moltbot.git synced 2026-04-24 07:01:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: refresh provider transport and synthetic auth refs

Browse Source
This commit is contained in:
Peter Steinberger
2026-04-04 21:31:50 +01:00
parent dd5439dd5b
commit 0fb53f1b90
3 changed files with 97 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
docs/plugins/architecture.md
View File

@@ -612,7 +612,18 @@ Provider plugins now have two layers:
runtime load, plus `providerAuthChoices` for cheap onboarding/auth-choice
labels and CLI flag metadata before runtime load
- config-time hooks: `catalog` / legacy `discovery` plus `applyConfigDefaults`
- runtime hooks: `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveDynamicModel`, `prepareDynamicModel`, `normalizeResolvedModel`, `capabilities`, `prepareExtraParams`, `wrapStreamFn`, `formatApiKey`, `refreshOAuth`, `buildAuthDoctorHint`, `matchesContextOverflowError`, `classifyFailoverReason`, `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`, `resolveDefaultThinkingLevel`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`
- runtime hooks: `normalizeTransport`, `normalizeConfig`,
`applyNativeStreamingUsageCompat`, `resolveConfigApiKey`,
`resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`,
`resolveDynamicModel`, `prepareDynamicModel`, `normalizeResolvedModel`,
`capabilities`, `prepareExtraParams`, `wrapStreamFn`, `formatApiKey`,
`refreshOAuth`, `buildAuthDoctorHint`, `matchesContextOverflowError`,
`classifyFailoverReason`, `isCacheTtlEligible`,
`buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`,
`isBinaryThinking`, `supportsXHighThinking`,
`resolveDefaultThinkingLevel`, `isModernModelRef`, `prepareRuntimeAuth`,
`resolveUsageAuth`, `fetchUsageSnapshot`, `buildReplayPolicy`,
`sanitizeReplayHistory`, `validateReplayTurns`
OpenClaw still owns the generic agent loop, failover, transcript handling, and
tool policy. These hooks are the extension surface for provider-specific behavior without
@@ -636,39 +647,43 @@ The "When to use" column is the quick decision guide.
| 1 | `catalog` | Publish provider config into `models.providers` during `models.json` generation | Provider owns a catalog or base URL defaults |
| 2 | `applyConfigDefaults` | Apply provider-owned global config defaults during config materialization | Defaults depend on auth mode, env, or provider model-family semantics |
| -- | _(built-in model lookup)_ | OpenClaw tries the normal registry/catalog path first | _(not a plugin hook)_ |
| 3 | `normalizeConfig` | Normalize `models.providers.<id>` before runtime/provider resolution | Provider needs config cleanup that should live with the plugin |
| 4 | `applyNativeStreamingUsageCompat` | Apply native streaming-usage compat rewrites to config providers | Provider needs endpoint-driven native streaming usage metadata fixes |
| 5 | `resolveConfigApiKey` | Resolve env-marker auth for config providers before runtime auth loading | Provider has provider-owned env-marker API-key resolution |
| 6 | `resolveDynamicModel` | Sync fallback for provider-owned model ids not in the local registry yet | Provider accepts arbitrary upstream model ids |
| 7 | `prepareDynamicModel` | Async warm-up, then `resolveDynamicModel` runs again | Provider needs network metadata before resolving unknown ids |
| 8 | `normalizeResolvedModel` | Final rewrite before the embedded runner uses the resolved model | Provider needs transport rewrites but still uses a core transport |
| 9 | `capabilities` | Provider-owned transcript/tooling metadata used by shared core logic | Provider needs transcript/provider-family quirks |
| 10 | `prepareExtraParams` | Request-param normalization before generic stream option wrappers | Provider needs default request params or per-provider param cleanup |
| 11 | `wrapStreamFn` | Stream wrapper after generic wrappers are applied | Provider needs request headers/body/model compat wrappers without a custom transport |
| 12 | `formatApiKey` | Auth-profile formatter: stored profile becomes the runtime `apiKey` string | Provider stores extra auth metadata and needs a custom runtime token shape |
| 13 | `refreshOAuth` | OAuth refresh override for custom refresh endpoints or refresh-failure policy | Provider does not fit the shared `pi-ai` refreshers |
| 14 | `buildAuthDoctorHint` | Repair hint appended when OAuth refresh fails | Provider needs provider-owned auth repair guidance after refresh failure |
| 15 | `matchesContextOverflowError` | Provider-owned context-window overflow matcher | Provider has raw overflow errors generic heuristics would miss |
| 16 | `classifyFailoverReason` | Provider-owned failover reason classification | Provider can map raw API/transport errors to rate-limit/overload/etc |
| 17 | `isCacheTtlEligible` | Prompt-cache policy for proxy/backhaul providers | Provider needs proxy-specific cache TTL gating |
| 18 | `buildMissingAuthMessage` | Replacement for the generic missing-auth recovery message | Provider needs a provider-specific missing-auth recovery hint |
| 19 | `suppressBuiltInModel` | Stale upstream model suppression plus optional user-facing error hint | Provider needs to hide stale upstream rows or replace them with a vendor hint |
| 20 | `augmentModelCatalog` | Synthetic/final catalog rows appended after discovery | Provider needs synthetic forward-compat rows in `models list` and pickers |
| 21 | `isBinaryThinking` | On/off reasoning toggle for binary-thinking providers | Provider exposes only binary thinking on/off |
| 22 | `supportsXHighThinking` | `xhigh` reasoning support for selected models | Provider wants `xhigh` on only a subset of models |
| 23 | `resolveDefaultThinkingLevel` | Default `/think` level for a specific model family | Provider owns default `/think` policy for a model family |
| 24 | `isModernModelRef` | Modern-model matcher for live profile filters and smoke selection | Provider owns live/smoke preferred-model matching |
| 25 | `prepareRuntimeAuth` | Exchange a configured credential into the actual runtime token/key just before inference | Provider needs a token exchange or short-lived request credential |
| 26 | `resolveUsageAuth` | Resolve usage/billing credentials for `/usage` and related status surfaces | Provider needs custom usage/quota token parsing or a different usage credential |
| 27 | `fetchUsageSnapshot` | Fetch and normalize provider-specific usage/quota snapshots after auth is resolved | Provider needs a provider-specific usage endpoint or payload parser |
| 28 | `buildReplayPolicy` | Return a replay policy controlling transcript handling for the provider | Provider needs custom transcript policy (for example, thinking-block stripping) |
| 29 | `sanitizeReplayHistory` | Rewrite replay history after generic transcript cleanup | Provider needs provider-specific replay rewrites beyond shared compaction helpers |
| 30 | `validateReplayTurns` | Final replay-turn validation or reshaping before the embedded runner | Provider transport needs stricter turn validation after generic sanitation |
| 3 | `normalizeTransport` | Normalize provider-family `api` / `baseUrl` before generic model assembly | Provider owns transport cleanup for custom provider ids in the same transport family |
| 4 | `normalizeConfig` | Normalize `models.providers.<id>` before runtime/provider resolution | Provider needs config cleanup that should live with the plugin |
| 5 | `applyNativeStreamingUsageCompat` | Apply native streaming-usage compat rewrites to config providers | Provider needs endpoint-driven native streaming usage metadata fixes |
| 6 | `resolveConfigApiKey` | Resolve env-marker auth for config providers before runtime auth loading | Provider has provider-owned env-marker API-key resolution |
| 7 | `resolveSyntheticAuth` | Surface local/self-hosted or config-backed auth without persisting plaintext | Provider can operate with a synthetic/local credential marker |
| 8 | `shouldDeferSyntheticProfileAuth` | Lower stored synthetic profile placeholders behind env/config-backed auth | Provider stores synthetic placeholder profiles that should not win precedence |
| 9 | `resolveDynamicModel` | Sync fallback for provider-owned model ids not in the local registry yet | Provider accepts arbitrary upstream model ids |
| 10 | `prepareDynamicModel` | Async warm-up, then `resolveDynamicModel` runs again | Provider needs network metadata before resolving unknown ids |
| 11 | `normalizeResolvedModel` | Final rewrite before the embedded runner uses the resolved model | Provider needs transport rewrites but still uses a core transport |
| 12 | `capabilities` | Provider-owned transcript/tooling metadata used by shared core logic | Provider needs transcript/provider-family quirks |
| 13 | `prepareExtraParams` | Request-param normalization before generic stream option wrappers | Provider needs default request params or per-provider param cleanup |
| 14 | `wrapStreamFn` | Stream wrapper after generic wrappers are applied | Provider needs request headers/body/model compat wrappers without a custom transport |
| 15 | `formatApiKey` | Auth-profile formatter: stored profile becomes the runtime `apiKey` string | Provider stores extra auth metadata and needs a custom runtime token shape |
| 16 | `refreshOAuth` | OAuth refresh override for custom refresh endpoints or refresh-failure policy | Provider does not fit the shared `pi-ai` refreshers |
| 17 | `buildAuthDoctorHint` | Repair hint appended when OAuth refresh fails | Provider needs provider-owned auth repair guidance after refresh failure |
| 18 | `matchesContextOverflowError` | Provider-owned context-window overflow matcher | Provider has raw overflow errors generic heuristics would miss |
| 19 | `classifyFailoverReason` | Provider-owned failover reason classification | Provider can map raw API/transport errors to rate-limit/overload/etc |
| 20 | `isCacheTtlEligible` | Prompt-cache policy for proxy/backhaul providers | Provider needs proxy-specific cache TTL gating |
| 21 | `buildMissingAuthMessage` | Replacement for the generic missing-auth recovery message | Provider needs a provider-specific missing-auth recovery hint |
| 22 | `suppressBuiltInModel` | Stale upstream model suppression plus optional user-facing error hint | Provider needs to hide stale upstream rows or replace them with a vendor hint |
| 23 | `augmentModelCatalog` | Synthetic/final catalog rows appended after discovery | Provider needs synthetic forward-compat rows in `models list` and pickers |
| 24 | `isBinaryThinking` | On/off reasoning toggle for binary-thinking providers | Provider exposes only binary thinking on/off |
| 25 | `supportsXHighThinking` | `xhigh` reasoning support for selected models | Provider wants `xhigh` on only a subset of models |
| 26 | `resolveDefaultThinkingLevel` | Default `/think` level for a specific model family | Provider owns default `/think` policy for a model family |
| 27 | `isModernModelRef` | Modern-model matcher for live profile filters and smoke selection | Provider owns live/smoke preferred-model matching |
| 28 | `prepareRuntimeAuth` | Exchange a configured credential into the actual runtime token/key just before inference | Provider needs a token exchange or short-lived request credential |
| 29 | `resolveUsageAuth` | Resolve usage/billing credentials for `/usage` and related status surfaces | Provider needs custom usage/quota token parsing or a different usage credential |
| 30 | `fetchUsageSnapshot` | Fetch and normalize provider-specific usage/quota snapshots after auth is resolved | Provider needs a provider-specific usage endpoint or payload parser |
| 31 | `buildReplayPolicy` | Return a replay policy controlling transcript handling for the provider | Provider needs custom transcript policy (for example, thinking-block stripping) |
| 32 | `sanitizeReplayHistory` | Rewrite replay history after generic transcript cleanup | Provider needs provider-specific replay rewrites beyond shared compaction helpers |
| 33 | `validateReplayTurns` | Final replay-turn validation or reshaping before the embedded runner | Provider transport needs stricter turn validation after generic sanitation |
`normalizeConfig` first checks the matched provider plugin, then falls through
other hook-capable provider plugins until one actually changes the config. That
keeps alias/compat provider shims working without requiring the caller to know
which bundled plugin owns the rewrite.
`normalizeTransport` and `normalizeConfig` first check the matched provider
plugin, then fall through other hook-capable provider plugins until one
actually changes the transport/config. That keeps alias/compat provider shims
working without requiring the caller to know which bundled plugin owns the
rewrite.
If the provider needs a fully custom wire protocol or custom request executor,
that is a different class of extension. These hooks are for provider behavior

73
docs/plugins/sdk-provider-plugins.md
View File

@@ -460,41 +460,44 @@ API key auth, and dynamic model resolution.
| --- | --- | --- |
| 1 | `catalog` | Model catalog or base URL defaults |
| 2 | `applyConfigDefaults` | Provider-owned global defaults during config materialization |
| 3 | `normalizeConfig` | Normalize `models.providers.<id>` config |
| 4 | `applyNativeStreamingUsageCompat` | Native streaming-usage compat rewrites for config providers |
| 5 | `resolveConfigApiKey` | Provider-owned env-marker auth resolution |
| 6 | `resolveDynamicModel` | Accept arbitrary upstream model IDs |
| 7 | `prepareDynamicModel` | Async metadata fetch before resolving |
| 8 | `normalizeResolvedModel` | Transport rewrites before the runner |
| 9 | `capabilities` | Legacy static capability bag; compatibility only |
| 10 | `buildReplayPolicy` | Custom transcript replay/compaction policy |
| 11 | `sanitizeReplayHistory` | Provider-specific replay rewrites after generic cleanup |
| 12 | `validateReplayTurns` | Strict replay-turn validation before the embedded runner |
| 13 | `normalizeToolSchemas` | Provider-owned tool-schema cleanup before registration |
| 14 | `inspectToolSchemas` | Provider-owned tool-schema diagnostics |
| 15 | `resolveReasoningOutputMode` | Tagged vs native reasoning-output contract |
| 16 | `prepareExtraParams` | Default request params |
| 17 | `createStreamFn` | Fully custom StreamFn transport |
| 18 | `wrapStreamFn` | Custom headers/body wrappers on the normal stream path |
| 19 | `resolveTransportTurnState` | Native per-turn headers/metadata |
| 20 | `resolveWebSocketSessionPolicy` | Native WS session headers/cool-down |
| 21 | `formatApiKey` | Custom runtime token shape |
| 22 | `refreshOAuth` | Custom OAuth refresh |
| 23 | `buildAuthDoctorHint` | Auth repair guidance |
| 24 | `matchesContextOverflowError` | Provider-owned overflow detection |
| 25 | `classifyFailoverReason` | Provider-owned rate-limit/overload classification |
| 26 | `isCacheTtlEligible` | Prompt cache TTL gating |
| 27 | `buildMissingAuthMessage` | Custom missing-auth hint |
| 28 | `suppressBuiltInModel` | Hide stale upstream rows |
| 29 | `augmentModelCatalog` | Synthetic forward-compat rows |
| 30 | `isBinaryThinking` | Binary thinking on/off |
| 31 | `supportsXHighThinking` | `xhigh` reasoning support |
| 32 | `resolveDefaultThinkingLevel` | Default `/think` policy |
| 33 | `isModernModelRef` | Live/smoke model matching |
| 34 | `prepareRuntimeAuth` | Token exchange before inference |
| 35 | `resolveUsageAuth` | Custom usage credential parsing |
| 36 | `fetchUsageSnapshot` | Custom usage endpoint |
| 37 | `onModelSelected` | Post-selection callback (e.g. telemetry) |
| 3 | `normalizeTransport` | Provider-family `api` / `baseUrl` cleanup before generic model assembly |
| 4 | `normalizeConfig` | Normalize `models.providers.<id>` config |
| 5 | `applyNativeStreamingUsageCompat` | Native streaming-usage compat rewrites for config providers |
| 6 | `resolveConfigApiKey` | Provider-owned env-marker auth resolution |
| 7 | `resolveSyntheticAuth` | Local/self-hosted or config-backed synthetic auth |
| 8 | `shouldDeferSyntheticProfileAuth` | Lower synthetic stored-profile placeholders behind env/config auth |
| 9 | `resolveDynamicModel` | Accept arbitrary upstream model IDs |
| 10 | `prepareDynamicModel` | Async metadata fetch before resolving |
| 11 | `normalizeResolvedModel` | Transport rewrites before the runner |
| 12 | `capabilities` | Legacy static capability bag; compatibility only |
| 13 | `buildReplayPolicy` | Custom transcript replay/compaction policy |
| 14 | `sanitizeReplayHistory` | Provider-specific replay rewrites after generic cleanup |
| 15 | `validateReplayTurns` | Strict replay-turn validation before the embedded runner |
| 16 | `normalizeToolSchemas` | Provider-owned tool-schema cleanup before registration |
| 17 | `inspectToolSchemas` | Provider-owned tool-schema diagnostics |
| 18 | `resolveReasoningOutputMode` | Tagged vs native reasoning-output contract |
| 19 | `prepareExtraParams` | Default request params |
| 20 | `createStreamFn` | Fully custom StreamFn transport |
| 21 | `wrapStreamFn` | Custom headers/body wrappers on the normal stream path |
| 22 | `resolveTransportTurnState` | Native per-turn headers/metadata |
| 23 | `resolveWebSocketSessionPolicy` | Native WS session headers/cool-down |
| 24 | `formatApiKey` | Custom runtime token shape |
| 25 | `refreshOAuth` | Custom OAuth refresh |
| 26 | `buildAuthDoctorHint` | Auth repair guidance |
| 27 | `matchesContextOverflowError` | Provider-owned overflow detection |
| 28 | `classifyFailoverReason` | Provider-owned rate-limit/overload classification |
| 29 | `isCacheTtlEligible` | Prompt cache TTL gating |
| 30 | `buildMissingAuthMessage` | Custom missing-auth hint |
| 31 | `suppressBuiltInModel` | Hide stale upstream rows |
| 32 | `augmentModelCatalog` | Synthetic forward-compat rows |
| 33 | `isBinaryThinking` | Binary thinking on/off |
| 34 | `supportsXHighThinking` | `xhigh` reasoning support |
| 35 | `resolveDefaultThinkingLevel` | Default `/think` policy |
| 36 | `isModernModelRef` | Live/smoke model matching |
| 37 | `prepareRuntimeAuth` | Token exchange before inference |
| 38 | `resolveUsageAuth` | Custom usage credential parsing |
| 39 | `fetchUsageSnapshot` | Custom usage endpoint |
| 40 | `onModelSelected` | Post-selection callback (e.g. telemetry) |
For detailed descriptions and real-world examples, see
[Internals: Provider Runtime Hooks](/plugins/architecture#provider-runtime-hooks).