CLI commands
Plugins
Gerencie Plugins do Gateway, pacotes de hooks e bundles compatíveis.
Guia do usuário final para instalar, habilitar e solucionar problemas de plugins.
Exemplos rápidos para instalar, listar, atualizar, desinstalar e publicar.
Modelo de compatibilidade de bundles.
Campos do manifesto e esquema de configuração.
Reforço de segurança para instalações de plugins.
Comandos
openclaw plugins list [--enabled] [--verbose] [--json]openclaw plugins search <query> [--limit <n>] [--json]openclaw plugins install <path-or-spec> [--link] [--force] [--pin] [--marketplace <source>]openclaw plugins inspect <id> [--runtime] [--json]openclaw plugins inspect --all [--runtime] [--json]openclaw plugins info <id> # alias for inspectopenclaw plugins enable <id>openclaw plugins disable <id>openclaw plugins uninstall <id> [--dry-run] [--keep-files] [--force]openclaw plugins update <id-or-npm-spec> | --all [--dry-run]openclaw plugins registry [--refresh] [--json]openclaw plugins doctoropenclaw plugins init <id> [--name <name>] [--type tool|provider] [--directory <path>]openclaw plugins build [--entry <path>] [--check]openclaw plugins validate [--entry <path>]openclaw plugins marketplace entries [--offline] [--feed-profile <name>] [--json]openclaw plugins marketplace list <source> [--json]openclaw plugins marketplace refresh [--feed-profile <name>] [--expected-sha256 <sha256>] [--json]Para investigar lentidão na instalação, inspeção, desinstalação ou atualização do registro, execute o
comando com OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1. O rastreamento grava as durações das fases
em stderr e mantém a saída JSON analisável. Consulte Depuração.
Criação
openclaw plugins init stock-quotes --name "Stock Quotes"cd stock-quotesnpm run plugin:buildnpm run plugin:validatePor padrão, plugins init cria um Plugin mínimo de ferramenta em TypeScript. O primeiro
argumento é o id do Plugin; --name define o nome de exibição. O OpenClaw usa o
id para o diretório de saída padrão e a nomenclatura do pacote. Estruturas de ferramenta usam
defineToolPlugin e geram scripts plugin:build e
plugin:validate no package.json, que compilam e depois chamam openclaw plugins build/validate.
plugins build importa o ponto de entrada compilado, lê seus metadados estáticos de ferramenta, grava
openclaw.plugin.json e mantém openclaw.extensions do package.json alinhado.
plugins validate verifica se o manifesto gerado, os metadados do pacote e a
exportação atual do ponto de entrada ainda estão de acordo. Consulte Plugins de ferramenta para
ver o fluxo completo de criação.
A estrutura grava código-fonte TypeScript, mas gera metadados a partir do ponto de entrada compilado
./dist/index.js, portanto o fluxo também funciona com a CLI publicada. Use
--entry <path> quando o ponto de entrada não for o ponto de entrada padrão do pacote. Use
plugins build --check na CI para falhar quando os metadados gerados estiverem desatualizados, sem
reescrever arquivos.
Estrutura de provedor
openclaw plugins init acme-models --name "Acme Models" --type providercd acme-modelsnpm installnpm run buildnpm testnpm run validateEstruturas de provedor criam um Plugin genérico de provedor de modelos compatível com OpenAI,
com integração de autenticação por chave de API, um script npm run validate que executa
clawhub package validate, metadados de pacote do ClawHub e um fluxo do GitHub Actions
acionado manualmente para futura publicação confiável por meio do OIDC do GitHub.
Estruturas de provedor não geram Skills e não usam
openclaw plugins build/validate; esses comandos destinam-se ao caminho de metadados gerados
da estrutura de ferramenta.
Antes de publicar, substitua a URL-base de API provisória, o catálogo de modelos, a rota da documentação, o texto de credenciais e o conteúdo do README pelos dados reais do provedor. Use o README gerado para a primeira publicação no ClawHub e para configurar o publicador confiável.
Instalação
openclaw plugins search "calendar" # search ClawHub pluginsopenclaw plugins install <package> # source auto-detectionopenclaw plugins install clawhub:<package> # ClawHub onlyopenclaw plugins install npm:<package> # npm onlyopenclaw plugins install npm-pack:<path.tgz> # local npm-pack tarballopenclaw plugins install git:github.com/<owner>/<repo> # git repoopenclaw plugins install git:github.com/<owner>/<repo>@<ref>openclaw plugins install <path> # local path or archiveopenclaw plugins install -l <path> # link instead of copyopenclaw plugins install <plugin>@<marketplace> # marketplace shorthandopenclaw plugins install <plugin> --marketplace <name> # marketplace (explicit)openclaw plugins install <package> --force # overwrite existing installopenclaw plugins install <package> --pin # pin resolved npm versionopenclaw plugins install clawhub:<package> --acknowledge-clawhub-riskopenclaw plugins install <package> --dangerously-force-unsafe-installMantenedores que testam instalações durante a configuração podem substituir as fontes automáticas de instalação de Plugins por variáveis de ambiente protegidas. Consulte Substituições de instalação de Plugins.
plugins search consulta o ClawHub em busca de pacotes code-plugin e
bundle-plugin instaláveis (não Skills; use openclaw skills search para elas).
O --limit padrão é 20, com limite máximo de 100. Ele apenas lê o catálogo remoto: não há
inspeção do estado local, alteração da configuração, instalação de pacote nem carregamento do runtime
do Plugin. Os resultados incluem o nome do pacote no ClawHub, a família, o canal, a versão,
o resumo e uma sugestão de instalação, como openclaw plugins install clawhub:<package>.
Inclusões de configuração e reparo de configuração inválida
Se sua seção plugins for baseada em um $include de arquivo único, plugins install/update/enable/disable/uninstall gravará diretamente nesse arquivo incluído e deixará openclaw.json intacto. Inclusões na raiz, matrizes de inclusões e inclusões com substituições no mesmo nível falham de forma segura, em vez de serem achatadas. Consulte Inclusões de configuração para ver os formatos compatíveis.
Se a configuração estiver inválida durante a instalação, plugins install normalmente falha de forma segura e orienta você a executar primeiro openclaw doctor --fix. Durante a inicialização e o recarregamento dinâmico do Gateway, uma configuração inválida de Plugin falha de forma segura como qualquer outra configuração inválida; openclaw doctor --fix pode colocar em quarentena a entrada inválida do Plugin. A única exceção documentada durante a instalação é um caminho restrito de recuperação de Plugins incluídos que aceitam explicitamente openclaw.install.allowInvalidConfigRecovery.
--force e reinstalação versus atualização
--force reutiliza o destino de instalação existente e sobrescreve no local um Plugin ou pacote de hooks já instalado. Use-o quando quiser reinstalar intencionalmente o mesmo id a partir de um novo caminho local, arquivo, pacote do ClawHub ou artefato npm. Para atualizações rotineiras de um Plugin npm já rastreado, prefira openclaw plugins update <id-or-npm-spec>.
Se você executar plugins install para um id de Plugin que já esteja instalado, o OpenClaw interromperá a operação e indicará plugins update <id-or-npm-spec> para uma atualização normal, ou plugins install <package> --force quando você realmente quiser sobrescrever a instalação atual a partir de uma fonte diferente. --force não é compatível com --link.
Escopo de --pin
--pin aplica-se apenas a instalações npm e registra o <name>@<version> exato resolvido. Não é compatível com instalações git: (em vez disso, fixe a referência na especificação, por exemplo, git:github.com/acme/plugin@v1.2.3) nem com --marketplace (instalações do marketplace persistem metadados da fonte do marketplace em vez de uma especificação npm).
--dangerously-force-unsafe-install
--dangerously-force-unsafe-install está obsoleto e agora não realiza nenhuma operação. O OpenClaw não executa mais o bloqueio interno de código perigoso durante instalações de Plugins.
Use a superfície security.installPolicy, controlada pelo operador, quando for necessária uma política de instalação específica do host. Hooks before_install de Plugins são hooks do ciclo de vida do runtime do Plugin, não o principal limite de política para instalações pela CLI.
Se um Plugin que você publicou no ClawHub estiver oculto ou bloqueado por uma verificação do registro, siga as etapas para publicadores em Publicação no ClawHub. --dangerously-force-unsafe-install não solicita que o ClawHub verifique novamente o Plugin nem torne pública uma versão bloqueada.
--acknowledge-clawhub-risk
Instalações de pacotes da comunidade no ClawHub verificam o registro de confiança da versão selecionada antes do download. Se o ClawHub desabilitar o download da versão, relatar resultados maliciosos na verificação ou colocar a versão em um estado de moderação bloqueante (em quarentena, revogada), o OpenClaw a recusará sem exceção, independentemente dessa opção. Para estados de moderação ou resultados de verificação arriscados, mas não bloqueantes, o OpenClaw mostra os detalhes de confiança e solicita confirmação antes de continuar.
Use --acknowledge-clawhub-risk somente depois de analisar o aviso do ClawHub e decidir continuar sem uma solicitação interativa. Resultados de verificação pendentes ou desatualizados (ainda não considerados limpos) geram um aviso, mas não exigem confirmação. Pacotes oficiais do ClawHub e fontes de Plugins incluídos do OpenClaw ignoram totalmente essa verificação de confiança da versão.
Pacotes de hooks e especificações npm
plugins install também é a superfície de instalação para pacotes de hooks que expõem openclaw.hooks em package.json. Use openclaw hooks para obter visibilidade filtrada dos hooks e habilitá-los individualmente, não para instalar pacotes.
As especificações npm são exclusivas do registro (nome do pacote mais uma versão exata ou dist-tag opcional). Especificações Git/URL/arquivo e intervalos semver são rejeitados. As instalações de dependências são executadas em um projeto npm gerenciado por plugin com --ignore-scripts por segurança, mesmo quando o shell tem configurações globais de instalação do npm. Os projetos npm gerenciados dos plugins herdam os overrides do npm no nível do pacote do OpenClaw, portanto as versões de segurança fixadas pelo host também se aplicam às dependências içadas dos plugins.
Use npm:<package> para tornar explícita a resolução pelo npm. Especificações de pacote simples também são instaladas diretamente do npm durante a transição de lançamento, a menos que correspondam ao id de um plugin oficial.
Especificações @openclaw/* brutas que correspondem a plugins incluídos são resolvidas para a cópia incluída e pertencente à imagem antes do fallback para npm. Por exemplo, openclaw plugins install @openclaw/discord@2026.5.20 --pin usa o plugin do Discord incluído na compilação atual do OpenClaw em vez de criar uma substituição npm gerenciada. Para forçar o uso do pacote npm externo, use openclaw plugins install npm:@openclaw/discord@2026.5.20 --pin.
Especificações simples e @latest permanecem no canal estável. Versões de correção do OpenClaw com data, como 2026.5.3-1, contam como estáveis para essa verificação. Se o npm resolver qualquer uma das formas para uma versão de pré-lançamento, o OpenClaw interrompe a operação e solicita que você aceite explicitamente usando uma tag de pré-lançamento (@beta/@rc) ou uma versão exata de pré-lançamento (@1.2.3-beta.4).
Para instalações npm sem uma versão exata (npm:<package> ou npm:<package>@latest), o OpenClaw verifica os metadados do pacote resolvido antes da instalação. Se o pacote estável mais recente exigir uma API de plugin do OpenClaw mais nova ou uma versão mínima do host superior, o OpenClaw inspeciona versões estáveis anteriores e instala a versão compatível mais recente. Versões exatas e dist-tags explícitas permanecem estritas: uma seleção incompatível falha e solicita que você atualize o OpenClaw ou escolha uma versão compatível.
Se uma especificação de instalação simples corresponder ao id de um plugin oficial (por exemplo, diffs), o OpenClaw instala diretamente a entrada do catálogo. Para instalar um pacote npm com o mesmo nome, use uma especificação explícita com escopo (por exemplo, @scope/diffs).
Repositórios Git
Use git:<repo> para instalar diretamente de um repositório Git. Formatos compatíveis: git:github.com/owner/repo, git:owner/repo, URLs completas https://, ssh://, git://, file:// e git@host:owner/repo.git. Adicione @<ref> ou #<ref> para fazer checkout de uma ramificação, tag ou commit antes da instalação.
As instalações via Git clonam em um diretório temporário, fazem checkout da referência solicitada quando presente e, em seguida, usam o instalador normal de diretórios de plugin; assim, a validação do manifesto, a política de instalação do operador, o trabalho de instalação do gerenciador de pacotes e os registros de instalação se comportam como nas instalações via npm. As instalações Git registradas incluem a URL/referência da origem e o commit resolvido, para que openclaw plugins update possa resolver novamente a origem mais tarde.
Após instalar via Git, use openclaw plugins inspect <id> --runtime --json para verificar registros de runtime, como métodos do Gateway e comandos da CLI. Se o plugin registrou uma raiz de CLI com api.registerCli, execute esse comando diretamente pela CLI raiz do OpenClaw, por exemplo, openclaw demo-plugin ping.
Arquivos compactados
Arquivos compactados compatíveis: .zip, .tgz, .tar.gz, .tar. Arquivos de plugins nativos do OpenClaw devem conter um openclaw.plugin.json válido na raiz extraída do plugin; arquivos que contêm apenas package.json são rejeitados antes que o OpenClaw grave os registros de instalação.
Use npm-pack:<path.tgz> quando o arquivo for um tarball npm-pack e você quiser
usar o mesmo caminho de projeto npm gerenciado por plugin usado pelas instalações
do registro, incluindo verificação de package-lock.json, varredura de dependências
içadas e registros de instalação npm. Caminhos simples de arquivos compactados
continuam sendo instalados como arquivos locais na raiz de extensões de plugins.
Instalações do marketplace do Claude também são compatíveis.
As instalações do ClawHub usam um localizador explícito clawhub:<package>:
openclaw plugins install clawhub:openclaw-codex-app-serveropenclaw plugins install clawhub:openclaw-codex-app-server@1.2.3Especificações simples de plugins válidas para npm são instaladas do npm por padrão durante a transição de lançamento, a menos que correspondam ao id de um plugin oficial:
openclaw plugins install openclaw-codex-app-serverUse npm: para tornar explícita a resolução exclusiva pelo npm:
openclaw plugins install npm:openclaw-codex-app-serveropenclaw plugins install npm:@openclaw/discord@2026.5.20openclaw plugins install npm:@scope/plugin-name@1.0.1O OpenClaw verifica a compatibilidade anunciada da API do plugin e da versão mínima do Gateway antes da instalação. Quando a versão selecionada do ClawHub publica um artefato ClawPack, o OpenClaw baixa o .tgz npm-pack versionado, verifica o cabeçalho de resumo do ClawHub e o resumo do artefato e, em seguida, o instala pelo caminho normal de arquivos compactados. Versões mais antigas do ClawHub sem metadados ClawPack continuam sendo instaladas pelo caminho legado de verificação do arquivo do pacote. As instalações registradas mantêm seus metadados de origem do ClawHub, tipo de artefato, integridade npm, shasum npm, nome do tarball e dados de resumo do ClawPack para atualizações posteriores.
Instalações do ClawHub sem versão mantêm uma especificação registrada sem versão para que openclaw plugins update possa acompanhar versões mais novas do ClawHub; seletores explícitos de versão ou tag, como clawhub:pkg@1.2.3 e clawhub:pkg@beta, permanecem fixados nesse seletor.
Forma abreviada de marketplace
Use a forma abreviada plugin@marketplace quando o nome do marketplace existir no cache local de registros do Claude em ~/.claude/plugins/known_marketplaces.json:
openclaw plugins marketplace list <marketplace-name>openclaw plugins install <plugin-name>@<marketplace-name>Use --marketplace para fornecer explicitamente a origem do marketplace:
openclaw plugins install <plugin-name> --marketplace <marketplace-name>openclaw plugins install <plugin-name> --marketplace <owner/repo>openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>openclaw plugins install <plugin-name> --marketplace ./my-marketplaceOrigens de marketplace
- um nome de marketplace conhecido pelo Claude em
~/.claude/plugins/known_marketplaces.json - uma raiz de marketplace local ou um caminho para
marketplace.json - uma forma abreviada de repositório do GitHub, como
owner/repo - uma URL de repositório do GitHub, como
https://github.com/owner/repo - uma URL Git
Regras de marketplaces remotos
Para marketplaces remotos carregados do GitHub ou do Git, as entradas de plugins devem permanecer dentro do repositório clonado do marketplace. O OpenClaw aceita origens de caminho relativo desse repositório e rejeita origens de plugins HTTP(S), com caminho absoluto, Git, GitHub e outras origens que não sejam caminhos em manifestos remotos.
Para caminhos locais e arquivos compactados, o OpenClaw detecta automaticamente:
- plugins nativos do OpenClaw (
openclaw.plugin.json) - pacotes compatíveis com Codex (
.codex-plugin/plugin.json) - pacotes compatíveis com Claude (
.claude-plugin/plugin.jsonou o layout padrão de componentes do Claude quando esse arquivo de manifesto está ausente) - pacotes compatíveis com Cursor (
.cursor-plugin/plugin.json)
Instalações locais gerenciadas devem ser diretórios de plugins ou arquivos compactados. Arquivos de plugin independentes .js,
.mjs, .cjs e .ts não são copiados para a raiz gerenciada de plugins
por plugins install, nem carregados quando colocados diretamente em
~/.openclaw/extensions ou <workspace>/.openclaw/extensions; essas
raízes descobertas automaticamente carregam diretórios de pacotes ou pacotes
de plugins e ignoram arquivos de script de nível superior como auxiliares locais.
Em vez disso, liste arquivos independentes explicitamente em plugins.load.paths.
Use -l/--link para apontar para um diretório de plugin local sem copiá-lo (adiciona
a plugins.load.paths):
openclaw plugins install -l ./my-plugin--link não é compatível com --force (plugins vinculados apontam diretamente
para o caminho de origem, portanto não há nada para sobrescrever no local),
--marketplace ou instalações git:, e exige um caminho local que já exista.
Listar
openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --json--enabledbooleanMostra apenas plugins habilitados.
--verbosebooleanAlterna da visualização em tabela para linhas de detalhes por plugin com metadados de formato/origem/procedência/versão/ativação.
--jsonbooleanInventário legível por máquina, além de diagnósticos do registro e estado da instalação das dependências do pacote.
Se a inicialização registrar plugins.allow is empty; discovered non-bundled plugins may auto-load: ...,
execute openclaw plugins list --enabled --verbose ou
openclaw plugins inspect <id> com o id de um plugin listado para confirmar os
ids dos plugins e copie os ids confiáveis para plugins.allow em openclaw.json.
Quando o aviso puder listar todos os plugins descobertos, ele exibirá um trecho
de plugins.allow pronto para colar que já inclui esses ids. Se um plugin for
carregado sem procedência de instalação/caminho de carregamento, inspecione o id
desse plugin e, em seguida, fixe o id confiável em plugins.allow ou reinstale
o plugin de uma origem confiável para que o OpenClaw registre a procedência da
instalação.
Para trabalhar em plugins incluídos dentro de uma imagem Docker empacotada,
monte com bind o diretório de origem do plugin sobre o caminho de origem
empacotado correspondente, como /app/extensions/synology-chat. O OpenClaw
descobre essa sobreposição de origem montada antes de
/app/dist/extensions/synology-chat; um diretório de origem simplesmente
copiado permanece inativo, portanto instalações empacotadas normais continuam
usando o dist compilado.
Para depuração de hooks no runtime:
openclaw plugins inspect <id> --runtime --jsonmostra os hooks registrados e os diagnósticos de uma passagem de inspeção com o módulo carregado. A inspeção em tempo de execução nunca instala dependências; useopenclaw doctor --fixpara limpar o estado de dependências legadas ou recuperar plugins ausentes disponíveis para download que sejam referenciados pela configuração.openclaw gateway status --deep --require-rpcconfirma a URL/o perfil acessível do Gateway, indicações sobre serviço/processo, o caminho da configuração e a integridade do RPC.- Hooks de conversa não integrados (
llm_input,llm_output,before_model_resolve,before_agent_reply,before_agent_run,before_agent_finalize,agent_end) exigemplugins.entries.<id>.hooks.allowConversationAccess=true.
Índice de plugins
Os metadados de instalação de plugins são um estado gerenciado pela máquina, não uma configuração do usuário. Instalações e atualizações os gravam no banco de dados de estado SQLite compartilhado, no diretório de estado ativo do OpenClaw. A linha installed_plugin_index armazena metadados duráveis de installRecords, incluindo registros de manifestos de plugins ausentes ou com problemas, além de um cache de registro frio derivado dos manifestos, usado por openclaw plugins update, pela desinstalação, pelos diagnósticos e pelo registro frio de plugins.
Quando o OpenClaw encontra registros legados distribuídos de plugins.installs na configuração, as leituras em tempo de execução os tratam como entrada de compatibilidade sem regravar openclaw.json. Gravações explícitas de plugins e openclaw doctor --fix movem esses registros para o índice de plugins e removem a chave da configuração quando gravações nela são permitidas; se qualquer uma das gravações falhar, os registros da configuração serão mantidos para que os metadados de instalação não sejam perdidos.
Desinstalação
openclaw plugins uninstall <id>openclaw plugins uninstall <id> --dry-runopenclaw plugins uninstall <id> --keep-filesopenclaw plugins uninstall <id> --forceuninstall remove os registros do plugin de plugins.entries, do índice de plugins persistido, das entradas das listas de permissão/bloqueio de plugins e das entradas vinculadas de plugins.load.paths, quando aplicável. A menos que --keep-files esteja definido, a desinstalação também remove o diretório de instalação gerenciada rastreado, mas somente quando ele é resolvido dentro da raiz de extensões de plugins do OpenClaw. Se o plugin for atualmente o proprietário do slot memory ou contextEngine, esse slot será redefinido para seu valor padrão (memory-core para memória e legacy para o mecanismo de contexto).
uninstall exibe uma prévia do que será removido e, em seguida, solicita Uninstall plugin "<id>"? antes de fazer alterações. Passe --force para ignorar a solicitação de confirmação (útil para scripts e execuções não interativas); sem essa opção, a desinstalação exige um TTY interativo. --dry-run exibe a mesma prévia e encerra sem solicitar confirmação nem alterar nada.
Atualização
openclaw plugins update <id-or-npm-spec>openclaw plugins update --allopenclaw plugins update <id-or-npm-spec> --dry-runopenclaw plugins update @openclaw/voice-callopenclaw plugins update openclaw-codex-app-server --acknowledge-clawhub-riskopenclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-installAs atualizações se aplicam às instalações de plugins rastreadas no índice gerenciado de plugins e às instalações rastreadas de pacotes de hooks em hooks.internal.installs.
Resolução entre ID de plugin e especificação npm
Quando você passa um ID de plugin, o OpenClaw reutiliza a especificação de instalação registrada para esse plugin. Isso significa que dist-tags armazenadas anteriormente, como @beta, e versões exatas fixadas continuam sendo usadas em execuções posteriores de update <id>.
Durante update <id> --dry-run, instalações npm fixadas em versões exatas permanecem fixadas. Se o OpenClaw também conseguir resolver a linha padrão do registro do pacote e essa linha padrão for mais recente que a versão fixada instalada, a simulação informa a versão fixada e exibe o comando explícito de atualização do pacote com @latest para seguir a linha padrão do registro.
Essa regra de atualização direcionada é diferente do caminho de manutenção em massa openclaw plugins update --all. As atualizações em massa ainda respeitam as especificações comuns de instalação rastreadas, mas registros confiáveis de plugins oficiais do OpenClaw podem ser sincronizados com o destino atual do catálogo oficial, em vez de permanecerem em um pacote oficial exato e desatualizado. Use a atualização direcionada update <id> quando quiser intencionalmente manter inalterada uma especificação oficial exata ou com tag.
Para instalações npm, você também pode passar uma especificação explícita de pacote npm com uma dist-tag ou versão exata. O OpenClaw resolve o nome desse pacote de volta para o registro do plugin rastreado, atualiza o plugin instalado e registra a nova especificação npm para futuras atualizações baseadas em ID.
Passar o nome do pacote npm sem uma versão ou tag também o resolve de volta para o registro do plugin rastreado. Use isso quando um plugin tiver sido fixado em uma versão exata e você quiser movê-lo de volta para a linha de versão padrão do registro.
Atualizações do canal beta
openclaw plugins update <id-or-npm-spec> direcionado reutiliza a especificação de plugin rastreada, a menos que você passe uma nova especificação. openclaw plugins update --all em massa usa o update.channel configurado ao sincronizar registros confiáveis de plugins oficiais com o destino do catálogo oficial; assim, instalações do canal beta podem permanecer na linha de versões beta, em vez de serem normalizadas silenciosamente para a versão estável/mais recente.
openclaw update também reconhece o canal de atualização ativo do OpenClaw: no canal beta, registros de plugins npm e ClawHub da linha padrão tentam primeiro @beta. Eles recorrem à especificação registrada padrão/mais recente se não houver uma versão beta do plugin; plugins npm também recorrem a ela quando o pacote beta existe, mas não passa na validação de instalação. Esse fallback é informado como um aviso e não faz a atualização do núcleo falhar. Versões exatas e tags explícitas permanecem fixadas nesse seletor para atualizações direcionadas.
Verificações de versão e divergência de integridade
Antes de uma atualização npm efetiva, o OpenClaw verifica a versão do pacote instalado em relação aos metadados do registro npm. Se a versão instalada e a identidade do artefato registrada já corresponderem ao destino resolvido, a atualização será ignorada sem download, reinstalação ou regravação de openclaw.json.
Quando existe um hash de integridade armazenado e o hash do artefato obtido muda, o OpenClaw trata isso como divergência de artefato npm. O comando interativo openclaw plugins update exibe os hashes esperado e real e solicita confirmação antes de continuar. Auxiliares de atualização não interativos interrompem de forma segura, a menos que o chamador forneça uma política explícita de continuação.
--dangerously-force-unsafe-install na atualização
--dangerously-force-unsafe-install também é aceito em plugins update por compatibilidade, mas está obsoleto e não altera mais o comportamento da atualização de plugins. A security.installPolicy do operador ainda pode bloquear atualizações; hooks before_install de plugins só se aplicam a processos nos quais os hooks de plugins estejam carregados.
--acknowledge-clawhub-risk na atualização
As atualizações de plugins da comunidade fornecidos pelo ClawHub executam a mesma verificação de confiança da versão exata usada nas instalações antes de baixar o pacote substituto. Use --acknowledge-clawhub-risk em automações revisadas que devam continuar quando a versão selecionada do ClawHub apresentar um aviso de confiança arriscado. Pacotes oficiais do ClawHub e fontes integradas de plugins do OpenClaw ignoram essa solicitação de confiança da versão.
Inspeção
openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --jsonopenclaw plugins inspect --allA inspeção mostra identidade, status de carregamento, origem, recursos do manifesto, sinalizadores de política, diagnósticos, metadados de instalação, recursos do pacote e qualquer suporte detectado a servidores MCP ou LSP, sem importar o tempo de execução do plugin por padrão. A saída JSON inclui os contratos do manifesto do plugin, como contracts.agentToolResultMiddleware e contracts.trustedToolPolicies, para que os operadores possam auditar declarações de superfícies confiáveis antes de ativar ou reiniciar um plugin. Adicione --runtime para carregar o módulo do plugin e incluir hooks, ferramentas, comandos, serviços, métodos do Gateway e rotas HTTP registrados. A inspeção em tempo de execução informa diretamente as dependências ausentes do plugin; instalações e reparos permanecem em openclaw plugins install, openclaw plugins update e openclaw doctor --fix.
Comandos da CLI pertencentes a plugins geralmente são instalados como grupos de comandos raiz de openclaw, mas os plugins também podem registrar comandos aninhados sob um grupo principal do núcleo, como openclaw nodes. Depois que inspect --runtime mostrar um comando em cliCommands, execute-o no caminho listado; por exemplo, um plugin que registra demo-git pode ser verificado com openclaw demo-git ping.
Cada plugin é classificado pelo que realmente registra em tempo de execução:
| Formato | Significado |
|---|---|
plain-capability |
exatamente um tipo de recurso (por exemplo, um plugin somente de provedor) |
hybrid-capability |
mais de um tipo de recurso (por exemplo, texto + fala + imagens) |
hook-only |
somente hooks, sem recursos, ferramentas, comandos, serviços ou rotas |
non-capability |
ferramentas/comandos/serviços, mas sem recursos |
Consulte Formatos de plugins para saber mais sobre o modelo de recursos.
Doctor
openclaw plugins doctordoctor informa erros de carregamento de plugins, diagnósticos de manifesto/descoberta, avisos de compatibilidade e referências obsoletas na configuração de plugins, como slots de plugins ausentes. Quando a árvore de instalação e a configuração de plugins estão limpas, ele exibe No plugin issues detected. Se ainda houver configuração obsoleta, mas a árvore de instalação estiver íntegra, o resumo informa isso em vez de sugerir integridade completa dos plugins.
Se um plugin configurado estiver presente no disco, mas bloqueado pelas verificações de segurança de caminho do carregador, a validação da configuração manterá a entrada do plugin e a informará como present but blocked. Corrija o diagnóstico de plugin bloqueado apresentado anteriormente, como a propriedade do caminho ou permissões de gravação para todos, em vez de remover plugins.entries.<id> ou plugins.allow da configuração.
Para falhas no formato do módulo, como a ausência das exportações register/activate, execute novamente com OPENCLAW_PLUGIN_LOAD_DEBUG=1 para incluir um resumo compacto do formato das exportações na saída de diagnóstico.
Registro
openclaw plugins registryopenclaw plugins registry --refreshopenclaw plugins registry --jsonO registro local de plugins é o modelo de leitura frio persistido do OpenClaw para identidade de plugins instalados, ativação, metadados de origem e propriedade das contribuições. A inicialização normal, a consulta do proprietário do provedor, a classificação da configuração de canais e o inventário de plugins podem lê-lo sem importar módulos de tempo de execução de plugins.
Use plugins registry para verificar se o registro persistido está presente, atualizado ou obsoleto. Use --refresh para reconstruí-lo com base no índice de plugins persistido, na política de configuração e nos metadados de manifesto/pacote. Esse é um caminho de reparo, não um caminho de ativação em tempo de execução.
openclaw doctor --fix também corrige divergências de npm gerenciado adjacentes ao registro: se um pacote @openclaw/* órfão ou recuperado em um projeto npm de plugin gerenciado ou na raiz npm gerenciada plana legada sobrepuser um plugin integrado, o Doctor removerá esse pacote obsoleto e reconstruirá o registro para que a inicialização valide em relação ao manifesto integrado. O Doctor também recria o vínculo do pacote openclaw do host nos plugins npm gerenciados que declaram peerDependencies.openclaw, para que importações locais ao pacote em tempo de execução, como openclaw/plugin-sdk/*, sejam resolvidas após atualizações ou reparos do npm.
Marketplace
openclaw plugins marketplace entriesopenclaw plugins marketplace entries --offlineopenclaw plugins marketplace entries --jsonopenclaw plugins marketplace entries --feed-profile <name>openclaw plugins marketplace entries --feed-url <url>openclaw plugins marketplace list <source>openclaw plugins marketplace list <source> --jsonopenclaw plugins marketplace refreshopenclaw plugins marketplace refresh --feed-profile <name>openclaw plugins marketplace refresh --feed-url <url>openclaw plugins marketplace refresh --expected-sha256 <sha256> --jsonplugins marketplace entries lista as entradas do feed configurado do marketplace do OpenClaw. Por padrão, ele tenta usar o feed hospedado e recorre ao snapshot aceito mais recente ou aos dados incluídos. Use --feed-profile <name> para ler um perfil configurado específico, --feed-url <url> para ler uma URL explícita de feed hospedado e --offline para ler o snapshot aceito mais recente sem buscar o feed.
plugins marketplace refresh atualiza o snapshot do feed hospedado configurado e informa se o OpenClaw aceitou dados hospedados, um snapshot hospedado ou dados alternativos incluídos. Use --expected-sha256 quando o chamador precisar que o comando falhe, a menos que uma carga útil hospedada recente corresponda a uma soma de verificação fixada.
O comando list do marketplace aceita um caminho local do marketplace, um caminho para marketplace.json, uma forma abreviada do GitHub como owner/repo, uma URL de repositório do GitHub ou uma URL git. --json exibe o rótulo da origem resolvida, além do manifesto do marketplace analisado e das entradas de plugins.
A atualização do marketplace carrega um feed hospedado do marketplace do OpenClaw e persiste a resposta validada como o snapshot local do feed hospedado. Sem opções, ela usa o perfil de feed padrão configurado. Use --feed-profile <name> para atualizar um perfil configurado específico, --feed-url <url> para atualizar uma URL explícita de feed hospedado, --expected-sha256 <sha256> para exigir uma soma de verificação correspondente da carga útil (sha256:<hex> ou um resumo hexadecimal simples de 64 caracteres) e --json para obter uma saída legível por máquina. URLs explícitas de feeds hospedados não devem incluir credenciais, strings de consulta nem fragmentos. Atualizações sem fixação podem informar um resultado de snapshot hospedado ou de dados alternativos incluídos sem causar falha no comando. Atualizações com fixação falham, a menos que aceitem uma carga útil hospedada recente, e atualizações hospedadas bem-sucedidas falham se o OpenClaw não conseguir persistir o snapshot validado.
