Konfiguracja i ustawienia Plugin

Dokumentacja referencyjna pakowania pluginów (metadane package.json), manifestów (openclaw.plugin.json), wpisów konfiguracji początkowej i schematów konfiguracji.

Metadane pakietu

Twój package.json potrzebuje pola openclaw, które informuje system pluginów, co zapewnia Twój plugin:

{  "name": "@myorg/openclaw-my-channel",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "channel": {      "id": "my-channel",      "label": "My Channel",      "blurb": "Short description of the channel."    }  }}

{  "name": "@myorg/openclaw-my-plugin",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "compat": {      "pluginApi": ">=2026.3.24-beta.2",      "minGatewayVersion": "2026.3.24-beta.2"    },    "build": {      "openclawVersion": "2026.3.24-beta.2",      "pluginSdkVersion": "2026.3.24-beta.2"    }  }}

Pola openclaw

openclaw.channel

openclaw.channel to lekkie metadane pakietu do wykrywania kanałów i powierzchni konfiguracji początkowej przed załadowaniem środowiska uruchomieniowego.

Przykład:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "My Channel",      "selectionLabel": "My Channel (self-hosted)",      "detailLabel": "My Channel Bot",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Webhook-based self-hosted chat integration.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Guide:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

exposure obsługuje:

• configured: uwzględnij kanał w powierzchniach list skonfigurowanych/statusowych
• setup: uwzględnij kanał w interaktywnych selektorach konfiguracji początkowej/konfiguracji
• docs: oznacz kanał jako publiczny w powierzchniach dokumentacji/nawigacji

openclaw.install

openclaw.install to metadane pakietu, a nie metadane manifestu.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

Odroczone pełne ładowanie

Pluginy kanałów mogą włączyć odroczone ładowanie za pomocą:

{  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "startup": {      "deferConfiguredChannelFullLoadUntilAfterListen": true    }  }}

Po włączeniu OpenClaw ładuje tylko setupEntry podczas fazy uruchamiania przed nasłuchiwaniem, nawet dla już skonfigurowanych kanałów. Pełny wpis ładuje się po rozpoczęciu nasłuchiwania przez gateway.

Jeśli Twój wpis konfiguracji początkowej/pełny wpis rejestruje metody RPC gateway, utrzymuj je w prefiksie specyficznym dla pluginu. Zarezerwowane przestrzenie nazw administracji rdzenia (config.*, exec.approvals.*, wizard.*, update.*) pozostają własnością rdzenia i zawsze rozwiązują się do operator.admin.

Manifest pluginu

Każdy natywny plugin musi dostarczać openclaw.plugin.json w katalogu głównym pakietu. OpenClaw używa go do walidacji konfiguracji bez wykonywania kodu pluginu.

{  "id": "my-plugin",  "name": "My Plugin",  "description": "Adds My Plugin capabilities to OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Webhook verification secret"      }    }  }}

Dla pluginów kanałów dodaj kind i channels:

{  "id": "my-channel",  "kind": "channel",  "channels": ["my-channel"],  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

Nawet pluginy bez konfiguracji muszą dostarczać schemat. Pusty schemat jest prawidłowy:

{  "id": "my-plugin",  "configSchema": {    "type": "object",    "additionalProperties": false  }}

Zobacz manifest Plugin, aby poznać pełną referencję schematu.

Publikowanie w ClawHub

Dla pakietów Plugin użyj polecenia ClawHub właściwego dla pakietu:

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

Punkt wejścia konfiguracji

Plik setup-entry.ts jest lekką alternatywą dla index.ts, którą OpenClaw ładuje, gdy potrzebuje tylko powierzchni konfiguracji (onboarding, naprawa konfiguracji, inspekcja wyłączonego kanału).

// setup-entry.ts  export default defineSetupPluginEntry(myChannelPlugin);

Pozwala to uniknąć ładowania ciężkiego kodu środowiska uruchomieniowego (bibliotek kryptograficznych, rejestracji CLI, usług działających w tle) podczas przepływów konfiguracji.

Kanały wbudowane w workspace, które trzymają eksporty bezpieczne dla konfiguracji w modułach bocznych, mogą użyć defineBundledChannelSetupEntry(...) z openclaw/plugin-sdk/channel-entry-contract zamiast defineSetupPluginEntry(...). Ten wbudowany kontrakt obsługuje także opcjonalny eksport runtime, dzięki czemu okablowanie środowiska uruchomieniowego w czasie konfiguracji może pozostać lekkie i jawne.

Wąskie importy pomocników konfiguracji

Dla gorących ścieżek tylko do konfiguracji preferuj wąskie szwy pomocników konfiguracji zamiast szerszego parasola plugin-sdk/setup, gdy potrzebujesz tylko części powierzchni konfiguracji:

Użyj szerszego szwu plugin-sdk/setup, gdy chcesz skorzystać z pełnego współdzielonego zestawu narzędzi konfiguracji, w tym pomocników łatek konfiguracji, takich jak moveSingleAccountChannelSectionToDefaultAccount(...).

Użyj createSetupTranslator(...) dla stałych tekstów kreatora konfiguracji. Podąża za ustawieniami regionalnymi kreatora CLI (OPENCLAW_LOCALE, a następnie zmiennymi ustawień regionalnych systemu) i wraca do angielskiego. Tekst konfiguracji specyficzny dla Plugin trzymaj w kodzie należącym do Plugin i używaj współdzielonych kluczy katalogu tylko dla wspólnych etykiet konfiguracji, tekstu statusu oraz oficjalnych tekstów konfiguracji wbudowanych Plugin.

Adaptery łatek konfiguracji pozostają bezpieczne do importu na gorącej ścieżce. Ich wyszukiwanie powierzchni kontraktu promowania wbudowanego pojedynczego konta jest leniwe, więc importowanie plugin-sdk/setup-runtime nie ładuje zachłannie wykrywania wbudowanej powierzchni kontraktu, zanim adapter zostanie faktycznie użyty.

Promowanie pojedynczego konta należące do kanału

Gdy kanał przechodzi z konfiguracji najwyższego poziomu pojedynczego konta na channels.<id>.accounts.*, domyślne współdzielone zachowanie przenosi promowane wartości z zakresu konta do accounts.default.

Kanały wbudowane mogą zawęzić lub nadpisać to promowanie przez swoją powierzchnię kontraktu konfiguracji:

• singleAccountKeysToMove: dodatkowe klucze najwyższego poziomu, które powinny zostać przeniesione do promowanego konta
• namedAccountPromotionKeys: gdy nazwane konta już istnieją, tylko te klucze są przenoszone do promowanego konta; współdzielone klucze zasad/dostarczania pozostają w katalogu głównym kanału
• resolveSingleAccountPromotionTarget(...): wybiera, które istniejące konto otrzyma promowane wartości

Schemat konfiguracji

Konfiguracja Plugin jest walidowana względem JSON Schema w manifeście. Użytkownicy konfigurują Plugin przez:

{  plugins: {    entries: {      "my-plugin": {        config: {          webhookSecret: "abc123",        },      },    },  },}

Twój Plugin otrzymuje tę konfigurację jako api.pluginConfig podczas rejestracji.

Dla konfiguracji specyficznej dla kanału użyj zamiast tego sekcji konfiguracji kanału:

{  channels: {    "my-channel": {      token: "bot-token",      allowFrom: ["user1", "user2"],    },  },}

Budowanie schematów konfiguracji kanału

Użyj buildChannelConfigSchema, aby przekonwertować schemat Zod na wrapper ChannelConfigSchema używany przez artefakty konfiguracji należące do Plugin:

  const accountSchema = z.object({  token: z.string().optional(),  allowFrom: z.array(z.string()).optional(),  accounts: z.object({}).catchall(z.any()).optional(),  defaultAccount: z.string().optional(),}); const configSchema = buildChannelConfigSchema(accountSchema);

Jeśli już tworzysz kontrakt jako JSON Schema lub TypeBox, użyj bezpośredniego pomocnika, aby OpenClaw mógł pominąć konwersję Zod-do-JSON-Schema na ścieżkach metadanych:

  const configSchema = buildJsonChannelConfigSchema(  Type.Object({    token: Type.Optional(Type.String()),    allowFrom: Type.Optional(Type.Array(Type.String())),  }),);

Dla Plugin firm trzecich kontraktem zimnej ścieżki nadal jest manifest Plugin: odzwierciedl wygenerowany JSON Schema w openclaw.plugin.json#channelConfigs, aby schemat konfiguracji, konfiguracja i powierzchnie UI mogły sprawdzać channels.<id> bez ładowania kodu środowiska uruchomieniowego.

Kreatory konfiguracji

Plugin kanałów mogą udostępniać interaktywne kreatory konfiguracji dla openclaw onboard. Kreator jest obiektem ChannelSetupWizard w ChannelPlugin:

 const setupWizard: ChannelSetupWizard = {  channel: "my-channel",  status: {    configuredLabel: "Connected",    unconfiguredLabel: "Not configured",    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),  },  credentials: [    {      inputKey: "token",      providerHint: "my-channel",      credentialLabel: "Bot token",      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",      keepPrompt: "Keep current token?",      inputPrompt: "Enter your bot token:",      inspect: ({ cfg, accountId }) => {        const token = (cfg.channels as any)?.["my-channel"]?.token;        return {          accountConfigured: Boolean(token),          hasConfiguredValue: Boolean(token),        };      },    },  ],};

Typ ChannelSetupWizard obsługuje credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize i więcej. Pełne przykłady znajdziesz w pakietach wbudowanych Plugin (na przykład Plugin Discord src/channel.setup.ts).

import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; const setupSurface = createOptionalChannelSetupSurface({  channel: "my-channel",  label: "My Channel",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// Returns { setupAdapter, setupWizard }

Publikowanie i instalowanie

Zewnętrzne Pluginy: opublikuj w ClawHub, a następnie zainstaluj:

openclaw plugins install @myorg/openclaw-my-plugin

openclaw plugins install clawhub:@myorg/openclaw-my-plugin

openclaw plugins install npm:@myorg/openclaw-my-plugin

Pluginy w repozytorium: umieść je w drzewie obszaru roboczego dołączonych Pluginów, a zostaną automatycznie wykryte podczas kompilacji.

Użytkownicy mogą instalować:

openclaw plugins install <package-name>

Metadane dołączonych pakietów są jawne, a nie wnioskowane z wygenerowanego JavaScriptu podczas uruchamiania Gateway. Zależności czasu wykonywania należą do pakietu Pluginu, który jest ich właścicielem; uruchamianie spakowanego OpenClaw nigdy nie naprawia ani nie kopiuje zależności Pluginów.

Powiązane

• Tworzenie Pluginów — przewodnik krok po kroku dla początkujących
• Manifest Pluginu — pełna dokumentacja schematu manifestu
• Punkty wejścia SDK — definePluginEntry i defineChannelPluginEntry