CLI commands

Plugins

Gerencie plugins do Gateway, pacotes de hooks e bundles compatíveis.

Sistema de Plugin

Guia do usuário final para instalar, habilitar e solucionar problemas de plugins.

Gerenciar plugins

Exemplos rápidos para instalar, listar, atualizar, desinstalar e publicar.

Bundles de Plugin

Modelo de compatibilidade de bundles.

Manifesto do Plugin

Campos do manifesto e esquema de configuração.

Segurança

Reforço de segurança para instalações de plugins.

Comandos

bash

openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --jsonopenclaw plugins search <query>openclaw plugins search <query> --limit 20openclaw plugins search <query> --jsonopenclaw plugins install <path-or-spec>openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --jsonopenclaw plugins inspect --allopenclaw plugins info <id>openclaw plugins enable <id>openclaw plugins disable <id>openclaw plugins registryopenclaw plugins registry --refreshopenclaw plugins uninstall <id>openclaw plugins doctoropenclaw plugins update <id-or-npm-spec>openclaw plugins update --allopenclaw plugins marketplace list <marketplace>openclaw plugins marketplace list <marketplace> --json

Para investigar instalação, inspeção, desinstalação ou atualização de registro lentas, execute o comando com OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1. O rastreamento escreve tempos de fase em stderr e mantém a saída JSON analisável. Consulte Depuração.

Instalar

bash

openclaw plugins search "calendar"                   # search ClawHub pluginsopenclaw plugins install <package>                      # npm by defaultopenclaw plugins install clawhub:<package>              # ClawHub onlyopenclaw plugins install npm:<package>                  # npm onlyopenclaw plugins install npm-pack:<path.tgz>            # local npm pack through npm install semanticsopenclaw plugins install git:github.com/<owner>/<repo>  # git repoopenclaw plugins install git:github.com/<owner>/<repo>@<ref>openclaw plugins install <package> --force              # overwrite existing installopenclaw plugins install <package> --pin                # pin versionopenclaw plugins install <package> --dangerously-force-unsafe-installopenclaw plugins install <path>                         # local pathopenclaw plugins install <plugin>@<marketplace>         # marketplaceopenclaw plugins install <plugin> --marketplace <name>  # marketplace (explicit)openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>

Mantenedores que testam instalações em tempo de configuração podem substituir automaticamente as fontes de instalação de plugins com variáveis de ambiente protegidas. Consulte Substituições de instalação de plugins.

plugins search consulta o ClawHub por pacotes de plugins instaláveis e imprime nomes de pacotes prontos para instalação. Ele pesquisa pacotes de code-plugin e bundle-plugin, não Skills. Use openclaw skills search para Skills do ClawHub.

Includes de configuração e reparo de configuração inválida

Se sua seção plugins for apoiada por um $include de arquivo único, plugins install/update/enable/disable/uninstall escreve nesse arquivo incluído e deixa openclaw.json intocado. Includes raiz, arrays de includes e includes com substituições irmãs falham fechados em vez de serem achatados. Consulte Includes de configuração para os formatos compatíveis.

Se a configuração for inválida durante a instalação, plugins install normalmente falha fechado e informa que você deve executar openclaw doctor --fix primeiro. Durante a inicialização do Gateway e o hot reload, configuração de plugin inválida falha fechado como qualquer outra configuração inválida; openclaw doctor --fix pode colocar a entrada de plugin inválida em quarentena. A única exceção documentada em tempo de instalação é um caminho estreito de recuperação de plugin integrado para plugins que optam explicitamente por openclaw.install.allowInvalidConfigRecovery.

--force e reinstalar vs atualizar

--force reutiliza o destino de instalação existente e sobrescreve no lugar um plugin ou pacote de hooks já instalado. Use quando você estiver reinstalando 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á está instalado, o OpenClaw para e aponta para plugins update <id-or-npm-spec> para uma atualização normal, ou para plugins install <package> --force quando você realmente quiser sobrescrever a instalação atual a partir de uma fonte diferente.

Escopo de --pin

--pin se aplica somente a instalações npm. Não é compatível com instalações git:; use uma ref git explícita, como git:github.com/acme/[email protected], quando quiser uma fonte fixada. Não é compatível com --marketplace, porque instalações de marketplace persistem metadados da fonte de marketplace em vez de uma especificação npm.

--dangerously-force-unsafe-install

--dangerously-force-unsafe-install é uma opção de emergência para falsos positivos no scanner integrado de código perigoso. Ela permite que a instalação continue mesmo quando o scanner integrado relata achados critical, mas não ignora bloqueios de política de hook before_install de plugin e não ignora falhas de varredura.

Esta flag da CLI se aplica a fluxos de instalação/atualização de plugins. Instalações de dependências de Skills apoiadas pelo Gateway usam a substituição de requisição correspondente dangerouslyForceUnsafeInstall, enquanto openclaw skills install permanece um fluxo separado de download/instalação de Skills do ClawHub.

Se um plugin que você publicou no ClawHub for bloqueado por uma varredura do registro, use as etapas de publicador em ClawHub.

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 visibilidade filtrada de hooks e habilitação por hook, não para instalação de pacotes.

Especificações npm são somente de registro (nome do pacote + versão exata opcional ou dist-tag). Especificações Git/URL/arquivo e intervalos semver são rejeitados. Instalações de dependências rodam localmente no projeto com --ignore-scripts por segurança, mesmo quando seu shell tem configurações globais de instalação npm. Raízes npm gerenciadas de plugins herdam os overrides npm no nível de pacote do OpenClaw, então pins de segurança do host também se aplicam a dependências de plugins içadas.

Use npm:<package> quando quiser tornar explícita a resolução npm. Especificações de pacote sem prefixo também instalam diretamente do npm durante a transição de lançamento.

Especificações sem prefixo e @latest permanecem na faixa estável. Versões de correção datadas do OpenClaw, como 2026.5.3-1, são versões estáveis para esta verificação. Se o npm resolver qualquer uma delas para uma pré-versão, o OpenClaw para e pede que você opte explicitamente por uma tag de pré-versão, como @beta/@rc, ou por uma versão de pré-lançamento exata, como @1.2.3-beta.4.

Se uma especificação sem prefixo corresponder a um id oficial de plugin (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 com escopo explícito (por exemplo, @scope/diffs).

Repositórios Git

Use git:<repo> para instalar diretamente a partir de um repositório git. Formatos compatíveis incluem 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 branch, tag ou commit antes da instalação.

Instalações git clonam para um diretório temporário, fazem checkout da ref solicitada quando presente e então usam o instalador normal de diretório de plugin. Isso significa que validação de manifesto, varredura de código perigoso, trabalho de instalação do gerenciador de pacotes e registros de instalação se comportam como instalações npm. Instalações git registradas incluem a URL/ref da fonte mais o commit resolvido para que openclaw plugins update possa resolver novamente a fonte posteriormente.

Depois de instalar a partir do git, use openclaw plugins inspect <id> --runtime --json para verificar registros em tempo de execução, como métodos de 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

Arquivos 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 de o OpenClaw escrever registros de instalação.

Use npm-pack:<path.tgz> quando o arquivo for um tarball npm-pack e você quiser testar o mesmo caminho de instalação de raiz npm gerenciada usado por instalações de registro, incluindo verificação de package-lock.json, varredura de dependências içadas e registros de instalação npm. Caminhos de arquivo comuns ainda instalam como arquivos locais sob a raiz de extensões de plugins.

Instalações do marketplace Claude também são compatíveis.

Instalações do ClawHub usam um localizador explícito clawhub:<package>:

bash

openclaw plugins install clawhub:openclaw-codex-app-serveropenclaw plugins install clawhub:[email protected]

Especificações de plugins seguras para npm sem prefixo instalam do npm por padrão durante a transição de lançamento:

bash

openclaw plugins install openclaw-codex-app-server

Use npm: para tornar explícita a resolução exclusiva por npm:

bash

openclaw plugins install npm:openclaw-codex-app-serveropenclaw plugins install npm:@scope/[email protected]

OpenClaw verifica a API de Plugin anunciada / compatibilidade mínima do Gateway antes da instalação. Quando a versão selecionada do ClawHub publica um artefato ClawPack, OpenClaw baixa o .tgz versionado do pacote npm, verifica o cabeçalho de digest do ClawHub e o digest do artefato, depois o instala pelo caminho normal de arquivo compactado. Versões mais antigas do ClawHub sem metadados de ClawPack ainda são instaladas pelo caminho legado de verificação de arquivo de pacote. Instalações registradas mantêm os metadados de origem do ClawHub, tipo de artefato, integridade npm, shasum npm, nome do tarball e fatos de digest do ClawPack para atualizações posteriores. Instalações não versionadas do ClawHub mantêm uma especificação registrada não versionada para que openclaw plugins update possa acompanhar versões mais novas do ClawHub; seletores explícitos de versão ou tag, como clawhub:[email protected] e clawhub:pkg@beta, permanecem fixados nesse seletor.

Abreviação de marketplace

Use a abreviação plugin@marketplace quando o nome do marketplace existir no cache de registro local do Claude em ~/.claude/plugins/known_marketplaces.json:

bash

openclaw plugins marketplace list <marketplace-name>openclaw plugins install <plugin-name>@<marketplace-name>

Use --marketplace quando quiser passar a origem do marketplace explicitamente:

bash

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

Origens de marketplace

um nome de marketplace conhecido pelo Claude em ~/.claude/plugins/known_marketplaces.json
uma raiz de marketplace local ou caminho de marketplace.json
uma abreviação de repositório GitHub, como owner/repo
uma URL de repositório GitHub, como https://github.com/owner/repo
uma URL git

Regras de marketplace remoto

Para marketplaces remotos carregados do GitHub ou git, as entradas de Plugin devem permanecer dentro do repositório de marketplace clonado. OpenClaw aceita origens de caminho relativo desse repositório e rejeita HTTP(S), caminhos absolutos, git, GitHub e outras origens de Plugin que não sejam caminhos em manifestos remotos.

Para caminhos e arquivos compactados locais, 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.json ou o layout padrão de componentes do Claude)
pacotes compatíveis com Cursor (.cursor-plugin/plugin.json)

Listar

bash

openclaw plugins listopenclaw plugins list --enabledopenclaw plugins list --verboseopenclaw plugins list --jsonopenclaw plugins search <query>openclaw plugins search <query> --limit 20openclaw plugins search <query> --json

--enabledboolean

Mostra apenas Plugins ativados.

--verboseboolean

Alterna da visualização em tabela para linhas de detalhes por Plugin com metadados de origem/procedência/versão/ativação.

--jsonboolean

Inventário legível por máquina, além de diagnósticos de registro e estado de instalação de dependências de pacote.

Note

plugins list lê primeiro o registro local persistido de Plugins, com um fallback derivado apenas do manifesto quando o registro está ausente ou inválido. Ele é útil para verificar se um Plugin está instalado, ativado e visível para o planejamento de inicialização a frio, mas não é uma sondagem de runtime ao vivo de um processo Gateway já em execução. Depois de alterar o código do Plugin, ativação, política de hooks ou plugins.load.paths, reinicie o Gateway que atende o canal antes de esperar que novo código register(api) ou hooks sejam executados. Para implantações remotas/em contêiner, verifique se você está reiniciando o filho real de openclaw gateway run, não apenas um processo wrapper.

plugins list --json inclui o dependencyStatus de cada Plugin a partir de dependencies e optionalDependencies do package.json. OpenClaw verifica se esses nomes de pacote estão presentes ao longo do caminho normal de lookup de node_modules do Node do Plugin; ele não importa código de runtime do Plugin, não executa um gerenciador de pacotes nem repara dependências ausentes.

plugins search é uma consulta remota ao catálogo do ClawHub. Ela não inspeciona o estado local, não altera configuração, não instala pacotes nem carrega código de runtime de Plugin. Os resultados de busca incluem o nome do pacote ClawHub, família, canal, versão, resumo e uma dica de instalação, como openclaw plugins install clawhub:<package>.

Para trabalho em Plugin incluído em 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. OpenClaw descobrirá essa sobreposição de origem montada antes de /app/dist/extensions/synology-chat; um diretório de origem simplesmente copiado permanece inerte, para que instalações empacotadas normais ainda usem o dist compilado.

Para depuração de hooks em runtime:

openclaw plugins inspect <id> --runtime --json mostra hooks registrados e diagnósticos de uma passagem de inspeção com módulo carregado. A inspeção de runtime nunca instala dependências; use openclaw doctor --fix para limpar estado legado de dependências ou recuperar Plugins baixáveis ausentes que são referenciados pela configuração.
openclaw gateway status --deep --require-rpc confirma o Gateway acessível, dicas de serviço/processo, caminho de configuração e integridade RPC.
Hooks de conversa não incluídos (llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize, agent_end) exigem plugins.entries.<id>.hooks.allowConversationAccess=true.

Use --link para evitar copiar um diretório local (adiciona a plugins.load.paths):

bash

openclaw plugins install -l ./my-plugin

Índice de Plugins

Metadados de instalação de Plugins são estado gerenciado por máquina, não configuração do usuário. Instalações e atualizações os gravam em plugins/installs.json no diretório de estado ativo do OpenClaw. Seu mapa de nível superior installRecords é a origem durável dos metadados de instalação, incluindo registros de manifestos de Plugin quebrados ou ausentes. O array plugins é o cache de registro a frio derivado do manifesto. O arquivo inclui um aviso de não editar e é usado por openclaw plugins update, desinstalação, diagnósticos e o registro a frio de Plugins.

Quando OpenClaw encontra registros legados enviados em plugins.installs na configuração, as leituras de runtime os tratam como entrada de compatibilidade sem reescrever openclaw.json. Gravações explícitas de Plugin e openclaw doctor --fix movem esses registros para o índice de Plugins e removem a chave de configuração quando gravações de configuração são permitidas; se qualquer uma das gravações falhar, os registros de configuração são mantidos para que os metadados de instalação não sejam perdidos.

Desinstalar

bash

openclaw plugins uninstall <id>openclaw plugins uninstall <id> --dry-runopenclaw plugins uninstall <id> --keep-files

uninstall remove registros de Plugin de plugins.entries, do índice persistido de Plugins, entradas de lista de permissão/bloqueio de Plugins e 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 quando ele está dentro da raiz de extensões de Plugins do OpenClaw. Para Plugins de active memory, o slot de memória é redefinido para memory-core.

Atualizar

bash

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 --dangerously-force-unsafe-install

Atualizações se aplicam a instalações de Plugin rastreadas no índice de Plugins gerenciado e a instalações de hook-pack rastreadas em hooks.internal.installs.

Resolver id de Plugin vs especificação npm

Quando você passa um id de Plugin, OpenClaw reutiliza a especificação de instalação registrada para esse Plugin. Isso significa que dist-tags armazenadas anteriormente, como @beta, e versões fixadas exatas continuam sendo usadas em execuções posteriores de update <id>.

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. OpenClaw resolve esse nome de pacote de volta para o registro de Plugin rastreado, atualiza esse 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 resolve de volta para o registro de 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 lançamento padrão do registro.

Atualizações do canal beta

openclaw plugins update reutiliza a especificação de Plugin rastreada, a menos que você passe uma nova especificação. openclaw update também conhece o canal de atualização ativo do OpenClaw: no canal beta, registros de Plugin npm e ClawHub da linha padrão tentam @beta primeiro e depois retornam para a especificação padrão/latest registrada se não existir lançamento beta do Plugin. Esse fallback é relatado como aviso e não falha a atualização do core. Versões exatas e tags explícitas permanecem fixadas nesse seletor.

Verificações de versão e desvio de integridade

Antes de uma atualização npm ao vivo, 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 é ignorada sem baixar, reinstalar ou reescrever openclaw.json.

Quando existe um hash de integridade armazenado e o hash do artefato buscado muda, OpenClaw trata isso como desvio de artefato npm. O comando interativo openclaw plugins update imprime os hashes esperado e real e pede confirmação antes de prosseguir. Auxiliares de atualização não interativos falham fechados, 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 está disponível em plugins update como uma substituição de emergência para falsos positivos da varredura integrada de código perigoso durante atualizações de Plugin. Ele ainda não ignora bloqueios de política before_install do Plugin nem bloqueio por falha de varredura, e se aplica apenas a atualizações de Plugin, não a atualizações de hook-pack.

Inspecionar

bash

openclaw plugins inspect <id>openclaw plugins inspect <id> --runtimeopenclaw plugins inspect <id> --json

A inspeção mostra identidade, status de carregamento, origem, capacidades do manifesto, sinalizadores de política, diagnósticos, metadados de instalação, capacidades de pacote e qualquer suporte detectado a servidor MCP ou LSP sem importar o runtime do Plugin por padrão. Adicione --runtime para carregar o módulo do Plugin e incluir hooks, ferramentas, comandos, serviços, métodos de Gateway e rotas HTTP registrados. A inspeção de runtime relata dependências de Plugin ausentes diretamente; instalações e reparos permanecem em openclaw plugins install, openclaw plugins update e openclaw doctor --fix.

Comandos CLI pertencentes a Plugins geralmente são instalados como grupos de comandos raiz openclaw, mas Plugins também podem registrar comandos aninhados sob um pai do core, 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 ele realmente registra em runtime:

plain-capability — um tipo de capability (por exemplo, um plugin somente de provedor)
hybrid-capability — vários tipos de capability (por exemplo, texto + fala + imagens)
hook-only — apenas hooks, sem capabilities ou superfícies
non-capability — ferramentas/comandos/serviços, mas sem capabilities

Consulte Formatos de Plugin para saber mais sobre o modelo de capability.

Diagnóstico

bash

openclaw plugins doctor

doctor relata erros de carregamento de plugin, diagnósticos de manifesto/descoberta e avisos de compatibilidade. Quando tudo está limpo, ele imprime No plugin issues detected.

Se um plugin configurado estiver presente no disco, mas bloqueado pelas verificações de segurança de caminho do loader, a validação de configuração mantém a entrada do plugin e a relata como present but blocked. Corrija o diagnóstico anterior de plugin bloqueado, como propriedade do caminho ou permissões graváveis por todos, em vez de remover a configuração plugins.entries.<id> ou plugins.allow.

Para falhas de formato de módulo, como exports register/activate ausentes, execute novamente com OPENCLAW_PLUGIN_LOAD_DEBUG=1 para incluir um resumo compacto do formato dos exports na saída de diagnóstico.

Registro

bash

openclaw plugins registryopenclaw plugins registry --refreshopenclaw plugins registry --json

O registro local de plugins é o modelo persistido de leitura fria do OpenClaw para identidade de plugins instalados, habilitação, metadados de origem e propriedade de contribuições. Inicialização normal, busca de proprietário de provedor, classificação de configuração de canal e inventário de plugins podem lê-lo sem importar módulos de runtime de plugin.

Use plugins registry para inspecionar se o registro persistido está presente, atual ou obsoleto. Use --refresh para reconstruí-lo a partir do índice de plugins persistido, da política de configuração e dos metadados de manifesto/pacote. Este é um caminho de reparo, não um caminho de ativação de runtime.

openclaw doctor --fix também repara desvios de npm gerenciado adjacentes ao registro: se um pacote @openclaw/* órfão ou recuperado sob a raiz npm de plugins gerenciados sombrear um plugin empacotado, o doctor remove esse pacote obsoleto e reconstrói o registro para que a inicialização valide contra o manifesto empacotado. O doctor também relinka o pacote host openclaw em plugins npm gerenciados que declaram peerDependencies.openclaw, para que imports de runtime locais ao pacote, como openclaw/plugin-sdk/*, resolvam após atualizações ou reparos de npm.

Marketplace

bash

openclaw plugins marketplace list <source>openclaw plugins marketplace list <source> --json

A listagem do marketplace aceita um caminho local de marketplace, um caminho marketplace.json, um atalho do GitHub como owner/repo, uma URL de repositório do GitHub ou uma URL git. --json imprime o rótulo da origem resolvida, além do manifesto de marketplace analisado e das entradas de plugin.

Relacionado

Was this useful?