diff --git a/docs/plugins/building-plugins.md b/docs/plugins/building-plugins.md index a39bf1c3888..56fea5ed3c5 100644 --- a/docs/plugins/building-plugins.md +++ b/docs/plugins/building-plugins.md @@ -38,6 +38,12 @@ falls back to npm automatically. +If a channel plugin is optional and may not be installed when onboarding/setup +runs, use `createOptionalChannelSetupSurface(...)` from +`openclaw/plugin-sdk/channel-setup`. It produces a setup adapter + wizard pair +that advertises the install requirement and fails closed on real config writes +until the plugin is installed. + ## Quick start: tool plugin This walkthrough creates a minimal plugin that registers an agent tool. Channel diff --git a/docs/plugins/sdk-channel-plugins.md b/docs/plugins/sdk-channel-plugins.md index 6048aea5682..76a5acb2781 100644 --- a/docs/plugins/sdk-channel-plugins.md +++ b/docs/plugins/sdk-channel-plugins.md @@ -93,10 +93,22 @@ For setup specifically: delegated setup-proxy builders - `openclaw/plugin-sdk/setup-adapter-runtime` is the narrow env-aware adapter seam for `createEnvPatchedAccountSetupAdapter` +- `openclaw/plugin-sdk/channel-setup` covers the optional-install setup + builders plus a few setup-safe primitives: + `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, + `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, + `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, and + `splitSetupEntries` - use the broader `openclaw/plugin-sdk/setup` seam only when you also need the heavier shared setup/config helpers such as `moveSingleAccountChannelSectionToDefaultAccount(...)` +If your channel only wants to advertise "install this plugin first" in setup +surfaces, prefer `createOptionalChannelSetupSurface(...)`. The generated +adapter/wizard fail closed on config writes and finalization, and they reuse +the same install-required message across validation, finalize, and docs-link +copy. + For other hot channel paths, prefer the narrow helpers over broader legacy surfaces: diff --git a/docs/plugins/sdk-migration.md b/docs/plugins/sdk-migration.md index 221f21f9c0f..43e21925695 100644 --- a/docs/plugins/sdk-migration.md +++ b/docs/plugins/sdk-migration.md @@ -163,12 +163,12 @@ Current bundled provider examples: | `plugin-sdk/setup` | Shared setup wizard helpers | Allowlist prompts, setup status builders | | `plugin-sdk/setup-runtime` | Setup-time runtime helpers | Lookup-note helpers, `promptResolvedAllowFrom`, `splitSetupEntries`, delegated setup proxies | | `plugin-sdk/setup-adapter-runtime` | Setup adapter helpers | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | Setup tooling helpers | CLI/archive/docs helpers for setup/install flows | + | `plugin-sdk/setup-tools` | Setup tooling helpers | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | | `plugin-sdk/account-core` | Multi-account helpers | Account list/config/action-gate helpers | | `plugin-sdk/account-id` | Account-id helpers | `DEFAULT_ACCOUNT_ID`, account-id normalization | | `plugin-sdk/account-resolution` | Account lookup helpers | Account lookup + default-fallback helpers | | `plugin-sdk/account-helpers` | Narrow account helpers | Account list/account-action helpers | - | `plugin-sdk/channel-setup` | Setup wizard adapters | `createOptionalChannelSetupSurface` | + | `plugin-sdk/channel-setup` | Setup wizard adapters | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | | `plugin-sdk/channel-pairing` | DM pairing primitives | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | Reply prefix + typing wiring | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | Config adapter factories | `createHybridChannelConfigAdapter` | diff --git a/docs/plugins/sdk-overview.md b/docs/plugins/sdk-overview.md index f0ad8926537..bff2a9c68ba 100644 --- a/docs/plugins/sdk-overview.md +++ b/docs/plugins/sdk-overview.md @@ -73,11 +73,11 @@ explicitly promotes one as public. | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | Root `openclaw.json` Zod schema export (`OpenClawSchema`) | - | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface` | + | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, plus `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | | `plugin-sdk/setup` | Shared setup wizard helpers, allowlist prompts, setup status builders | | `plugin-sdk/setup-runtime` | `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | Setup CLI/archive/docs helpers | + | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | | `plugin-sdk/account-core` | Multi-account config/action-gate helpers, default-account fallback helpers | | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, account-id normalization helpers | | `plugin-sdk/account-resolution` | Account lookup + default-fallback helpers | diff --git a/docs/plugins/sdk-setup.md b/docs/plugins/sdk-setup.md index 280d21283c7..cd8cf09c547 100644 --- a/docs/plugins/sdk-setup.md +++ b/docs/plugins/sdk-setup.md @@ -296,7 +296,7 @@ For hot setup-only paths, prefer the narrow setup helper seams over the broader | ---------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `plugin-sdk/setup-runtime` | setup-time runtime helpers that stay available in `setupEntry` / deferred channel startup | `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | environment-aware account setup adapters | `createEnvPatchedAccountSetupAdapter` | -| `plugin-sdk/setup-tools` | setup/install CLI/archive/docs helpers | `formatCliCommand`, `detectBinary`, `extractArchive`, `formatDocsLink` | +| `plugin-sdk/setup-tools` | setup/install CLI/archive/docs helpers | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | Use the broader `plugin-sdk/setup` seam when you want the full shared setup toolbox, including config-patch helpers such as @@ -444,6 +444,29 @@ const setupSurface = createOptionalChannelSetupSurface({ // Returns { setupAdapter, setupWizard } ``` +`plugin-sdk/channel-setup` also exposes the lower-level +`createOptionalChannelSetupAdapter(...)` and +`createOptionalChannelSetupWizard(...)` builders when you only need one half of +that optional-install surface. + +The generated optional adapter/wizard fail closed on real config writes. They +reuse one install-required message across `validateInput`, +`applyAccountConfig`, and `finalize`, and append a docs link when `docsPath` is +set. + +For binary-backed setup UIs, prefer the shared delegated helpers instead of +copying the same binary/status glue into every channel: + +- `createDetectedBinaryStatus(...)` for status blocks that vary only by labels, + hints, scores, and binary detection +- `createCliPathTextInput(...)` for path-backed text inputs +- `createDelegatedSetupWizardStatusResolvers(...)`, + `createDelegatedPrepare(...)`, `createDelegatedFinalize(...)`, and + `createDelegatedResolveConfigured(...)` when `setupEntry` needs to forward to + a heavier full wizard lazily +- `createDelegatedTextInputShouldPrompt(...)` when `setupEntry` only needs to + delegate a `textInputs[*].shouldPrompt` decision + ## Publishing and installing **External plugins:** publish to [ClawHub](/tools/clawhub) or npm, then install: