You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
gpt-pilot/docs/plugins/sdk-setup.md

133 lines
3.5 KiB
Markdown

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

---
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)