--- read_when: - Utilizzo della CLI di ClawHub - Debug di installazione, aggiornamento o pubblicazione summary: 'Riferimento CLI: comandi, flag, configurazione e comportamento del lockfile.' x-i18n: generated_at: "2026-07-03T17:25:39Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 23065775d74e7b52ed250051b8724b780c28dfdfc0adf9b8f115f7133fbdd77b source_path: clawhub/cli.md workflow: 16 --- # CLI Pacchetto CLI: `clawhub`, binario: `clawhub`. Installalo globalmente con npm o pnpm: ```bash npm i -g clawhub # or pnpm add -g clawhub ``` Poi verificalo: ```bash clawhub --help clawhub login clawhub whoami ``` ## Flag globali - `--workdir `: directory di lavoro (predefinita: cwd; ripiega sul workspace Clawdbot se configurato) - `--dir `: directory di installazione sotto workdir (predefinita: `skills`) - `--site `: URL di base per l'accesso dal browser (predefinito: `https://clawhub.ai`) - `--registry `: 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: ```bash export HTTPS_PROXY=http://proxy.example.com:3128 export NO_PROXY=localhost,127.0.0.1 clawhub 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 `/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 `/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 ` / `unstar ` - Aggiunge/rimuove una competenza dai tuoi elementi in evidenza. - Chiama `POST /api/v1/stars/` e `DELETE /api/v1/stars/`. - `--yes` salta la conferma. ### `search ` - 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 ` (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: ` v ` (riepilogo troncato a 50 caratteri). ### `inspect @owner/slug` - Recupera i metadati della competenza e i file di versione senza installare. - `--version `: ispeziona una versione specifica (predefinita: latest). - `--tag `: ispeziona una versione con tag (ad es. `latest`). - `--versions`: elenca la cronologia delle versioni (prima pagina). - `--limit `: numero massimo di versioni da elencare (1-200). - `--files`: elenca i file per la versione selezionata. - `--file `: 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 `//`. - Rifiuta di sovrascrivere le competenze bloccate; esegui prima `clawhub unpin `. - Scrive: - `/.clawhub/lock.json` (legacy `.clawdhub`) - `/.clawhub/origin.json` (legacy `.clawdhub`) ### `uninstall ` - Rimuove `//` 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 `/.clawhub/lock.json` (legacy `.clawdhub`). - Mostra `pinned` accanto alle competenze congelate con `clawhub pin`, incluso il motivo facoltativo. ### `pin ` - Contrassegna una competenza installata come bloccata nel lockfile. - `--reason ` registra perché la competenza è congelata. - Le competenze bloccate vengono saltate da `update --all` e rifiutate da `update ` diretto. - Le competenze bloccate rifiutano anche `install --force`, così i byte locali non possono essere sostituiti accidentalmente. ### `unpin ` - 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 ` fallisce rapidamente per le competenze bloccate e ti dice di eseguire prima `clawhub unpin `. - `update --all` salta gli slug bloccati e stampa un riepilogo di ciò che è rimasto congelato. ### `skill publish ` - 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 ` 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 ` 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 `. ```bash clawhub skill publish ./my-skill --dry-run clawhub skill publish ./my-skill clawhub skill publish ./my-skill --version 2.0.0 ``` #### GitHub Actions Il workflow riutilizzabile di ClawHub [`skill-publish.yml`](https://github.com/openclaw/clawhub/blob/main/.github/workflows/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 ` 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 ` 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. ```bash clawhub sync --all --dry-run clawhub sync --all clawhub sync --root ./skills --owner openclaw --bump minor ``` ### `scan --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 ` 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. ```bash clawhub scan --slug gifgrep clawhub scan --slug gifgrep --version 1.2.3 clawhub scan --slug gifgrep --update --output report.zip ``` ### `scan download ` - 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 ` sceglie il percorso di destinazione. ```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 fornisce un workflow riutilizzabile ufficiale su [`/.github/workflows/skill-publish.yml`](https://github.com/openclaw/clawhub/blob/76b4f36bb0f7409ed7cb9c6fd6f1ccf81396ee88/.github/workflows/skill-publish.yml) per repository di competenze e repository di cataloghi. Configurazione tipica del catalogo: ```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 }} ``` 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 ` - 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 ` 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 ` registra una nota di moderazione su un'eliminazione reversibile dell'intera skill e nel log di audit. - `--note ` è un alias di `--reason`. - `--yes` salta la conferma. ### `undelete ` - 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 ` registra una nota di moderazione sulla skill e nel log di audit. - `--note ` è un alias di `--reason`. - `--yes` salta la conferma. ### `hide ` - Nasconde una skill (proprietario, moderatore o amministratore). - Alias di `delete`. ### `unhide ` - Rende di nuovo visibile una skill (proprietario, moderatore o amministratore). - Alias di `undelete`. ### `skill rename ` - 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 ` - 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 [--message "..."] [--yes]` - `transfer list [--outgoing]` - `transfer accept [--yes]` - `transfer reject [--yes]` - `transfer cancel [--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 `, `--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, predefinito: 25) - `--json` Esempi: ```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 ` - Recupera i metadati del pacchetto senza installarlo. - Usalo per metadati del Plugin, compatibilità, verifica, sorgente e ispezione di versioni/file. - `--version `: ispeziona una versione specifica (predefinito: più recente). - `--tag `: ispeziona una versione con tag (ad es. `latest`). - `--versions`: elenca la cronologia delle versioni (prima pagina). - `--limit `: numero massimo di versioni da elencare (1-100). - `--files`: elenca i file per la versione selezionata. - `--file `: recupera il contenuto grezzo del file (solo file di testo; limite 200 KB). - `--json`: output leggibile da macchina. ### `package download ` - 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 `: scarica una versione specifica. - `--tag `: scarica una versione con tag (predefinito: `latest`). - `-o, --output `: file o directory di output. - `--force`: sovrascrive un file di output esistente. - `--json`: output leggibile da macchina. Esempi: ```bash clawhub package download @openclaw/example-plugin --tag latest clawhub package download @openclaw/example-plugin --version 1.2.3 -o artifacts/ ``` ### `package verify ` - 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 `: nome del pacchetto per risolvere i metadati previsti dell'artefatto. - `--version ` o `--tag `: versione prevista del pacchetto. - `--sha256 `: SHA-256 di ClawHub previsto. - `--npm-integrity `: integrità npm prevista. - `--npm-shasum `: shasum npm previsto. - `--json`: output leggibile da macchina. Esempi: ```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 ` - 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 `: scrive i report del Plugin Inspector in questa directory. - `--openclaw `: 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: ```bash 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](/clawhub/plugin-validation-fixes), quindi riesegui il comando. ### `package delete ` - Senza `--version`, elimina in modo reversibile un pacchetto e tutte le release. - `--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 `: elimina definitivamente una versione non più recente. - `--yes`: salta la conferma. - `--json`: output leggibile da macchina. Esempio: ```bash clawhub package delete @openclaw/example-plugin --yes clawhub package delete @openclaw/example-plugin --version 1.2.3 --yes ``` ### `package undelete ` - 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: ```bash clawhub package undelete @openclaw/example-plugin --yes ``` ### `package transfer ` - 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 `: handle del publisher di destinazione. - `--reason `: motivo di audit facoltativo. - `--json`: output leggibile da macchina. Esempio: ```bash 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 `: versione del pacchetto facoltativa da allegare alla segnalazione. - `--reason `: motivo della segnalazione obbligatorio. - `--json`: output leggibile da macchina. Esempio: ```bash 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: ```bash clawhub package moderation-status @openclaw/example-plugin ``` ### `package readiness ` - 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: ```bash clawhub package readiness @openclaw/example-plugin ``` ### `package migration-status ` - 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: ```bash clawhub package migration-status @openclaw/example-plugin ``` ### `publisher create ` - 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. ```bash clawhub publisher create opik --display-name "Opik" ``` ### `package publish ` - Pubblica un plugin di codice o un plugin bundle tramite `POST /api/v1/packages`. - `` 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 ` 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`. ```bash 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: ```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 ``` #### Flusso con cartella locale Per i plugin di codice, la pubblicazione da cartella crea e carica un artefatto ClawPack dalla cartella del pacchetto: ```bash clawhub package publish ./my-plugin --family code-plugin --dry-run clawhub 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: ```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" } } } ``` 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](/clawhub/plugin-validation-fixes). #### GitHub Actions ClawHub distribuisce anche un workflow riutilizzabile ufficiale in [`/.github/workflows/package-publish.yml`](https://github.com/openclaw/clawhub/blob/76b4f36bb0f7409ed7cb9c6fd6f1ccf81396ee88/.github/workflows/package-publish.yml) per repository di plugin. Configurazione tipica del chiamante: ```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 }} ``` 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 ` - 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: ```bash clawhub package trusted-publisher get @openclaw/example-plugin ``` ### `package trusted-publisher set ` - 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 ` deve essere `owner/repo`. - `--workflow-filename ` deve corrispondere al nome del file workflow in `.github/workflows/`. - `--environment ` è 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 `: repository GitHub, per esempio `openclaw/example-plugin`. - `--workflow-filename `: nome file del workflow, per esempio `package-publish.yml`. - `--environment `: ambiente GitHub Actions facoltativo con corrispondenza esatta. - `--json`: output leggibile da macchina. Esempio: ```bash clawhub package trusted-publisher set @openclaw/example-plugin \ --repository openclaw/example-plugin \ --workflow-filename package-publish.yml \ --environment release ``` ### `package trusted-publisher delete ` - 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: ```bash clawhub package trusted-publisher delete @openclaw/example-plugin ``` ### Telemetria di installazione - Inviata dopo `clawhub install ` 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`.