--- read_when: - Utiliser la CLI ClawHub - Déboguer l’installation, la mise à jour ou la publication summary: 'Référence CLI : commandes, indicateurs, configuration et comportement du fichier de verrouillage.' x-i18n: generated_at: "2026-07-03T15:23:55Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 23065775d74e7b52ed250051b8724b780c28dfdfc0adf9b8f115f7133fbdd77b source_path: clawhub/cli.md workflow: 16 --- # CLI Package CLI : `clawhub`, binaire : `clawhub`. Installez-le globalement avec npm ou pnpm : ```bash npm i -g clawhub # or pnpm add -g clawhub ``` Puis vérifiez-le : ```bash clawhub --help clawhub login clawhub whoami ``` ## Indicateurs globaux - `--workdir ` : répertoire de travail (par défaut : cwd ; bascule vers l’espace de travail Clawdbot s’il est configuré) - `--dir ` : répertoire d’installation sous le répertoire de travail (par défaut : `skills`) - `--site ` : URL de base pour la connexion dans le navigateur (par défaut : `https://clawhub.ai`) - `--registry ` : URL de base de l’API (par défaut : découverte, sinon `https://clawhub.ai`) - `--no-input` : désactiver les invites Équivalents d’environnement : - `CLAWHUB_SITE` (ancien `CLAWDHUB_SITE`) - `CLAWHUB_REGISTRY` (ancien `CLAWDHUB_REGISTRY`) - `CLAWHUB_WORKDIR` (ancien `CLAWDHUB_WORKDIR`) ### Proxy HTTP La CLI respecte les variables d’environnement standard de proxy HTTP pour les systèmes derrière des proxys d’entreprise ou des réseaux restreints : - `HTTPS_PROXY` / `https_proxy` - `HTTP_PROXY` / `http_proxy` - `NO_PROXY` / `no_proxy` Quand l’une de ces variables est définie, la CLI achemine les requêtes sortantes via le proxy spécifié. `HTTPS_PROXY` est utilisé pour les requêtes HTTPS, `HTTP_PROXY` pour le HTTP simple. `NO_PROXY` / `no_proxy` est respecté pour contourner le proxy pour des hôtes ou domaines spécifiques. C’est requis sur les systèmes où les connexions sortantes directes sont bloquées (par exemple les conteneurs Docker, les VPS Hetzner avec Internet uniquement via proxy, les pare-feu d’entreprise). Exemple : ```bash export HTTPS_PROXY=http://proxy.example.com:3128 export NO_PROXY=localhost,127.0.0.1 clawhub search "my query" ``` Quand aucune variable de proxy n’est définie, le comportement est inchangé (connexions directes). ## Fichier de configuration Stocke votre jeton d’API + l’URL du registre mise en cache. - macOS : `~/Library/Application Support/clawhub/config.json` - Linux/XDG : `$XDG_CONFIG_HOME/clawhub/config.json` ou `~/.config/clawhub/config.json` - Windows : `%APPDATA%\\clawhub\\config.json` - Bascule ancienne : si `clawhub/config.json` n’existe pas encore mais que `clawdhub/config.json` existe, la CLI réutilise l’ancien chemin - remplacement : `CLAWHUB_CONFIG_PATH` (ancien `CLAWDHUB_CONFIG_PATH`) ## Commandes ### `login` / `auth login` - Par défaut : ouvre le navigateur vers `/cli/auth` et termine via le rappel local loopback. - Sans interface : `clawhub login --token clh_...` - Interactif distant/sans interface : `clawhub login --device` affiche un code et attend pendant que vous l’autorisez sur `/cli/device`. ### `whoami` - Vérifie le jeton stocké via `/api/v1/whoami`. ### `token` - Affiche le jeton d’API stocké sur stdout. - Utile pour transmettre un jeton de connexion local à des commandes de configuration de secrets CI. ### `star ` / `unstar ` - Ajoute/retire une Skill de vos éléments mis en avant. - Appelle `POST /api/v1/stars/` et `DELETE /api/v1/stars/`. - `--yes` ignore la confirmation. ### `search ` - Appelle `/api/v1/search?q=...`. - La sortie inclut le slug de la Skill, l’identifiant du propriétaire, le nom d’affichage et le score de pertinence. - La recherche favorise les correspondances exactes de jetons slug/nom avant la popularité des téléchargements. Un jeton slug autonome comme `map` correspond plus fortement à `personal-map` qu’à la sous-chaîne dans `amap`. - La popularité est un faible a priori de classement, pas une garantie de première position. - Si une Skill devrait apparaître mais n’apparaît pas, exécutez `clawhub inspect @owner/slug` en étant connecté pour vérifier les diagnostics de modération visibles par le propriétaire avant de renommer les métadonnées. ### `explore` - Liste les Skills les plus récentes via `/api/v1/skills?limit=...&sort=createdAt` (triées par `createdAt` décroissant). - Indicateurs : - `--limit ` (1-200, par défaut : 25) - `--sort newest|updated|rating|downloads|trending` (par défaut : newest). Les anciens alias de tri d’installation fonctionnent encore pour compatibilité. - `--json` (sortie lisible par machine) - Sortie : ` v ` (résumé tronqué à 50 caractères). ### `inspect @owner/slug` - Récupère les métadonnées de Skill et les fichiers de version sans installer. - `--version ` : inspecter une version spécifique (par défaut : latest). - `--tag ` : inspecter une version étiquetée (par exemple `latest`). - `--versions` : lister l’historique des versions (première page). - `--limit ` : nombre maximal de versions à lister (1-200). - `--files` : lister les fichiers pour la version sélectionnée. - `--file ` : récupérer le contenu brut du fichier (fichiers texte uniquement ; limite de 200 Ko). - `--json` : sortie lisible par machine. ### `install @owner/slug` - Résout la dernière version pour le propriétaire et la Skill nommés. - Télécharge le zip via `/api/v1/download`. - Extrait dans `//`. - Refuse d’écraser les Skills épinglées ; exécutez d’abord `clawhub unpin `. - Écrit : - `/.clawhub/lock.json` (ancien `.clawdhub`) - `/.clawhub/origin.json` (ancien `.clawdhub`) ### `uninstall ` - Supprime `//` et supprime l’entrée du fichier de verrouillage. - Envoie une télémétrie au mieux pendant que vous êtes connecté afin que les décomptes d’installation actuels puissent être désactivés. - Interactif : demande une confirmation. - Non interactif (`--no-input`) : nécessite `--yes`. ### `list` - Lit `/.clawhub/lock.json` (ancien `.clawdhub`). - Affiche `pinned` à côté des Skills gelées avec `clawhub pin`, y compris la raison facultative. ### `pin ` - Marque une Skill installée comme épinglée dans le fichier de verrouillage. - `--reason ` enregistre pourquoi la Skill est gelée. - Les Skills épinglées sont ignorées par `update --all` et rejetées par `update ` direct. - Les Skills épinglées rejettent aussi `install --force` afin que les octets locaux ne puissent pas être remplacés accidentellement. ### `unpin ` - Supprime l’épinglage du fichier de verrouillage d’une Skill installée afin que les futures mises à jour puissent la modifier. ### `update [@owner/slug]` / `update --all` - Calcule l’empreinte à partir des fichiers locaux. - Si l’empreinte correspond à une version connue : aucune invite. - Si l’empreinte ne correspond pas : - refuse par défaut - écrase avec `--force` (ou invite, si interactif) - Les Skills épinglées ne sont jamais mises à jour par `--force`. - `update ` échoue rapidement pour les Skills épinglées et vous indique d’exécuter d’abord `clawhub unpin `. - `update --all` ignore les slugs épinglés et affiche un résumé de ce qui est resté gelé. ### `skill publish ` - Compare l’empreinte du bundle local avec ClawHub et se termine avec succès quand le contenu est déjà publié. - Les nouvelles Skills utilisent `1.0.0` par défaut ; les Skills modifiées utilisent par défaut la version de correctif suivante. - `--version ` sélectionne explicitement une version et publie même quand le contenu correspond à une version existante. - `--dry-run` résout la publication sans téléverser ; `--json` affiche un résultat lisible par machine. - `--owner ` publie sous un identifiant d’éditeur d’organisation/utilisateur quand l’acteur dispose de l’accès éditeur. - `--migrate-owner` déplace une Skill existante vers `--owner` pendant la publication d’une nouvelle version. Nécessite un accès admin/propriétaire sur les deux éditeurs. - Le comportement du propriétaire et de la revue est expliqué dans `docs/publishing.md`. - Publier une Skill signifie qu’elle est publiée sous `MIT-0` sur ClawHub. - Les Skills publiées peuvent être utilisées, modifiées et redistribuées librement sans attribution. - ClawHub ne prend pas en charge les Skills payantes ni la tarification par Skill. - Ancien alias : `publish `. ```bash clawhub skill publish ./my-skill --dry-run clawhub skill publish ./my-skill clawhub skill publish ./my-skill --version 2.0.0 ``` #### GitHub Actions Le workflow réutilisable de ClawHub [`skill-publish.yml`](https://github.com/openclaw/clawhub/blob/main/.github/workflows/skill-publish.yml) appelle `skill publish` pour un `skill_path`, ou pour chaque dossier de Skill immédiat sous `root` (par défaut : `skills`). Il ignore les Skills inchangées et utilise le même comportement automatique de version de correctif. Définissez `dry_run: true` pour prévisualiser sans jeton. Les publications réelles nécessitent le secret `clawhub_token`. ### `sync` - Analyse le répertoire de travail actuel, le répertoire de Skills configuré et tous les dossiers `--root ` à la recherche de dossiers de Skills locaux contenant `SKILL.md` ou `skill.md`. - Compare chaque empreinte de Skill locale avec ClawHub et publie uniquement les Skills nouvelles ou modifiées. - Les nouvelles Skills sont publiées en `1.0.0` ; les Skills modifiées publient par défaut la version de correctif suivante. Utilisez `--bump minor|major` pour les lots de mise à jour qui doivent avancer d’un pas semver plus grand. - `--dry-run` affiche le plan de publication sans téléverser ; `--json` affiche un plan lisible par machine. - `--all` publie toutes les Skills nouvelles ou modifiées sans invite. Sans `--all`, les terminaux interactifs vous permettent de sélectionner les Skills à publier. - `--owner ` publie sous un identifiant d’éditeur d’organisation/utilisateur quand l’acteur dispose de l’accès éditeur. - `sync` est uniquement une publication à sens unique. Il n’installe pas, ne met pas à jour, ne télécharge pas et ne signale pas la télémétrie d’installation/téléchargement. ```bash clawhub sync --all --dry-run clawhub sync --all clawhub sync --root ./skills --owner openclaw --bump minor ``` ### `scan --slug ` - Nécessite `clawhub login`. - Exécute ClawHub ClawScan via `POST /api/v1/skills/-/scan`, puis interroge jusqu’à ce que l’analyse soit terminale. - Les analyses sont asynchrones et peuvent prendre du temps. Pendant la file d’attente, l’indicateur du terminal affiche la position actuelle de l’analyse priorisée et le nombre d’analyses en attente devant elle. - Les analyses publiées nécessitent un accès de gestion propriétaire ou éditeur. Les modérateurs/admins peuvent utiliser le même backend via `clawhub-admin`. - `--update` est valide uniquement avec `--slug` ; il réécrit les résultats d’analyse publiée réussis dans la version sélectionnée. - `--output ` télécharge l’archive complète du rapport avec `manifest.json`, `clawscan.json`, `skillspector.json`, `static-analysis.json`, `virustotal.json` et `README.md`. - `--json` affiche la réponse complète de l’interrogation pour l’automatisation. - Les analyses de chemins locaux ne sont plus prises en charge. Téléversez une nouvelle version, puis utilisez `scan download` pour récupérer les résultats d’analyse stockés pour cette version soumise. ```bash clawhub scan --slug gifgrep clawhub scan --slug gifgrep --version 1.2.3 clawhub scan --slug gifgrep --update --output report.zip ``` ### `scan download ` - Nécessite `clawhub login`. - Télécharge le ZIP de rapport d’analyse stocké pour une version de Skill ou de Plugin soumise, y compris les versions qui ont été bloquées ou masquées par les vérifications de sécurité ClawHub. - Les téléchargements de Skill utilisent le slug de la Skill et utilisent `--kind skill` par défaut. - Les téléchargements de Plugin utilisent le nom du package et nécessitent `--kind plugin`. - `--version` est requis afin que les auteurs inspectent la version soumise exacte que ClawHub a bloquée. - `--output ` choisit le chemin de destination. ```bash clawhub scan download gifgrep --version 1.2.3 clawhub scan download @scope/demo --version 2.0.0 --kind plugin --output report.zip ``` #### GitHub Actions ClawHub fournit un workflow réutilisable officiel à [`/.github/workflows/skill-publish.yml`](https://github.com/openclaw/clawhub/blob/76b4f36bb0f7409ed7cb9c6fd6f1ccf81396ee88/.github/workflows/skill-publish.yml) pour les dépôts de Skills et les dépôts de catalogues. Configuration de catalogue typique : ```yaml name: Skill Publish on: pull_request: workflow_dispatch: jobs: dry-run: if: github.event_name == 'pull_request' uses: openclaw/clawhub/.github/workflows/skill-publish.yml@v1 with: owner: nvidia dry_run: true publish: if: github.event_name == 'workflow_dispatch' uses: openclaw/clawhub/.github/workflows/skill-publish.yml@v1 with: owner: nvidia dry_run: false secrets: clawhub_token: ${{ secrets.CLAWHUB_TOKEN }} ``` Notes : - `root` utilise `skills` par défaut pour les dépôts de catalogues. - Passez `skill_path: skills/review-helper` pour traiter un seul dossier de Skill. - `owner` correspond à l’indicateur CLI `--owner` ; omettez-le pour publier en tant qu’utilisateur authentifié. - La publication de Skills V1 utilise `clawhub_token` ; la publication approuvée GitHub OIDC est réservée aux packages pour le moment. ### `delete ` - Sans `--version`, supprime provisoirement une skill (propriétaire, modérateur ou administrateur). - Appelle `DELETE /api/v1/skills/{slug}`. - Les suppressions provisoires initiées par le propriétaire réservent le slug pendant 30 jours ; la commande affiche l’heure d’expiration. - `--version ` supprime définitivement une version possédée qui n’est pas la plus récente via une route fail-closed propre à la version. Les versions supprimées ne peuvent pas être restaurées ni republiées. Publiez un remplacement avant de supprimer la version actuellement la plus récente. Le personnel de la plateforme ne contourne pas la propriété pour ce flux limité aux versions. - `--reason ` enregistre une note de modération sur une suppression provisoire de skill entière et dans le journal d’audit. - `--note ` est un alias de `--reason`. - `--yes` ignore la confirmation. ### `undelete ` - Restaure une skill masquée (propriétaire, modérateur ou administrateur). - Il n’existe pas d’annulation de suppression de version ; les versions supprimées définitivement ne peuvent pas être restaurées. - Appelle `POST /api/v1/skills/{slug}/undelete`. - `--reason ` enregistre une note de modération sur la skill et dans le journal d’audit. - `--note ` est un alias de `--reason`. - `--yes` ignore la confirmation. ### `hide ` - Masque une skill (propriétaire, modérateur ou administrateur). - Alias de `delete`. ### `unhide ` - Réaffiche une skill (propriétaire, modérateur ou administrateur). - Alias de `undelete`. ### `skill rename ` - Renomme une skill possédée et conserve le slug précédent comme alias de redirection. - Appelle `POST /api/v1/skills/{slug}/rename`. - `--yes` ignore la confirmation. ### `skill merge ` - Fusionne une skill possédée dans une autre skill possédée. - Le slug source cesse d’être listé publiquement et devient un alias de redirection vers la cible. - Appelle `POST /api/v1/skills/{sourceSlug}/merge`. - `--yes` ignore la confirmation. ### `transfer` - Flux de transfert de propriété. - Les transferts vers des identifiants d’utilisateurs créent une demande en attente que le destinataire accepte. - Les transferts vers des identifiants d’organisation/éditeur s’appliquent immédiatement uniquement lorsque l’acteur dispose d’un accès administrateur au propriétaire actuel et à l’éditeur de destination. - Sous-commandes : - `transfer request [--message "..."] [--yes]` - `transfer list [--outgoing]` - `transfer accept [--yes]` - `transfer reject [--yes]` - `transfer cancel [--yes]` - Points de terminaison : - `POST /api/v1/skills/{slug}/transfer` - `POST /api/v1/skills/{slug}/transfer/accept` - `POST /api/v1/skills/{slug}/transfer/reject` - `POST /api/v1/skills/{slug}/transfer/cancel` - `GET /api/v1/transfers/incoming` - `GET /api/v1/transfers/outgoing` ### `package explore [query...]` - Parcourt ou recherche dans le catalogue unifié des packages via `GET /api/v1/packages` et `GET /api/v1/packages/search`. - Utilisez ceci pour les plugins et les autres entrées de familles de packages ; `search` au niveau supérieur reste la surface de recherche des skills. - Indicateurs : - `--family skill|code-plugin|bundle-plugin` - `--official` - `--executes-code` - `--target `, `--os `, `--arch `, `--libc ` - `--requires-browser`, `--requires-desktop`, `--requires-native-deps` - `--requires-external-service`, `--external-service ` - `--binary `, `--os-permission ` - `--artifact-kind legacy-zip|npm-pack` - `--npm-mirror` - `--limit ` (1-100, valeur par défaut : 25) - `--json` Exemples : ```bash clawhub package explore --family code-plugin clawhub package explore --family code-plugin --os darwin --requires-desktop clawhub package explore --family code-plugin --artifact-kind npm-pack clawhub package explore --npm-mirror clawhub package explore episodic-claw --family code-plugin ``` ### `package inspect ` - Récupère les métadonnées du package sans l’installer. - Utilisez ceci pour les métadonnées de plugin, la compatibilité, la vérification, la source et l’inspection des versions/fichiers. - `--version ` : inspecte une version spécifique (par défaut : la plus récente). - `--tag ` : inspecte une version étiquetée (par exemple `latest`). - `--versions` : liste l’historique des versions (première page). - `--limit ` : nombre maximal de versions à lister (1-100). - `--files` : liste les fichiers de la version sélectionnée. - `--file ` : récupère le contenu brut du fichier (fichiers texte uniquement ; limite de 200 Ko). - `--json` : sortie lisible par machine. ### `package download ` - Résout une version de package via `GET /api/v1/packages/{name}/versions/{version}/artifact`. - Télécharge l’artéfact depuis le `downloadUrl` du résolveur. - Vérifie le SHA-256 ClawHub pour tous les artéfacts. - Pour les artéfacts ClawPack npm-pack, vérifie aussi l’intégrité npm `sha512`, le shasum npm et le nom/la version dans le `package.json` de l’archive tar. - Les versions ZIP héritées se téléchargent via la route ZIP héritée. - Indicateurs : - `--version ` : télécharge une version spécifique. - `--tag ` : télécharge une version étiquetée (par défaut : `latest`). - `-o, --output ` : fichier ou répertoire de sortie. - `--force` : écrase un fichier de sortie existant. - `--json` : sortie lisible par machine. Exemples : ```bash clawhub package download @openclaw/example-plugin --tag latest clawhub package download @openclaw/example-plugin --version 1.2.3 -o artifacts/ ``` ### `package verify ` - Calcule le SHA-256 ClawHub, l’intégrité npm `sha512` et le shasum npm pour un artéfact local. - Avec `--package`, résout les métadonnées attendues depuis ClawHub et compare le fichier local aux métadonnées de l’artéfact publié. - Avec des indicateurs directs de condensat, vérifie sans requête réseau. - Indicateurs : - `--package ` : nom du package pour résoudre les métadonnées d’artéfact attendues. - `--version ` ou `--tag ` : version attendue du package. - `--sha256 ` : SHA-256 ClawHub attendu. - `--npm-integrity ` : intégrité npm attendue. - `--npm-shasum ` : shasum npm attendu. - `--json` : sortie lisible par machine. Exemples : ```bash clawhub package verify ./example-plugin-1.2.3.tgz --package @openclaw/example-plugin --version 1.2.3 clawhub package verify ./example-plugin-1.2.3.tgz --sha256 ``` ### `package validate ` - Exécute le Plugin Inspector intégré de la CLI ClawHub sur un dossier de package de plugin local. - Utilise par défaut une validation hors ligne/statique, sans localiser ni importer un checkout OpenClaw local. - Les erreurs de compatibilité bloquantes quittent avec un code non nul. Les constats d’avertissement uniquement sont affichés mais quittent avec zéro. - Indicateurs : - `--out ` : écrit les rapports de Plugin Inspector dans ce répertoire. - `--openclaw ` : inspecte par rapport à un checkout OpenClaw local explicite. - `--runtime` : active la capture d’exécution ; importe le code du plugin. - `--allow-execute` : autorise la capture d’exécution dans un espace de travail isolé. - `--no-mock-sdk` : désactive le SDK OpenClaw simulé pendant la capture d’exécution. - `--json` : sortie lisible par machine. Exemple : ```bash clawhub package validate ./example-plugin ``` Si la validation signale un constat concernant le package, le manifeste, l’import SDK ou l’artéfact, consultez [Corrections de validation des plugins](/fr/clawhub/plugin-validation-fixes), puis réexécutez la commande. ### `package delete ` - Sans `--version`, supprime provisoirement un package et toutes ses versions publiées. - `--version ` supprime définitivement une version possédée qui n’est pas la plus récente via une route fail-closed, propre à la version. Les versions supprimées ne peuvent pas être restaurées ni republiées. Publiez un remplacement avant de supprimer la version actuellement la plus récente. Ce flux limité aux versions exige le propriétaire du package ou un administrateur d’éditeur d’organisation ; le personnel de la plateforme ne contourne pas la propriété du package. - La suppression provisoire de package entier exige le propriétaire du package, un propriétaire/administrateur d’éditeur d’organisation, un modérateur de plateforme ou un administrateur de plateforme. - Indicateurs : - `--version ` : supprime définitivement une version non la plus récente. - `--yes` : ignore la confirmation. - `--json` : sortie lisible par machine. Exemple : ```bash clawhub package delete @openclaw/example-plugin --yes clawhub package delete @openclaw/example-plugin --version 1.2.3 --yes ``` ### `package undelete ` - Restaure un package supprimé provisoirement et ses versions publiées. - Il n’existe pas d’annulation de suppression de version ; les versions supprimées définitivement ne peuvent pas être restaurées. - Exige le propriétaire du package, un propriétaire/administrateur d’éditeur d’organisation, un modérateur de plateforme ou un administrateur de plateforme. - Appelle `POST /api/v1/packages/{name}/undelete`. - Indicateurs : - `--yes` : ignore la confirmation. - `--json` : sortie lisible par machine. Exemple : ```bash clawhub package undelete @openclaw/example-plugin --yes ``` ### `package transfer ` - Transfère un package à un autre éditeur. - Exige un accès administrateur au propriétaire actuel du package et à l’éditeur de destination, sauf si l’opération est effectuée par un administrateur de plateforme. - Les noms de packages à portée doivent être transférés au propriétaire de portée correspondant. - Appelle `POST /api/v1/packages/{name}/transfer`. - Indicateurs : - `--to ` : identifiant de l’éditeur de destination. - `--reason ` : motif d’audit facultatif. - `--json` : sortie lisible par machine. Exemple : ```bash clawhub package transfer @openclaw/example-plugin --to openclaw ``` ### `package report` - Commande authentifiée pour signaler un package aux modérateurs. - Appelle `POST /api/v1/packages/{name}/report`. - Les signalements se font au niveau du package, éventuellement liés à une version, et deviennent visibles par les modérateurs pour examen. - Les signalements ne masquent pas automatiquement les packages et ne bloquent pas les téléchargements par eux-mêmes. - Indicateurs : - `--version ` : version facultative du package à associer au signalement. - `--reason ` : motif de signalement obligatoire. - `--json` : sortie lisible par machine. Exemple : ```bash clawhub package report @openclaw/example-plugin --version 1.2.3 --reason "suspicious native payload" ``` ### `package moderation-status` - Commande propriétaire pour vérifier la visibilité de modération du package. - Appelle `GET /api/v1/packages/{name}/moderation`. - Affiche l’état d’analyse actuel du package, le nombre de signalements ouverts, l’état de modération manuelle de la dernière version publiée, l’état de blocage des téléchargements et les motifs de modération. - Indicateurs : - `--json` : sortie lisible par machine. Exemple : ```bash clawhub package moderation-status @openclaw/example-plugin ``` ### `package readiness ` - Vérifie si un package est prêt pour une consommation future par OpenClaw. - Appelle `GET /api/v1/packages/{name}/readiness`. - Signale les bloqueurs pour le statut officiel, la disponibilité ClawPack, le condensat d’artéfact, la provenance de la source, la compatibilité OpenClaw, les cibles hôtes, les métadonnées d’environnement et l’état d’analyse. - Indicateurs : - `--json` : sortie lisible par machine. Exemple : ```bash clawhub package readiness @openclaw/example-plugin ``` ### `package migration-status ` - Affiche l’état de migration orienté opérateur pour un package susceptible de remplacer un plugin OpenClaw intégré. - Appelle le même point de terminaison de disponibilité calculée que `package readiness`, mais affiche l’état axé sur la migration, la dernière version, l’état de package officiel, les vérifications et les bloqueurs. - Indicateurs : - `--json` : sortie lisible par machine. Exemple : ```bash clawhub package migration-status @openclaw/example-plugin ``` ### `publisher create ` - Crée un éditeur d’organisation appartenant à l’utilisateur authentifié. - L’identifiant est normalisé en minuscules et peut être fourni avec ou sans `@`. - Les éditeurs d’organisation nouvellement créés ne sont pas fiables/officiels par défaut. - Échoue si l’identifiant est déjà utilisé par un éditeur, un utilisateur ou une route réservée existants. ```bash clawhub publisher create opik --display-name "Opik" ``` ### `package publish ` - Publie un Plugin de code ou un Plugin de bundle via `POST /api/v1/packages`. - `` accepte : - Chemin de dossier local : `./my-plugin` - Archive tarball npm-pack ClawPack locale : `./my-plugin-1.2.3.tgz` - Dépôt GitHub : `owner/repo` ou `owner/repo@ref` - URL GitHub : `https://github.com/owner/repo` - Les métadonnées sont détectées automatiquement depuis `package.json`, `openclaw.plugin.json` et les vrais marqueurs de bundle OpenClaw tels que `.codex-plugin/plugin.json`, `.claude-plugin/plugin.json` et `.cursor-plugin/plugin.json`. - Les sources `.tgz` sont traitées comme des ClawPack. La CLI téléverse les octets npm-pack exacts et utilise le contenu `package/` extrait uniquement pour la validation et le préremplissage des métadonnées. - Les dossiers de Plugin de code sont empaquetés dans une archive tarball npm ClawPack avant le téléversement afin que les installations OpenClaw puissent vérifier l’artefact exact. Les dossiers de Plugin de bundle continuent d’utiliser le chemin de publication par fichiers extraits. - Pour les sources GitHub, l’attribution de source est remplie automatiquement depuis le dépôt, le commit résolu, la ref et le sous-chemin. - Pour les dossiers locaux, l’attribution de source est détectée automatiquement depuis le git local lorsque le remote d’origine pointe vers GitHub. - Les Plugins de code externes doivent déclarer explicitement `openclaw.compat.pluginApi` et `openclaw.build.openclawVersion`. Le champ de premier niveau `package.json.version` n’est pas utilisé comme solution de repli pour la validation de publication. - `--dry-run` prévisualise la charge utile de publication résolue sans téléverser. - `--json` émet une sortie lisible par machine pour la CI. - `--owner ` publie sous un identifiant d’éditeur utilisateur ou organisation lorsque l’acteur dispose de l’accès éditeur. - Les noms de packages scoped doivent correspondre au propriétaire sélectionné. Voir `docs/publishing.md`. - Les options existantes (`--family`, `--name`, `--version`, `--source-repo`, `--source-commit`, `--source-ref`, `--source-path`) fonctionnent toujours comme substitutions. - Les dépôts GitHub privés nécessitent `GITHUB_TOKEN`. ```bash clawhub package publish ./plugin.tgz --owner openclaw ``` #### Flux local recommandé Utilisez d’abord `--dry-run` afin de pouvoir confirmer les métadonnées de package résolues et l’attribution de source avant de créer une version réelle : ```bash npm pack clawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin --dry-run clawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin ``` #### Flux de dossier local Pour les Plugins de code, la publication de dossier construit et téléverse un artefact ClawPack depuis le dossier du package : ```bash clawhub package publish ./my-plugin --family code-plugin --dry-run clawhub package publish ./my-plugin --family code-plugin ``` #### `package.json` minimal pour `--family code-plugin` Les Plugins de code externes ont besoin d’une petite quantité de métadonnées OpenClaw dans `package.json`. Ce manifeste minimal suffit pour une publication réussie : ```json { "name": "@myorg/openclaw-my-plugin", "version": "1.0.0", "type": "module", "openclaw": { "extensions": ["./index.ts"], "compat": { "pluginApi": ">=2026.3.24-beta.2" }, "build": { "openclawVersion": "2026.3.24-beta.2" } } } ``` Champs requis : - `openclaw.compat.pluginApi` - `openclaw.build.openclawVersion` Notes : - `package.json.version` est la version de publication de votre package, mais elle n’est pas utilisée comme solution de repli pour la validation de compatibilité/build OpenClaw. - `openclaw.hostTargets` et `openclaw.environment` sont des métadonnées facultatives. ClawHub peut les afficher lorsqu’elles sont présentes, mais elles ne sont pas requises pour publier. - `openclaw.compat.minGatewayVersion` et `openclaw.build.pluginSdkVersion` sont des compléments facultatifs si vous souhaitez publier des métadonnées de compatibilité plus détaillées. - Si vous utilisez une ancienne version de la CLI `clawhub`, mettez-la à niveau avant de publier afin que les vérifications locales préalables s’exécutent avant le téléversement. - Si la validation signale un code de remédiation, consultez [Correctifs de validation de Plugin](/fr/clawhub/plugin-validation-fixes). #### GitHub Actions ClawHub fournit également un workflow réutilisable officiel à l’adresse [`/.github/workflows/package-publish.yml`](https://github.com/openclaw/clawhub/blob/76b4f36bb0f7409ed7cb9c6fd6f1ccf81396ee88/.github/workflows/package-publish.yml) pour les dépôts de Plugins. Configuration d’appel typique : ```yaml name: Package Publish on: pull_request: workflow_dispatch: push: tags: - "v*" jobs: dry-run: if: github.event_name == 'pull_request' uses: openclaw/clawhub/.github/workflows/package-publish.yml@v0.12.0 with: dry_run: true publish: if: github.event_name == 'workflow_dispatch' || startsWith(github.ref, 'refs/tags/') permissions: contents: read id-token: write uses: openclaw/clawhub/.github/workflows/package-publish.yml@v0.12.0 with: dry_run: false secrets: clawhub_token: ${{ secrets.CLAWHUB_TOKEN }} ``` Notes : - Le workflow réutilisable définit par défaut `source` sur le dépôt appelant. - Pour les monorepos, transmettez `source_path` afin que le workflow publie le dossier du package Plugin, par exemple `source_path: extensions/codex`. - Épinglez le workflow réutilisable à une balise stable ou à un SHA de commit complet. N’exécutez pas la publication de version depuis `@main`. - `pull_request` doit utiliser `dry_run: true` afin que la CI reste non polluante. - Les publications réelles doivent être limitées aux événements approuvés tels que `workflow_dispatch` ou les poussées de balises. - La publication approuvée sans secret fonctionne uniquement sur `workflow_dispatch` ; les poussées de balises nécessitent toujours `clawhub_token`. - Gardez `clawhub_token` disponible pour la première publication, les packages non approuvés ou les publications d’urgence. - Le workflow téléverse le résultat JSON comme artefact et l’expose comme sorties de workflow. ### `package trusted-publisher get ` - Affiche la configuration d’éditeur approuvé GitHub Actions pour un package. - Utilisez ceci après avoir défini la configuration pour confirmer le dépôt, le nom de fichier du workflow et l’épinglage facultatif de l’environnement. - Options : - `--json` : sortie lisible par machine. Exemple : ```bash clawhub package trusted-publisher get @openclaw/example-plugin ``` ### `package trusted-publisher set ` - Attache ou remplace la configuration d’éditeur approuvé GitHub Actions pour un package existant. - Le package doit d’abord être créé via la publication `clawhub package publish` normale manuelle ou authentifiée par jeton. - Une fois la configuration définie, les futures publications GitHub Actions prises en charge peuvent utiliser OIDC/la publication approuvée sans jeton ClawHub longue durée. - `--repository ` doit être `owner/repo`. - `--workflow-filename ` doit correspondre au nom du fichier de workflow dans `.github/workflows/`. - `--environment ` est facultatif. Lorsqu’il est configuré, l’environnement GitHub Actions dans la revendication OIDC doit correspondre exactement. - ClawHub vérifie le dépôt GitHub configuré lorsque cette commande s’exécute. Les dépôts publics peuvent être vérifiés via les métadonnées publiques GitHub. Les dépôts privés nécessitent que ClawHub ait accès à ce dépôt GitHub, par exemple via une future installation de GitHub App ClawHub ou une autre intégration GitHub autorisée. - Options : - `--repository ` : dépôt GitHub, par exemple `openclaw/example-plugin`. - `--workflow-filename ` : nom du fichier de workflow, par exemple `package-publish.yml`. - `--environment ` : environnement GitHub Actions facultatif à correspondance exacte. - `--json` : sortie lisible par machine. Exemple : ```bash clawhub package trusted-publisher set @openclaw/example-plugin \ --repository openclaw/example-plugin \ --workflow-filename package-publish.yml \ --environment release ``` ### `package trusted-publisher delete ` - Supprime la configuration d’éditeur approuvé d’un package. - Utilisez ceci comme retour arrière si le workflow, le dépôt ou l’épinglage d’environnement doit être désactivé ou recréé. - Les futures publications réelles doivent utiliser la publication authentifiée normale jusqu’à ce que la configuration soit redéfinie. - Options : - `--json` : sortie lisible par machine. Exemple : ```bash clawhub package trusted-publisher delete @openclaw/example-plugin ``` ### Télémétrie d’installation - Envoyée après `clawhub install ` lorsque vous êtes connecté, sauf si `CLAWHUB_DISABLE_TELEMETRY=1` est défini. - Le signalement est effectué au mieux. Les commandes d’installation n’échouent pas si la télémétrie est indisponible. - Détails : `docs/telemetry.md`.