Punkty wejścia Pluginu

​

Punkty wejścia pakietu

{
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"],
    "setupEntry": "./src/setup-entry.ts",
    "runtimeSetupEntry": "./dist/setup-entry.js"
  }
}

• extensions i setupEntry są źródłowymi punktami wejścia używanymi podczas programowania w obszarze roboczym i kopii roboczej git.
• runtimeExtensions i runtimeSetupEntry są preferowane w przypadku zainstalowanych pakietów: pozwalają pakietom npm pominąć kompilację TypeScript podczas działania.
• runtimeExtensions, jeśli występuje, musi odpowiadać extensions pod względem długości tablicy (punkty wejścia są parowane według pozycji). runtimeSetupEntry wymaga setupEntry.
• Jeśli zadeklarowano artefakt runtimeExtensions/runtimeSetupEntry, ale go brakuje, instalacja lub wykrywanie kończy się błędem pakowania; OpenClaw nie przechodzi po cichu na kod źródłowy. Przejście awaryjne na kod źródłowy (opisane niżej) ma zastosowanie tylko wtedy, gdy w ogóle nie zadeklarowano punktu wejścia środowiska uruchomieniowego.
• Jeśli zainstalowany pakiet deklaruje tylko źródłowy punkt wejścia TypeScript, OpenClaw szuka odpowiadającego mu zbudowanego pliku dist/*.js (lub .mjs/.cjs) i go używa; w przeciwnym razie przechodzi na kod źródłowy TypeScript.
• Wszystkie ścieżki punktów wejścia muszą pozostawać w katalogu pakietu pluginu. Punkty wejścia środowiska uruchomieniowego ani wywnioskowane zbudowane odpowiedniki JS nie sprawiają, że wychodząca poza katalog ścieżka źródłowa extensions lub setupEntry staje się prawidłowa.

​

defineToolPlugin

import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";

export default defineToolPlugin({
  id: "stock-quotes",
  name: "Notowania giełdowe",
  description: "Pobiera notowania giełdowe.",
  configSchema: Type.Object({
    apiKey: Type.Optional(Type.String({ description: "Klucz API." })),
  }),
  tools: (tool) => [
    tool({
      name: "quote",
      label: "Notowanie",
      description: "Pobiera notowanie.",
      parameters: Type.Object({
        symbol: Type.String({ description: "Symbol giełdowy." }),
      }),
      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
    }),
  ],
});

• configSchema jest opcjonalne; jego pominięcie powoduje użycie ścisłego schematu pustego obiektu (wygenerowany manifest nadal zawiera configSchema).
• execute zwraca zwykły ciąg znaków lub wartość możliwą do serializacji jako JSON; funkcja pomocnicza opakowuje ją jako tekstowy wynik narzędzia z details ustawionym na pierwotną (nieprzekształconą w ciąg znaków) wartość zwracaną.
• W przypadku niestandardowych wyników narzędzi openclaw/plugin-sdk/tool-results eksportuje textResult i jsonResult.
• Nazwy narzędzi są statyczne, dlatego openclaw plugins build wyprowadza contracts.tools z zadeklarowanych narzędzi bez ręcznego powielania nazw.
• Ładowanie w środowisku uruchomieniowym pozostaje ścisłe: zainstalowane pluginy nadal wymagają openclaw.plugin.json i package.json openclaw.extensions. OpenClaw nigdy nie wykonuje kodu pluginu w celu wywnioskowania brakujących danych manifestu.

​

definePluginEntry

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "my-plugin",
  name: "Mój plugin",
  description: "Krótkie podsumowanie",
  register(api) {
    api.registerProvider({/* ... */});
    api.registerTool({/* ... */});
  },
});

• id musi odpowiadać manifestowi openclaw.plugin.json.
• Zewnętrzne katalogi sesji używają openclaw/plugin-sdk/session-catalog i api.registerSessionCatalog({ id, label, list, read, continueSession?, archive? }). Rdzeń jest właścicielem metod Gateway sessions.catalog.*; dostawcy zwracają projekcje hosta, sesji i znormalizowanego transkryptu bez rejestrowania wywołań RPC.
• kind jest przestarzałe: zamiast tego należy zadeklarować wyłączny slot ("memory" lub "context-engine") w polu kind manifestu openclaw.plugin.json. kind punktu wejścia środowiska uruchomieniowego pozostaje jedynie awaryjnym mechanizmem zgodności dla starszych pluginów.
• configSchema może być funkcją umożliwiającą leniwe obliczanie. OpenClaw rozwiązuje i zapamiętuje schemat przy pierwszym dostępie, dzięki czemu kosztowne konstruktory schematów są uruchamiane tylko raz.
• Deskryptor nodeHostCommands może definiować isAvailable({ config, env }). Zwrócenie false pomija to polecenie i jego funkcję w deklaracji Gateway bezinterfejsowego Node. OpenClaw oblicza tę wartość na podstawie lokalnej konfiguracji startowej Node; procedury obsługi poleceń nadal powinny sprawdzać dostępność podczas wywołania.

​

defineChannelPluginEntry

import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "Mój kanał",
  description: "Krótkie podsumowanie",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerCliMetadata(api) {
    api.registerCli(/* ... */);
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});

• setRuntime jest wykonywane w każdym trybie z wyjątkiem "cli-metadata" i "tool-discovery". W tym miejscu należy przechowywać odwołanie do środowiska uruchomieniowego, zwykle za pomocą createPluginRuntimeStore.
• registerCliMetadata jest wykonywane dla "cli-metadata", "discovery" i "full". Należy używać go jako kanonicznego miejsca dla należących do kanału deskryptorów CLI, aby pomoc główna nie aktywowała pluginu, migawki wykrywania zawierały statyczne metadane poleceń, a zwykła rejestracja CLI pozostawała zgodna z pełnym ładowaniem pluginu.
• registerFull jest wykonywane tylko dla "full" i "tool-discovery". W przypadku "tool-discovery" jest wykonywane zamiast rejestracji kanału: OpenClaw całkowicie pomija registerChannel/setRuntime i wywołuje wyłącznie registerFull, dlatego wszelkie operacje rejestracji dostawcy lub narzędzia wymagane przez kanał do samodzielnego wykrywania albo wykonywania narzędzi muszą znajdować się właśnie tam, a nie za zwykłą konfiguracją kanału.
• Rejestracja wykrywania nie aktywuje pluginu, ale nie odbywa się bez importowania: OpenClaw może obliczyć zaufany punkt wejścia pluginu i moduł pluginu kanału w celu zbudowania migawki. Importy najwyższego poziomu nie powinny powodować skutków ubocznych, a gniazda, klienty, procesy robocze i usługi należy umieszczać wyłącznie w ścieżkach "full".
• Podobnie jak definePluginEntry, configSchema może być leniwą fabryką; OpenClaw zapamiętuje rozwiązany schemat przy pierwszym dostępie.

• Należy używać api.registerCli(..., { descriptors: [...] }) dla należących do pluginu głównych poleceń CLI, które mają być ładowane leniwie, ale nie mogą znikać z głównego drzewa analizy składniowej CLI. Nazwy deskryptorów muszą składać się z liter, cyfr, łączników i znaków podkreślenia oraz zaczynać się literą lub cyfrą; OpenClaw odrzuca inne formaty i usuwa terminalowe sekwencje sterujące z opisów przed wyświetleniem pomocy. Należy uwzględnić każdy główny korzeń polecenia udostępniany przez rejestrator. Samo commands pozostaje na zachłannie ładowanej ścieżce zgodności.
• Należy używać api.registerNodeCliFeature(...) dla poleceń funkcji sparowanego Node, aby trafiały pod openclaw nodes (odpowiednik registerCli(registrar, { parentPath: ["nodes"], ... })).
• W przypadku innych zagnieżdżonych poleceń pluginu należy dodać parentPath i zarejestrować polecenia w obiekcie program przekazanym do rejestratora; OpenClaw rozwiązuje go do polecenia nadrzędnego przed wywołaniem pluginu.
• W przypadku pluginów kanałów deskryptory CLI należy rejestrować z registerCliMetadata, a registerFull powinno koncentrować się na zadaniach dotyczących wyłącznie środowiska uruchomieniowego.
• Jeśli registerFull rejestruje również metody RPC Gateway, należy umieścić je pod prefiksem właściwym dla pluginu. Zastrzeżone przestrzenie nazw administracyjnych rdzenia (config.*, exec.approvals.*, wizard.*, update.*) są zawsze wymuszane jako operator.admin.

​

defineSetupPluginEntry

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);

import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";

export default defineBundledChannelSetupEntry({
  importMetaUrl: import.meta.url,
  plugin: {
    specifier: "./channel-plugin-api.js",
    exportName: "myChannelPlugin",
  },
  runtime: {
    specifier: "./runtime-api.js",
    exportName: "setMyChannelRuntime",
  },
  registerSetupRuntime(api) {
    api.registerHttpRoute({
      path: "/my-channel/events",
      auth: "plugin",
      handler: async (req, res) => {
        /* trasa bezpieczna dla konfiguracji */
      },
    });
  },
});

​

Tryb rejestracji

register(api) {
  if (
    api.registrationMode === "cli-metadata" ||
    api.registrationMode === "discovery" ||
    api.registrationMode === "full"
  ) {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

  if (api.registrationMode === "tool-discovery") {
    // Rejestruj tylko powierzchnie możliwości (dostawców/narzędzia), bez kanału.
    return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // Ciężkie rejestracje przeznaczone wyłącznie dla środowiska wykonawczego
  api.registerService(/* ... */);
}

api.registerService({
  id: "index-events",
  start(ctx) {
    ctx.gatewayEvents?.emit("changed", { revision: 1 }, { scope: "operator.read" });
  },
});

​

Formy pluginów

​

Powiązane materiały

• Omówienie SDK — interfejs API rejestracji i dokumentacja ścieżek podrzędnych
• Pomocniki środowiska wykonawczego — api.runtime i createPluginRuntimeStore
• Konfiguracja i ustawienia — manifest, wpis konfiguracji, odroczone ładowanie
• Pluginy kanałów — tworzenie obiektu ChannelPlugin
• Pluginy dostawców — rejestracja dostawcy i hooki