> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # Cli # CLI Pacote da CLI: `clawhub`, binário: `clawhub`. Instale globalmente com npm ou pnpm: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} npm i -g clawhub # or pnpm add -g clawhub ``` Depois verifique: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub --help clawhub login clawhub whoami ``` ## Flags globais * `--workdir `: diretório de trabalho (padrão: cwd; recorre ao workspace do Clawdbot se configurado) * `--dir `: diretório de instalação em workdir (padrão: `skills`) * `--site `: URL base para login no navegador (padrão: `https://clawhub.ai`) * `--registry `: URL base da API (padrão: descoberta; caso contrário, `https://clawhub.ai`) * `--no-input`: desabilita prompts Equivalentes de env: * `CLAWHUB_SITE` (legado `CLAWDHUB_SITE`) * `CLAWHUB_REGISTRY` (legado `CLAWDHUB_REGISTRY`) * `CLAWHUB_WORKDIR` (legado `CLAWDHUB_WORKDIR`) ### Proxy HTTP A CLI respeita variáveis de ambiente padrão de proxy HTTP para sistemas atrás de proxies corporativos ou redes restritas: * `HTTPS_PROXY` / `https_proxy` * `HTTP_PROXY` / `http_proxy` * `NO_PROXY` / `no_proxy` Quando qualquer uma dessas variáveis está definida, a CLI roteia solicitações de saída pelo proxy especificado. `HTTPS_PROXY` é usado para solicitações HTTPS, `HTTP_PROXY` para HTTP simples. `NO_PROXY` / `no_proxy` é respeitado para ignorar o proxy para hosts ou domínios específicos. Isso é necessário em sistemas onde conexões diretas de saída são bloqueadas (por exemplo, contêineres Docker, VPS Hetzner com internet somente via proxy, firewalls corporativos). Exemplo: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export HTTPS_PROXY=http://proxy.example.com:3128 export NO_PROXY=localhost,127.0.0.1 clawhub search "my query" ``` Quando nenhuma variável de proxy está definida, o comportamento permanece inalterado (conexões diretas). ## Arquivo de configuração Armazena seu token de API + URL de registro em 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` * Fallback legado: se `clawhub/config.json` ainda não existir, mas `clawdhub/config.json` existir, a CLI reutiliza o caminho legado * substituição: `CLAWHUB_CONFIG_PATH` (legado `CLAWDHUB_CONFIG_PATH`) ## Comandos ### `login` / `auth login` * Padrão: abre o navegador em `/cli/auth` e conclui via callback de loopback. * Headless: `clawhub login --token clh_...` * Interativo remoto/headless: `clawhub login --device` imprime um código e aguarda enquanto você o autoriza em `/cli/device`. ### `whoami` * Verifica o token armazenado via `/api/v1/whoami`. ### `token` * Imprime o token de API armazenado em stdout. * Útil para encaminhar um token de login local para comandos de configuração de segredo de CI. ### `star ` / `unstar ` * Adiciona/remove uma skill dos seus destaques. * Chama `POST /api/v1/stars/` e `DELETE /api/v1/stars/`. * `--yes` pula a confirmação. ### `search ` * Chama `/api/v1/search?q=...`. * A saída inclui o slug da skill, handle do proprietário, nome de exibição e pontuação de relevância. * A busca favorece correspondências exatas de token de slug/nome antes da popularidade de downloads. Um token de slug independente como `map` corresponde a `personal-map` mais fortemente do que à substring dentro de `amap`. * Popularidade é um pequeno prior de ranqueamento, não uma garantia de posição superior. * Se uma skill deveria aparecer, mas não aparece, execute `clawhub inspect @owner/slug` enquanto estiver logado para verificar diagnósticos de moderação visíveis ao proprietário antes de renomear metadados. ### `explore` * Lista as skills mais novas via `/api/v1/skills?limit=...&sort=createdAt` (ordenadas por `createdAt` desc). * Flags: * `--limit ` (1-200, padrão: 25) * `--sort newest|updated|rating|downloads|trending` (padrão: newest). Aliases legados de ordenação de instalação ainda funcionam por compatibilidade. * `--json` (saída legível por máquina) * Saída: ` v ` (resumo truncado para 50 caracteres). ### `inspect @owner/slug` * Busca metadados da skill e arquivos de versão sem instalar. * `--version `: inspeciona uma versão específica (padrão: mais recente). * `--tag `: inspeciona uma versão marcada (por exemplo, `latest`). * `--versions`: lista o histórico de versões (primeira página). * `--limit `: máximo de versões a listar (1-200). * `--files`: lista arquivos da versão selecionada. * `--file `: busca conteúdo bruto de arquivo (somente arquivos de texto; limite de 200 KB). * `--json`: saída legível por máquina. ### `install @owner/slug` * Resolve a versão mais recente para o proprietário e a skill nomeados. * Baixa zip via `/api/v1/download`. * Extrai para `//`. * Recusa sobrescrever skills fixadas; execute `clawhub unpin ` primeiro. * Grava: * `/.clawhub/lock.json` (legado `.clawdhub`) * `/.clawhub/origin.json` (legado `.clawdhub`) ### `uninstall ` * Remove `//` e exclui a entrada do lockfile. * Envia telemetria em best-effort enquanto estiver logado para que as contagens de instalação atuais possam ser desativadas. * Interativo: pede confirmação. * Não interativo (`--no-input`): requer `--yes`. ### `list` * Lê `/.clawhub/lock.json` (legado `.clawdhub`). * Mostra `pinned` ao lado de skills congeladas com `clawhub pin`, incluindo o motivo opcional. ### `pin ` * Marca uma skill instalada como fixada no lockfile. * `--reason ` registra por que a skill está congelada. * Skills fixadas são ignoradas por `update --all` e rejeitadas por `update ` direto. * Skills fixadas também rejeitam `install --force` para que os bytes locais não sejam substituídos acidentalmente. ### `unpin ` * Remove a fixação do lockfile de uma skill instalada para que atualizações futuras possam modificá-la. ### `update [@owner/slug]` / `update --all` * Calcula a impressão digital a partir de arquivos locais. * Se a impressão digital corresponder a uma versão conhecida: sem prompt. * Se a impressão digital não corresponder: * recusa por padrão * sobrescreve com `--force` (ou prompt, se interativo) * Skills fixadas nunca são atualizadas por `--force`. * `update ` falha rapidamente para skills fixadas e orienta você a executar `clawhub unpin ` primeiro. * `update --all` ignora slugs fixados e imprime um resumo do que permaneceu congelado. ### `skill publish ` * Compara a impressão digital do pacote local com o ClawHub e sai com sucesso quando o conteúdo já está publicado. * Novas skills usam `1.0.0` por padrão; skills alteradas usam a próxima versão patch por padrão. * `--version ` seleciona explicitamente uma versão e publica mesmo quando o conteúdo corresponde a uma versão existente. * `--dry-run` resolve a publicação sem fazer upload; `--json` imprime um resultado legível por máquina. * `--owner ` publica sob um handle de publicador de org/usuário quando o ator tem acesso de publicador. * `--migrate-owner` move uma skill existente para `--owner` enquanto publica uma nova versão. Requer acesso de admin/proprietário em ambos os publicadores. * O comportamento de proprietário e revisão é explicado em `docs/publishing.md`. * Publicar uma skill significa que ela é lançada sob `MIT-0` no ClawHub. * Skills publicadas são livres para usar, modificar e redistribuir sem atribuição. * O ClawHub não oferece suporte a skills pagas nem precificação por skill. * Alias legado: `publish `. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub skill publish ./my-skill --dry-run clawhub skill publish ./my-skill clawhub skill publish ./my-skill --version 2.0.0 ``` #### GitHub Actions O workflow reutilizável [`skill-publish.yml`](https://github.com/openclaw/clawhub/blob/main/.github/workflows/skill-publish.yml) do ClawHub chama `skill publish` para um `skill_path`, ou para cada pasta de skill imediata em `root` (padrão: `skills`). Ele ignora skills inalteradas e usa o mesmo comportamento automático de versão patch. Defina `dry_run: true` para pré-visualizar sem um token. Publicações reais exigem o segredo `clawhub_token`. ### `sync` * Varre o workdir atual, o diretório de skills configurado e quaisquer pastas `--root ` em busca de pastas de skill locais contendo `SKILL.md` ou `skill.md`. * Compara cada impressão digital de skill local com o ClawHub e publica somente skills novas ou alteradas. * Novas skills são publicadas como `1.0.0`; skills alteradas publicam a próxima versão patch por padrão. Use `--bump minor|major` para lotes de atualização que devem avançar em um passo semver maior. * `--dry-run` mostra o plano de publicação sem fazer upload; `--json` imprime um plano legível por máquina. * `--all` publica toda skill nova ou alterada sem perguntar. Sem `--all`, terminais interativos permitem selecionar as skills a publicar. * `--owner ` publica sob um handle de publicador de org/usuário quando o ator tem acesso de publicador. * `sync` é somente publicação unidirecional. Ele não instala, atualiza, baixa nem relata telemetria de instalação/download. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub sync --all --dry-run clawhub sync --all clawhub sync --root ./skills --owner openclaw --bump minor ``` ### `scan --slug ` * Requer `clawhub login`. * Executa o ClawScan do ClawHub por meio de `POST /api/v1/skills/-/scan` e depois consulta até que a varredura seja terminal. * Varreduras são assíncronas e podem levar tempo para concluir. Enquanto estiver na fila, o spinner do terminal mostra a posição atual priorizada da varredura e quantas varreduras estão à frente. * Varreduras publicadas exigem propriedade ou acesso de gerenciamento de publicador. Moderadores/admins podem usar o mesmo backend por meio de `clawhub-admin`. * `--update` é válido somente com `--slug`; ele grava resultados bem-sucedidos de varredura publicada de volta na versão selecionada. * `--output ` baixa o arquivo completo do relatório com `manifest.json`, `clawscan.json`, `skillspector.json`, `static-analysis.json`, `virustotal.json` e `README.md`. * `--json` imprime a resposta completa de consulta para automação. * Varreduras de caminho local não são mais suportadas. Faça upload de uma nova versão e depois use `scan download` para recuperar os resultados de varredura armazenados para essa versão enviada. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub scan --slug gifgrep clawhub scan --slug gifgrep --version 1.2.3 clawhub scan --slug gifgrep --update --output report.zip ``` ### `scan download ` * Requer `clawhub login`. * Baixa o ZIP do relatório de varredura armazenado para uma versão enviada de skill ou plugin, incluindo versões que foram bloqueadas ou ocultadas por verificações de segurança do ClawHub. * Downloads de skill usam o slug da skill e usam `--kind skill` por padrão. * Downloads de plugin usam o nome do pacote e exigem `--kind plugin`. * `--version` é obrigatório para que autores inspecionem a versão exata enviada que o ClawHub bloqueou. * `--output ` escolhe o caminho de destino. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub scan download gifgrep --version 1.2.3 clawhub scan download @scope/demo --version 2.0.0 --kind plugin --output report.zip ``` #### GitHub Actions O ClawHub fornece um workflow reutilizável oficial em [`/.github/workflows/skill-publish.yml`](https://github.com/openclaw/clawhub/blob/76b4f36bb0f7409ed7cb9c6fd6f1ccf81396ee88/.github/workflows/skill-publish.yml) para repositórios de skill e repositórios de catálogo. Configuração típica de catálogo: ```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 }} ``` Observações: * `root` usa `skills` como padrão para repositórios de catálogo. * Passe `skill_path: skills/review-helper` para processar uma pasta de skill. * `owner` mapeia para a flag `--owner` da CLI; omita para publicar como o usuário autenticado. * A publicação de skills V1 usa `clawhub_token`; publicação confiável por GitHub OIDC é somente para pacotes por enquanto. ### `delete ` * Sem `--version`, exclui temporariamente uma skill (proprietário, moderador ou administrador). * Chama `DELETE /api/v1/skills/{slug}`. * Exclusões temporárias iniciadas pelo proprietário reservam o slug por 30 dias; o comando imprime o horário de expiração. * `--version ` exclui permanentemente uma versão própria não mais recente por meio de uma rota fail-closed específica da versão. Versões excluídas não podem ser restauradas nem republicadas. Publique uma substituição antes de excluir a versão mais recente atual. A equipe da plataforma não ignora a propriedade para este fluxo apenas de versão. * `--reason ` registra uma nota de moderação em uma exclusão temporária da skill inteira e no log de auditoria. * `--note ` é um alias para `--reason`. * `--yes` pula a confirmação. ### `undelete ` * Restaura uma skill oculta (proprietário, moderador ou administrador). * Não há restauração de versão; versões excluídas permanentemente não podem ser restauradas. * Chama `POST /api/v1/skills/{slug}/undelete`. * `--reason ` registra uma nota de moderação na skill e no log de auditoria. * `--note ` é um alias para `--reason`. * `--yes` pula a confirmação. ### `hide ` * Oculta uma skill (proprietário, moderador ou administrador). * Alias para `delete`. ### `unhide ` * Reexibe uma skill (proprietário, moderador ou administrador). * Alias para `undelete`. ### `skill rename ` * Renomeia uma skill própria e mantém o slug anterior como alias de redirecionamento. * Chama `POST /api/v1/skills/{slug}/rename`. * `--yes` pula a confirmação. ### `skill merge ` * Mescla uma skill própria em outra skill própria. * O slug de origem deixa de ser listado publicamente e se torna um alias de redirecionamento para o destino. * Chama `POST /api/v1/skills/{sourceSlug}/merge`. * `--yes` pula a confirmação. ### `transfer` * Fluxo de transferência de propriedade. * Transferências para handles de usuários criam uma solicitação pendente que o destinatário aceita. * Transferências para handles de organizações/publicadores são aplicadas imediatamente apenas quando o ator tem acesso de administrador tanto ao proprietário atual quanto ao publicador de destino. * Subcomandos: * `transfer request [--message "..."] [--yes]` * `transfer list [--outgoing]` * `transfer accept [--yes]` * `transfer reject [--yes]` * `transfer cancel [--yes]` * Endpoints: * `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...]` * Navega ou pesquisa no catálogo unificado de pacotes via `GET /api/v1/packages` e `GET /api/v1/packages/search`. * Use isto para plugins e outras entradas da família de pacotes; `search` de nível superior permanece a superfície de pesquisa de skills. * Flags: * `--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, padrão: 25) * `--json` Exemplos: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ` * Busca metadados do pacote sem instalar. * Use isto para metadados de plugin, compatibilidade, verificação, origem e inspeção de versão/arquivo. * `--version `: inspeciona uma versão específica (padrão: mais recente). * `--tag `: inspeciona uma versão marcada (por exemplo, `latest`). * `--versions`: lista o histórico de versões (primeira página). * `--limit `: máximo de versões a listar (1-100). * `--files`: lista arquivos da versão selecionada. * `--file `: busca o conteúdo bruto do arquivo (somente arquivos de texto; limite de 200 KB). * `--json`: saída legível por máquina. ### `package download ` * Resolve uma versão de pacote por meio de `GET /api/v1/packages/{name}/versions/{version}/artifact`. * Baixa o artefato a partir do `downloadUrl` do resolvedor. * Verifica o SHA-256 do ClawHub para todos os artefatos. * Para artefatos ClawPack npm-pack, também verifica a integridade npm `sha512`, o shasum npm e o nome/versão do `package.json` do tarball. * Versões ZIP legadas são baixadas pela rota ZIP legada. * Flags: * `--version `: baixa uma versão específica. * `--tag `: baixa uma versão marcada (padrão: `latest`). * `-o, --output `: arquivo ou diretório de saída. * `--force`: sobrescreve um arquivo de saída existente. * `--json`: saída legível por máquina. Exemplos: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub package download @openclaw/example-plugin --tag latest clawhub package download @openclaw/example-plugin --version 1.2.3 -o artifacts/ ``` ### `package verify ` * Calcula o SHA-256 do ClawHub, a integridade npm `sha512` e o shasum npm para um artefato local. * Com `--package`, resolve os metadados esperados no ClawHub e compara o arquivo local com os metadados do artefato publicado. * Com flags diretas de digest, verifica sem uma consulta de rede. * Flags: * `--package `: nome do pacote para resolver os metadados esperados do artefato. * `--version ` ou `--tag `: versão esperada do pacote. * `--sha256 `: SHA-256 esperado do ClawHub. * `--npm-integrity `: integridade npm esperada. * `--npm-shasum `: shasum npm esperado. * `--json`: saída legível por máquina. Exemplos: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ` * Executa o Plugin Inspector integrado da CLI do ClawHub contra uma pasta local de pacote de plugin. * O padrão é validação offline/estática, sem localizar nem importar um checkout local do OpenClaw. * Erros graves de compatibilidade saem com código diferente de zero. Achados apenas de aviso são impressos, mas saem com zero. * Flags: * `--out `: grava relatórios do Plugin Inspector neste diretório. * `--openclaw `: inspeciona contra um checkout local explícito do OpenClaw. * `--runtime`: habilita captura de runtime; importa código de plugin. * `--allow-execute`: permite captura de runtime em um workspace isolado. * `--no-mock-sdk`: desabilita o SDK OpenClaw simulado durante a captura de runtime. * `--json`: saída legível por máquina. Exemplo: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub package validate ./example-plugin ``` Se a validação relatar um achado de pacote, manifesto, importação de SDK ou artefato, consulte [Correções de validação de plugin](/pt-BR/clawhub/plugin-validation-fixes) e execute o comando novamente. ### `package delete ` * Sem `--version`, exclui temporariamente um pacote e todas as versões. * `--version ` exclui permanentemente uma versão própria não mais recente por meio de uma rota fail-closed específica da versão. Versões excluídas não podem ser restauradas nem republicadas. Publique uma substituição antes de excluir a versão mais recente atual. Este fluxo apenas de versão exige o proprietário do pacote ou um administrador de publicador de organização; a equipe da plataforma não ignora a propriedade do pacote. * A exclusão temporária do pacote inteiro exige o proprietário do pacote, um proprietário/administrador de publicador de organização, moderador da plataforma ou administrador da plataforma. * Flags: * `--version `: exclui permanentemente uma versão não mais recente. * `--yes`: pula a confirmação. * `--json`: saída legível por máquina. Exemplo: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub package delete @openclaw/example-plugin --yes clawhub package delete @openclaw/example-plugin --version 1.2.3 --yes ``` ### `package undelete ` * Restaura um pacote e versões excluídos temporariamente. * Não há restauração de versão; versões excluídas permanentemente não podem ser restauradas. * Exige o proprietário do pacote, um proprietário/administrador de publicador de organização, moderador da plataforma, ou administrador da plataforma. * Chama `POST /api/v1/packages/{name}/undelete`. * Flags: * `--yes`: pula a confirmação. * `--json`: saída legível por máquina. Exemplo: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub package undelete @openclaw/example-plugin --yes ``` ### `package transfer ` * Transfere um pacote para outro publicador. * Exige acesso de administrador tanto ao proprietário atual do pacote quanto ao publicador de destino, a menos que seja realizado por um administrador da plataforma. * Nomes de pacotes com escopo devem ser transferidos para o proprietário de escopo correspondente. * Chama `POST /api/v1/packages/{name}/transfer`. * Flags: * `--to `: handle do publicador de destino. * `--reason `: motivo opcional de auditoria. * `--json`: saída legível por máquina. Exemplo: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub package transfer @openclaw/example-plugin --to openclaw ``` ### `package report` * Comando autenticado para denunciar um pacote aos moderadores. * Chama `POST /api/v1/packages/{name}/report`. * Denúncias são no nível do pacote, opcionalmente vinculadas a uma versão, e ficam visíveis para os moderadores analisarem. * Denúncias não ocultam pacotes automaticamente nem bloqueiam downloads por si só. * Flags: * `--version `: versão opcional do pacote a anexar à denúncia. * `--reason `: motivo obrigatório da denúncia. * `--json`: saída legível por máquina. Exemplo: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub package report @openclaw/example-plugin --version 1.2.3 --reason "suspicious native payload" ``` ### `package moderation-status` * Comando do proprietário para verificar a visibilidade de moderação do pacote. * Chama `GET /api/v1/packages/{name}/moderation`. * Mostra o estado atual de varredura do pacote, a contagem de denúncias abertas, o estado de moderação manual da versão mais recente, o estado de bloqueio de download e os motivos de moderação. * Flags: * `--json`: saída legível por máquina. Exemplo: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub package moderation-status @openclaw/example-plugin ``` ### `package readiness ` * Verifica se um pacote está pronto para consumo futuro pelo OpenClaw. * Chama `GET /api/v1/packages/{name}/readiness`. * Relata bloqueadores para status oficial, disponibilidade do ClawPack, digest do artefato, proveniência da origem, compatibilidade com OpenClaw, destinos de host, metadados de ambiente e estado de varredura. * Flags: * `--json`: saída legível por máquina. Exemplo: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub package readiness @openclaw/example-plugin ``` ### `package migration-status ` * Mostra o status de migração orientado a operadores para um pacote que pode substituir um plugin OpenClaw integrado. * Chama o mesmo endpoint de prontidão calculada que `package readiness`, mas imprime status focado em migração, versão mais recente, estado de pacote oficial, verificações e bloqueadores. * Flags: * `--json`: saída legível por máquina. Exemplo: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub package migration-status @openclaw/example-plugin ``` ### `publisher create ` * Cria um publicador de organização pertencente ao usuário autenticado. * O handle é normalizado para minúsculas e pode ser passado com ou sem `@`. * Publicadores de organização recém-criados não são confiáveis/oficiais por padrão. * Falha se o handle já for usado por um publicador, usuário ou rota reservada existente. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub publisher create opik --display-name "Opik" ``` ### `package publish ` * Publica um plugin de código ou plugin de bundle via `POST /api/v1/packages`. * `` aceita: * Caminho de pasta local: `./my-plugin` * Tarball npm-pack local do ClawPack: `./my-plugin-1.2.3.tgz` * Repositório do GitHub: `owner/repo` ou `owner/repo@ref` * URL do GitHub: `https://github.com/owner/repo` * Os metadados são detectados automaticamente a partir de `package.json`, `openclaw.plugin.json` e marcadores reais de bundle do OpenClaw, como `.codex-plugin/plugin.json`, `.claude-plugin/plugin.json` e `.cursor-plugin/plugin.json`. * Fontes `.tgz` são tratadas como ClawPack. A CLI envia os bytes exatos do npm-pack e usa o conteúdo extraído de `package/` apenas para validação e preenchimento prévio de metadados. * Pastas de plugin de código são empacotadas em um tarball npm do ClawPack antes do envio para que instalações do OpenClaw possam verificar o artefato exato. Pastas de plugin de bundle ainda usam o caminho de publicação por arquivos extraídos. * Para fontes do GitHub, a atribuição da fonte é preenchida automaticamente a partir do repositório, commit resolvido, ref e subcaminho. * Para pastas locais, a atribuição da fonte é detectada automaticamente a partir do git local quando o remoto origin aponta para o GitHub. * Plugins de código externos devem declarar `openclaw.compat.pluginApi` e `openclaw.build.openclawVersion` explicitamente. `package.json.version` de nível superior não é usado como fallback para validação de publicação. * `--dry-run` pré-visualiza o payload de publicação resolvido sem enviar. * `--json` emite saída legível por máquina para CI. * `--owner ` publica sob um identificador de publicador de usuário ou organização quando o ator tem acesso de publicador. * Nomes de pacote com escopo devem corresponder ao owner selecionado. Consulte `docs/publishing.md`. * Flags existentes (`--family`, `--name`, `--version`, `--source-repo`, `--source-commit`, `--source-ref`, `--source-path`) ainda funcionam como substituições. * Repositórios privados do GitHub exigem `GITHUB_TOKEN`. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub package publish ./plugin.tgz --owner openclaw ``` #### Fluxo local recomendado Use `--dry-run` primeiro para confirmar os metadados resolvidos do pacote e a atribuição da fonte antes de criar uma versão ativa: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ``` #### Fluxo de pasta local Para plugins de código, a publicação de pasta cria e envia um artefato ClawPack a partir da pasta do pacote: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub package publish ./my-plugin --family code-plugin --dry-run clawhub package publish ./my-plugin --family code-plugin ``` #### `package.json` mínimo para `--family code-plugin` Plugins de código externos precisam de uma pequena quantidade de metadados do OpenClaw em `package.json`. Este manifesto mínimo é suficiente para uma publicação bem-sucedida: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "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" } } } ``` Campos obrigatórios: * `openclaw.compat.pluginApi` * `openclaw.build.openclawVersion` Observações: * `package.json.version` é a versão de lançamento do seu pacote, mas não é usado como fallback para validação de compatibilidade/build do OpenClaw. * `openclaw.hostTargets` e `openclaw.environment` são metadados opcionais. O ClawHub pode exibi-los quando presentes, mas eles não são obrigatórios para publicação. * `openclaw.compat.minGatewayVersion` e `openclaw.build.pluginSdkVersion` são extras opcionais se você quiser publicar metadados de compatibilidade mais detalhados. * Se você estiver usando uma versão mais antiga da CLI `clawhub`, atualize antes de publicar para que as verificações locais de preflight sejam executadas antes do envio. * Se a validação relatar um código de remediação, consulte [Correções de validação de Plugin](/pt-BR/clawhub/plugin-validation-fixes). #### GitHub Actions O ClawHub também fornece um workflow reutilizável oficial em [`/.github/workflows/package-publish.yml`](https://github.com/openclaw/clawhub/blob/76b4f36bb0f7409ed7cb9c6fd6f1ccf81396ee88/.github/workflows/package-publish.yml) para repositórios de plugin. Configuração típica do chamador: ```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 }} ``` Observações: * O workflow reutilizável define `source` como o repositório chamador por padrão. * Para monorepos, passe `source_path` para que o workflow publique a pasta do pacote do plugin, por exemplo `source_path: extensions/codex`. * Fixe o workflow reutilizável a uma tag estável ou a um SHA de commit completo. Não execute publicação de release a partir de `@main`. * `pull_request` deve usar `dry_run: true` para que a CI permaneça sem efeitos colaterais. * Publicações reais devem ser limitadas a eventos confiáveis, como `workflow_dispatch` ou pushes de tags. * Publicação confiável sem segredo só funciona em `workflow_dispatch`; pushes de tags ainda precisam de `clawhub_token`. * Mantenha `clawhub_token` disponível para a primeira publicação, pacotes não confiáveis ou publicações emergenciais. * O workflow envia o resultado JSON como um artefato e o expõe como saídas do workflow. ### `package trusted-publisher get ` * Mostra a configuração de publicador confiável do GitHub Actions para um pacote. * Use isto depois de definir a configuração para confirmar o repositório, o nome do arquivo de workflow e o pin opcional de ambiente. * Flags: * `--json`: saída legível por máquina. Exemplo: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub package trusted-publisher get @openclaw/example-plugin ``` ### `package trusted-publisher set ` * Anexa ou substitui a configuração de publicador confiável do GitHub Actions para um pacote existente. * O pacote deve ser criado primeiro por meio de uma publicação normal manual ou autenticada por token com `clawhub package publish`. * Depois que a configuração for definida, publicações futuras compatíveis pelo GitHub Actions poderão usar OIDC/publicação confiável sem um token ClawHub de longa duração. * `--repository ` deve ser `owner/repo`. * `--workflow-filename ` deve corresponder ao nome do arquivo de workflow em `.github/workflows/`. * `--environment ` é opcional. Quando configurado, o ambiente do GitHub Actions na declaração OIDC deve corresponder exatamente. * O ClawHub verifica o repositório GitHub configurado quando este comando é executado. Repositórios públicos podem ser verificados por meio de metadados públicos do GitHub. Repositórios privados exigem que o ClawHub tenha acesso do GitHub a esse repositório, por exemplo por meio de uma instalação futura do GitHub App do ClawHub ou outra integração autorizada do GitHub. * Flags: * `--repository `: repositório do GitHub, por exemplo `openclaw/example-plugin`. * `--workflow-filename `: nome do arquivo de workflow, por exemplo `package-publish.yml`. * `--environment `: ambiente do GitHub Actions opcional com correspondência exata. * `--json`: saída legível por máquina. Exemplo: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub package trusted-publisher set @openclaw/example-plugin \ --repository openclaw/example-plugin \ --workflow-filename package-publish.yml \ --environment release ``` ### `package trusted-publisher delete ` * Remove a configuração de publicador confiável de um pacote. * Use isto como rollback se o workflow, repositório ou pin de ambiente precisar ser desabilitado ou recriado. * Publicações reais futuras devem usar publicação autenticada normal até que a configuração seja definida novamente. * Flags: * `--json`: saída legível por máquina. Exemplo: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} clawhub package trusted-publisher delete @openclaw/example-plugin ``` ### Telemetria de instalação * Enviada após `clawhub install ` quando conectado, a menos que `CLAWHUB_DISABLE_TELEMETRY=1` esteja definido. * O relatório é feito em melhor esforço. Comandos de instalação não falham se a telemetria estiver indisponível. * Detalhes: `docs/telemetry.md`.