Saltar al contenido principal

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.

El SDK de plugins es el contrato tipado entre los plugins y el núcleo. Esta página es la referencia sobre qué importar y qué puedes registrar.
Esta página es para autores de plugins que usan openclaw/plugin-sdk/* dentro de OpenClaw. Para apps externas, scripts, paneles, trabajos de CI y extensiones de IDE que quieran ejecutar agentes a través del Gateway, usa en su lugar el SDK de apps de OpenClaw y el paquete @openclaw/sdk.
¿Buscas una guía práctica? Empieza con Creación de plugins, usa Plugins de canal para plugins de canal, Plugins de proveedor para plugins de proveedor, Plugins de backend de CLI para backends locales de CLI de IA y Hooks de plugins para plugins de herramientas o hooks de ciclo de vida.

Convención de importación

Importa siempre desde una subruta específica:
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
Cada subruta es un módulo pequeño y autónomo. Esto mantiene el arranque rápido y evita problemas de dependencias circulares. Para helpers de entrada/compilación específicos de canal, prefiere openclaw/plugin-sdk/channel-core; reserva openclaw/plugin-sdk/core para la superficie paraguas más amplia y helpers compartidos como buildChannelConfigSchema. Para la configuración de canal, publica el JSON Schema propiedad del canal mediante openclaw.plugin.json#channelConfigs. La subruta plugin-sdk/channel-config-schema es para primitivas de esquema compartidas y el generador genérico. Los plugins incluidos de OpenClaw usan plugin-sdk/bundled-channel-config-schema para esquemas retenidos de canales incluidos. Las exportaciones de compatibilidad obsoletas permanecen en plugin-sdk/channel-config-schema-legacy; ninguna subruta de esquema incluido es un patrón para plugins nuevos.
No importes seams de conveniencia con marca de proveedor o canal (por ejemplo openclaw/plugin-sdk/slack, .../discord, .../signal, .../whatsapp). Los plugins incluidos componen subrutas genéricas del SDK dentro de sus propios barrels api.ts / runtime-api.ts; los consumidores del núcleo deben usar esos barrels locales del plugin o añadir un contrato SDK genérico y estrecho cuando una necesidad sea realmente transversal entre canales.Un conjunto pequeño de seams auxiliares de plugins incluidos sigue apareciendo en el mapa de exportación generado cuando tiene uso rastreado por propietarios. Existen solo para mantenimiento de plugins incluidos y no son rutas de importación recomendadas para nuevos plugins de terceros.openclaw/plugin-sdk/discord y openclaw/plugin-sdk/telegram-account también se mantienen como fachadas de compatibilidad obsoletas para uso rastreado por propietarios. No copies esas rutas de importación en plugins nuevos; usa en su lugar helpers de runtime inyectados y subrutas genéricas del SDK de canal.

Referencia de subrutas

El SDK de plugins se expone como un conjunto de subrutas estrechas agrupadas por área (entrada de plugin, canal, proveedor, autenticación, runtime, capacidad, memoria y helpers reservados de plugins incluidos). Para ver el catálogo completo, agrupado y enlazado, consulta Subrutas del SDK de plugins. El inventario de entrypoints del compilador está en scripts/lib/plugin-sdk-entrypoints.json; las exportaciones de paquetes se generan a partir del subconjunto público tras restar las subrutas locales de prueba/internas del repositorio enumeradas en scripts/lib/plugin-sdk-private-local-only-subpaths.json. Ejecuta pnpm plugin-sdk:surface para auditar el recuento de exportaciones públicas. Las subrutas públicas obsoletas con suficiente antigüedad y sin uso en código de producción de extensiones incluidas se rastrean en scripts/lib/plugin-sdk-deprecated-public-subpaths.json; los barrels amplios de reexportación obsoletos se rastrean en scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json.

API de registro

El callback register(api) recibe un objeto OpenClawPluginApi con estos métodos:

Registro de capacidades

MétodoQué registra
api.registerProvider(...)Inferencia de texto (LLM)
api.registerAgentHarness(...)Ejecutor de agentes experimental de bajo nivel
api.registerCliBackend(...)Backend local de inferencia de CLI
api.registerChannel(...)Canal de mensajería
api.registerSpeechProvider(...)Síntesis de texto a voz / STT
api.registerRealtimeTranscriptionProvider(...)Transcripción en tiempo real por streaming
api.registerRealtimeVoiceProvider(...)Sesiones de voz dúplex en tiempo real
api.registerMediaUnderstandingProvider(...)Análisis de imagen/audio/video
api.registerImageGenerationProvider(...)Generación de imágenes
api.registerMusicGenerationProvider(...)Generación de música
api.registerVideoGenerationProvider(...)Generación de video
api.registerWebFetchProvider(...)Proveedor de obtención / scraping web
api.registerWebSearchProvider(...)Búsqueda web

Herramientas y comandos

MétodoQué registra
api.registerTool(tool, opts?)Herramienta de agente (obligatoria o { optional: true })
api.registerCommand(def)Comando personalizado (omite el LLM)
Los comandos de plugin pueden establecer agentPromptGuidance cuando el agente necesita una pista breve de enrutamiento propiedad del comando. Mantén ese texto sobre el propio comando; no añadas políticas específicas de proveedor o plugin a los generadores de prompts del núcleo.

Infraestructura

MétodoQué registra
api.registerHook(events, handler, opts?)Hook de evento
api.registerHttpRoute(params)Endpoint HTTP del Gateway
api.registerGatewayMethod(name, handler)Método RPC del Gateway
api.registerGatewayDiscoveryService(service)Anunciante de descubrimiento del Gateway local
api.registerCli(registrar, opts?)Subcomando de CLI
api.registerNodeCliFeature(registrar, opts?)CLI de funcionalidad de Node bajo openclaw nodes
api.registerService(service)Servicio en segundo plano
api.registerInteractiveHandler(registration)Handler interactivo
api.registerAgentToolResultMiddleware(...)Middleware de runtime para resultados de herramientas
api.registerMemoryPromptSupplement(builder)Sección aditiva de prompt adyacente a memoria
api.registerMemoryCorpusSupplement(adapter)Corpus aditivo de búsqueda/lectura de memoria

Hooks de host para plugins de flujo de trabajo

Los hooks de host son los seams del SDK para plugins que necesitan participar en el ciclo de vida del host en vez de limitarse a añadir un proveedor, canal o herramienta. Son contratos genéricos; Plan Mode puede usarlos, pero también pueden hacerlo flujos de aprobación, compuertas de política de workspace, monitores en segundo plano, asistentes de configuración y plugins complementarios de UI.
MétodoContrato que posee
api.session.state.registerSessionExtension(...)Estado de sesión propiedad del plugin, compatible con JSON, proyectado mediante sesiones del Gateway
api.session.workflow.enqueueNextTurnInjection(...)Contexto duradero exactamente una vez inyectado en el siguiente turno del agente para una sesión
api.registerTrustedToolPolicy(...)Política de herramientas previa al plugin, incluida/de confianza, que puede bloquear o reescribir parámetros de herramientas
api.registerToolMetadata(...)Metadatos de visualización del catálogo de herramientas sin cambiar la implementación de la herramienta
api.registerCommand(...)Comandos de plugin con ámbito; los resultados de comando pueden establecer continueAgent: true; los comandos nativos de Discord admiten descriptionLocalizations
api.session.controls.registerControlUiDescriptor(...)Descriptores de contribución de UI de control para superficies de sesión, herramienta, ejecución o configuración
api.lifecycle.registerRuntimeLifecycle(...)Callbacks de limpieza para recursos de runtime propiedad del plugin en rutas de reset/eliminación/recarga
api.agent.events.registerAgentEventSubscription(...)Suscripciones a eventos saneadas para estado de flujo de trabajo y monitores
api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)Estado temporal por ejecución del plugin, limpiado en el ciclo de vida terminal de la ejecución
api.session.workflow.registerSessionSchedulerJob(...)Metadatos de limpieza para trabajos de programador propiedad del plugin; no programa trabajo ni crea registros de tareas
api.session.workflow.sendSessionAttachment(...)Entrega de archivos adjuntos, mediada por el host y solo para incluidos, a la ruta de sesión directa saliente activa
api.session.workflow.scheduleSessionTurn(...) / unscheduleSessionTurnsByTag(...)Turnos de sesión programados respaldados por Cron, solo para incluidos, más limpieza basada en etiquetas
api.session.controls.registerSessionAction(...)Acciones de sesión tipadas que los clientes pueden despachar mediante el Gateway
Usa los espacios de nombres agrupados para código de plugin nuevo:
  • 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(...)
Los métodos planos equivalentes siguen disponibles como aliases de compatibilidad obsoletos para plugins existentes. No añadas código de plugin nuevo que llame directamente a api.registerSessionExtension, api.enqueueNextTurnInjection, api.registerControlUiDescriptor, api.registerRuntimeLifecycle, api.registerAgentEventSubscription, api.emitAgentEvent, api.setRunContext, api.getRunContext, api.clearRunContext, api.registerSessionSchedulerJob, api.registerSessionAction, api.sendSessionAttachment, api.scheduleSessionTurn o api.unscheduleSessionTurnsByTag. scheduleSessionTurn(...) es una utilidad de ámbito de sesión sobre el programador Cron del Gateway. Cron posee la temporización y crea el registro de tarea en segundo plano cuando se ejecuta el turno; el SDK de Plugin solo restringe la sesión de destino, la nomenclatura propiedad del plugin y la limpieza. Usa api.runtime.tasks.managedFlows dentro del turno programado cuando el trabajo en sí necesite estado duradero de Task Flow de varios pasos. Los contratos dividen la autoridad intencionalmente:
  • Los plugins externos pueden poseer extensiones de sesión, descriptores de interfaz de usuario, comandos, metadatos de herramientas, inyecciones del siguiente turno y hooks normales.
  • Las políticas de herramientas de confianza se ejecutan antes que los hooks ordinarios before_tool_call y son solo empaquetadas porque participan en la política de seguridad del host.
  • La propiedad de comandos reservados es solo empaquetada. Los plugins externos deben usar sus propios nombres de comando o alias.
  • allowPromptInjection=false desactiva los hooks que mutan prompts, incluidos agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, los campos de prompt de before_agent_start heredado y enqueueNextTurnInjection.
Ejemplos de consumidores que no son de Plan:
Arquetipo de pluginHooks usados
Flujo de aprobaciónExtensión de sesión, continuación de comando, inyección del siguiente turno, descriptor de interfaz de usuario
Puerta de política de presupuesto/espacio de trabajoPolítica de herramienta de confianza, metadatos de herramienta, proyección de sesión
Monitor de ciclo de vida en segundo planoLimpieza de ciclo de vida de runtime, suscripción a eventos de agente, propiedad/limpieza del programador de sesión, contribución al prompt de heartbeat, descriptor de interfaz de usuario
Asistente de configuración u onboardingExtensión de sesión, comandos con ámbito, descriptor de interfaz de usuario de Control
Los namespaces de administración central reservados (config.*, exec.approvals.*, wizard.*, update.*) siempre permanecen como operator.admin, incluso si un plugin intenta asignarles un ámbito de método de gateway más limitado. Prefiere prefijos específicos del plugin para los métodos propiedad del plugin.
Los plugins empaquetados pueden usar api.registerAgentToolResultMiddleware(...) cuando necesiten reescribir el resultado de una herramienta después de la ejecución y antes de que el runtime devuelva ese resultado al modelo. Esta es la costura de confianza neutral al runtime para reductores de salida asíncronos como tokenjuice.Los plugins empaquetados deben declarar contracts.agentToolResultMiddleware para cada runtime de destino, por ejemplo ["pi", "codex"]. Los plugins externos no pueden registrar este middleware; conserva los hooks normales de plugins de OpenClaw para trabajos que no necesiten temporización de resultado de herramienta previa al modelo. Se eliminó la antigua ruta de registro de fábrica de extensiones incrustadas exclusiva de Pi.

Registro de descubrimiento del Gateway

api.registerGatewayDiscoveryService(...) permite que un plugin anuncie el Gateway activo en un transporte de descubrimiento local como mDNS/Bonjour. OpenClaw llama al servicio durante el arranque del Gateway cuando el descubrimiento local está habilitado, pasa los puertos actuales del Gateway y datos de pista TXT no secretos, y llama al manejador stop devuelto durante el apagado del 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() };
  },
});
Los plugins de descubrimiento del Gateway no deben tratar los valores TXT anunciados como secretos o autenticación. El descubrimiento es una pista de enrutamiento; la autenticación del Gateway y la fijación TLS siguen poseyendo la confianza.

Metadatos de registro de CLI

api.registerCli(registrar, opts?) acepta dos tipos de metadatos de comando:
  • commands: nombres de comando explícitos propiedad del registrador
  • descriptors: descriptores de comando en tiempo de análisis usados para ayuda de CLI, enrutamiento y registro lazy de CLI de plugin
  • parentPath: ruta opcional del comando padre para grupos de comandos anidados, como ["nodes"]
Para funciones de nodos emparejados, prefiere api.registerNodeCliFeature(registrar, opts?). Es un pequeño wrapper alrededor de api.registerCli(..., { parentPath: ["nodes"] }) y hace que comandos como openclaw nodes canvas sean funciones de nodo explícitas propiedad del plugin. Si quieres que un comando de plugin permanezca cargado de forma lazy en la ruta normal de CLI raíz, proporciona descriptors que cubran cada raíz de comando de nivel superior expuesta por ese registrador.
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,
      },
    ],
  },
);
Los comandos anidados reciben el comando padre resuelto como program:
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,
      },
    ],
  },
);
Usa commands por sí solo únicamente cuando no necesites registro lazy de CLI raíz. Esa ruta de compatibilidad eager sigue siendo compatible, pero no instala marcadores de posición respaldados por descriptores para carga lazy en tiempo de análisis.

Registro de backend de CLI

api.registerCliBackend(...) permite que un plugin posea la configuración predeterminada para un backend local de CLI de IA como codex-cli.
  • El id del backend se convierte en el prefijo de proveedor en referencias de modelo como codex-cli/gpt-5.
  • La config del backend usa la misma forma que agents.defaults.cliBackends.<id>.
  • La configuración del usuario sigue prevaleciendo. OpenClaw fusiona agents.defaults.cliBackends.<id> sobre el valor predeterminado del plugin antes de ejecutar la CLI.
  • Usa normalizeConfig cuando un backend necesite reescrituras de compatibilidad después de la fusión (por ejemplo, normalizar formas antiguas de flags).
  • Usa resolveExecutionArgs para reescrituras de argv de ámbito de solicitud que pertenezcan al dialecto de CLI, como mapear niveles de pensamiento de OpenClaw a un flag nativo de esfuerzo.
Para una guía de autoría de extremo a extremo, consulta plugins de backend de CLI.

Slots exclusivos

MétodoQué registra
api.registerContextEngine(id, factory)Motor de contexto (uno activo a la vez). El callback assemble() recibe availableTools y citationsMode para que el motor pueda adaptar adiciones al prompt.
api.registerMemoryCapability(capability)Capacidad de memoria unificada
api.registerMemoryPromptSection(builder)Constructor de sección de prompt de memoria
api.registerMemoryFlushPlan(resolver)Resolutor de plan de vaciado de memoria
api.registerMemoryRuntime(runtime)Adaptador de runtime de memoria

Adaptadores de embeddings de memoria

MétodoQué registra
api.registerMemoryEmbeddingProvider(adapter)Adaptador de embedding de memoria para el plugin activo
  • registerMemoryCapability es la API exclusiva preferida para plugins de memoria.
  • registerMemoryCapability también puede exponer publicArtifacts.listArtifacts(...) para que los plugins complementarios puedan consumir artefactos de memoria exportados mediante openclaw/plugin-sdk/memory-host-core en lugar de acceder al diseño privado de un plugin de memoria específico.
  • registerMemoryPromptSection, registerMemoryFlushPlan y registerMemoryRuntime son API exclusivas heredadas compatibles para plugins de memoria.
  • MemoryFlushPlan.model puede fijar el turno de vaciado a una referencia exacta provider/model, como ollama/qwen3:8b, sin heredar la cadena de fallback activa.
  • registerMemoryEmbeddingProvider permite que el plugin de memoria activo registre uno o más ids de adaptador de embedding (por ejemplo openai, gemini o un id personalizado definido por el plugin).
  • La configuración de usuario como agents.defaults.memorySearch.provider y agents.defaults.memorySearch.fallback se resuelve contra esos ids de adaptador registrados.

Eventos y ciclo de vida

MétodoQué hace
api.on(hookName, handler, opts?)Hook de ciclo de vida tipado
api.onConversationBindingResolved(handler)Callback de enlace de conversación
Consulta hooks de Plugin para ver ejemplos, nombres de hooks comunes y semántica de guardas.

Semántica de decisión de hooks

  • before_tool_call: devolver { block: true } es terminal. Una vez que cualquier manejador lo establece, se omiten los manejadores de menor prioridad.
  • before_tool_call: devolver { block: false } se trata como sin decisión (igual que omitir block), no como una anulación.
  • before_install: devolver { block: true } es terminal. Una vez que cualquier manejador lo establece, se omiten los manejadores de menor prioridad.
  • before_install: devolver { block: false } se trata como sin decisión (igual que omitir block), no como una anulación.
  • reply_dispatch: devolver { handled: true, ... } es terminal. Una vez que cualquier manejador reclama el despacho, se omiten los manejadores de menor prioridad y la ruta predeterminada de despacho del modelo.
  • message_sending: devolver { cancel: true } es terminal. Una vez que cualquier manejador lo establece, se omiten los manejadores de menor prioridad.
  • message_sending: devolver { cancel: false } se trata como sin decisión (igual que omitir cancel), no como una anulación.
  • message_received: usa el campo tipado threadId cuando necesites enrutamiento entrante de hilo/tema. Conserva metadata para extras específicos del canal.
  • message_sending: usa los campos de enrutamiento tipados replyToId / threadId antes de recurrir a metadata específico del canal.
  • gateway_start: usa ctx.config, ctx.workspaceDir y ctx.getCron?.() para el estado de arranque propiedad del gateway en lugar de depender de hooks internos gateway:startup.
  • cron_changed: observa cambios de ciclo de vida de cron propiedad del gateway. Usa event.job?.state?.nextRunAtMs y ctx.getCron?.() al sincronizar programadores de activación externos, y conserva OpenClaw como la fuente de verdad para las comprobaciones de vencimiento y la ejecución.

Campos del objeto API

CampoTipoDescripción
api.idstringid de Plugin
api.namestringNombre para mostrar
api.versionstring?Versión del Plugin (opcional)
api.descriptionstring?Descripción del Plugin (opcional)
api.sourcestringRuta de origen del Plugin
api.rootDirstring?Directorio raíz del Plugin (opcional)
api.configOpenClawConfigInstantánea de configuración actual (instantánea activa de runtime en memoria cuando esté disponible)
api.pluginConfigRecord<string, unknown>Configuración específica del Plugin desde plugins.entries.<id>.config
api.runtimePluginRuntimeAyudantes de runtime
api.loggerPluginLoggerRegistrador con ámbito (debug, info, warn, error)
api.registrationModePluginRegistrationModeModo de carga actual; "setup-runtime" es la ventana ligera de inicio/configuración previa a la entrada completa
api.resolvePath(input)(string) => stringResuelve la ruta relativa a la raíz del Plugin

Convención de módulos internos

Dentro de tu Plugin, usa archivos barrel locales para importaciones internas:
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)
Nunca importes tu propio Plugin mediante openclaw/plugin-sdk/<your-plugin> desde código de producción. Enruta las importaciones internas mediante ./api.ts o ./runtime-api.ts. La ruta del SDK es solo el contrato externo.
Las superficies públicas de Plugins integrados cargadas por fachada (api.ts, runtime-api.ts, index.ts, setup-entry.ts y archivos públicos de entrada similares) prefieren la instantánea activa de configuración de runtime cuando OpenClaw ya está en ejecución. Si todavía no existe una instantánea de runtime, recurren al archivo de configuración resuelto en disco. Las fachadas de Plugins integrados empaquetados deben cargarse mediante los cargadores de fachadas de Plugins de OpenClaw; las importaciones directas desde dist/extensions/... omiten las comprobaciones de manifiesto y sidecar de runtime que las instalaciones empaquetadas usan para el código propiedad del Plugin. Los Plugins de proveedores pueden exponer un barrel de contrato local y reducido del Plugin cuando un ayudante es intencionadamente específico del proveedor y todavía no pertenece a una subruta genérica del SDK. Ejemplos integrados:
  • Anthropic: superficie pública api.ts / contract-api.ts para ayudantes de streaming de encabezado beta de Claude y service_tier.
  • @openclaw/openai-provider: api.ts exporta constructores de proveedor, ayudantes de modelo predeterminado y constructores de proveedor en tiempo real.
  • @openclaw/openrouter-provider: api.ts exporta el constructor de proveedor junto con ayudantes de onboarding/configuración.
El código de producción de extensiones también debe evitar importaciones de openclaw/plugin-sdk/<other-plugin>. Si un ayudante es realmente compartido, promuévelo a una subruta neutral del SDK como openclaw/plugin-sdk/speech, .../provider-model-shared u otra superficie orientada a capacidades en lugar de acoplar dos Plugins entre sí.

Relacionado

Puntos de entrada

Opciones de definePluginEntry y defineChannelPluginEntry.

Ayudantes de runtime

Referencia completa del espacio de nombres api.runtime.

Configuración inicial y configuración

Empaquetado, manifiestos y esquemas de configuración.

Pruebas

Utilidades de prueba y reglas de lint.

Migración del SDK

Migración desde superficies obsoletas.

Internos del Plugin

Arquitectura profunda y modelo de capacidades.