​

Manifiesto del plugin (openclaw.plugin.json)

• Paquete Codex: .codex-plugin/plugin.json
• Paquete Claude: .claude-plugin/plugin.json o el diseño predeterminado de componentes de Claude sin manifiesto
• Paquete Cursor: .cursor-plugin/plugin.json

​

Qué hace este archivo

• identidad del plugin
• validación de configuración
• metadatos de autenticación y onboarding que deban estar disponibles sin iniciar el runtime del plugin
• metadatos de alias y autoactivación que deban resolverse antes de cargar el runtime del plugin
• metadatos abreviados de propiedad de familias de modelos que deban activar automáticamente el plugin antes de cargar el runtime
• instantáneas estáticas de propiedad de capacidades usadas para el cableado de compatibilidad empaquetada y la cobertura de contratos
• metadatos de configuración específicos de canal que deban fusionarse en superficies de catálogo y validación sin cargar el runtime
• sugerencias de interfaz de configuración

• registrar comportamiento en runtime
• declarar puntos de entrada de código
• metadatos de instalación npm

​

Ejemplo mínimo

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

​

Ejemplo completo

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

​

Referencia de campos de nivel superior

​

Referencia de providerAuthChoices

​

Referencia de uiHints

{
  "uiHints": {
    "apiKey": {
      "label": "Clave API",
      "help": "Usada para solicitudes a OpenRouter",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}

​

Referencia de contracts

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

​

Referencia de channelConfigs

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

​

Referencia de modelSupport

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

• las referencias explícitas provider/model usan los metadatos de manifiesto providers del propietario
• modelPatterns tiene prioridad sobre modelPrefixes
• si un plugin no empaquetado y uno empaquetado coinciden ambos, gana el plugin no empaquetado
• la ambigüedad restante se ignora hasta que el usuario o la configuración especifiquen un proveedor

​

Manifiesto frente a package.json

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

​

Campos de package.json que afectan a discovery

​

Requisitos de JSON Schema

• Todo plugin debe incluir un JSON Schema, incluso si no acepta configuración.
• Se acepta un esquema vacío (por ejemplo, { "type": "object", "additionalProperties": false }).
• Los esquemas se validan en tiempo de lectura/escritura de configuración, no en runtime.

​

Comportamiento de validación

• Las claves desconocidas channels.* son errores, a menos que el id de canal esté declarado por el manifiesto de un plugin.
• plugins.entries.<id>, plugins.allow, plugins.deny y plugins.slots.* deben hacer referencia a ids de plugins detectables. Los ids desconocidos son errores.
• Si un plugin está instalado pero tiene un manifiesto o esquema roto o ausente, la validación falla y Doctor informa del error del plugin.
• Si la configuración del plugin existe pero el plugin está deshabilitado, la configuración se conserva y aparece una advertencia en Doctor + registros.

​

Notas

• El manifiesto es obligatorio para plugins nativos de OpenClaw, incluidas las cargas desde el sistema de archivos local.
• El runtime sigue cargando el módulo del plugin por separado; el manifiesto es solo para discovery + validación.
• Los manifiestos nativos se analizan con JSON5, por lo que se aceptan comentarios, comas finales y claves sin comillas siempre que el valor final siga siendo un objeto.
• El cargador de manifiestos solo lee los campos de manifiesto documentados. Evita añadir claves de nivel superior personalizadas aquí.
• providerAuthEnvVars es la ruta ligera de metadatos para sondeos de autenticación, validación de marcadores de entorno y superficies similares de autenticación de proveedor que no deberían iniciar el runtime del plugin solo para inspeccionar nombres de variables de entorno.
• providerAuthChoices es la ruta ligera de metadatos para selectores de opciones de autenticación, resolución de --auth-choice, mapeo de proveedor preferido y registro simple de flags de CLI en onboarding antes de cargar el runtime del proveedor. Para metadatos del asistente en runtime que requieren código del proveedor, consulta Hooks de runtime del proveedor.
• Los tipos exclusivos de plugin se seleccionan mediante plugins.slots.*.
  • kind: "memory" se selecciona mediante plugins.slots.memory.
  • kind: "context-engine" se selecciona mediante plugins.slots.contextEngine (predeterminado: legacy integrado).
• channels, providers, cliBackends y skills pueden omitirse cuando un plugin no los necesite.
• Si tu plugin depende de módulos nativos, documenta los pasos de compilación y cualquier requisito de lista de permitidos del gestor de paquetes (por ejemplo, pnpm allow-build-scripts
  • pnpm rebuild <package>).

​

Relacionado

• Crear plugins — introducción a los plugins
• Arquitectura de plugins — arquitectura interna
• Resumen del SDK — referencia del SDK de plugins