mirror of https://github.com/openclaw/openclaw.git
docs: refresh provider sdk hook docs
This commit is contained in:
Peter Steinberger
parent
d1bf2c6de1
commit
75fb29ffe6
|
|
@ -79,10 +79,11 @@ subpaths is in `scripts/lib/plugin-sdk-entrypoints.json`.
|
|||
| --- | --- |
|
||||
| `plugin-sdk/cli-backend` | CLI backend defaults + watchdog constants |
|
||||
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile` |
|
||||
| `plugin-sdk/provider-model-shared` | `normalizeModelCompat` |
|
||||
| `plugin-sdk/provider-model-shared` | `normalizeModelCompat`, `buildProviderReplayFamilyHooks` |
|
||||
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog` |
|
||||
| `plugin-sdk/provider-tools` | `buildProviderToolCompatFamilyHooks`, Gemini schema helpers |
|
||||
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` and similar |
|
||||
| `plugin-sdk/provider-stream` | Stream wrapper types |
|
||||
| `plugin-sdk/provider-stream` | Stream wrapper types + provider stream wrappers |
|
||||
| `plugin-sdk/provider-onboard` | Onboarding config patch helpers |
|
||||
| `plugin-sdk/global-singleton` | Process-local singleton/map/cache helpers |
|
||||
</Accordion>
|
||||
|
|
|
|||
|
|
@ -242,6 +242,36 @@ API key auth, and dynamic model resolution.
|
|||
Most providers only need `catalog` + `resolveDynamicModel`. Add hooks
|
||||
incrementally as your provider requires them.
|
||||
|
||||
Shared helper builders now cover the most common replay/tool-compat
|
||||
families, so plugins usually do not need to hand-wire each hook one by one:
|
||||
|
||||
```typescript
|
||||
import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared";
|
||||
import { buildProviderToolCompatFamilyHooks } from "openclaw/plugin-sdk/provider-tools";
|
||||
import { createGoogleThinkingPayloadWrapper } from "openclaw/plugin-sdk/provider-stream";
|
||||
|
||||
const GOOGLE_FAMILY_HOOKS = {
|
||||
...buildProviderReplayFamilyHooks({ family: "google-gemini" }),
|
||||
wrapStreamFn: (ctx) =>
|
||||
createGoogleThinkingPayloadWrapper(ctx.streamFn, ctx.thinkingLevel),
|
||||
...buildProviderToolCompatFamilyHooks("gemini"),
|
||||
};
|
||||
|
||||
api.registerProvider({
|
||||
id: "acme-gemini-compatible",
|
||||
// ...
|
||||
...GOOGLE_FAMILY_HOOKS,
|
||||
});
|
||||
```
|
||||
|
||||
Available replay families today:
|
||||
|
||||
- `openai-compatible`
|
||||
- `anthropic-by-model`
|
||||
- `google-gemini`
|
||||
- `passthrough-gemini`
|
||||
- `hybrid-anthropic-openai`
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Token exchange">
|
||||
For providers that need a token exchange before each inference call:
|
||||
|
|
@ -320,34 +350,40 @@ 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 | `resolveDynamicModel` | Accept arbitrary upstream model IDs |
|
||||
| 5 | `prepareDynamicModel` | Async metadata fetch before resolving |
|
||||
| 6 | `normalizeResolvedModel` | Transport rewrites before the runner |
|
||||
| 7 | `capabilities` | Transcript/tooling metadata (data, not callable) |
|
||||
| 8 | `prepareExtraParams` | Default request params |
|
||||
| 9 | `wrapStreamFn` | Custom headers/body wrappers |
|
||||
| 10 | `resolveTransportTurnState` | Native per-turn headers/metadata |
|
||||
| 11 | `resolveWebSocketSessionPolicy` | Native WS session headers/cool-down |
|
||||
| 12 | `formatApiKey` | Custom runtime token shape |
|
||||
| 13 | `refreshOAuth` | Custom OAuth refresh |
|
||||
| 14 | `buildAuthDoctorHint` | Auth repair guidance |
|
||||
| 15 | `matchesContextOverflowError` | Provider-owned overflow detection |
|
||||
| 16 | `classifyFailoverReason` | Provider-owned rate-limit/overload classification |
|
||||
| 17 | `isCacheTtlEligible` | Prompt cache TTL gating |
|
||||
| 18 | `buildMissingAuthMessage` | Custom missing-auth hint |
|
||||
| 19 | `suppressBuiltInModel` | Hide stale upstream rows |
|
||||
| 20 | `augmentModelCatalog` | Synthetic forward-compat rows |
|
||||
| 21 | `isBinaryThinking` | Binary thinking on/off |
|
||||
| 22 | `supportsXHighThinking` | `xhigh` reasoning support |
|
||||
| 23 | `resolveDefaultThinkingLevel` | Default `/think` policy |
|
||||
| 24 | `isModernModelRef` | Live/smoke model matching |
|
||||
| 25 | `prepareRuntimeAuth` | Token exchange before inference |
|
||||
| 26 | `resolveUsageAuth` | Custom usage credential parsing |
|
||||
| 27 | `fetchUsageSnapshot` | Custom usage endpoint |
|
||||
| 28 | `onModelSelected` | Post-selection callback (e.g. telemetry) |
|
||||
| 29 | `buildReplayPolicy` | Custom transcript policy (e.g. thinking-block stripping) |
|
||||
| 30 | `sanitizeReplayHistory` | Provider-specific replay rewrites after generic cleanup |
|
||||
| 31 | `validateReplayTurns` | Strict replay-turn validation before the embedded runner |
|
||||
| 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) |
|
||||
|
||||
For detailed descriptions and real-world examples, see
|
||||
[Internals: Provider Runtime Hooks](/plugins/architecture#provider-runtime-hooks).
|
||||
|
|
|
|||
Loading…
Reference in New Issue