Configura el archivo openclaw.plugin.json: Guía rápida

Qué hace este archivo

openclaw.plugin.json contiene los metadatos que OpenClaw lee antes de cargar el código de tu plugin.

Úsalo para:

• Identidad del plugin
• Validación de configuración
• Metadatos de autenticación y onboarding que deben estar disponibles sin arrancar el runtime del plugin
• Metadatos de alias y auto-activación que deben resolverse antes de que cargue el runtime
• Metadatos de propiedad de familias de modelos (shorthand) para activar el plugin automáticamente
• Instantáneas estáticas de propiedad de capacidades para el cableado de compatibilidad y cobertura de contratos
• Metadatos de configuración específicos del canal para integrar en el catálogo y superficies de validación
• Sugerencias para la interfaz de usuario (UI hints) de configuración

No lo uses para:

• Registrar comportamientos de runtime o declarar puntos de entrada de código
• Metadatos de npm install

Esos elementos deben ir en el código de tu plugin y en el package.json.

Ejemplo mínimo

{
  "id": "voice-call",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

Ejemplo completo

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider plugin",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "cliBackends": ["openrouter-cli"],
  "providerAuthEnvVars": {
    "openrouter": ["OPENROUTER_API_KEY"]
  },
  "providerAuthAliases": {
    "openrouter-coding": "openrouter"
  },
  "channelEnvVars": {
    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]
  },
  "providerAuthChoices": [
    {
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
      "choiceLabel": "OpenRouter API key",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "OpenRouter API key",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}

Referencia de campos de nivel superior

Campo	Requerido	Tipo	Significado
id	Sí	string	ID canónico del plugin. Es el ID usado en plugins.entries.<id>.
configSchema	Sí	object	JSON Schema inline para la configuración de este plugin.
enabledByDefault	No	true	Marca un plugin empaquetado como habilitado por defecto. Omítelo o usa un valor distinto a true para dejarlo deshabilitado.
legacyPluginIds	No	string[]	IDs antiguos que se normalizan a este ID canónico.
autoEnableWhenConfiguredProviders	No	string[]	IDs de proveedores que activan automáticamente este plugin cuando la configuración o los modelos los mencionan.
kind	No	"memory" | "context-engine"	Declara un tipo de plugin exclusivo usado por plugins.slots.*.
channels	No	string[]	IDs de canales propiedad de este plugin. Se usa para descubrimiento y validación.
providers	No	string[]	IDs de proveedores propiedad de este plugin.
modelSupport	No	object	Metadatos rápidos de familias de modelos para auto-cargar el plugin antes del runtime.
cliBackends	No	string[]	IDs de backends de inferencia CLI propiedad de este plugin.
commandAliases	No	object[]	Nombres de comandos propiedad de este plugin para diagnósticos de CLI y configuración antes de cargar el runtime.
providerAuthEnvVars	No	Record<string, string[]>	Metadatos ligeros de variables de entorno para autenticación de proveedores que OpenClaw inspecciona sin cargar código.
providerAuthAliases	No	Record<string, string>	IDs de proveedores que reutilizan la autenticación de otro proveedor (ej. un proveedor de coding que comparte API key).
channelEnvVars	No	Record<string, string[]>	Metadatos ligeros de variables de entorno para canales. Úsalo para configuración de canales basada en entorno.
providerAuthChoices	No	object[]	Metadatos de opciones de autenticación para selectores de onboarding y resolución de flags de CLI.
contracts	No	object	Instantánea estática de capacidades para voz, transcripción, generación de imágenes, búsqueda web y herramientas.
channelConfigs	No	Record<string, object>	Metadatos de configuración de canales que se fusionan en las superficies de validación antes del runtime.
skills	No	string[]	Directorios de skills a cargar, relativos a la raíz del plugin.
name	No	string	Nombre del plugin legible para humanos.
description	No	string	Resumen corto mostrado en las interfaces del plugin.
version	No	string	Versión informativa del plugin.
uiHints	No	Record<string, object>	Etiquetas de UI, placeholders y avisos de sensibilidad para los campos de configuración.

Referencia de providerAuthChoices

Cada entrada en providerAuthChoices describe una opción de onboarding o de autenticación. OpenClaw lee esta configuración antes de que se cargue el runtime del provider.

Campo	Requerido	Tipo	Qué significa
provider	Sí	string	ID del provider al que pertenece esta opción.
method	Sí	string	ID del método de autenticación al que se debe dirigir.
choiceId	Sí	string	ID estable de la opción de autenticación usado en los flujos de onboarding y CLI.
choiceLabel	No	string	Etiqueta visible para el usuario. Si se omite, OpenClaw usa el choiceId.
choiceHint	No	string	Texto de ayuda corto para el selector.
assistantPriority	No	number	Los valores más bajos aparecen primero en los selectores interactivos del asistente.
assistantVisibility	No	"visible" | "manual-only"	Oculta la opción en los selectores del asistente pero permite la selección manual mediante la CLI.
deprecatedChoiceIds	No	string[]	IDs de opciones antiguas que deben redirigir a los usuarios a esta nueva opción.
groupId	No	string	ID de grupo opcional para agrupar opciones relacionadas.
groupLabel	No	string	Etiqueta visible para el usuario para ese grupo.
groupHint	No	string	Texto de ayuda corto para el grupo.
optionKey	No	string	Key de opción interna para flujos de autenticación simples de un solo flag.
cliFlag	No	string	Nombre del flag de la CLI, como --openrouter-api-key.
cliOption	No	string	Formato completo de la opción de la CLI, como --openrouter-api-key <key>.
cliDescription	No	string	Descripción que se muestra en la ayuda de la CLI.
onboardingScopes	No	Array&lt;"text-inference" | "image-generation"&gt;	En qué interfaces de onboarding debe aparecer esta opción. Si se omite, el valor por defecto es ["text-inference"].

Referencia de commandAliases

Usa commandAliases cuando un plugin sea propietario de un nombre de comando de runtime que los usuarios podrían intentar añadir por error en plugins.allow o ejecutar como un comando raíz de la CLI. OpenClaw utiliza estos metadatos para realizar diagnósticos sin necesidad de importar el código de runtime del plugin.

{
  "commandAliases": [
    {
      "name": "dreaming",
      "kind": "runtime-slash",
      "cliCommand": "memory"
    }
  ]
}

Campo	Requerido	Tipo	Qué significa
name	Sí	string	Nombre del comando que pertenece a este plugin.
kind	No	"runtime-slash"	Marca el alias como un comando slash de chat en lugar de un comando raíz de la CLI.
cliCommand	No	string	Comando raíz de la CLI relacionado para sugerir operaciones de CLI, si existe alguno.

Referencia de uiHints

uiHints es un mapa que vincula los nombres de los campos de configuración con pequeñas pistas para su renderizado en la interfaz.

{
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "help": "Used for OpenRouter requests",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}

Cada pista de campo puede incluir:

Campo	Tipo	Qué significa
label	string	Etiqueta del campo visible para el usuario.
help	string	Texto de ayuda corto.
tags	string[]	Etiquetas de UI opcionales.
advanced	boolean	Marca el campo como una opción avanzada.
sensitive	boolean	Marca el campo como secreto o sensible.
placeholder	string	Texto de marcador de posición para los inputs de formularios.

Referencia de contracts

Usa contracts únicamente para metadatos estáticos de propiedad de capacidades que OpenClaw pueda leer sin importar el runtime del plugin.

{
  "contracts": {
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

Cada lista es opcional:

Campo	Tipo	Qué significa
speechProviders	string[]	IDs de providers de voz que posee este plugin.
realtimeTranscriptionProviders	string[]	IDs de providers de transcripción en tiempo real que posee este plugin.
realtimeVoiceProviders	string[]	IDs de providers de voz en tiempo real que posee este plugin.
mediaUnderstandingProviders	string[]	IDs de providers de comprensión de medios que posee este plugin.
imageGenerationProviders	string[]	IDs de providers de generación de imágenes que posee este plugin.
videoGenerationProviders	string[]	IDs de providers de generación de vídeo que posee este plugin.
webFetchProviders	string[]	IDs de providers de web-fetch que posee este plugin.
webSearchProviders	string[]	IDs de providers de búsqueda web que posee este plugin.
tools	string[]	Nombres de herramientas de agentes que posee este plugin para verificaciones de contrato vinculadas.

Referencia de channelConfigs

Usa channelConfigs cuando un plugin de canal necesite metadatos de configuración ligeros antes de que se cargue el runtime.

{
  "channelConfigs": {
    "matrix": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "homeserverUrl": { "type": "string" }
        }
      },
      "uiHints": {
        "homeserverUrl": {
          "label": "Homeserver URL",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "Matrix homeserver connection",
      "preferOver": ["matrix-legacy"]
    }
  }
}

Cada entrada de canal puede incluir:

Campo	Tipo	Qué significa
schema	object	JSON Schema para channels.<id>. Requerido para cada entrada de configuración de canal declarada.
uiHints	Record<string, object>	Etiquetas de UI, placeholders o pistas de datos sensibles opcionales para esa sección.
label	string	Etiqueta del canal que se integra en el selector cuando los metadatos del runtime no están listos.
description	string	Descripción corta del canal para las interfaces de inspección y catálogo.
preferOver	string[]	IDs de plugins antiguos o de menor prioridad que este canal debe superar en la selección.

Referencia de modelSupport

Usa modelSupport cuando OpenClaw deba inferir tu plugin de proveedor a partir de IDs de modelo abreviados como gpt-5.4 o claude-sonnet-4.6 antes de que se cargue el runtime del plugin.

{
  "modelSupport": {
    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],
    "modelPatterns": ["^computer-use-preview"]
  }
}

OpenClaw aplica este orden de precedencia:

• Las referencias explícitas provider/model usan los metadatos del manifiesto de los providers propietarios.
• modelPatterns tiene prioridad sobre modelPrefixes.
• Si un plugin no integrado y uno integrado coinciden, el plugin no integrado gana.
• Cualquier ambigüedad restante se ignora hasta que tú o la configuración especifiquéis un proveedor.

Campos:

Campo	Tipo	Qué significa
modelPrefixes	string[]	Prefijos que coinciden mediante startsWith con IDs de modelos abreviados.
modelPatterns	string[]	Fuentes de Regex que coinciden con IDs de modelos tras eliminar el sufijo del perfil.

Las claves de capacidad de nivel superior antiguas están obsoletas. Usa openclaw doctor --fix para mover speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders y webSearchProviders bajo contracts. La carga normal del manifiesto ya no trata esos campos de nivel superior como propiedad de capacidad.

Manifest frente a package.json

Estos dos archivos tienen tareas distintas:

Archivo	Úsalo para
openclaw.plugin.json	Discovery, validación de config, metadatos de elección de auth y pistas de UI que deben existir antes de que el código del plugin se ejecute
package.json	Metadatos de npm, instalación de dependencias, el bloque openclaw usado para entrypoints y metadatos del catálogo

Si no tienes claro dónde va un metadato, sigue esta regla:

• Si OpenClaw debe conocerlo antes de cargar el código del plugin, ponlo en openclaw.plugin.json
• Si se trata de empaquetado, archivos de entrada o el comportamiento de instalación de npm, ponlo en package.json

Campos de package.json que afectan al discovery

Algunos metadatos del plugin previos al runtime viven intencionadamente en package.json bajo el bloque openclaw en lugar de en openclaw.plugin.json.

Ejemplos importantes:

Campo	Qué significa
openclaw.extensions	Declara entrypoints nativos del plugin.
openclaw.setupEntry	Entrypoint ligero solo para setup usado durante el onboarding y el inicio diferido de canales.
openclaw.channel	Metadatos ligeros del catálogo de canales como etiquetas, rutas de docs, alias y textos de selección.
openclaw.channel.configuredState	Metadatos ligeros del verificador de estado configurado que pueden responder si ya existe un setup basado solo en env sin cargar todo el runtime del canal.
openclaw.channel.persistedAuthState	Metadatos ligeros del verificador de auth persistida que pueden responder si ya hay alguna sesión iniciada sin cargar todo el runtime del canal.
openclaw.install.npmSpec / openclaw.install.localPath	Pistas de instalación y actualización para plugins empaquetados o publicados externamente.
openclaw.install.defaultChoice	Ruta de instalación preferida cuando hay múltiples fuentes de instalación disponibles.
openclaw.install.minHostVersion	Versión mínima soportada del host de OpenClaw, usando un suelo de semver como >=2026.3.22.
openclaw.install.allowInvalidConfigRecovery	Permite una ruta estrecha de recuperación por reinstalación de plugins empaquetados cuando la config no es válida.
openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen	Permite que las superficies de canal solo para setup se carguen antes que el plugin de canal completo durante el inicio.

openclaw.install.minHostVersion se aplica durante la instalación y la carga del registro del manifest. Los valores no válidos se rechazan; los valores más nuevos pero válidos omiten el plugin en hosts antiguos.

openclaw.install.allowInvalidConfigRecovery es intencionadamente limitado. No hace que cualquier configuración rota sea instalable. Actualmente solo permite que los flujos de instalación se recuperen de fallos específicos de actualización de plugins empaquetados obsoletos, como una ruta de plugin empaquetado que falta o una entrada channels.<id> antigua para ese mismo plugin. Otros errores de configuración seguirán bloqueando la instalación y enviarán a los operadores a ejecutar openclaw doctor --fix.

openclaw.channel.persistedAuthState son metadatos de paquete para un módulo verificador diminuto:

{
  "openclaw": {
    "channel": {
      "id": "whatsapp",
      "persistedAuthState": {
        "specifier": "./auth-presence",
        "exportName": "hasAnyWhatsAppAuth"
      }
    }
  }
}

Úsalo cuando los flujos de setup, doctor o estado configurado necesiten una sonda de auth rápida de tipo sí/no antes de que se cargue el plugin de canal completo. El export de destino debe ser una función pequeña que solo lea el estado persistido; no la pases a través del barrel principal del runtime del canal.

openclaw.channel.configuredState sigue la misma estructura para comprobaciones ligeras de configuración solo por env:

{
  "openclaw": {
    "channel": {
      "id": "telegram",
      "configuredState": {
        "specifier": "./configured-state",
        "exportName": "hasTelegramConfiguredState"
      }
    }
  }
}

Úsalo cuando un canal pueda responder al estado configurado desde env u otros inputs pequeños ajenos al runtime. Si la comprobación necesita una resolución de configuración completa o el runtime real del canal, mantén esa lógica en el hook config.hasConfiguredState del plugin.

Requisitos de JSON Schema

• Cada plugin debe incluir un JSON Schema, incluso si no acepta ninguna configuración.
• Un esquema vacío es aceptable (por ejemplo, { "type": "object", "additionalProperties": false }).
• Los esquemas se validan en el momento de lectura y escritura de la configuración, no en el runtime.

Comportamiento de validación

• Las claves channels.* desconocidas se consideran errores, a menos que el ID del canal esté declarado en el manifest de un plugin.
• plugins.entries.<id>, plugins.allow, plugins.deny y plugins.slots.* deben hacer referencia a IDs de plugins descubribles. Los IDs desconocidos generan errores.
• Si un plugin está instalado pero tiene un manifest o schema roto o ausente, la validación falla y Doctor informa del error del plugin.
• Si existe configuración del plugin pero este está deshabilitado, la configuración se conserva y se muestra un aviso en Doctor y en los logs.

Consulta la Referencia de configuración para ver el schema completo de plugins.*.

Notas

• El manifest es obligatorio para los plugins nativos de OpenClaw, incluyendo las cargas desde el sistema de archivos local.
• El runtime carga el módulo del plugin de forma independiente; el manifest solo se utiliza para el descubrimiento y la validación.
• Los manifests nativos se analizan con JSON5, por lo que se aceptan comentarios, comas finales y claves sin comillas, siempre que el valor final sea un objeto.
• El cargador de manifests solo lee los campos documentados. Evita añadir claves personalizadas de nivel superior aquí.
• providerAuthEnvVars es la ruta rápida de metadatos para sondas de autenticación, validación de marcadores de entorno y superficies similares que no deberían iniciar el runtime del plugin solo para inspeccionar nombres de variables.
• providerAuthAliases permite que las variantes de un provider reutilicen las variables de entorno de autenticación, perfiles, autenticación basada en configuración y opciones de registro de API-key de otro provider sin programar esa relación de forma rígida en el core.
• channelEnvVars es la ruta rápida de metadatos para valores por defecto del entorno de shell, prompts de configuración y superficies de canales similares que no deberían iniciar el runtime del plugin solo para inspeccionar nombres de variables.
• providerAuthChoices es la ruta rápida de metadatos para selectores de opciones de autenticación, resolución de --auth-choice, mapeo de providers preferidos y registro simple de flags de la CLI antes de que se cargue el runtime del provider. Para metadatos del asistente de runtime que requieran código del provider, consulta Hooks de runtime del provider.
• Los tipos de plugins exclusivos se seleccionan a través de plugins.slots.*.
  • kind: "memory" se selecciona mediante plugins.slots.memory.
  • kind: "context-engine" se selecciona mediante plugins.slots.contextEngine (por defecto: el valor integrado legacy).
• Puedes omitir channels, providers, cliBackends y skills cuando un plugin no los necesite.
• Si tu plugin depende de módulos nativos, documenta los pasos de construcción y cualquier requisito de lista de permitidos del gestor de paquetes (por ejemplo, en pnpm usa allow-build-scripts — pnpm rebuild <package>).

Relacionado

• Construir Plugins — primeros pasos con plugins
• Arquitectura de Plugins — arquitectura interna
• Resumen del SDK — referencia del SDK de plugins