​

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 e incorporación que deban estar disponibles sin iniciar el tiempo de ejecución del plugin
• metadatos de alias y activación automática que deban resolverse antes de que se cargue el tiempo de ejecución del plugin
• metadatos abreviados de propiedad de familias de modelos que deban activar automáticamente el plugin antes de que se cargue el tiempo de ejecución
• instantáneas estáticas de propiedad de capacidades usadas para el cableado de compatibilidad integrado y la cobertura de contratos
• metadatos de configuración específicos del canal que deban fusionarse en las superficies de catálogo y validación sin cargar el tiempo de ejecución
• pistas de UI de configuración

• registrar comportamiento en tiempo de ejecución
• declarar entrypoints 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 de proveedor de OpenRouter",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "cliBackends": ["openrouter-cli"],
  "providerAuthEnvVars": {
    "openrouter": ["OPENROUTER_API_KEY"]
  },
  "channelEnvVars": {
    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]
  },
  "providerAuthChoices": [
    {
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
      "choiceLabel": "Clave de API de OpenRouter",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "Clave de API de OpenRouter",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "Clave de 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 de API",
      "help": "Se usa para solicitudes de 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 tienen prioridad sobre modelPrefixes
• si coinciden un plugin no integrado y uno integrado, gana el plugin no integrado
• 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 sobre empaquetado, archivos de entrada o comportamiento de instalación npm, colócalo en package.json

​

Campos de package.json que afectan al descubrimiento

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

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

​

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 el momento de lectura/escritura de la configuración, no en tiempo de ejecución.

​

Comportamiento de validación

• Las claves desconocidas channels.* son errores, salvo que el ID del canal esté declarado por un manifiesto de plugin.
• plugins.entries.<id>, plugins.allow, plugins.deny y plugins.slots.* deben hacer referencia a IDs de plugin 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 existe configuración del plugin pero el plugin está deshabilitado, la configuración se conserva y se muestra una advertencia en Doctor + los registros.

​

Notas

• El manifiesto es obligatorio para los plugins nativos de OpenClaw, incluidas las cargas desde el sistema de archivos local.
• El tiempo de ejecución sigue cargando el módulo del plugin por separado; el manifiesto es solo para descubrimiento + 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 aquí claves personalizadas de nivel superior.
• providerAuthEnvVars es la ruta ligera de metadatos para sondas de autenticación, validación de marcadores de entorno y superficies similares de autenticación de proveedor que no deberían iniciar el tiempo de ejecución del plugin solo para inspeccionar nombres de variables de entorno.
• channelEnvVars es la ruta ligera de metadatos para respaldo de variables de entorno del shell, prompts de configuración y superficies similares de canal que no deberían iniciar el tiempo de ejecución 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, asignación de proveedor preferido y registro simple de flags de CLI de incorporación antes de que se cargue el tiempo de ejecución del proveedor. Para metadatos del asistente en tiempo de ejecución que requieran código del proveedor, consulta Hooks de tiempo de ejecución del proveedor.
• Los tipos exclusivos de plugins 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 permitida del gestor de paquetes (por ejemplo, pnpm allow-build-scripts
  • pnpm rebuild <package>).

​

Relacionado

• Building Plugins — primeros pasos con plugins
• Plugin Architecture — arquitectura interna
• SDK Overview — referencia del SDK de plugins