Przejdź do głównej treści

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Dokumentacja referencyjna dotycząca pakowania Plugin (package.json metadata), manifestów (openclaw.plugin.json), wpisów konfiguracji początkowej i schematów konfiguracji.
Szukasz przewodnika krok po kroku? Przewodniki how-to omawiają pakowanie w kontekście: Channel plugins i Provider plugins.

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."
    }
  }
}
Jeśli publikujesz Plugin zewnętrznie w ClawHub, te pola compat i build są wymagane. Kanoniczne fragmenty publikowania znajdują się w docs/snippets/plugin-publish/.

Pola openclaw

extensions
string[]
Pliki punktów wejścia (względem katalogu głównego pakietu).
setupEntry
string
Lekki wpis wyłącznie do konfiguracji początkowej (opcjonalny).
channel
object
Metadane katalogowe kanału dla powierzchni konfiguracji początkowej, selektora, szybkiego startu i statusu.
providers
string[]
Identyfikatory dostawców rejestrowane przez ten Plugin.
install
object
Wskazówki instalacji: npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery.
startup
object
Flagi zachowania podczas uruchamiania.

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.
PoleTypZnaczenie
idstringKanoniczny identyfikator kanału.
labelstringGłówna etykieta kanału.
selectionLabelstringEtykieta selektora/konfiguracji początkowej, gdy powinna różnić się od label.
detailLabelstringDodatkowa etykieta szczegółowa dla bogatszych katalogów kanałów i powierzchni statusu.
docsPathstringŚcieżka dokumentacji dla linków konfiguracji początkowej i wyboru.
docsLabelstringZastępcza etykieta używana dla linków do dokumentacji, gdy powinna różnić się od identyfikatora kanału.
blurbstringKrótki opis onboardingowy/katalogowy.
ordernumberKolejność sortowania w katalogach kanałów.
aliasesstring[]Dodatkowe aliasy wyszukiwania dla wyboru kanału.
preferOverstring[]Identyfikatory Plugin/kanałów o niższym priorytecie, które ten kanał powinien wyprzedzać.
systemImagestringOpcjonalna nazwa ikony/obrazu systemowego dla katalogów UI kanałów.
selectionDocsPrefixstringTekst prefiksu przed linkami do dokumentacji w powierzchniach wyboru.
selectionDocsOmitLabelbooleanPokazuj ścieżkę dokumentacji bezpośrednio zamiast etykietowanego linku do dokumentacji w tekście wyboru.
selectionExtrasstring[]Dodatkowe krótkie ciągi dołączane w tekście wyboru.
markdownCapablebooleanOznacza kanał jako obsługujący markdown dla decyzji o formatowaniu wychodzącym.
exposureobjectKontrolki widoczności kanału dla konfiguracji początkowej, list skonfigurowanych i powierzchni dokumentacji.
quickstartAllowFrombooleanWłącza ten kanał do standardowego przepływu szybkiego startu allowFrom.
forceAccountBindingbooleanWymaga jawnego powiązania konta nawet wtedy, gdy istnieje tylko jedno konto.
preferSessionLookupForAnnounceTargetbooleanPreferuj wyszukiwanie sesji podczas rozwiązywania celów ogłoszeń dla tego kanału.
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
showConfigured i showInSetup pozostają obsługiwane jako starsze aliasy. Preferuj exposure.

openclaw.install

openclaw.install to metadane pakietu, a nie metadane manifestu.
PoleTypZnaczenie
clawhubSpecstringKanoniczna specyfikacja ClawHub dla instalacji/aktualizacji oraz przepływów onboardingowych instalacji na żądanie.
npmSpecstringKanoniczna specyfikacja npm dla zapasowych przepływów instalacji/aktualizacji.
localPathstringLokalna ścieżka deweloperska lub ścieżka instalacji dołączonej.
defaultChoice"clawhub" | "npm" | "local"Preferowane źródło instalacji, gdy dostępnych jest wiele źródeł.
minHostVersionstringMinimalna obsługiwana wersja OpenClaw w formie >=x.y.z lub >=x.y.z-prerelease.
expectedIntegritystringOczekiwany ciąg integralności npm dist, zwykle sha512-..., dla instalacji przypiętych.
allowInvalidConfigRecoverybooleanPozwala przepływom ponownej instalacji dołączonego Plugin odzyskiwać się po określonych awariach nieaktualnej konfiguracji.
Interaktywny onboarding używa również openclaw.install dla powierzchni instalacji na żądanie. Jeśli Twój Plugin udostępnia opcje uwierzytelniania dostawcy lub metadane konfiguracji początkowej/katalogu kanału przed załadowaniem środowiska uruchomieniowego, onboarding może pokazać ten wybór, poprosić o instalację z ClawHub, npm lub lokalną, zainstalować albo włączyć Plugin, a następnie kontynuować wybrany przepływ. Opcje onboardingu ClawHub używają clawhubSpec i są preferowane, gdy są obecne; opcje npm wymagają zaufanych metadanych katalogu ze specyfikacją rejestru npmSpec; dokładne wersje i expectedIntegrity są opcjonalnymi przypięciami npm. Jeśli expectedIntegrity jest obecne, przepływy instalacji/aktualizacji egzekwują je dla npm. Metadane „co pokazać” trzymaj w openclaw.plugin.json, a metadane „jak to zainstalować” w package.json.
Jeśli ustawiono minHostVersion, egzekwują je zarówno instalacja, jak i ładowanie rejestru manifestów dla niedołączonych Plugin. Starsze hosty pomijają zewnętrzne Plugin; nieprawidłowe ciągi wersji są odrzucane. Zakłada się, że dołączone źródłowe Plugin mają tę samą wersję co checkout hosta.
Dla przypiętych instalacji npm zachowaj dokładną wersję w npmSpec i dodaj oczekiwaną integralność artefaktu:
{
  "openclaw": {
    "install": {
      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",
      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",
      "defaultChoice": "npm"
    }
  }
}
allowInvalidConfigRecovery nie jest ogólnym obejściem dla uszkodzonych konfiguracji. Służy wyłącznie do wąskiego odzyskiwania dołączonego Plugin, aby ponowna instalacja/konfiguracja początkowa mogła naprawić znane pozostałości po aktualizacji, takie jak brakująca ścieżka dołączonego Plugin lub nieaktualny wpis channels.<id> dla tego samego Plugin. Jeśli konfiguracja jest uszkodzona z niezwiązanych powodów, instalacja nadal kończy się niepowodzeniem w trybie zamkniętym i informuje operatora, aby uruchomił openclaw doctor --fix.

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.
Włączaj odroczone ładowanie tylko wtedy, gdy Twój setupEntry rejestruje wszystko, czego Gateway potrzebuje przed rozpoczęciem nasłuchiwania (rejestrację kanału, trasy HTTP, metody Gateway). Jeśli pełny wpis odpowiada za wymagane możliwości uruchomieniowe, zachowaj zachowanie domyślne.
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-run
clawhub package publish your-org/your-plugin
Starszy alias publikowania tylko dla Skills jest przeznaczony dla Skills. Pakiety Plugin powinny zawsze używać clawhub package publish.

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
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { myChannelPlugin } from "./src/channel.js";

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.
  • Kanał jest wyłączony, ale potrzebuje powierzchni konfiguracji/onboardingu.
  • Kanał jest włączony, ale nieskonfigurowany.
  • Włączone jest odroczone ładowanie (deferConfiguredChannelFullLoadUntilAfterListen).
  • Obiekt Plugin kanału (przez defineSetupPluginEntry).
  • Wszelkie trasy HTTP wymagane przed nasłuchem Gateway.
  • Wszelkie metody Gateway potrzebne podczas uruchamiania.
Te metody Gateway uruchamiane na starcie nadal powinny unikać zarezerwowanych głównych przestrzeni nazw administracyjnych, takich jak config.* lub update.*.
  • Rejestracje CLI.
  • Usługi działające w tle.
  • Ciężkie importy runtime (kryptografia, SDK).
  • Metody Gateway potrzebne dopiero po uruchomieniu.

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:
Ścieżka importuDo czego służyKluczowe eksporty
plugin-sdk/setup-runtimepomocnicy runtime czasu konfiguracji, którzy pozostają dostępni w setupEntry / odroczonym uruchamianiu kanałucreatePatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy
plugin-sdk/setup-adapter-runtimeprzestarzały alias zgodności; użyj plugin-sdk/setup-runtimecreateEnvPatchedAccountSetupAdapter
plugin-sdk/setup-toolspomocnicy konfiguracji/instalacji CLI/archiwów/dokumentacjiformatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR
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
Matrix jest bieżącym dołączonym przykładem. Jeśli istnieje dokładnie jedno nazwane konto Matrix albo jeśli defaultAccount wskazuje na istniejący klucz niekanoniczny, taki jak Ops, promocja zachowuje to konto zamiast tworzyć nowy wpis accounts.default.

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:
import { z } from "zod";
import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";

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:
import { Type } from "typebox";
import { buildJsonChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";

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:
import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";

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).
W przypadku monitów listy dozwolonych DM, które potrzebują tylko standardowego przepływu note -> prompt -> parse -> merge -> patch, preferuj współdzielone pomocniki konfiguracji z openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) i createNestedChannelParsedAllowFromPrompt(...).
W przypadku bloków statusu konfiguracji kanału, które różnią się tylko etykietami, wynikami i opcjonalnymi dodatkowymi wierszami, preferuj createStandardChannelSetupStatus(...) z openclaw/plugin-sdk/setup zamiast ręcznie tworzyć ten sam obiekt status w każdym Plugin.
W przypadku opcjonalnych powierzchni konfiguracji, które powinny pojawiać się tylko w określonych kontekstach, użyj createOptionalChannelSetupSurface z openclaw/plugin-sdk/channel-setup:
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 }
plugin-sdk/channel-setup udostępnia również niższopoziomowe konstruktory createOptionalChannelSetupAdapter(...) i createOptionalChannelSetupWizard(...), gdy potrzebujesz tylko jednej połowy tej opcjonalnej powierzchni instalacji.Wygenerowany opcjonalny adapter/kreator bezpiecznie odmawia rzeczywistych zapisów konfiguracji. Ponownie używa jednego komunikatu o wymaganej instalacji w validateInput, applyAccountConfig i finalize oraz dołącza link do dokumentacji, gdy ustawione jest docsPath.
W przypadku UI konfiguracji wspieranych przez pliki binarne preferuj współdzielone delegowane pomocniki zamiast kopiować to samo połączenie binarne/statusu do każdego kanału:
  • createDetectedBinaryStatus(...) dla bloków statusu, które różnią się tylko etykietami, wskazówkami, wynikami i wykrywaniem pliku binarnego
  • createCliPathTextInput(...) dla wejść tekstowych opartych na ścieżce
  • createDelegatedSetupWizardStatusResolvers(...), createDelegatedPrepare(...), createDelegatedFinalize(...) i createDelegatedResolveConfigured(...), gdy setupEntry musi leniwie przekazać obsługę do cięższego pełnego kreatora
  • createDelegatedTextInputShouldPrompt(...), gdy setupEntry musi tylko delegować decyzję textInputs[*].shouldPrompt

Publikowanie i instalowanie

Zewnętrzne Pluginy: opublikuj w ClawHub, a następnie zainstaluj:
openclaw plugins install @myorg/openclaw-my-plugin
Gołe specyfikacje pakietów są instalowane z npm podczas przełączenia uruchomieniowego.
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>
W przypadku instalacji ze źródeł npm openclaw plugins install instaluje pakiet w ~/.openclaw/npm z wyłączonymi skryptami cyklu życia. Utrzymuj drzewa zależności Pluginów jako czyste JS/TS i unikaj pakietów wymagających kompilacji przez postinstall.
Uruchomienie Gateway nie instaluje zależności Pluginów. Przepływy instalacji npm/git/ClawHub odpowiadają za uzgodnienie zależności; lokalne Pluginy muszą mieć już zainstalowane swoje zależności.
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