Konfiguracja i ustawienia Plugin

Dokumentacja referencyjna dotycząca pakowania Plugin (package.json metadata), 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, 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",  "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 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 skonfigurowanych powierzchniach listowania w stylu statusu
• 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/[email protected]",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

Odroczone pełne ładowanie

Plugin kanału 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 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, trzymaj je pod prefiksem specyficznym dla Plugin. Zarezerwowane podstawowe przestrzenie nazw administracyjnych (config.*, exec.approvals.*, wizard.*, update.*) pozostają własnością core i zawsze rozwiązują się do operator.admin.

Manifest Plugin

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

{  "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 kanału dodaj kind i channels:

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

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

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

Zobacz Manifest Plugin, aby uzyskać pełną dokumentację referencyjną schematu.

Publikowanie w ClawHub

Dla pakietów Plugin użyj polecenia ClawHub specyficznego 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 (onboarding, naprawa konfiguracji, inspekcja wyłączonego kanału).

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

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

Kanały dołączone w obszarze roboczym, które utrzymują bezpieczne dla konfiguracji eksporty w modułach bocznych, mogą używać defineBundledChannelSetupEntry(...) z openclaw/plugin-sdk/channel-entry-contract zamiast defineSetupPluginEntry(...). Ten dołączony kontrakt obsługuje również opcjonalny eksport runtime, dzięki czemu okablowanie runtime podczas 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 seams pomocników konfiguracji zamiast szerszego parasola plugin-sdk/setup, gdy potrzebujesz tylko części powierzchni konfiguracji:

Użyj szerszego seam plugin-sdk/setup, gdy chcesz pełny współdzielony zestaw narzędzi konfiguracji, w tym pomocniki łatek konfiguracji, takie jak moveSingleAccountChannelSectionToDefaultAccount(...).

Adaptery łatek konfiguracji pozostają bezpieczne dla gorącej ścieżki przy imporcie. Ich dołączone wyszukiwanie powierzchni kontraktu promocji pojedynczego konta jest leniwe, więc importowanie plugin-sdk/setup-runtime nie ładuje z wyprzedzeniem wykrywania dołączonej powierzchni kontraktu, zanim adapter zostanie faktycznie użyty.

Promocja pojedynczego konta zarządzana przez kanał

Gdy kanał aktualizuje się z konfiguracji najwyższego poziomu dla pojedynczego konta do channels.<id>.accounts.*, domyślne współdzielone zachowanie polega na przeniesieniu promowanych wartości o zakresie konta do accounts.default.

Dołączone kanały mogą zawęzić lub nadpisać tę promocję przez swoją powierzchnię kontraktu konfiguracji:

• singleAccountKeysToMove: dodatkowe klucze najwyższego poziomu, które powinny zostać przeniesione do promowanego konta
• namedAccountPromotionKeys: gdy konta nazwane już istnieją, tylko te klucze trafiają do promowanego konta; współdzielone klucze polityki/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ą 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"],    },  },}

Budowanie schematów konfiguracji kanału

Użyj buildChannelConfigSchema, aby przekonwertować schemat Zod na opakowanie ChannelConfigSchema używane 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())),  }),);

W przypadku Pluginów zewnętrznych 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 runtime.

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

Typ ChannelSetupWizard obsługuje credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize i więcej. Pełne przykłady znajdziesz w pakietach dołączonych Pluginów (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 dołączonym drzewie obszaru roboczego Pluginów, a zostaną automatycznie wykryte podczas kompilacji.

Użytkownicy mogą instalować:

openclaw plugins install <package-name>

Metadane dołączonego pakietu są jawne, a nie wywnioskowane ze skompilowanego JavaScriptu podczas uruchamiania gateway. Zależności uruchomieniowe należą do pakietu Pluginu, który jest ich właścicielem; uruchomienie spakowanego OpenClaw nigdy nie naprawia ani nie odzwierciedla zależności Pluginów.

Powiązane

• Tworzenie Pluginów — przewodnik krok po kroku ułatwiający rozpoczęcie pracy
• Manifest Pluginu — pełna dokumentacja schematu manifestu
• Punkty wejścia SDK — definePluginEntry i defineChannelPluginEntry