Konfiguracja i ustawienia Pluginu

Dokumentacja pakowania Pluginów (metadane package.json), manifestów (openclaw.plugin.json), punktów konfiguracji i schematów konfiguracji.

Metadane pakietu

Plik package.json musi zawierać pole openclaw, które informuje system Pluginów, co udostępnia 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 oraz wyświetlania interfejsów konfiguracji 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ędnia kanał w widokach list skonfigurowanych kanałów i widokach stanu
• setup: uwzględnia kanał w interaktywnych selektorach konfiguracji
• docs: oznacza kanał jako publicznie widoczny w dokumentacji i nawigacji

openclaw.install

openclaw.install to metadane pakietu, a nie 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 w fazie uruchamiania przed rozpoczęciem nasłuchiwania, nawet w przypadku już skonfigurowanych kanałów. Pełny punkt wejścia jest ładowany po rozpoczęciu nasłuchiwania przez Gateway.

Jeśli punkty wejścia konfiguracji lub pełnego ładowania rejestrują metody RPC Gateway, umieść je pod prefiksem właściwym dla danego Pluginu. Zastrzeżone przestrzenie nazw administracyjnych rdzenia (config.*, exec.approvals.*, wizard.*, update.*) pozostają własnością rdzenia i są zawsze normalizowane do operator.admin.

Manifest Pluginu

Każdy natywny Plugin musi zawierać plik openclaw.plugin.json w katalogu głównym pakietu. OpenClaw używa go do walidowania 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 channels (a w przypadku Pluginów dostawców dodaj providers):

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

Nawet Pluginy bez konfiguracji muszą zawierać schemat. Pusty schemat jest prawidłowy:

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

Pełną dokumentację schematu zawiera strona Manifest Pluginu.

Publikowanie w ClawHub

Pakiety Skills i Pluginów korzystają z oddzielnych poleceń publikowania w ClawHub. W przypadku pakietów Pluginów użyj polecenia przeznaczonego dla pakietów:

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

Punkt wejścia konfiguracji

setup-entry.ts to lekka alternatywa 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 środowiska wykonawczego (bibliotek kryptograficznych, rejestracji CLI, usług działających w tle) podczas procesów konfiguracji.

Kanały dołączone do obszaru roboczego, które przechowują bezpieczne dla konfiguracji eksporty w modułach pomocniczych, mogą używać defineBundledChannelSetupEntry(...) z openclaw/plugin-sdk/channel-entry-contract zamiast defineSetupPluginEntry(...). Ten kontrakt dołączonego kanału obsługuje również opcjonalny eksport runtime, dzięki czemu powiązania środowiska wykonawczego na etapie konfiguracji mogą pozostać lekkie i jawne.

Wąskie importy pomocnicze konfiguracji

W przypadku intensywnie używanych ścieżek przeznaczonych wyłącznie do konfiguracji preferuj wąskie interfejsy pomocnicze konfiguracji zamiast szerszego modułu zbiorczego plugin-sdk/setup, jeśli potrzebujesz tylko części powierzchni konfiguracji:

Użyj szerszego interfejsu plugin-sdk/setup, jeśli potrzebujesz pełnego wspólnego zestawu narzędzi konfiguracyjnych, w tym funkcji pomocniczych do modyfikowania konfiguracji, takich jak moveSingleAccountChannelSectionToDefaultAccount(...).

Używaj createSetupTranslator(...) do stałych tekstów kreatora konfiguracji. Funkcja ta stosuje ustawienia regionalne kreatora CLI (OPENCLAW_LOCALE, a następnie systemowe zmienne ustawień regionalnych) i w razie potrzeby używa języka angielskiego. Teksty konfiguracji właściwe dla Pluginu przechowuj w kodzie należącym do Pluginu, a współdzielonych kluczy katalogu używaj wyłącznie do wspólnych etykiet konfiguracji, tekstów stanu i tekstów konfiguracji oficjalnych dołączonych Pluginów.

Adaptery modyfikowania konfiguracji pozostają bezpieczne dla intensywnie używanych ścieżek już podczas importu. Wyszukiwanie powierzchni kontraktu dołączonego kanału dotyczącej promowania pojedynczego konta jest leniwe, dlatego importowanie plugin-sdk/setup-runtime nie powoduje natychmiastowego ładowania mechanizmu wykrywania powierzchni kontraktów dołączonych kanałów, zanim adapter zostanie faktycznie użyty.

Promowanie pojedynczego konta należące do kanału

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

Dołączone kanały mogą zawęzić lub zastąpić to promowanie za pośrednictwem swojej powierzchni kontraktu konfiguracji:

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

Schemat konfiguracji

Konfiguracja Pluginu jest walidowana względem schematu JSON w manifeście. Użytkownicy konfigurują Pluginy za pomocą:

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

Podczas rejestracji Plugin otrzymuje tę konfigurację jako api.pluginConfig.

W przypadku konfiguracji właściwej 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 przekształcić schemat Zod w 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 kontrakt jest już tworzony jako schemat JSON lub TypeBox, użyj bezpośredniej funkcji pomocniczej, aby OpenClaw mógł pominąć konwersję ze schematu Zod do schematu JSON na ścieżkach metadanych:

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

W przypadku Pluginów innych firm kontraktem ścieżki nieaktywnej nadal jest manifest Pluginu: odwzoruj wygenerowany schemat JSON w openclaw.plugin.json#channelConfigs, aby powierzchnie schematu konfiguracji, konfiguracji początkowej i interfejsu użytkownika mogły analizować channels.<id> bez ładowania kodu środowiska wykonawczego.

Kreatory konfiguracji

Pluginy 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),        };      },    },  ],};

ChannelSetupWizard obsługuje również textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize i inne elementy. Pełny przykład dołączonego Pluginu znajduje się w pliku src/setup-core.ts Pluginu Discord.

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 przestrzeni roboczej dołączonych pluginów; zostaną automatycznie wykryte podczas kompilacji.

Metadane dołączonych pakietów są jawne, a nie wywnioskowane ze skompilowanego kodu JavaScript podczas uruchamiania Gateway. Zależności środowiska uruchomieniowego należą do pakietu pluginu, który jest ich właścicielem; uruchamianie spakowanego OpenClaw nigdy nie naprawia ani nie powiela zależności pluginów.

Powiązane materiały

• Tworzenie pluginów — przewodnik wprowadzający krok po kroku
• Manifest pluginu — pełna dokumentacja schematu manifestu
• Punkty wejścia SDK — definePluginEntry i defineChannelPluginEntry