mirror of
https://github.com/openclaw/openclaw.git
synced 2026-03-24 08:21:39 +00:00
133 lines
3.5 KiB
Markdown
133 lines
3.5 KiB
Markdown
---
|
||
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)
|