Omówienie Plugin SDK

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.

​

Konwencja importu

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

​

Odniesienie podścieżek

​

API rejestracji

​

Rejestracja capability

​

Narzędzia i polecenia

​

Infrastruktura

​

Hooki hosta dla pluginów przepływu pracy

• 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ą być właścicielami rozszerzeń sesji, deskryptorów UI, poleceń, metadanych narzędzi, wstrzyknięć do następnego turn i zwykłych hooków.
• Zaufane polityki narzędzi uruchamiają się przed zwykłymi hookami before_tool_call i są dostępne tylko dla elementów dołączonych w pakiecie, ponieważ uczestniczą w polityce bezpieczeństwa hosta.
• Zastrzeżona własność poleceń jest dostępna tylko dla elementów dołączonych w pakiecie. Zewnętrzne pluginy powinny używać własnych nazw poleceń lub aliasów.
• allowPromptInjection=false wyłącza hooki modyfikujące prompt, w tym agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, pola promptu ze starszego before_agent_start oraz enqueueNextTurnInjection.

​

Rejestracja odkrywania 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ń będących własnością rejestratora
• descriptors: deskryptory poleceń używane podczas parsowania dla 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 backendu CLI

• id backendu staje się prefiksem dostawcy w referencjach modeli, takich jak codex-cli/gpt-5.
• config backendu używa tego samego kształtu co agents.defaults.cliBackends.<id>.
• Konfiguracja użytkownika nadal wygrywa. OpenClaw scala agents.defaults.cliBackends.<id> nad domyślną konfiguracją pluginu przed uruchomieniem CLI.
• Użyj normalizeConfig, gdy backend wymaga przepisania zgodności po scaleniu (na przykład normalizacji starych kształtów flag).
• Użyj resolveExecutionArgs dla przepisania argv o zakresie żądania, które należy do dialektu CLI, takiego jak mapowanie poziomów myślenia OpenClaw na natywną flagę effort.

​

Wyłączne sloty

​

Adaptery embeddingów pamięci

• registerMemoryCapability jest preferowanym, wyłącznym API pluginu pamięci.
• registerMemoryCapability może także udostępniać publicArtifacts.listArtifacts(...), aby pluginy towarzyszące mogły konsumować wyeksportowane artefakty pamięci przez openclaw/plugin-sdk/memory-host-core zamiast sięgać do prywatnego układu konkretnego pluginu pamięci.
• registerMemoryPromptSection, registerMemoryFlushPlan i registerMemoryRuntime to zgodne ze starszymi wersjami, wyłączne API pluginu pamięci.
• MemoryFlushPlan.model może przypiąć turn opróżniania do dokładnej referencji provider/model, takiej jak ollama/qwen3:8b, bez dziedziczenia aktywnego łańcucha fallback.
• registerMemoryEmbeddingProvider pozwala aktywnemu pluginowi pamięci zarejestrować jeden lub więcej identyfikatorów adapterów embeddingów (na przykład openai, gemini albo niestandardowy identyfikator zdefiniowany przez plugin).
• Konfiguracja użytkownika, taka jak agents.defaults.memorySearch.provider i agents.defaults.memorySearch.fallback, jest rozwiązywana względem tych zarejestrowanych identyfikatorów adapterów.

​

Zdarzenia i cykl życia

​

Semantyka decyzji hooków

• before_tool_call: zwrócenie { block: true } jest końcowe. Gdy dowolny handler je ustawi, handlery 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 końcowe. Gdy dowolny handler je ustawi, handlery 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 końcowe. Gdy dowolny handler przejmie wysyłkę, handlery o niższym priorytecie i domyślna ścieżka wysyłki modelu są pomijane.
• message_sending: zwrócenie { cancel: true } jest końcowe. Gdy dowolny handler je ustawi, handlery 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: użyj typowanego pola threadId, gdy potrzebujesz routingu przychodzącego wątku/tematu. Zachowaj metadata dla dodatków specyficznych dla kanału.
• message_sending: użyj typowanych pól routingu replyToId / threadId, zanim przejdziesz do specyficznego dla kanału metadata.
• gateway_start: użyj ctx.config, ctx.workspaceDir i ctx.getCron?.() dla stanu startowego będącego własnością Gateway zamiast polegać na wewnętrznych hookach gateway:startup.
• cron_changed: obserwuj zmiany cyklu życia Cron będącego własnością Gateway. Użyj event.job?.state?.nextRunAtMs i ctx.getCron?.() podczas synchronizacji zewnętrznych harmonogramów wybudzania i utrzymuj OpenClaw jako źródło prawdy dla sprawdzania terminów oraz wykonania.

​

Pola obiektu API

​

Konwencja modułów wewnętrznych

my-plugin/
  api.ts            # Public exports for external consumers
  runtime-api.ts    # Internal-only runtime exports
  index.ts          # Plugin entry point
  setup-entry.ts    # Lightweight setup-only entry (optional)

• Anthropic: publiczna granica api.ts / contract-api.ts dla pomocników strumienia nagłówka beta Claude i service_tier.
• @openclaw/openai-provider: api.ts eksportuje konstruktory dostawcy, pomocniki modelu domyślnego i konstruktory dostawcy czasu rzeczywistego.
• @openclaw/openrouter-provider: api.ts eksportuje konstruktor dostawcy oraz pomocniki onboardingu/konfiguracji.

​

Powiązane