Ustawianie i konfiguracja Plugin

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

# Metadane pakietu

Twój package.json wymaga pola 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",
  "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 używane do wykrywania kanałów i powierzchni konfiguracji 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ędnia kanał w powierzchniach list skonfigurowanych/statusowych
• setup: uwzględnia kanał w interaktywnych selektorach konfiguracji/ustawień
• docs: oznacza 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

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/pełny wpis rejestruje metody RPC gatewaya, trzymaj je pod prefiksem specyficznym dla pluginu. Zarezerwowane przestrzenie nazw podstawowej administracji (config.*, exec.approvals.*, wizard.*, update.*) pozostają własnością rdzenia 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 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 Plugin, aby uzyskać pełną dokumentację referencyjną schematu.

# Publikowanie w ClawHub

W przypadku pakietów pluginów użyj polecenia ClawHub specyficznego dla pakietu:

clawhub package publish your-org/your-plugin --dry-run
clawhub 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żanie, naprawa konfiguracji, inspekcja wyłączonego kanału).

// setup-entry.ts


export default defineSetupPluginEntry(myChannelPlugin);

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

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

# Wąskie importy pomocników konfiguracji

Dla gorących ścieżek tylko 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 mieć 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 pakietowe wyszukiwanie powierzchni kontraktu promocji pojedynczego konta jest leniwe, więc importowanie plugin-sdk/setup-runtime nie ładuje zachłannie wykrywania pakietowej powierzchni kontraktu, zanim adapter zostanie faktycznie użyty.

# Promocja pojedynczego konta zarządzana przez kanał

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

Kanały pakietowe 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 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 otrzymuje promowane wartości

# Schemat konfiguracji

Konfiguracja Plugin 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.

W przypadku 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 zarządzane przez 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 firm trzecich kontraktem zimnej ścieżki nadal jest manifest Plugin: odwzoruj wygenerowany JSON Schema do 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 pluginów pakietowych (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ą zainstalować:

openclaw plugins install <package-name>

Metadane dołączonego pakietu są jawne, a nie wywnioskowane ze skompilowanego JavaScript podczas uruchamiania Gateway. Zależności uruchomieniowe należą do pakietu pluginu, który jest ich właścicielem; uruchamianie 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 Plugin — pełna dokumentacja schematu manifestu
• Punkty wejścia SDK — definePluginEntry i defineChannelPluginEntry