Omówienie SDK Pluginów

​

Konwencja importowania

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

​

Dokumentacja ścieżek podrzędnych

​

API rejestracji

​

Rejestrowanie możliwości

​

Narzędzia i polecenia

agentPromptGuidance: [
  "Global command hint.",
  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },
];

​

Infrastruktura

​

Haki hosta dla Pluginów przepływu pracy

api.session.controls.registerControlUiDescriptor({
  surface: "tab",
  id: "logbook",
  label: "Logbook",
  description: "Your day as a timeline, built from screen snapshots.",
  icon: "sun",
  group: "control",
  requiredScopes: ["operator.write"],
});

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

• Zewnętrzne Pluginy mogą odpowiadać za rozszerzenia sesji, deskryptory interfejsu użytkownika, polecenia, metadane narzędzi, wstrzyknięcia do następnej tury i zwykłe haki.
• Zaufane zasady narzędzi są wykonywane przed zwykłymi hakami before_tool_call i są zaufane przez hosta. Zasady wbudowane są wykonywane jako pierwsze; zasady zainstalowanych Pluginów wymagają jawnego włączenia oraz umieszczenia ich lokalnych identyfikatorów w contracts.trustedToolPolicies, a następnie są wykonywane w kolejności ładowania Pluginów. Identyfikatory zasad są ograniczone do rejestrującego je Pluginu.
• Zastrzeżone polecenia mogą należeć wyłącznie do wbudowanych Pluginów. Zewnętrzne Pluginy powinny używać własnych nazw poleceń lub aliasów.
• allowPromptInjection=false wyłącza haki modyfikujące prompt, w tym agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, pola promptu ze starszego before_agent_start oraz enqueueNextTurnInjection.

​

Rejestracja wykrywania Gateway

api.registerGatewayDiscoveryService({
  id: "my-discovery",
  async advertise(ctx) {
    const handle = await startMyAdvertiser({
      gatewayPort: ctx.gatewayPort,
      tls: ctx.gatewayTlsEnabled,
      displayName: ctx.machineDisplayName,
    });
    return { stop: () => handle.stop() };
  },
});

​

Metadane rejestracji CLI

• commands: jawne nazwy poleceń należące do rejestratora
• descriptors: deskryptory poleceń używane podczas parsowania na potrzeby pomocy CLI, routingu i leniwej rejestracji CLI Pluginu
• parentPath: opcjonalna ścieżka polecenia nadrzędnego dla zagnieżdżonych grup poleceń, takich jak ["nodes"]

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Manage Matrix accounts, verification, devices, and profile state",
        hasSubcommands: true,
      },
    ],
  },
);

api.registerCli(
  async ({ program }) => {
    const { registerNodesCanvasCommands } = await import("./src/cli.js");
    registerNodesCanvasCommands(program);
  },
  {
    parentPath: ["nodes"],
    descriptors: [
      {
        name: "canvas",
        description: "Capture or render canvas content from a paired node",
        hasSubcommands: true,
      },
    ],
  },
);

​

Rejestracja zaplecza CLI

• id zaplecza staje się prefiksem dostawcy w odwołaniach do modeli, takich jak my-cli/gpt-5.
• config zaplecza używa tej samej struktury co agents.defaults.cliBackends.<id>.
• Konfiguracja użytkownika nadal ma pierwszeństwo. Przed uruchomieniem CLI OpenClaw nakłada agents.defaults.cliBackends.<id> na domyślną konfigurację Pluginu.
• Użyj normalizeConfig, gdy zaplecze wymaga po scaleniu przekształceń zapewniających zgodność (na przykład normalizacji starych struktur flag).
• Użyj resolveExecutionArgs do modyfikacji argumentów argv w zakresie żądania, które należą do dialektu CLI, takich jak mapowanie poziomów rozumowania OpenClaw na natywną flagę nakładu. Hook otrzymuje ctx.executionMode; użyj "side-question", aby dodać natywne dla zaplecza flagi izolacji dla efemerycznych wywołań /btw. Jeśli te flagi niezawodnie wyłączają natywne narzędzia w CLI, w którym są one poza tym zawsze włączone, zadeklaruj również sideQuestionToolMode: "disabled".
• Zaplecza, które mogą wyłączyć wszystkie natywne narzędzia dla określonego uruchomienia, mogą deklarować nativeToolMode: "selectable". Ograniczone wywołania przekazują pustą krotkę ctx.toolAvailability.native wraz z dokładną listą dozwolonych MCP izolowaną przez hosta; resolveExecutionArgs musi wymuszać oba te ograniczenia w końcowych argumentach argv nowego lub wznawianego uruchomienia. Jeśli zaplecze nie może tego zrobić, OpenClaw bezpiecznie odmawia wykonania.

​

Wyłączne miejsca

​

Przestarzałe adaptery osadzania pamięci

• registerMemoryCapability jest preferowanym wyłącznym interfejsem API Pluginu pamięci.
• registerMemoryCapability może również udostępniać publicArtifacts.listArtifacts(...), aby towarzyszące Pluginy mogły korzystać z wyeksportowanych artefaktów pamięci za pośrednictwem openclaw/plugin-sdk/memory-host-core, zamiast uzyskiwać dostęp do prywatnego układu konkretnego Pluginu pamięci.
• registerMemoryPromptSection, registerMemoryFlushPlan i registerMemoryRuntime to wyłączne interfejsy API Pluginu pamięci zachowane ze względów zgodności ze starszymi wersjami.
• MemoryFlushPlan.model może przypiąć turę opróżniania do dokładnego odwołania provider/model, takiego jak ollama/qwen3:8b, bez dziedziczenia aktywnego łańcucha rezerwowego.
• registerMemoryEmbeddingProvider jest przestarzałe. Nowi dostawcy osadzania powinni używać api.registerEmbeddingProvider(...) i contracts.embeddingProviders.
• Istniejący dostawcy specyficzni dla pamięci nadal działają w okresie migracji, ale inspekcja Pluginu zgłasza to jako dług zgodności w przypadku Pluginów, które nie są dołączone.

​

Zdarzenia i cykl życia

​

Semantyka decyzji hooków

• before_tool_call: zwrócenie { block: true } jest rozstrzygające. Gdy dowolny moduł obsługi ustawi tę wartość, moduły obsługi o niższym priorytecie są pomijane.
• before_tool_call: zwrócenie { block: false } jest traktowane jako brak decyzji (tak samo jak pominięcie block), a nie jako nadpisanie.
• before_install: zwrócenie { block: true } jest rozstrzygające. Gdy dowolny moduł obsługi ustawi tę wartość, moduły obsługi o niższym priorytecie są pomijane.
• before_install: zwrócenie { block: false } jest traktowane jako brak decyzji (tak samo jak pominięcie block), a nie jako nadpisanie.
• reply_dispatch: zwrócenie { handled: true, ... } jest rozstrzygające. Gdy dowolny moduł obsługi przejmie wysyłanie, moduły obsługi o niższym priorytecie oraz domyślna ścieżka wysyłania modelu są pomijane.
• message_sending: zwrócenie { cancel: true } jest rozstrzygające. Gdy dowolny moduł obsługi ustawi tę wartość, moduły obsługi o niższym priorytecie są pomijane.
• message_sending: zwrócenie { cancel: false } jest traktowane jako brak decyzji (tak samo jak pominięcie cancel), a nie jako nadpisanie.
• message_received: gdy potrzebujesz kierowania przychodzących wiadomości według wątku lub tematu, użyj typowanego pola threadId. Pole metadata zachowaj na dodatkowe dane specyficzne dla kanału.
• message_sending: najpierw używaj typowanych pól kierowania replyToId / threadId, a dopiero potem korzystaj z pola metadata specyficznego dla kanału.
• gateway_start: do stanu uruchamiania będącego własnością Gateway używaj ctx.config, ctx.workspaceDir i ctx.getCron?.() zamiast polegać na wewnętrznych punktach zaczepienia gateway:startup. Cron może być w tym momencie nadal ładowany.
• cron_reconciled: po uruchomieniu lub ponownym załadowaniu harmonogramu odbuduj pełną zewnętrzną projekcję Cron. Obejmuje ona reason oraz efektywny stan enabled, w tym enabled: false, natomiast ctx.getCron?.() zwraca dokładnie uzgodniony harmonogram. Przekaż ctx.abortSignal do trwałych operacji projekcji; zostaną one przerwane, gdy ta migawka harmonogramu zostanie zastąpiona lub Gateway zostanie zamknięty.
• cron_changed: obserwuj zmiany cyklu życia Cron będącego własnością Gateway. Zdarzenia scheduled i removed są wskazówkami uzgadniania po zatwierdzeniu, a nie uporządkowanym dziennikiem zmian. W zdarzeniu zaplanowania pole event.nextRunAtMs nie występuje, gdy zadanie nie ma następnego wybudzenia; zdarzenie usunięcia nadal zawiera migawkę usuniętego zadania.

​

Pola obiektu API

​

Konwencja modułów wewnętrznych

my-plugin/
  api.ts            # Eksporty publiczne dla zewnętrznych odbiorców
  runtime-api.ts    # Eksporty środowiska wykonawczego wyłącznie do użytku wewnętrznego
  index.ts          # Punkt wejścia pluginu
  setup-entry.ts    # Lekki punkt wejścia wyłącznie do konfiguracji (opcjonalny)

• Anthropic: publiczny punkt styku api.ts / contract-api.ts dla funkcji pomocniczych nagłówków wersji beta Claude i strumieni service_tier.
• @openclaw/openai-provider: api.ts eksportuje konstruktory dostawcy, funkcje pomocnicze modelu domyślnego oraz konstruktory dostawcy czasu rzeczywistego.
• @openclaw/openrouter-provider: api.ts eksportuje konstruktor dostawcy oraz funkcje pomocnicze wdrażania i konfiguracji.

​

Powiązane materiały