​

Manifeste de plugin (openclaw.plugin.json)

• Bundle Codex : .codex-plugin/plugin.json
• Bundle Claude : .claude-plugin/plugin.json ou la disposition par défaut des composants Claude sans manifeste
• Bundle Cursor : .cursor-plugin/plugin.json

​

Ce que fait ce fichier

• l’identité du plugin
• la validation de la configuration
• les métadonnées d’authentification et d’onboarding qui doivent être disponibles sans démarrer le runtime du plugin
• les métadonnées d’alias et d’activation automatique qui doivent être résolues avant le chargement du runtime du plugin
• les métadonnées abrégées de propriété de famille de modèles qui doivent activer automatiquement le plugin avant le chargement du runtime
• les instantanés statiques de propriété de capacités utilisés pour le câblage de compatibilité groupé et la couverture des contrats
• les métadonnées de configuration spécifiques au canal qui doivent être fusionnées dans le catalogue et les surfaces de validation sans charger le runtime
• les indications d’interface pour la configuration

• enregistrer un comportement d’exécution
• déclarer des points d’entrée de code
• les métadonnées d’installation npm

​

Exemple minimal

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

​

Exemple enrichi

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "Plugin fournisseur OpenRouter",
  "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": "Clé API OpenRouter",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "Clé API OpenRouter",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "Clé API",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}

​

Référence des champs de niveau supérieur

​

Référence providerAuthChoices

​

Référence uiHints

{
  "uiHints": {
    "apiKey": {
      "label": "Clé API",
      "help": "Utilisée pour les requêtes OpenRouter",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}

​

Référence 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"]
  }
}

​

Référence channelConfigs

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

​

Référence modelSupport

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

• les références explicites provider/model utilisent les métadonnées de manifeste providers du propriétaire
• modelPatterns l’emporte sur modelPrefixes
• si un plugin non groupé et un plugin groupé correspondent tous deux, le plugin non groupé l’emporte
• l’ambiguïté restante est ignorée jusqu’à ce que l’utilisateur ou la configuration spécifie un fournisseur

​

Manifeste versus package.json

• si OpenClaw doit la connaître avant de charger le code du plugin, placez-la dans openclaw.plugin.json
• si elle concerne le packaging, les fichiers d’entrée ou le comportement d’installation npm, placez-la dans package.json

​

Champs package.json qui affectent la découverte

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

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

​

Exigences du schéma JSON

• Chaque plugin doit fournir un schéma JSON, même s’il n’accepte aucune configuration.
• Un schéma vide est acceptable (par exemple, { "type": "object", "additionalProperties": false }).
• Les schémas sont validés au moment de la lecture/écriture de la configuration, pas à l’exécution.

​

Comportement de validation

• Les clés channels.* inconnues sont des erreurs, sauf si l’ID de canal est déclaré par un manifeste de plugin.
• plugins.entries.<id>, plugins.allow, plugins.deny et plugins.slots.* doivent référencer des IDs de plugin découvrables. Les IDs inconnus sont des erreurs.
• Si un plugin est installé mais possède un manifeste ou un schéma cassé ou manquant, la validation échoue et Doctor signale l’erreur du plugin.
• Si une configuration de plugin existe mais que le plugin est désactivé, la configuration est conservée et un avertissement est affiché dans Doctor + les logs.

​

Notes

• Le manifeste est obligatoire pour les plugins natifs OpenClaw, y compris les chargements depuis le système de fichiers local.
• Le runtime charge toujours le module du plugin séparément ; le manifeste sert uniquement à la découverte + validation.
• Les manifestes natifs sont analysés avec JSON5, donc les commentaires, les virgules finales et les clés non entre guillemets sont acceptés tant que la valeur finale reste un objet.
• Seuls les champs de manifeste documentés sont lus par le chargeur de manifeste. Évitez d’ajouter ici des clés personnalisées de niveau supérieur.
• providerAuthEnvVars est le chemin de métadonnées léger pour les sondes d’authentification, la validation des marqueurs d’env et les surfaces similaires d’authentification fournisseur qui ne doivent pas démarrer le runtime du plugin juste pour inspecter les noms d’env.
• providerAuthAliases permet à des variantes de fournisseur de réutiliser l’authentification d’un autre fournisseur : variables d’environnement, profils d’authentification, auth basée sur la configuration et choix d’onboarding par clé API, sans coder en dur cette relation dans le core.
• channelEnvVars est le chemin de métadonnées léger pour les replis shell-env, les invites de configuration et les surfaces similaires de canal qui ne doivent pas démarrer le runtime du plugin juste pour inspecter les noms d’env.
• providerAuthChoices est le chemin de métadonnées léger pour les sélecteurs de choix d’authentification, la résolution de --auth-choice, la correspondance du fournisseur préféré et l’enregistrement simple des flags CLI d’onboarding avant le chargement du runtime fournisseur. Pour les métadonnées d’assistant runtime qui nécessitent du code fournisseur, voir Hooks runtime fournisseur.
• Les types exclusifs de plugin sont sélectionnés via plugins.slots.*.
  • kind: "memory" est sélectionné par plugins.slots.memory.
  • kind: "context-engine" est sélectionné par plugins.slots.contextEngine (par défaut : legacy intégré).
• channels, providers, cliBackends et skills peuvent être omis lorsqu’un plugin n’en a pas besoin.
• Si votre plugin dépend de modules natifs, documentez les étapes de build et toute exigence de liste d’autorisation du gestionnaire de paquets (par exemple, pnpm allow-build-scripts
  • pnpm rebuild <package>).

​

Liens associés

• Créer des plugins — prise en main des plugins
• Architecture des plugins — architecture interne
• Vue d’ensemble du SDK — référence du SDK de plugin