CLI

Pacchetto CLI: clawhub, binario: clawhub.

Installalo globalmente con npm o pnpm:

npm i -g clawhub# orpnpm add -g clawhub

Poi verificalo:

clawhub --helpclawhub loginclawhub whoami

Flag globali

• --workdir <dir>: directory di lavoro (predefinita: cwd; ripiega sul workspace Clawdbot se configurato)
• --dir <dir>: directory di installazione sotto workdir (predefinita: skills)
• --site <url>: URL di base per l'accesso dal browser (predefinito: https://clawhub.ai)
• --registry <url>: URL di base dell'API (predefinito: rilevato, altrimenti https://clawhub.ai)
• --no-input: disabilita i prompt

Equivalenti env:

• CLAWHUB_SITE (legacy CLAWDHUB_SITE)
• CLAWHUB_REGISTRY (legacy CLAWDHUB_REGISTRY)
• CLAWHUB_WORKDIR (legacy CLAWDHUB_WORKDIR)

Proxy HTTP

La CLI rispetta le variabili d'ambiente proxy HTTP standard per i sistemi dietro proxy aziendali o reti con restrizioni:

• HTTPS_PROXY / https_proxy
• HTTP_PROXY / http_proxy
• NO_PROXY / no_proxy

Quando una di queste variabili è impostata, la CLI instrada le richieste in uscita tramite il proxy specificato. HTTPS_PROXY viene usato per le richieste HTTPS, HTTP_PROXY per HTTP semplice. NO_PROXY / no_proxy viene rispettato per bypassare il proxy per host o domini specifici.

Questo è necessario sui sistemi in cui le connessioni dirette in uscita sono bloccate (ad es. container Docker, VPS Hetzner con internet solo tramite proxy, firewall aziendali).

Esempio:

export HTTPS_PROXY=http://proxy.example.com:3128export NO_PROXY=localhost,127.0.0.1clawhub search "my query"

Quando non è impostata alcuna variabile proxy, il comportamento resta invariato (connessioni dirette).

File di configurazione

Memorizza il tuo token API + l'URL del registro nella cache.

• macOS: ~/Library/Application Support/clawhub/config.json
• Linux/XDG: $XDG_CONFIG_HOME/clawhub/config.json o ~/.config/clawhub/config.json
• Windows: %APPDATA%\\clawhub\\config.json
• Fallback legacy: se clawhub/config.json non esiste ancora ma clawdhub/config.json esiste, la CLI riusa il percorso legacy
• override: CLAWHUB_CONFIG_PATH (legacy CLAWDHUB_CONFIG_PATH)

Comandi

login / auth login

• Predefinito: apre il browser su <site>/cli/auth e completa tramite callback loopback.
• Headless: clawhub login --token clh_...
• Remoto/headless interattivo: clawhub login --device stampa un codice e attende mentre lo autorizzi su <site>/cli/device.

whoami

• Verifica il token memorizzato tramite /api/v1/whoami.

token

• Stampa il token API memorizzato su stdout.
• Utile per passare tramite pipe un token di accesso locale ai comandi di configurazione dei segreti CI.

star <skill> / unstar <skill>

• Aggiunge/rimuove una competenza dai tuoi elementi in evidenza.
• Chiama POST /api/v1/stars/<slug> e DELETE /api/v1/stars/<slug>.
• --yes salta la conferma.

search <query...>

• Chiama /api/v1/search?q=....
• L'output include lo slug della competenza, l'handle del proprietario, il nome visualizzato e il punteggio di rilevanza.
• La ricerca favorisce le corrispondenze esatte dei token di slug/nome prima della popolarità dei download. Un token slug autonomo come map corrisponde a personal-map più fortemente della sottostringa dentro amap.
• La popolarità è un piccolo priore di classificazione, non una garanzia di posizionamento in cima.
• Se una competenza dovrebbe apparire ma non appare, esegui clawhub inspect @owner/slug mentre sei autenticato per controllare la diagnostica di moderazione visibile al proprietario prima di rinominare i metadati.

explore

• Elenca le competenze più recenti tramite /api/v1/skills?limit=...&sort=createdAt (ordinate per createdAt desc).
• Flag:
  • --limit <n> (1-200, predefinito: 25)
  • --sort newest|updated|rating|downloads|trending (predefinito: newest). Gli alias di ordinamento legacy dell'installazione funzionano ancora per compatibilità.
  • --json (output leggibile da macchina)
• Output: <slug> v<version> <age> <summary> (riepilogo troncato a 50 caratteri).

inspect @owner/slug

• Recupera i metadati della competenza e i file di versione senza installare.
• --version <version>: ispeziona una versione specifica (predefinita: latest).
• --tag <tag>: ispeziona una versione con tag (ad es. latest).
• --versions: elenca la cronologia delle versioni (prima pagina).
• --limit <n>: numero massimo di versioni da elencare (1-200).
• --files: elenca i file per la versione selezionata.
• --file <path>: recupera il contenuto grezzo del file (solo file di testo; limite 200 KB).
• --json: output leggibile da macchina.

install @owner/slug

• Risolve l'ultima versione per il proprietario e la competenza indicati.
• Scarica lo zip tramite /api/v1/download.
• Estrae in <workdir>/<dir>/<slug>.
• Rifiuta di sovrascrivere le competenze bloccate; esegui prima clawhub unpin <skill>.
• Scrive:
  • <workdir>/.clawhub/lock.json (legacy .clawdhub)
  • <skill>/.clawhub/origin.json (legacy .clawdhub)

uninstall <skill>

• Rimuove <workdir>/<dir>/<slug> ed elimina la voce nel lockfile.
• Invia telemetria non garantita mentre sei autenticato, così i conteggi di installazione correnti possono essere disattivati.
• Interattivo: chiede conferma.
• Non interattivo (--no-input): richiede --yes.

list

• Legge <workdir>/.clawhub/lock.json (legacy .clawdhub).
• Mostra pinned accanto alle competenze congelate con clawhub pin, incluso il motivo facoltativo.

pin <skill>

• Contrassegna una competenza installata come bloccata nel lockfile.
• --reason <text> registra perché la competenza è congelata.
• Le competenze bloccate vengono saltate da update --all e rifiutate da update <skill> diretto.
• Le competenze bloccate rifiutano anche install --force, così i byte locali non possono essere sostituiti accidentalmente.

unpin <skill>

• Rimuove il blocco del lockfile da una competenza installata, così gli aggiornamenti futuri possono modificarla.

update [@owner/slug] / update --all

• Calcola l'impronta dai file locali.
• Se l'impronta corrisponde a una versione nota: nessun prompt.
• Se l'impronta non corrisponde:
  • rifiuta per impostazione predefinita
  • sovrascrive con --force (o prompt, se interattivo)
• Le competenze bloccate non vengono mai aggiornate da --force.
• update <skill> fallisce rapidamente per le competenze bloccate e ti dice di eseguire prima clawhub unpin <skill>.
• update --all salta gli slug bloccati e stampa un riepilogo di ciò che è rimasto congelato.

skill publish <path>

• Confronta l'impronta del bundle locale con ClawHub ed esce con successo quando il contenuto è già pubblicato.
• Le nuove competenze usano come predefinito 1.0.0; le competenze modificate usano come predefinita la versione patch successiva.
• --version <version> seleziona esplicitamente una versione e pubblica anche quando il contenuto corrisponde a una versione esistente.
• --dry-run risolve la pubblicazione senza caricare; --json stampa un risultato leggibile da macchina.
• --owner <handle> pubblica sotto un handle editore org/utente quando l'attore ha accesso di pubblicazione.
• --migrate-owner sposta una competenza esistente su --owner pubblicando una nuova versione. Richiede accesso admin/proprietario su entrambi gli editori.
• Il comportamento di proprietario e revisione è spiegato in docs/publishing.md.
• Pubblicare una competenza significa che viene rilasciata sotto MIT-0 su ClawHub.
• Le competenze pubblicate sono libere da usare, modificare e ridistribuire senza attribuzione.
• ClawHub non supporta competenze a pagamento o prezzi per singola competenza.
• Alias legacy: publish <path>.

clawhub skill publish ./my-skill --dry-runclawhub skill publish ./my-skillclawhub skill publish ./my-skill --version 2.0.0

GitHub Actions

Il workflow riutilizzabile di ClawHub skill-publish.yml chiama skill publish per uno skill_path, oppure per ogni cartella di competenza immediata sotto root (predefinito: skills). Salta le competenze non modificate e usa lo stesso comportamento automatico di versione patch.

Imposta dry_run: true per un'anteprima senza token. Le pubblicazioni reali richiedono il segreto clawhub_token.

sync

• Scansiona la workdir corrente, la directory delle competenze configurata e qualsiasi cartella --root <dir> alla ricerca di cartelle di competenze locali contenenti SKILL.md o skill.md.
• Confronta l'impronta di ogni competenza locale con ClawHub e pubblica solo competenze nuove o modificate.
• Le nuove competenze vengono pubblicate come 1.0.0; le competenze modificate pubblicano la versione patch successiva per impostazione predefinita. Usa --bump minor|major per batch di aggiornamento che dovrebbero avanzare di un passo semver più grande.
• --dry-run mostra il piano di pubblicazione senza caricare; --json stampa un piano leggibile da macchina.
• --all pubblica ogni competenza nuova o modificata senza prompt. Senza --all, i terminali interattivi ti permettono di selezionare le competenze da pubblicare.
• --owner <handle> pubblica sotto un handle editore org/utente quando l'attore ha accesso di pubblicazione.
• sync è solo pubblicazione unidirezionale. Non installa, aggiorna, scarica né segnala telemetria di installazione/download.

clawhub sync --all --dry-runclawhub sync --allclawhub sync --root ./skills --owner openclaw --bump minor

scan --slug <slug>

• Richiede clawhub login.
• Esegue ClawHub ClawScan tramite POST /api/v1/skills/-/scan, poi esegue polling finché la scansione è terminale.
• Le scansioni sono asincrone e possono richiedere tempo per completarsi. Mentre sono in coda, l'indicatore del terminale mostra la posizione di scansione prioritaria corrente e quante scansioni la precedono.
• Le scansioni pubblicate richiedono proprietà o accesso di gestione dell'editore. Moderatori/admin possono usare lo stesso backend tramite clawhub-admin.
• --update è valido solo con --slug; scrive i risultati di scansione pubblicata riusciti nella versione selezionata.
• --output <file.zip> scarica l'archivio completo del report con manifest.json, clawscan.json, skillspector.json, static-analysis.json, virustotal.json e README.md.
• --json stampa la risposta completa del polling per l'automazione.
• Le scansioni di percorsi locali non sono più supportate. Carica una nuova versione, poi usa scan download per recuperare i risultati di scansione memorizzati per quella versione inviata.

clawhub scan --slug gifgrepclawhub scan --slug gifgrep --version 1.2.3clawhub scan --slug gifgrep --update --output report.zip

scan download <name>

• Richiede clawhub login.
• Scarica lo ZIP del report di scansione memorizzato per una versione di competenza o Plugin inviata, incluse le versioni bloccate o nascoste dai controlli di sicurezza di ClawHub.
• I download delle competenze usano lo slug della competenza e usano come predefinito --kind skill.
• I download dei Plugin usano il nome del pacchetto e richiedono --kind plugin.
• --version è richiesto affinché gli autori ispezionino l'esatta versione inviata che ClawHub ha bloccato.
• --output <file.zip> sceglie il percorso di destinazione.

clawhub scan download gifgrep --version 1.2.3clawhub scan download @scope/demo --version 2.0.0 --kind plugin --output report.zip

GitHub Actions

ClawHub fornisce un workflow riutilizzabile ufficiale su /.github/workflows/skill-publish.yml per repository di competenze e repository di cataloghi.

Configurazione tipica del catalogo:

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 }}

Note:

• root usa come predefinito skills per i repository di cataloghi.
• Passa skill_path: skills/review-helper per elaborare una cartella di competenza.
• owner corrisponde al flag CLI --owner; omettilo per pubblicare come utente autenticato.
• La pubblicazione di competenze V1 usa clawhub_token; la pubblicazione attendibile GitHub OIDC è solo per pacchetti per ora.

delete <skill>

• Senza --version, elimina in modo reversibile una skill (proprietario, moderatore o amministratore).
• Chiama DELETE /api/v1/skills/{slug}.
• Le eliminazioni reversibili avviate dal proprietario riservano lo slug per 30 giorni; il comando stampa l'ora di scadenza.
• --version <version> elimina definitivamente una versione posseduta non più recente tramite una route specifica per versione, fail-closed. Le versioni eliminate non possono essere ripristinate o ripubblicate. Pubblica una sostituzione prima di eliminare la versione più recente corrente. Il personale della piattaforma non aggira la proprietà per questo flusso solo versione.
• --reason <text> registra una nota di moderazione su un'eliminazione reversibile dell'intera skill e nel log di audit.
• --note <text> è un alias di --reason.
• --yes salta la conferma.

undelete <skill>

• Ripristina una skill nascosta (proprietario, moderatore o amministratore).
• Non esiste ripristino di versione; le versioni eliminate definitivamente non possono essere ripristinate.
• Chiama POST /api/v1/skills/{slug}/undelete.
• --reason <text> registra una nota di moderazione sulla skill e nel log di audit.
• --note <text> è un alias di --reason.
• --yes salta la conferma.

hide <skill>

• Nasconde una skill (proprietario, moderatore o amministratore).
• Alias di delete.

unhide <skill>

• Rende di nuovo visibile una skill (proprietario, moderatore o amministratore).
• Alias di undelete.

skill rename <skill> <new-name>

• Rinomina una skill posseduta e mantiene lo slug precedente come alias di reindirizzamento.
• Chiama POST /api/v1/skills/{slug}/rename.
• --yes salta la conferma.

skill merge <source> <target>

• Unisce una skill posseduta in un'altra skill posseduta.
• Lo slug di origine smette di essere elencato pubblicamente e diventa un alias di reindirizzamento verso la destinazione.
• Chiama POST /api/v1/skills/{sourceSlug}/merge.
• --yes salta la conferma.

transfer

• Flusso di trasferimento della proprietà.
• I trasferimenti verso handle utente creano una richiesta in sospeso che il destinatario accetta.
• I trasferimenti verso handle di organizzazione/publisher vengono applicati immediatamente solo quando l'attore ha accesso amministratore sia al proprietario corrente sia al publisher di destinazione.
• Sottocomandi:
  • transfer request <skill> <handle> [--message "..."] [--yes]
  • transfer list [--outgoing]
  • transfer accept <skill> [--yes]
  • transfer reject <skill> [--yes]
  • transfer cancel <skill> [--yes]
• Endpoint:
  • 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...]

• Esplora o cerca nel catalogo pacchetti unificato tramite GET /api/v1/packages e GET /api/v1/packages/search.
• Usalo per Plugin e altre voci della famiglia di pacchetti; search di primo livello resta la superficie di ricerca delle skill.
• Flag:
  • --family skill|code-plugin|bundle-plugin
  • --official
  • --executes-code
  • --target <target>, --os <os>, --arch <arch>, --libc <libc>
  • --requires-browser, --requires-desktop, --requires-native-deps
  • --requires-external-service, --external-service <name>
  • --binary <name>, --os-permission <name>
  • --artifact-kind legacy-zip|npm-pack
  • --npm-mirror
  • --limit <n> (1-100, predefinito: 25)
  • --json

Esempi:

clawhub package explore --family code-pluginclawhub package explore --family code-plugin --os darwin --requires-desktopclawhub package explore --family code-plugin --artifact-kind npm-packclawhub package explore --npm-mirrorclawhub package explore episodic-claw --family code-plugin

package inspect <name>

• Recupera i metadati del pacchetto senza installarlo.
• Usalo per metadati del Plugin, compatibilità, verifica, sorgente e ispezione di versioni/file.
• --version <version>: ispeziona una versione specifica (predefinito: più recente).
• --tag <tag>: ispeziona una versione con tag (ad es. latest).
• --versions: elenca la cronologia delle versioni (prima pagina).
• --limit <n>: numero massimo di versioni da elencare (1-100).
• --files: elenca i file per la versione selezionata.
• --file <path>: recupera il contenuto grezzo del file (solo file di testo; limite 200 KB).
• --json: output leggibile da macchina.

package download <name>

• Risolve una versione del pacchetto tramite GET /api/v1/packages/{name}/versions/{version}/artifact.
• Scarica l'artefatto dal downloadUrl del resolver.
• Verifica lo SHA-256 di ClawHub per tutti gli artefatti.
• Per gli artefatti ClawPack npm-pack, verifica anche l'integrità npm sha512, lo shasum npm e nome/versione del package.json del tarball.
• Le versioni ZIP legacy vengono scaricate tramite la route ZIP legacy.
• Flag:
  • --version <version>: scarica una versione specifica.
  • --tag <tag>: scarica una versione con tag (predefinito: latest).
  • -o, --output <path>: file o directory di output.
  • --force: sovrascrive un file di output esistente.
  • --json: output leggibile da macchina.

Esempi:

clawhub package download @openclaw/example-plugin --tag latestclawhub package download @openclaw/example-plugin --version 1.2.3 -o artifacts/

package verify <file>

• Calcola lo SHA-256 di ClawHub, l'integrità npm sha512 e lo shasum npm per un artefatto locale.
• Con --package, risolve i metadati previsti da ClawHub e confronta il file locale con i metadati dell'artefatto pubblicato.
• Con flag digest diretti, verifica senza una ricerca di rete.
• Flag:
  • --package <name>: nome del pacchetto per risolvere i metadati previsti dell'artefatto.
  • --version <version> o --tag <tag>: versione prevista del pacchetto.
  • --sha256 <hex>: SHA-256 di ClawHub previsto.
  • --npm-integrity <sri>: integrità npm prevista.
  • --npm-shasum <sha1>: shasum npm previsto.
  • --json: output leggibile da macchina.

Esempi:

clawhub package verify ./example-plugin-1.2.3.tgz --package @openclaw/example-plugin --version 1.2.3clawhub package verify ./example-plugin-1.2.3.tgz --sha256 <hex>

package validate <source>

• Esegue il Plugin Inspector incluso nella CLI di ClawHub su una cartella di pacchetto Plugin locale.
• Per impostazione predefinita usa la convalida offline/statica, senza localizzare o importare un checkout OpenClaw locale.
• Gli errori di compatibilità gravi escono con codice diverso da zero. I risultati solo di avviso vengono stampati ma escono con zero.
• Flag:
  • --out <dir>: scrive i report del Plugin Inspector in questa directory.
  • --openclaw <path>: ispeziona rispetto a un checkout OpenClaw locale esplicito.
  • --runtime: abilita l'acquisizione runtime; importa il codice del Plugin.
  • --allow-execute: consente l'acquisizione runtime in un workspace isolato.
  • --no-mock-sdk: disabilita l'SDK OpenClaw simulato durante l'acquisizione runtime.
  • --json: output leggibile da macchina.

Esempio:

clawhub package validate ./example-plugin

Se la convalida segnala un risultato relativo a pacchetto, manifest, import dell'SDK o artefatto, consulta Correzioni di convalida dei Plugin, quindi riesegui il comando.

package delete <name>

• Senza --version, elimina in modo reversibile un pacchetto e tutte le release.
• --version <version> elimina definitivamente una release posseduta non più recente tramite una route specifica per versione, fail-closed. Le versioni eliminate non possono essere ripristinate o ripubblicate. Pubblica una sostituzione prima di eliminare la versione più recente corrente. Questo flusso solo versione richiede il proprietario del pacchetto o un amministratore del publisher dell'organizzazione; il personale della piattaforma non aggira la proprietà del pacchetto.
• L'eliminazione reversibile dell'intero pacchetto richiede il proprietario del pacchetto, un proprietario/amministratore del publisher dell'organizzazione, un moderatore della piattaforma o un amministratore della piattaforma.
• Flag:
  • --version <version>: elimina definitivamente una versione non più recente.
  • --yes: salta la conferma.
  • --json: output leggibile da macchina.

Esempio:

clawhub package delete @openclaw/example-plugin --yesclawhub package delete @openclaw/example-plugin --version 1.2.3 --yes

package undelete <name>

• Ripristina un pacchetto eliminato in modo reversibile e le release.
• Non esiste ripristino di versione; le versioni eliminate definitivamente non possono essere ripristinate.
• Richiede il proprietario del pacchetto, un proprietario/amministratore del publisher dell'organizzazione, un moderatore della piattaforma o un amministratore della piattaforma.
• Chiama POST /api/v1/packages/{name}/undelete.
• Flag:
  • --yes: salta la conferma.
  • --json: output leggibile da macchina.

Esempio:

clawhub package undelete @openclaw/example-plugin --yes

package transfer <name>

• Trasferisce un pacchetto a un altro publisher.
• Richiede accesso amministratore sia al proprietario corrente del pacchetto sia al publisher di destinazione, salvo esecuzione da parte di un amministratore della piattaforma.
• I nomi dei pacchetti con ambito devono essere trasferiti al proprietario dell'ambito corrispondente.
• Chiama POST /api/v1/packages/{name}/transfer.
• Flag:
  • --to <owner>: handle del publisher di destinazione.
  • --reason <text>: motivo di audit facoltativo.
  • --json: output leggibile da macchina.

Esempio:

clawhub package transfer @openclaw/example-plugin --to openclaw

package report

• Comando autenticato per segnalare un pacchetto ai moderatori.
• Chiama POST /api/v1/packages/{name}/report.
• Le segnalazioni sono a livello di pacchetto, possono essere facoltativamente collegate a una versione e diventano visibili ai moderatori per la revisione.
• Le segnalazioni non nascondono automaticamente i pacchetti né bloccano i download da sole.
• Flag:
  • --version <version>: versione del pacchetto facoltativa da allegare alla segnalazione.
  • --reason <text>: motivo della segnalazione obbligatorio.
  • --json: output leggibile da macchina.

Esempio:

clawhub package report @openclaw/example-plugin --version 1.2.3 --reason "suspicious native payload"

package moderation-status

• Comando per il proprietario per controllare la visibilità di moderazione del pacchetto.
• Chiama GET /api/v1/packages/{name}/moderation.
• Mostra lo stato attuale della scansione del pacchetto, il conteggio delle segnalazioni aperte, lo stato di moderazione manuale della release più recente, lo stato di blocco dei download e i motivi di moderazione.
• Flag:
  • --json: output leggibile da macchina.

Esempio:

clawhub package moderation-status @openclaw/example-plugin

package readiness <name>

• Controlla se un pacchetto è pronto per il consumo futuro da parte di OpenClaw.
• Chiama GET /api/v1/packages/{name}/readiness.
• Segnala i blocchi per stato ufficiale, disponibilità ClawPack, digest dell'artefatto, provenienza del sorgente, compatibilità OpenClaw, target host, metadati di ambiente e stato della scansione.
• Flag:
  • --json: output leggibile da macchina.

Esempio:

clawhub package readiness @openclaw/example-plugin

package migration-status <name>

• Mostra lo stato di migrazione orientato agli operatori per un pacchetto che potrebbe sostituire un Plugin OpenClaw incluso.
• Chiama lo stesso endpoint di readiness calcolata di package readiness, ma stampa stato focalizzato sulla migrazione, versione più recente, stato del pacchetto ufficiale, controlli e blocchi.
• Flag:
  • --json: output leggibile da macchina.

Esempio:

clawhub package migration-status @openclaw/example-plugin

publisher create <handle>

• Crea un publisher dell'organizzazione posseduto dall'utente autenticato.
• L'handle viene normalizzato in minuscolo e può essere passato con o senza @.
• I publisher dell'organizzazione appena creati non sono attendibili/ufficiali per impostazione predefinita.
• Fallisce se l'handle è già usato da un publisher, utente o route riservata esistente.

clawhub publisher create opik --display-name "Opik"

package publish <source>

• Pubblica un plugin di codice o un plugin bundle tramite POST /api/v1/packages.
• <source> accetta:
  • Percorso di cartella locale: ./my-plugin
  • Tarball npm-pack ClawPack locale: ./my-plugin-1.2.3.tgz
  • Repository GitHub: owner/repo o owner/repo@ref
  • URL GitHub: https://github.com/owner/repo
• I metadati vengono rilevati automaticamente da package.json, openclaw.plugin.json e da marcatori reali di bundle OpenClaw come .codex-plugin/plugin.json, .claude-plugin/plugin.json e .cursor-plugin/plugin.json.
• Le sorgenti .tgz sono trattate come ClawPack. La CLI carica i byte npm-pack esatti e usa i contenuti estratti di package/ solo per la convalida e la precompilazione dei metadati.
• Le cartelle dei plugin di codice vengono impacchettate in un tarball npm ClawPack prima del caricamento, in modo che le installazioni di OpenClaw possano verificare l'artefatto esatto. Le cartelle dei plugin bundle continuano a usare il percorso di pubblicazione con file estratti.
• Per le sorgenti GitHub, l'attribuzione della sorgente viene popolata automaticamente dal repository, dal commit risolto, dal ref e dal sottopercorso.
• Per le cartelle locali, l'attribuzione della sorgente viene rilevata automaticamente da git locale quando il remote origin punta a GitHub.
• I plugin di codice esterni devono dichiarare esplicitamente openclaw.compat.pluginApi e openclaw.build.openclawVersion. package.json.version di primo livello non viene usato come fallback per la convalida della pubblicazione.
• --dry-run mostra un'anteprima del payload di pubblicazione risolto senza caricarlo.
• --json emette output leggibile da macchina per la CI.
• --owner <handle> pubblica sotto un handle editore utente o organizzazione quando l'attore ha accesso come editore.
• I nomi dei pacchetti con ambito devono corrispondere al proprietario selezionato. Vedi docs/publishing.md.
• I flag esistenti (--family, --name, --version, --source-repo, --source-commit, --source-ref, --source-path) continuano a funzionare come override.
• I repository GitHub privati richiedono GITHUB_TOKEN.

clawhub package publish ./plugin.tgz --owner openclaw

Flusso locale consigliato

Usa prima --dry-run così puoi confermare i metadati del pacchetto risolti e l'attribuzione della sorgente prima di creare una release reale:

npm packclawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin --dry-runclawhub package publish ./my-plugin-1.2.3.tgz --family code-plugin

Flusso con cartella locale

Per i plugin di codice, la pubblicazione da cartella crea e carica un artefatto ClawPack dalla cartella del pacchetto:

clawhub package publish ./my-plugin --family code-plugin --dry-runclawhub package publish ./my-plugin --family code-plugin

package.json minimale per --family code-plugin

I plugin di codice esterni richiedono una piccola quantità di metadati OpenClaw in package.json. Questo manifest minimale è sufficiente per una pubblicazione riuscita:

{  "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"    }  }}

Campi obbligatori:

• openclaw.compat.pluginApi
• openclaw.build.openclawVersion

Note:

• package.json.version è la versione di release del tuo pacchetto, ma non viene usata come fallback per la convalida di compatibilità/build di OpenClaw.
• openclaw.hostTargets e openclaw.environment sono metadati facoltativi. ClawHub può mostrarli quando presenti, ma non sono richiesti per la pubblicazione.
• openclaw.compat.minGatewayVersion e openclaw.build.pluginSdkVersion sono extra facoltativi se vuoi pubblicare metadati di compatibilità più dettagliati.
• Se stai usando una release precedente della CLI clawhub, aggiorna prima di pubblicare affinché i controlli preliminari locali vengano eseguiti prima del caricamento.
• Se la convalida riporta un codice di correzione, vedi Correzioni di convalida dei Plugin.

GitHub Actions

ClawHub distribuisce anche un workflow riutilizzabile ufficiale in /.github/workflows/package-publish.yml per repository di plugin.

Configurazione tipica del chiamante:

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 }}

Note:

• Il workflow riutilizzabile imposta per impostazione predefinita source sul repository chiamante.
• Per i monorepo, passa source_path affinché il workflow pubblichi la cartella del pacchetto plugin, per esempio source_path: extensions/codex.
• Fissa il workflow riutilizzabile a un tag stabile o a uno SHA di commit completo. Non eseguire la pubblicazione di release da @main.
• pull_request dovrebbe usare dry_run: true così la CI rimane non inquinante.
• Le pubblicazioni reali dovrebbero essere limitate a eventi attendibili come workflow_dispatch o push di tag.
• La pubblicazione attendibile senza un segreto funziona solo su workflow_dispatch; i push di tag richiedono comunque clawhub_token.
• Mantieni clawhub_token disponibile per la prima pubblicazione, per pacchetti non attendibili o per pubblicazioni di emergenza.
• Il workflow carica il risultato JSON come artefatto e lo espone come output del workflow.

package trusted-publisher get <name>

• Mostra la configurazione dell'editore attendibile GitHub Actions per un pacchetto.
• Usalo dopo aver impostato la configurazione per confermare il repository, il nome file del workflow e il pin facoltativo dell'ambiente.
• Flag:
  • --json: output leggibile da macchina.

Esempio:

clawhub package trusted-publisher get @openclaw/example-plugin

package trusted-publisher set <name>

• Collega o sostituisce la configurazione dell'editore attendibile GitHub Actions per un pacchetto esistente.
• Il pacchetto deve essere prima creato tramite la normale pubblicazione manuale o autenticata con token clawhub package publish.
• Dopo l'impostazione della configurazione, le future pubblicazioni GitHub Actions supportate possono usare OIDC/pubblicazione attendibile senza un token ClawHub a lunga durata.
• --repository <repo> deve essere owner/repo.
• --workflow-filename <file> deve corrispondere al nome del file workflow in .github/workflows/.
• --environment <name> è facoltativo. Quando configurato, l'ambiente GitHub Actions nella dichiarazione OIDC deve corrispondere esattamente.
• ClawHub verifica il repository GitHub configurato quando questo comando viene eseguito. I repository pubblici possono essere verificati tramite metadati GitHub pubblici. I repository privati richiedono che ClawHub abbia accesso GitHub a quel repository, per esempio tramite una futura installazione della GitHub App di ClawHub o un'altra integrazione GitHub autorizzata.
• Flag:
  • --repository <repo>: repository GitHub, per esempio openclaw/example-plugin.
  • --workflow-filename <file>: nome file del workflow, per esempio package-publish.yml.
  • --environment <name>: ambiente GitHub Actions facoltativo con corrispondenza esatta.
  • --json: output leggibile da macchina.

Esempio:

clawhub package trusted-publisher set @openclaw/example-plugin \  --repository openclaw/example-plugin \  --workflow-filename package-publish.yml \  --environment release

package trusted-publisher delete <name>

• Rimuove la configurazione dell'editore attendibile da un pacchetto.
• Usalo come rollback se il workflow, il repository o il pin dell'ambiente devono essere disabilitati o ricreati.
• Le future pubblicazioni reali devono usare la normale pubblicazione autenticata finché la configurazione non viene impostata di nuovo.
• Flag:
  • --json: output leggibile da macchina.

Esempio:

clawhub package trusted-publisher delete @openclaw/example-plugin

Telemetria di installazione

• Inviata dopo clawhub install <slug> quando hai effettuato l'accesso, a meno che CLAWHUB_DISABLE_TELEMETRY=1 sia impostato.
• La segnalazione è best-effort. I comandi di installazione non falliscono se la telemetria non è disponibile.
• Dettagli: docs/telemetry.md.