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