​

Aspectos internos de plugins

​

Modelo público de capacidades

​

Postura de compatibilidad externa

• plugins externos existentes: mantén funcionando las integraciones basadas en hooks; trátalo como la base de compatibilidad
• nuevos plugins nativos/incluidos: da preferencia al registro explícito de capacidades sobre accesos específicos de proveedor o nuevos diseños solo con hooks
• plugins externos que adoptan el registro de capacidades: permitido, pero trata las superficies helper específicas de capacidad como cambiantes, a menos que la documentación marque explícitamente un contrato como estable

• las API de registro de capacidades son la dirección prevista
• los hooks heredados siguen siendo la ruta más segura para evitar rupturas en plugins externos durante la transición
• no todas las subrutas helper exportadas son iguales; da preferencia al contrato documentado y estrecho, no a exports helper incidentales

​

Formas de los plugins

• plain-capability — registra exactamente un tipo de capacidad (por ejemplo, un plugin solo de proveedor como mistral)
• hybrid-capability — registra varios tipos de capacidad (por ejemplo openai posee inferencia de texto, voz, comprensión multimedia y generación de imágenes)
• hook-only — registra solo hooks (tipados o personalizados), sin capacidades, herramientas, comandos ni servicios
• non-capability — registra herramientas, comandos, servicios o rutas, pero no capacidades

​

Hooks heredados

• mantenerlo funcionando
• documentarlo como heredado
• preferir before_model_resolve para trabajo de reemplazo de modelo/proveedor
• preferir before_prompt_build para trabajo de mutación del prompt
• eliminarlo solo cuando el uso real caiga y la cobertura de fixtures demuestre la seguridad de la migración

​

Señales de compatibilidad

​

Descripción general de la arquitectura

1. Manifest + descubrimiento OpenClaw encuentra plugins candidatos a partir de rutas configuradas, raíces de espacio de trabajo, raíces globales de extensiones y extensiones incluidas. El descubrimiento lee primero los manifests nativos openclaw.plugin.json más los manifests de bundles compatibles.
2. Habilitación + validación El núcleo decide si un plugin descubierto está habilitado, deshabilitado, bloqueado o seleccionado para una ranura exclusiva como memory.
3. Carga en tiempo de ejecución Los plugins nativos de OpenClaw se cargan en proceso mediante jiti y registran capacidades en un registro central. Los bundles compatibles se normalizan en registros del registro sin importar código de tiempo de ejecución.
4. Consumo de superficie El resto de OpenClaw lee el registro para exponer herramientas, canales, configuración de proveedores, hooks, rutas HTTP, comandos CLI y servicios.

• los metadatos en tiempo de análisis vienen de registerCli(..., { descriptors: [...] })
• el módulo CLI real del plugin puede seguir siendo lazy y registrarse en la primera invocación

• el descubrimiento + la validación de configuración deben funcionar a partir de metadatos de manifest/schema sin ejecutar código del plugin
• el comportamiento nativo de tiempo de ejecución proviene de la ruta register(api) del módulo del plugin

​

Plugins de canal y la herramienta compartida de mensajes

• el núcleo posee el host de la herramienta compartida message, el cableado del prompt, la contabilidad de sesiones/hilos y el despacho de ejecución
• los plugins de canal poseen el descubrimiento de acciones con alcance, el descubrimiento de capacidades y cualquier fragmento de schema específico del canal
• los plugins de canal poseen la gramática de conversación de sesión específica del proveedor, como cómo los ids de conversación codifican ids de hilo o heredan de conversaciones padre
• los plugins de canal ejecutan la acción final a través de su adaptador de acciones

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• requesterSenderId entrante de confianza

• outbound.sendPoll es la base compartida para canales que encajan en el modelo común de poll
• actions.handleAction("poll") es la ruta preferida para semánticas de poll específicas del canal o parámetros extra de poll

​

Modelo de propiedad de capacidades

• un plugin de empresa normalmente debe poseer todas las superficies de OpenClaw de esa empresa
• un plugin de función normalmente debe poseer toda la superficie de la función que introduce
• los canales deben consumir capacidades compartidas del núcleo en lugar de volver a implementar comportamiento de proveedor de forma ad hoc

• el plugin incluido openai posee el comportamiento del proveedor de modelos OpenAI y el comportamiento de voz + realtime-voice + media-understanding + image-generation de OpenAI
• el plugin incluido elevenlabs posee el comportamiento de voz de ElevenLabs
• el plugin incluido microsoft posee el comportamiento de voz de Microsoft
• el plugin incluido google posee el comportamiento del proveedor de modelos Google más el comportamiento de media-understanding + image-generation + web-search de Google
• el plugin incluido firecrawl posee el comportamiento de web-fetch de Firecrawl
• los plugins incluidos minimax, mistral, moonshot y zai poseen sus backends de media-understanding
• el plugin voice-call es un plugin de función: posee transporte de llamadas, herramientas, CLI, rutas y el puente de media-stream de Twilio, pero consume capacidades compartidas de voz más realtime-transcription y realtime-voice en lugar de importar plugins de proveedor directamente

• OpenAI vive en un solo plugin aunque abarque modelos de texto, voz, imágenes y futuro video
• otro proveedor puede hacer lo mismo para su propia superficie
• los canales no se preocupan por qué plugin de proveedor posee el proveedor; consumen el contrato de capacidad compartida expuesto por el núcleo

• plugin = límite de propiedad
• capability = contrato central que varios plugins pueden implementar o consumir

1. definir la capacidad faltante en el núcleo
2. exponerla a través de la API/runtime del plugin de forma tipada
3. conectar canales/funciones contra esa capacidad
4. dejar que los plugins de proveedor registren implementaciones

​

Capas de capacidad

• capa central de capacidad: orquestación compartida, política, respaldo, reglas de fusión de configuración, semántica de entrega y contratos tipados
• capa de plugin de proveedor: APIs específicas del proveedor, autenticación, catálogos de modelos, síntesis de voz, generación de imágenes, futuros backends de video, endpoints de uso
• capa de plugin de canal/función: integración de Slack/Discord/voice-call/etc. que consume capacidades centrales y las presenta en una superficie

• el núcleo posee la política TTS en tiempo de respuesta, el orden de respaldo, preferencias y entrega por canal
• openai, elevenlabs y microsoft poseen las implementaciones de síntesis
• voice-call consume el helper de tiempo de ejecución TTS de telefonía

​

Ejemplo de plugin de empresa con varias capacidades

import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
import {
  describeImageWithModel,
  transcribeOpenAiCompatibleAudio,
} from "openclaw/plugin-sdk/media-understanding";

const plugin: OpenClawPluginDefinition = {
  id: "exampleai",
  name: "ExampleAI",
  register(api) {
    api.registerProvider({
      id: "exampleai",
      // hooks de auth/catálogo de modelos/tiempo de ejecución
    });

    api.registerSpeechProvider({
      id: "exampleai",
      // configuración de voz del proveedor — implementa directamente la interfaz SpeechProviderPlugin
    });

    api.registerMediaUnderstandingProvider({
      id: "exampleai",
      capabilities: ["image", "audio", "video"],
      async describeImage(req) {
        return describeImageWithModel({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
      async transcribeAudio(req) {
        return transcribeOpenAiCompatibleAudio({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
    });

    api.registerWebSearchProvider(
      createPluginBackedWebSearchProvider({
        id: "exampleai-search",
        // lógica de credenciales + fetch
      }),
    );
  },
};

export default plugin;

• un plugin posee la superficie del proveedor
• el núcleo sigue poseyendo los contratos de capacidad
• los canales y plugins de función consumen helpers api.runtime.*, no código del proveedor
• las pruebas de contrato pueden afirmar que el plugin registró las capacidades que dice poseer

​

Ejemplo de capacidad: comprensión de video

1. el núcleo define el contrato de media-understanding
2. los plugins de proveedor registran describeImage, transcribeAudio y describeVideo según corresponda
3. los plugins de canal y de función consumen el comportamiento compartido del núcleo en lugar de conectarse directamente al código del proveedor

​

Contratos y aplicación

• los autores de plugins obtienen un estándar interno estable
• el núcleo puede rechazar propiedad duplicada como dos plugins que registren el mismo id de proveedor
• el inicio puede mostrar diagnósticos accionables para registros mal formados
• las pruebas de contrato pueden hacer cumplir la propiedad de plugins incluidos y evitar derivas silenciosas

1. aplicación del registro en tiempo de ejecución El registro de plugins valida los registros a medida que se cargan los plugins. Ejemplos: ids de proveedor duplicados, ids de proveedor de voz duplicados y registros mal formados producen diagnósticos de plugins en lugar de comportamiento indefinido.
2. pruebas de contrato Los plugins incluidos se capturan en registros de contrato durante las ejecuciones de prueba para que OpenClaw pueda afirmar explícitamente la propiedad. Hoy esto se usa para proveedores de modelos, proveedores de voz, proveedores de búsqueda web y propiedad de registro incluida.

​

Qué pertenece a un contrato

• tipados
• pequeños
• específicos por capacidad
• propiedad del núcleo
• reutilizables por varios plugins
• consumibles por canales/funciones sin conocimiento del proveedor

• política específica del proveedor oculta en el núcleo
• escapes puntuales de plugin que omiten el registro
• código de canal que accede directamente a una implementación de proveedor
• objetos ad hoc de tiempo de ejecución que no forman parte de OpenClawPluginApi ni de api.runtime

​

Modelo de ejecución

• un plugin nativo puede registrar herramientas, manejadores de red, hooks y servicios
• un error en un plugin nativo puede hacer caer o desestabilizar el gateway
• un plugin nativo malicioso equivale a ejecución de código arbitrario dentro del proceso de OpenClaw

• plugins.allow confía en ids de plugin, no en la procedencia de la fuente.
• Un plugin de espacio de trabajo con el mismo id que un plugin incluido oculta intencionalmente la copia incluida cuando ese plugin de espacio de trabajo está habilitado/en allowlist.
• Esto es normal y útil para desarrollo local, pruebas de parches y hotfixes.

​

Límite de exportación

• subrutas helper específicas de plugins incluidos
• subrutas de plomería de tiempo de ejecución no pensadas como API pública
• helpers de conveniencia específicos del proveedor
• helpers de setup/onboarding que son detalles de implementación

​

Pipeline de carga

1. descubrir raíces candidatas de plugins
2. leer manifests nativos o compatibles de bundles y metadatos de paquetes
3. rechazar candidatos inseguros
4. normalizar la configuración de plugins (plugins.enabled, allow, deny, entries, slots, load.paths)
5. decidir la habilitación para cada candidato
6. cargar módulos nativos habilitados mediante jiti
7. llamar a los hooks nativos register(api) (o activate(api) — un alias heredado) y recopilar registros en el registro de plugins
8. exponer el registro a superficies de comandos/runtime

​

Comportamiento manifest-first

• identificar el plugin
• descubrir canales/skills/schema de configuración declarados o capacidades del bundle
• validar plugins.entries.<id>.config
• ampliar etiquetas/placeholders de la UI de control
• mostrar metadatos de instalación/catálogo

​

Qué almacena en caché el cargador

• resultados de descubrimiento
• datos del registro de manifests
• registros de plugins cargados

• Define OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1 o OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1 para desactivar estas cachés.
• Ajusta las ventanas de caché con OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS y OPENCLAW_PLUGIN_MANIFEST_CACHE_MS.

​

Modelo de registro

• registros de plugins (identidad, fuente, origen, estado, diagnósticos)
• herramientas
• hooks heredados y hooks tipados
• canales
• proveedores
• manejadores RPC del gateway
• rutas HTTP
• registradores CLI
• servicios en segundo plano
• comandos propiedad del plugin

• módulo del plugin -> registro en el registro
• tiempo de ejecución del núcleo -> consumo del registro

​

Callbacks de binding de conversación

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // Ahora existe un binding para este plugin + conversación.
        console.log(event.binding?.conversationId);
        return;
      }

      // La solicitud fue denegada; limpia cualquier estado local pendiente.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" o "denied"
• decision: "allow-once", "allow-always" o "deny"
• binding: el binding resuelto para solicitudes aprobadas
• request: el resumen original de la solicitud, sugerencia de desacople, id del remitente y metadatos de conversación

​

Hooks de tiempo de ejecución del proveedor

• metadatos del manifest: providerAuthEnvVars para búsqueda barata de auth por entorno antes de cargar el runtime, más providerAuthChoices para etiquetas baratas de onboarding/auth-choice y metadatos de flags CLI antes de cargar el runtime
• hooks en tiempo de configuración: catalog / heredado discovery más applyConfigDefaults
• hooks de tiempo de ejecución: normalizeModelId, normalizeTransport, normalizeConfig, applyNativeStreamingUsageCompat, resolveConfigApiKey, resolveSyntheticAuth, shouldDeferSyntheticProfileAuth, resolveDynamicModel, prepareDynamicModel, normalizeResolvedModel, contributeResolvedModelCompat, capabilities, normalizeToolSchemas, inspectToolSchemas, resolveReasoningOutputMode, prepareExtraParams, createStreamFn, wrapStreamFn, resolveTransportTurnState, resolveWebSocketSessionPolicy, formatApiKey, refreshOAuth, buildAuthDoctorHint, matchesContextOverflowError, classifyFailoverReason, isCacheTtlEligible, buildMissingAuthMessage, suppressBuiltInModel, augmentModelCatalog, isBinaryThinking, supportsXHighThinking, resolveDefaultThinkingLevel, isModernModelRef, prepareRuntimeAuth, resolveUsageAuth, fetchUsageSnapshot, createEmbeddingProvider, buildReplayPolicy, sanitizeReplayHistory, validateReplayTurns, onModelSelected

​

Orden y uso de hooks

​

Ejemplo de proveedor

api.registerProvider({
  id: "example-proxy",
  label: "Example Proxy",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "Auto" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

Ejemplos integrados

• Anthropic usa resolveDynamicModel, capabilities, buildAuthDoctorHint, resolveUsageAuth, fetchUsageSnapshot, isCacheTtlEligible, resolveDefaultThinkingLevel, applyConfigDefaults, isModernModelRef y wrapStreamFn porque posee compatibilidad futura con Claude 4.6, sugerencias de familia de proveedor, guía de reparación de auth, integración de endpoint de uso, elegibilidad de caché de prompt, valores predeterminados de configuración conscientes de la auth, política predeterminada/adaptativa de thinking para Claude y modelado de stream específico de Anthropic para headers beta, /fast / serviceTier y context1m.
• Los helpers de stream específicos de Claude en Anthropic se mantienen por ahora en el seam público api.ts / contract-api.ts del propio plugin incluido. Esa superficie del paquete exporta wrapAnthropicProviderStream, helpers de beta-header, análisis de service_tier y builders de wrapper de Anthropic de bajo nivel, en lugar de ampliar el SDK genérico en torno a las reglas beta-header de un solo proveedor.
• OpenAI usa resolveDynamicModel, normalizeResolvedModel y capabilities más buildMissingAuthMessage, suppressBuiltInModel, augmentModelCatalog, supportsXHighThinking e isModernModelRef porque posee compatibilidad futura con GPT-5.4, la normalización directa de OpenAI openai-completions -> openai-responses, pistas de auth conscientes de Codex, supresión de Spark, filas sintéticas de OpenAI y política de thinking / modelo live de GPT-5; la familia de stream openai-responses-defaults posee los wrappers nativos compartidos de OpenAI Responses para headers de atribución, /fast/serviceTier, verbosidad de texto, web search nativo de Codex, modelado de payload de compatibilidad de razonamiento y gestión de contexto de Responses.
• OpenRouter usa catalog más resolveDynamicModel y prepareDynamicModel porque el proveedor es pass-through y puede exponer nuevos ids de modelo antes de que se actualice el catálogo estático de OpenClaw; también usa capabilities, wrapStreamFn e isCacheTtlEligible para mantener fuera del núcleo los headers de solicitud específicos del proveedor, los metadatos de enrutamiento, los parches de razonamiento y la política de caché de prompt. Su política de replay viene de la familia passthrough-gemini, mientras que la familia de stream openrouter-thinking posee la inyección de razonamiento proxy y los saltos para modelos no compatibles / auto.
• GitHub Copilot usa catalog, auth, resolveDynamicModel y capabilities más prepareRuntimeAuth y fetchUsageSnapshot porque necesita login por dispositivo propiedad del proveedor, comportamiento de respaldo de modelos, particularidades de transcripción de Claude, un intercambio de token de GitHub -> token de Copilot y un endpoint de uso propiedad del proveedor.
• OpenAI Codex usa catalog, resolveDynamicModel, normalizeResolvedModel, refreshOAuth y augmentModelCatalog más prepareExtraParams, resolveUsageAuth y fetchUsageSnapshot porque sigue ejecutándose sobre transportes centrales de OpenAI pero posee su normalización de transporte/base URL, política de respaldo de refresh OAuth, elección de transporte predeterminada, filas sintéticas del catálogo Codex e integración del endpoint de uso de ChatGPT; comparte la misma familia de stream openai-responses-defaults que OpenAI directo.
• Google AI Studio y Gemini CLI OAuth usan resolveDynamicModel, buildReplayPolicy, sanitizeReplayHistory, resolveReasoningOutputMode, wrapStreamFn e isModernModelRef porque la familia de replay google-gemini posee el respaldo de compatibilidad futura de Gemini 3.1, la validación nativa de replay de Gemini, el saneamiento de replay de bootstrap, el modo etiquetado de salida de razonamiento y el emparejamiento moderno de modelos, mientras que la familia de stream google-thinking posee la normalización del payload de thinking de Gemini; Gemini CLI OAuth también usa formatApiKey, resolveUsageAuth y fetchUsageSnapshot para formateo de tokens, análisis de tokens y conexión al endpoint de cuota.
• Anthropic Vertex usa buildReplayPolicy a través de la familia de replay anthropic-by-model para que la limpieza de replay específica de Claude quede limitada a ids de Claude en lugar de aplicarse a cada transporte anthropic-messages.
• Amazon Bedrock usa buildReplayPolicy, matchesContextOverflowError, classifyFailoverReason y resolveDefaultThinkingLevel porque posee la clasificación específica de Bedrock de errores de throttle/not-ready/context-overflow para tráfico Anthropic-on-Bedrock; su política de replay sigue compartiendo la misma barrera solo-Claude anthropic-by-model.
• OpenRouter, Kilocode, Opencode y Opencode Go usan buildReplayPolicy a través de la familia de replay passthrough-gemini porque hacen proxy de modelos Gemini mediante transportes compatibles con OpenAI y necesitan saneamiento de firmas de thought de Gemini sin validación nativa de replay de Gemini ni reescrituras de bootstrap.
• MiniMax usa buildReplayPolicy a través de la familia de replay hybrid-anthropic-openai porque un proveedor posee tanto semántica de mensajes Anthropic como OpenAI-compatible; mantiene la eliminación de bloques de thinking solo de Claude en el lado Anthropic y, al mismo tiempo, vuelve a sobrescribir el modo de salida de razonamiento a nativo, y la familia de stream minimax-fast-mode posee las reescrituras de modelo en modo rápido en la ruta de stream compartida.
• Moonshot usa catalog más wrapStreamFn porque sigue usando el transporte compartido de OpenAI pero necesita normalización del payload de thinking propiedad del proveedor; la familia de stream moonshot-thinking mapea la configuración más el estado /think a su payload nativo binario de thinking.
• Kilocode usa catalog, capabilities, wrapStreamFn e isCacheTtlEligible porque necesita headers de solicitud propiedad del proveedor, normalización del payload de razonamiento, sugerencias de transcripción de Gemini y control de TTL de caché de Anthropic; la familia de stream kilocode-thinking mantiene la inyección de thinking de Kilo en la ruta de stream proxy compartida mientras omite kilo/auto y otros ids de modelo proxy que no admiten payloads explícitos de razonamiento.
• Z.AI usa resolveDynamicModel, prepareExtraParams, wrapStreamFn, isCacheTtlEligible, isBinaryThinking, isModernModelRef, resolveUsageAuth y fetchUsageSnapshot porque posee respaldo GLM-5, valores predeterminados tool_stream, UX de thinking binario, emparejamiento moderno de modelos y tanto auth de uso como obtención de cuota; la familia de stream tool-stream-default-on mantiene el wrapper predeterminado de tool_stream fuera del pegamento manuscrito por proveedor.
• xAI usa normalizeResolvedModel, normalizeTransport, contributeResolvedModelCompat, prepareExtraParams, wrapStreamFn, resolveSyntheticAuth, resolveDynamicModel e isModernModelRef porque posee normalización nativa del transporte xAI Responses, reescrituras de alias de Grok fast-mode, tool_stream predeterminado, limpieza estricta de herramientas / payload de razonamiento, reutilización de auth de respaldo para herramientas propiedad del plugin, resolución de modelo Grok con compatibilidad futura y parches de compatibilidad propiedad del proveedor como el perfil de schema de herramientas de xAI, palabras clave de schema no compatibles, web_search nativo y decodificación de argumentos de llamadas a herramientas con entidades HTML.
• Mistral, OpenCode Zen y OpenCode Go usan solo capabilities para mantener las particularidades de transcripción/herramientas fuera del núcleo.
• Proveedores incluidos solo de catálogo como byteplus, cloudflare-ai-gateway, huggingface, kimi-coding, nvidia, qianfan, synthetic, together, venice, vercel-ai-gateway y volcengine usan solo catalog.
• Qwen usa catalog para su proveedor de texto más registros compartidos de media-understanding y video-generation para sus superficies multimodales.
• MiniMax y Xiaomi usan catalog más hooks de uso porque su comportamiento /usage es propiedad del plugin aunque la inferencia siga ejecutándose a través de los transportes compartidos.

​

Helpers de tiempo de ejecución

const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

• textToSpeech devuelve la carga útil normal de salida TTS del núcleo para superficies de archivo/nota de voz.
• Usa la configuración central messages.tts y la selección de proveedor.
• Devuelve buffer de audio PCM + frecuencia de muestreo. Los plugins deben remuestrear/codificar para los proveedores.
• listVoices es opcional por proveedor. Úsalo para selectores de voz o flujos de setup propiedad del proveedor.
• Los listados de voces pueden incluir metadatos más ricos como configuración regional, género y etiquetas de personalidad para selectores conscientes del proveedor.
• OpenAI y ElevenLabs admiten telefonía hoy. Microsoft no.

api.registerSpeechProvider({
  id: "acme-speech",
  label: "Acme Speech",
  isConfigured: ({ config }) => Boolean(config.messages?.tts),
  synthesize: async (req) => {
    return {
      audioBuffer: Buffer.from([]),
      outputFormat: "mp3",
      fileExtension: ".mp3",
      voiceCompatible: false,
    };
  },
});

• Mantén la política TTS, el respaldo y la entrega de respuestas en el núcleo.
• Usa proveedores de voz para comportamiento de síntesis propiedad del proveedor.
• La entrada heredada edge de Microsoft se normaliza al id de proveedor microsoft.
• El modelo de propiedad preferido está orientado a empresa: un plugin de proveedor puede poseer texto, voz, imagen y futuros proveedores multimedia a medida que OpenClaw agregue esos contratos de capacidad.

api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});

• Mantén la orquestación, el respaldo, la configuración y el cableado del canal en el núcleo.
• Mantén el comportamiento del proveedor en el plugin del proveedor.
• La expansión aditiva debe seguir siendo tipada: nuevos métodos opcionales, nuevos campos opcionales de resultado, nuevas capacidades opcionales.
• La generación de video ya sigue el mismo patrón:
  • el núcleo posee el contrato de capacidad y el helper de tiempo de ejecución
  • los plugins de proveedor registran api.registerVideoGenerationProvider(...)
  • los plugins de función/canal consumen api.runtime.videoGeneration.*

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Opcional cuando el MIME no puede inferirse de forma fiable:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* es la superficie compartida preferida para comprensión de imagen/audio/video.
• Usa la configuración central de audio de media-understanding (tools.media.audio) y el orden de respaldo del proveedor.
• Devuelve { text: undefined } cuando no se produce salida de transcripción (por ejemplo, entrada omitida/no compatible).
• api.runtime.stt.transcribeAudioFile(...) permanece como alias de compatibilidad.

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider y model son reemplazos opcionales por ejecución, no cambios persistentes de sesión.
• OpenClaw solo respeta esos campos de reemplazo para llamadores de confianza.
• Para ejecuciones de respaldo propiedad del plugin, los operadores deben optar explícitamente con plugins.entries.<id>.subagent.allowModelOverride: true.
• Usa plugins.entries.<id>.subagent.allowedModels para restringir plugins de confianza a objetivos canónicos concretos provider/model, o "*" para permitir explícitamente cualquier objetivo.
• Las ejecuciones de subagente de plugins no confiables siguen funcionando, pero las solicitudes de reemplazo se rechazan en lugar de recurrir silenciosamente a un valor predeterminado.

const providers = api.runtime.webSearch.listProviders({
  config: api.config,
});

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw plugin runtime helpers",
    count: 5,
  },
});

• Mantén la selección de proveedor, la resolución de credenciales y la semántica compartida de la solicitud en el núcleo.
• Usa proveedores de búsqueda web para transportes de búsqueda específicos del proveedor.
• api.runtime.webSearch.* es la superficie compartida preferida para plugins de función/canal que necesiten comportamiento de búsqueda sin depender del wrapper de herramienta del agente.

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "A friendly lobster mascot", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...): genera una imagen usando la cadena configurada de proveedores de generación de imágenes.
• listProviders(...): lista proveedores disponibles de generación de imágenes y sus capacidades.

​

Rutas HTTP del Gateway

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

• path: ruta bajo el servidor HTTP del gateway.
• auth: obligatorio. Usa "gateway" para requerir la auth normal del gateway, o "plugin" para auth gestionada por el plugin / verificación de webhook.
• match: opcional. "exact" (predeterminado) o "prefix".
• replaceExisting: opcional. Permite al mismo plugin reemplazar su propio registro de ruta existente.
• handler: devuelve true cuando la ruta ha manejado la solicitud.

• api.registerHttpHandler(...) fue eliminado y provocará un error de carga del plugin. Usa api.registerHttpRoute(...) en su lugar.
• Las rutas de plugins deben declarar auth explícitamente.
• Los conflictos exactos path + match se rechazan salvo que replaceExisting: true, y un plugin no puede reemplazar la ruta de otro plugin.
• Las rutas solapadas con distintos niveles de auth se rechazan. Mantén las cadenas de caída exact/prefix solo en el mismo nivel de auth.
• Las rutas auth: "plugin" no reciben automáticamente alcances de tiempo de ejecución de operador. Son para webhooks/verificación de firma gestionados por el plugin, no para llamadas helper privilegiadas del Gateway.
• Las rutas auth: "gateway" se ejecutan dentro de un alcance de tiempo de ejecución de solicitud del Gateway, pero ese alcance es intencionalmente conservador:
  • la auth bearer de secreto compartido (gateway.auth.mode = "token" / "password") mantiene los alcances de runtime de rutas de plugin fijados a operator.write, incluso si quien llama envía x-openclaw-scopes
  • los modos HTTP de confianza con identidad (por ejemplo trusted-proxy o gateway.auth.mode = "none" en un ingreso privado) respetan x-openclaw-scopes solo cuando el encabezado está explícitamente presente
  • si x-openclaw-scopes está ausente en esas solicitudes de rutas de plugin con identidad, el alcance de runtime recurre a operator.write
• Regla práctica: no asumas que una ruta de plugin con auth de gateway es una superficie implícita de administración. Si tu ruta necesita comportamiento exclusivo de admin, exige un modo de auth con identidad y documenta el contrato explícito del encabezado x-openclaw-scopes.

​

Rutas de import del Plugin SDK

• openclaw/plugin-sdk/plugin-entry para primitivas de registro de plugins.
• openclaw/plugin-sdk/core para el contrato genérico compartido orientado a plugins.
• openclaw/plugin-sdk/config-schema para el export del schema Zod raíz de openclaw.json (OpenClawSchema).
• Primitivas estables de canal como openclaw/plugin-sdk/channel-setup, openclaw/plugin-sdk/setup-runtime, openclaw/plugin-sdk/setup-adapter-runtime, openclaw/plugin-sdk/setup-tools, openclaw/plugin-sdk/channel-pairing, openclaw/plugin-sdk/channel-contract, openclaw/plugin-sdk/channel-feedback, openclaw/plugin-sdk/channel-inbound, openclaw/plugin-sdk/channel-lifecycle, openclaw/plugin-sdk/channel-reply-pipeline, openclaw/plugin-sdk/command-auth, openclaw/plugin-sdk/secret-input y openclaw/plugin-sdk/webhook-ingress para cableado compartido de setup/auth/reply/webhook. channel-inbound es el hogar compartido para debounce, coincidencia de menciones, formato de sobres y helpers de contexto de sobre entrante. channel-setup es el seam estrecho de setup para instalación opcional. setup-runtime es la superficie de setup segura para runtime usada por setupEntry / inicio diferido, incluidos los adaptadores de parche de setup seguros para import. setup-adapter-runtime es el seam del adaptador de setup de cuenta consciente del entorno. setup-tools es el seam pequeño de helpers CLI/archivo/docs (formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR).
• Subrutas de dominio como openclaw/plugin-sdk/channel-config-helpers, openclaw/plugin-sdk/allow-from, openclaw/plugin-sdk/channel-config-schema, openclaw/plugin-sdk/telegram-command-config, openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/approval-runtime, openclaw/plugin-sdk/config-runtime, openclaw/plugin-sdk/infra-runtime, openclaw/plugin-sdk/agent-runtime, openclaw/plugin-sdk/lazy-runtime, openclaw/plugin-sdk/reply-history, openclaw/plugin-sdk/routing, openclaw/plugin-sdk/status-helpers, openclaw/plugin-sdk/text-runtime, openclaw/plugin-sdk/runtime-store y openclaw/plugin-sdk/directory-runtime para helpers compartidos de runtime/configuración. telegram-command-config es el seam público estrecho para normalización/validación de comandos personalizados de Telegram y sigue disponible incluso si la superficie de contrato incluida de Telegram no está disponible temporalmente. text-runtime es el seam compartido de texto/markdown/registro, incluida la eliminación de texto visible para el asistente, helpers de renderizado/fragmentación de markdown, helpers de redacción, helpers de etiquetas de directivas y utilidades de texto seguro.
• Los seams de canal específicos de aprobación deben preferir un único contrato approvalCapability en el plugin. Luego, el núcleo lee auth, entrega, renderizado y comportamiento de enrutamiento nativo de aprobaciones a través de esa única capacidad en lugar de mezclar el comportamiento de aprobaciones en campos no relacionados del plugin.
• openclaw/plugin-sdk/channel-runtime está obsoleto y permanece solo como shim de compatibilidad para plugins más antiguos. El código nuevo debe importar las primitivas genéricas más estrechas, y el código del repositorio no debe agregar nuevos imports del shim.
• Los internos de extensiones incluidas siguen siendo privados. Los plugins externos deben usar solo subrutas openclaw/plugin-sdk/*. El código/pruebas del núcleo de OpenClaw puede usar los puntos de entrada públicos del repositorio bajo la raíz de un paquete de plugin como index.js, api.js, runtime-api.js, setup-entry.js y archivos de alcance estrecho como login-qr-api.js. Nunca importes src/* de un paquete de plugin desde el núcleo ni desde otra extensión.
• División del punto de entrada del repositorio: <plugin-package-root>/api.js es el barrel de helpers/tipos, <plugin-package-root>/runtime-api.js es el barrel solo de tiempo de ejecución, <plugin-package-root>/index.js es la entrada del plugin incluido y <plugin-package-root>/setup-entry.js es la entrada del plugin de setup.
• Ejemplos actuales de proveedores incluidos:
  • Anthropic usa api.js / contract-api.js para helpers de stream de Claude como wrapAnthropicProviderStream, helpers de beta-header y parsing de service_tier.
  • OpenAI usa api.js para builders de proveedor, helpers de modelos predeterminados y builders de proveedores realtime.
  • OpenRouter usa api.js para su builder de proveedor más helpers de onboarding/configuración, mientras que register.runtime.js puede seguir reexportando helpers genéricos plugin-sdk/provider-stream para uso local del repositorio.
• Los puntos de entrada públicos cargados mediante facade prefieren la instantánea activa de configuración de runtime cuando existe una, y luego recurren al archivo de configuración resuelto en disco cuando OpenClaw aún no está sirviendo una instantánea de runtime.
• Las primitivas genéricas compartidas siguen siendo el contrato público preferido del SDK. Aún existe un pequeño conjunto reservado de compatibilidad de seams helper con marca de canal incluida. Trátalos como seams de mantenimiento/compatibilidad incluidos, no como nuevos objetivos de import de terceros; los nuevos contratos entre canales deben seguir llegando a subrutas genéricas plugin-sdk/* o a los barrels locales api.js / runtime-api.js del plugin.

• Evita el barrel raíz openclaw/plugin-sdk en código nuevo.
• Da preferencia primero a las primitivas estables y estrechas. Las nuevas subrutas de setup/pairing/reply/feedback/contract/inbound/threading/command/secret-input/webhook/infra/ allowlist/status/message-tool son el contrato previsto para nuevo trabajo de plugins incluidos y externos. El análisis/emparejamiento de targets pertenece a openclaw/plugin-sdk/channel-targets. Las barreras de acciones de mensaje y los helpers de id de mensaje de reacciones pertenecen a openclaw/plugin-sdk/channel-actions.
• Los barrels helper específicos de extensiones incluidas no son estables por defecto. Si un helper solo lo necesita una extensión incluida, mantenlo detrás del seam local api.js o runtime-api.js de la extensión en lugar de promoverlo a openclaw/plugin-sdk/<extension>.
• Los nuevos seams helper compartidos deben ser genéricos, no de marca de canal. El análisis compartido de target pertenece a openclaw/plugin-sdk/channel-targets; los internos específicos del canal siguen detrás del seam local api.js o runtime-api.js del plugin propietario.
• Existen subrutas específicas por capacidad como image-generation, media-understanding y speech porque los plugins nativos/incluidos las usan hoy. Su presencia no significa por sí sola que cada helper exportado sea un contrato externo congelado a largo plazo.

​

Schemas de herramientas de mensajes

• createMessageToolButtonsSchema() para cargas tipo cuadrícula de botones
• createMessageToolCardSchema() para cargas de tarjetas estructuradas

​

Resolución de target de canal

• messaging.inferTargetChatType({ to }) decide si un target normalizado debe tratarse como direct, group o channel antes de la búsqueda en el directorio.
• messaging.targetResolver.looksLikeId(raw, normalized) indica al núcleo si una entrada debe pasar directamente a una resolución tipo id en lugar de una búsqueda en directorio.
• messaging.targetResolver.resolveTarget(...) es el respaldo del plugin cuando el núcleo necesita una resolución final propiedad del proveedor después de la normalización o después de un fallo en el directorio.
• messaging.resolveOutboundSessionRoute(...) posee la construcción específica del proveedor de la ruta de sesión saliente una vez resuelto un target.

• Usa inferTargetChatType para decisiones de categoría que deban ocurrir antes de buscar peers/groups.
• Usa looksLikeId para comprobaciones del tipo “tratar esto como un id de target explícito/nativo”.
• Usa resolveTarget como respaldo específico del proveedor para normalización, no para búsqueda amplia en directorio.
• Mantén ids nativos del proveedor como chat ids, thread ids, JIDs, handles e room ids dentro de valores target o parámetros específicos del proveedor, no en campos genéricos del SDK.

​

Directorios respaldados por configuración

• peers DM controlados por allowlist
• mapas configurados de canal/grupo
• respaldos estáticos de directorio con alcance por cuenta

• filtrado de consulta
• aplicación de límites
• helpers de deduplicación/normalización
• construcción de ChannelDirectoryEntry[]

​

Catálogos de proveedores

• { provider } para una entrada de proveedor
• { providers } para varias entradas de proveedor

• simple: proveedores simples controlados por API key o entorno
• profile: proveedores que aparecen cuando existen perfiles de auth
• paired: proveedores que sintetizan varias entradas de proveedor relacionadas
• late: último paso, después de otros proveedores implícitos

• discovery sigue funcionando como alias heredado
• si se registran ambos catalog y discovery, OpenClaw usa catalog

​

Inspección de canal de solo lectura

• resolveAccount(...) es la ruta de runtime. Puede asumir que las credenciales están completamente materializadas y puede fallar rápidamente cuando faltan secretos requeridos.
• Las rutas de comandos de solo lectura como openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve y los flujos de doctor/config repair no deberían necesitar materializar credenciales de runtime solo para describir la configuración.

• Devuelve solo estado descriptivo de la cuenta.
• Conserva enabled y configured.
• Incluye campos de origen/estado de credenciales cuando sea relevante, como:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• No necesitas devolver valores brutos de tokens solo para informar disponibilidad de solo lectura. Devolver tokenStatus: "available" (y el campo de origen correspondiente) es suficiente para comandos tipo status.
• Usa configured_unavailable cuando una credencial esté configurada mediante SecretRef pero no disponible en la ruta de comandos actual.

​

Package packs

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

• el propio registro del canal
• cualquier ruta HTTP que deba estar disponible antes de que el gateway empiece a escuchar
• cualquier método del gateway, herramienta o servicio que deba existir durante esa misma ventana

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

{
  "name": "@scope/my-channel",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

​

Metadatos de catálogo de canales

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: etiqueta secundaria para superficies más ricas de catálogo/status
• docsLabel: sobrescribe el texto del enlace de documentación
• preferOver: ids de plugin/canal de menor prioridad a los que esta entrada del catálogo debe adelantar
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: controles de copia para superficies de selección
• markdownCapable: marca el canal como compatible con markdown para decisiones de formato saliente
• showConfigured: oculta el canal en superficies de listado de canales configurados cuando se define en false
• quickstartAllowFrom: hace que el canal opte por el flujo estándar quickstart de allowFrom
• forceAccountBinding: requiere binding explícito de cuenta incluso cuando solo existe una cuenta
• preferSessionLookupForAnnounceTarget: prefiere la búsqueda de sesión al resolver objetivos de announce

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

Plugins de motor de contexto

export default function (api) {
  api.registerContextEngine("lossless-claw", () => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages }) {
      return { messages, estimatedTokens: 0 };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

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

export default function (api) {
  api.registerContextEngine("my-memory-engine", () => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages }) {
      return { messages, estimatedTokens: 0 };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

Agregar una nueva capacidad

1. define el contrato central Decide qué comportamiento compartido debe poseer el núcleo: política, respaldo, fusión de configuración, ciclo de vida, semántica orientada a canales y forma del helper de tiempo de ejecución.
2. agrega superficies tipadas de registro/runtime para plugins Amplía OpenClawPluginApi y/o api.runtime con la superficie tipada de capacidad más pequeña que sea útil.
3. conecta consumidores del núcleo + canales/funciones Los canales y plugins de función deben consumir la nueva capacidad a través del núcleo, no importando directamente una implementación del proveedor.
4. registra implementaciones de proveedores Luego los plugins de proveedor registran sus backends contra la capacidad.
5. agrega cobertura de contrato Agrega pruebas para que la propiedad y la forma del registro sigan siendo explícitas con el tiempo.

​

Lista de verificación de capacidades

• tipos del contrato central en src/<capability>/types.ts
• ejecutor/helper de runtime central en src/<capability>/runtime.ts
• superficie de registro de la API de plugins en src/plugins/types.ts
• cableado del registro de plugins en src/plugins/registry.ts
• exposición de runtime de plugins en src/plugins/runtime/* cuando los plugins de función/canal necesiten consumirla
• helpers de captura/prueba en src/test-utils/plugin-registration.ts
• afirmaciones de propiedad/contrato en src/plugins/contracts/registry.ts
• documentación para operadores/plugins en docs/

​

Plantilla de capacidad

// contrato central
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// API de plugin
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// helper de runtime compartido para plugins de función/canal
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• el núcleo posee el contrato de capacidad + la orquestación
• los plugins de proveedor poseen las implementaciones del proveedor
• los plugins de función/canal consumen helpers de runtime
• las pruebas de contrato mantienen explícita la propiedad