Konfiguracja i ustawienia Plugin

Dokumentacja referencyjna dla 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 wymaga 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",  "dependencies": {    "typebox": "1.1.39"  },  "peerDependencies": {    "openclaw": ">=2026.3.24-beta.2"  },  "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 służące do wykrywania kanałów i powierzchni konfiguracji początkowej przed załadowaniem środowiska wykonawczego.

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 rozpoczęciem nasłuchiwania, nawet dla już skonfigurowanych kanałów. Pełny wpis ładuje się po tym, jak Gateway zacznie nasłuchiwać.

Jeśli Twój wpis konfiguracji początkowej/pełny wpis rejestruje metody RPC Gateway, utrzymuj je pod prefiksem specyficznym dla Pluginu. Zarezerwowane główne przestrzenie nazw administracyjnych (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"      }    }  }}

W przypadku 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 Pluginu, aby poznać pełne odniesienie do schematu.

Publikowanie w ClawHub

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

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

Wpis konfiguracji

Plik setup-entry.ts jest lekką alternatywą dla index.ts, którą OpenClaw ładuje, gdy potrzebuje tylko powierzchni konfiguracji (wdrażania, naprawy konfiguracji, inspekcji wyłączonego kanału).

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

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

Kanały wbudowane w obszar roboczy, które trzymają eksporty bezpieczne dla konfiguracji w modułach pomocniczych, 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 uruchomieniowe w czasie konfiguracji może pozostać lekkie i jawne.

Wąskie importy pomocników konfiguracji

Dla gorących ścieżek przeznaczonych 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 pełny współdzielony zestaw narzędzi konfiguracji, w tym pomocniki łatek konfiguracji, takie jak moveSingleAccountChannelSectionToDefaultAccount(...).

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

Adaptery łatek konfiguracji pozostają bezpieczne na gorącej ścieżce podczas importu. Ich wyszukiwanie powierzchni kontraktu wbudowanej promocji pojedynczego konta jest leniwe, więc zaimportowanie plugin-sdk/setup-runtime nie ładuje z wyprzedzeniem odkrywania powierzchni kontraktu wbudowanego, zanim adapter zostanie faktycznie użyty.

Promocja pojedynczego konta należąca do kanału

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

Kanały wbudowane mogą zawęzić lub zastąpić tę promocję 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 przenoszą się do promowanego konta; współdzielone klucze polityki/dostarczania pozostają w korzeniu kanału
• resolveSingleAccountPromotionTarget(...): wybiera, które istniejące konto otrzymuje promowane wartości

Schemat konfiguracji

Konfiguracja Pluginu jest sprawdzana względem JSON Schema w manifeście. Użytkownicy konfigurują Pluginy 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"],    },  },}

Tworzenie schematów konfiguracji kanałów

Użyj buildChannelConfigSchema, aby przekonwertować schemat Zod na opakowanie ChannelConfigSchema używane przez artefakty konfiguracji należące do Pluginu:

  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ów zewnętrznych kontraktem zimnej ścieżki nadal jest manifest Pluginu: odzwierciedl wygenerowany JSON Schema w openclaw.plugin.json#channelConfigs, aby schemat konfiguracji, konfiguracja i powierzchnie UI mogły sprawdzać channels.<id> bez ładowania kodu uruchomieniowego.

Kreatory konfiguracji

Pluginy kanałów mogą dostarczać 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ów (na przykład w Pluginie 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łączanych Pluginów, a zostaną automatycznie wykryte podczas budowania.

Użytkownicy mogą zainstalować:

openclaw plugins install <package-name>

Metadane dołączanego pakietu są jawne, a nie wywnioskowane ze zbudowanego JavaScript podczas uruchamiania Gateway. Zależności uruchomieniowe należą do pakietu Pluginu, który je posiada; uruchamianie spakowanego OpenClaw nigdy nie naprawia ani nie odzwierciedla zależności Pluginów.

Powiązane

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