docs(plugin-sdk): document public SDK surface

2026-04-24 07:01:49 +00:00 · 2026-03-22 08:50:43 -07:00
parent e1ff24903f
commit 05279539a8
34 changed files with 1260 additions and 16 deletions
--- a/docs/plugins/sdk-setup.md
+++ b/docs/plugins/sdk-setup.md
@@ -0,0 +1,132 @@
+---
+title: "Plugin Setup"
+sidebarTitle: "Setup"
+summary: "Shared setup-wizard helpers for channel plugins, provider plugins, and secret inputs"
+read_when:
+  - You are building a setup or onboarding flow
+  - You need shared allowlist or DM policy setup helpers
+  - You need the shared secret-input schema
+---
+
+# Plugin Setup
+
+OpenClaw exposes shared setup helpers so plugin setup flows behave like the
+built-in ones.
+
+Main subpaths:
+
+- `openclaw/plugin-sdk/setup`
+- `openclaw/plugin-sdk/channel-setup`
+- `openclaw/plugin-sdk/secret-input`
+
+## Channel setup helpers
+
+Use `plugin-sdk/channel-setup` when a channel plugin needs the standard setup
+adapter and setup wizard shapes.
+
+### Optional channel plugins
+
+If a channel is installable but not always present, use
+`createOptionalChannelSetupSurface(...)`:
+
+```ts
+import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup";
+
+export const optionalExampleSetup = createOptionalChannelSetupSurface({
+  channel: "example",
+  label: "Example Channel",
+  npmSpec: "@openclaw/example-channel",
+  docsPath: "/channels/example",
+});
+```
+
+That returns:
+
+- `setupAdapter`
+- `setupWizard`
+
+Both surfaces produce a consistent “install this plugin first” experience.
+
+## Shared setup helpers
+
+`plugin-sdk/setup` re-exports the setup primitives used by bundled channels.
+
+Common helpers:
+
+- `applySetupAccountConfigPatch(...)`
+- `createPatchedAccountSetupAdapter(...)`
+- `createEnvPatchedAccountSetupAdapter(...)`
+- `createTopLevelChannelDmPolicy(...)`
+- `setSetupChannelEnabled(...)`
+- `promptResolvedAllowFrom(...)`
+- `promptSingleChannelSecretInput(...)`
+
+### Example: patch channel config in setup
+
+```ts
+import {
+  DEFAULT_ACCOUNT_ID,
+  createPatchedAccountSetupAdapter,
+  setSetupChannelEnabled,
+} from "openclaw/plugin-sdk/setup";
+
+export const exampleSetupAdapter = createPatchedAccountSetupAdapter({
+  resolveAccountId: ({ accountId }) => accountId ?? DEFAULT_ACCOUNT_ID,
+  applyPatch: ({ nextConfig, accountId }) => {
+    const resolvedAccountId = accountId ?? DEFAULT_ACCOUNT_ID;
+    return setSetupChannelEnabled({
+      nextConfig,
+      channel: "example",
+      accountId: resolvedAccountId,
+      enabled: true,
+    });
+  },
+});
+```
+
+## Secret input schema
+
+Use `plugin-sdk/secret-input` instead of rolling your own secret-input parser.
+
+```ts
+import {
+  buildOptionalSecretInputSchema,
+  buildSecretInputArraySchema,
+  buildSecretInputSchema,
+  hasConfiguredSecretInput,
+} from "openclaw/plugin-sdk/secret-input";
+
+const ApiKeySchema = buildSecretInputSchema();
+const OptionalApiKeySchema = buildOptionalSecretInputSchema();
+const ExtraKeysSchema = buildSecretInputArraySchema();
+
+const parsed = OptionalApiKeySchema.safeParse(process.env.EXAMPLE_API_KEY);
+if (parsed.success && hasConfiguredSecretInput(parsed.data)) {
+  // ...
+}
+```
+
+## Provider setup note
+
+Provider-specific onboarding helpers live on provider-focused subpaths:
+
+- `plugin-sdk/provider-auth`
+- `plugin-sdk/provider-onboard`
+- `plugin-sdk/provider-setup`
+- `plugin-sdk/self-hosted-provider-setup`
+
+See [Provider Plugin SDK](/plugins/sdk-provider-plugins).
+
+## Setup guidance
+
+- Keep setup input schemas strict and small.
+- Reuse OpenClaw’s allowlist, DM-policy, and secret-input helpers.
+- Keep setup-entry modules thin; move behavior into `src/`.
+- Link docs from setup flows when install or auth steps are manual.
+
+## Related
+
+- [Plugin SDK Overview](/plugins/sdk-overview)
+- [Plugin Entry Points](/plugins/sdk-entrypoints)
+- [Provider Plugin SDK](/plugins/sdk-provider-plugins)
+- [Plugin Manifest](/plugins/manifest)